Commit 33ecd638 authored by Fabio Frazao's avatar Fabio Frazao
Browse files

create_database->Fix typos on tutorial

parent fe4e573c
This source diff could not be displayed because it is too large. You can view the blob instead.
......@@ -13081,7 +13081,7 @@ div#notebook {
<p>The data is a subset of the recordings used in the <a href="https://soi.st-andrews.ac.uk/dclde2013/">2013 DCLDE challenge</a>, in which participants had to detect calls from the North Atlantic Right Whale. To keep the tutorial simple, we will only use recording from a couple of days containing the characteristic <strong>upcall</strong>. The size of the database will also be modest. In practice you'll probably want to have more data available to train your classifiers/detectors. But the steps included here should give you a good understanding of the data preparation steps. We will even use a simple data augmentation techinique to increase the size of the training dataset.</p>
<p>Starting with the raw wavfiles and annotations, we will build a database of spectrograms that will be used to train a deep neural network capable of distinguishing upcalls from the background sounds. For our purposes, 'background' includes all sounds that are not upcalls, from other animal vocalizations to ambient noises produced by waves.</p>
<p>You can find the audio files and the annotations in the <code>data</code> folder within .zip file at the top of this page.</p>
<p>This is a common scenario: you have audio recordings and annotations indicating where in these recording the signals of interest are. However, if your data is not in the exact same format, we encourage you to explore the documentation, since Ketos has a variety of tools that won't be necessary in this tutorial.</p>
<p>This is a common scenario: you have audio recordings and annotations indicating where in these recording the signals of interest are. However, if your data is not in the exact same format, we encourage you to explore the <a href="https://docs.meridian.cs.dal.ca/ketos/modules/data_handling/index.html">documentation</a>, since Ketos has a variety of tools that won't be necessary in this tutorial.</p>
<h2 id="Contents:">Contents:<a class="anchor-link" href="#Contents:">&#182;</a></h2><p><a href="#section1">1. Importing the packages</a><br>
<a href="#section2">2. Loading the annotations</a><br>
<a href="#section3">3. Putting the annotations in the Ketos format</a><br>
......@@ -13105,14 +13105,14 @@ div#notebook {
<div class="cell border-box-sizing text_cell rendered"><div class="prompt input_prompt">
</div><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h3 id="1.-Importing-the-packages">1. Importing the packages<a class="anchor-link" href="#1.-Importing-the-packages">&#182;</a></h3><p>For this tutorial we will use several modules within ketos and also the pandas and pytables packages</p>
<h3 id="1.-Importing-the-packages">1. Importing the packages<a class="anchor-link" href="#1.-Importing-the-packages">&#182;</a></h3><p>For this tutorial we will use several modules within ketos and also the pandas package</p>
</div>
</div>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[3]:</div>
<div class="prompt input_prompt">In&nbsp;[2]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="kn">import</span> <span class="nn">pandas</span> <span class="k">as</span> <span class="nn">pd</span>
......@@ -13139,14 +13139,14 @@ div#notebook {
<div class="cell border-box-sizing text_cell rendered"><div class="prompt input_prompt">
</div><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h3 id="2.-Loading-the-annotations">2. Loading the annotations<a class="anchor-link" href="#2.-Loading-the-annotations">&#182;</a></h3><p>Our annotations are saved in two <em>.csv</em> files (separated by ';'): "annotations_train.csv" and "annotations_test.csv", which we will use to create the training and test datasets respectively.</p>
<h3 id="2.-Loading-the-annotations">2. Loading the annotations<a class="anchor-link" href="#2.-Loading-the-annotations">&#182;</a></h3><p>Our annotations are saved in two <em>.csv</em> files (separated by ';'): "annotations_train.csv" and "annotations_test.csv", which we will use to create the training and test datasets respectively. These files can also be found within the .zip file at the top of the page.</p>
</div>
</div>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[5]:</div>
<div class="prompt input_prompt">In&nbsp;[3]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">annot_train</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">read_csv</span><span class="p">(</span><span class="s2">&quot;annotations_train.csv&quot;</span><span class="p">)</span>
......@@ -13168,7 +13168,7 @@ div#notebook {
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[6]:</div>
<div class="prompt input_prompt">In&nbsp;[4]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">annot_train</span>
......@@ -13184,7 +13184,7 @@ div#notebook {
<div class="output_area">
<div class="prompt output_prompt">Out[6]:</div>
<div class="prompt output_prompt">Out[4]:</div>
......@@ -13779,7 +13779,7 @@ div#notebook {
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[7]:</div>
<div class="prompt input_prompt">In&nbsp;[5]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">annot_test</span>
......@@ -13795,7 +13795,7 @@ div#notebook {
<div class="output_area">
<div class="prompt output_prompt">Out[7]:</div>
<div class="prompt output_prompt">Out[5]:</div>
......@@ -14476,14 +14476,14 @@ The columns indicate:</p>
</div><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h3 id="3.-Putting-the-annotations-in-the-Ketos-format">3. Putting the annotations in the Ketos format<a class="anchor-link" href="#3.-Putting-the-annotations-in-the-Ketos-format">&#182;</a></h3><p>Let's check if our annotations follow the Ketos standard.</p>
<p>If that's the case, the function <code>sl.is_standardized</code> will return <code>False</code>.</p>
<p>If that's the case, the function <code>sl.is_standardized</code> will return <code>True</code>.</p>
</div>
</div>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[8]:</div>
<div class="prompt input_prompt">In&nbsp;[6]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">sl</span><span class="o">.</span><span class="n">is_standardized</span><span class="p">(</span><span class="n">annot_train</span><span class="p">)</span>
......@@ -14542,7 +14542,7 @@ The columns indicate:</p>
<div class="output_area">
<div class="prompt output_prompt">Out[8]:</div>
<div class="prompt output_prompt">Out[6]:</div>
......@@ -14567,11 +14567,10 @@ The columns indicate:</p>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[9]:</div>
<div class="prompt input_prompt">In&nbsp;[7]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="c1"># sl.is_standardized(annot_test, verbose=False)</span>
<span class="n">sl</span><span class="o">.</span><span class="n">is_standardized</span><span class="p">(</span><span class="n">annot_test</span><span class="p">)</span>
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">sl</span><span class="o">.</span><span class="n">is_standardized</span><span class="p">(</span><span class="n">annot_test</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
......@@ -14584,50 +14583,7 @@ The columns indicate:</p>
<div class="output_area">
<div class="prompt"></div>
<div class="output_subarea output_stream output_stdout output_text">
<pre> Your table is not in the Ketos format.
It should have two levels of indices: filename and annot_id.
It should also contain at least the &#39;label&#39; column.
If your annotations have time information, these should appear in the &#39;start&#39; and &#39;end&#39; columns
extra columns are allowed.
Here is a minimum example:
label
filename annot_id
file1.wav 0 2
1 1
2 2
file2.wav 0 2
1 2
2 1
And here is a table with time information and a few extra columns (&#39;min_freq&#39;, &#39;max_freq&#39; and &#39;file_time_stamp&#39;)
start end label min_freq max_freq file_time_stamp
filename annot_id
file1.wav 0 7.0 8.1 2 180.6 294.3 2019-02-24 13:15:00
1 8.5 12.5 1 174.2 258.7 2019-02-24 13:15:00
2 13.1 14.0 2 183.4 292.3 2019-02-24 13:15:00
file2.wav 0 2.2 3.1 2 148.8 286.6 2019-02-24 13:30:00
1 5.8 6.8 2 156.6 278.3 2019-02-24 13:30:00
2 9.0 13.0 1 178.2 304.5 2019-02-24 13:30:00
</pre>
</div>
</div>
<div class="output_area">
<div class="prompt output_prompt">Out[9]:</div>
<div class="prompt output_prompt">Out[7]:</div>
......@@ -14646,16 +14602,16 @@ The columns indicate:</p>
</div><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Neither of our annotations are in the format ketos expects. But we can use the <code>sl.standardize</code> function to convert to the specified format.</p>
<p>The <em>annot_id</em> column is created automatically by the <code>sl.standardize</code> function. From the remaining required columns infdicated in the example above, we already have <em>start</em>, <em>end</em> and <em>label</em>. Our <em>sound_file</em> column needs to be renamed to <em>filename</em>, so we will need to provide a dictionary to specify that.</p>
<p>We have one extra column, <em>datetime</em>, that we don't really need to keep, so we'll set <code>trim_table=False</code>, which will only include a the required columns in the standardized tables.</p>
<p>If we wanted to keep the datetime (or any other columns), we would just set <code>trim_table=True</code>. One situation in which you might to do that is you need this information to split a dataset in train/test or train/validation/test, because then you can sort all your annotations by time and make sure the training training set does not overlap with the validation/test. But in our case, the annotations are already split.</p>
<p>The <em>annot_id</em> column is created automatically by the <code>sl.standardize</code> function. From the remaining required columns indicated in the example above, we already have <em>start</em>, <em>end</em> and <em>label</em>. Our <em>sound_file</em> column needs to be renamed to <em>filename</em>, so we will need to provide a dictionary to specify that.</p>
<p>We have one extra column, <em>datetime</em>, that we don't really need to keep, so we'll set <code>trim_table=True</code>, which will discard any columns that are not required by the standardized.</p>
<p>If we wanted to keep the datetime (or any other columns), we would just set <code>trim_table=False</code>. One situation in which you might want to do that is if you need this information to split a dataset into train/test or train/validation/test, because then you can sort all your annotations by time and make sure the training set does not overlap with the validation/test. But in our case, the annotations are already split.</p>
</div>
</div>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[10]:</div>
<div class="prompt input_prompt">In&nbsp;[8]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">map_to_ketos_annot_std</span> <span class="o">=</span><span class="p">{</span><span class="s1">&#39;sound_file&#39;</span><span class="p">:</span> <span class="s1">&#39;filename&#39;</span><span class="p">}</span>
......@@ -14678,7 +14634,7 @@ The columns indicate:</p>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[11]:</div>
<div class="prompt input_prompt">In&nbsp;[9]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">std_annot_train</span>
......@@ -14694,7 +14650,7 @@ The columns indicate:</p>
<div class="output_area">
<div class="prompt output_prompt">Out[11]:</div>
<div class="prompt output_prompt">Out[9]:</div>
......@@ -15117,7 +15073,7 @@ The columns indicate:</p>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[12]:</div>
<div class="prompt input_prompt">In&nbsp;[10]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">std_annot_test</span>
......@@ -15133,7 +15089,7 @@ The columns indicate:</p>
<div class="output_area">
<div class="prompt output_prompt">Out[12]:</div>
<div class="prompt output_prompt">Out[10]:</div>
......@@ -15573,8 +15529,8 @@ The columns indicate:</p>
<div class="cell border-box-sizing text_cell rendered"><div class="prompt input_prompt">
</div><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h3 id="4.-Creating-segments-of-uniform-length">4. Creating segments of uniform length<a class="anchor-link" href="#4.-Creating-segments-of-uniform-length">&#182;</a></h3><p>If you look back at our <code>std_annot_train</code> and <code>std_annot_test</code> you'll notice that each annotation has a variable length, since they mark the beginning and end of an upcall and these have variable durations. For our purposes, we want each signal in the database to be represented as a spectrogram, all of same length. Each spectrogram will be labelled as containing an upcall or not.</p>
<p>The <code>sl.select</code> function in ketos can help us to do just that: for each annotated upcall, select a portion of the recording surrounding it. It takes a standard selections table as input and let's you specify the lenght of the oputput segments. We'll use 3 seconds, as it is enough to encompass most upcalls.</p>
<h3 id="4.-Creating-segments-of-uniform-length">4. Creating segments of uniform length<a class="anchor-link" href="#4.-Creating-segments-of-uniform-length">&#182;</a></h3><p>If you look back at our <code>std_annot_train</code> and <code>std_annot_test</code> you'll notice that annotations have a variety of lengths, since they mark the beginning and end of an upcall and these have variable durations. For our purposes, we want each signal in the database to be represented as spectrograms, all of same length. Each spectrogram will be labelled as containing an upcall or not.</p>
<p>The <code>sl.select</code> function in ketos can help us to do just that: for each annotated upcall, it'll select a portion of the recording surrounding it. It takes a standard selections table as input and lets you specify the length of the output segments. We'll use 3 seconds, as it is enough to encompass most upcalls.</p>
<p>Our standardized tables only contain annotated upcalls. Later we will also want some examples of segments that only contain background noise, but for now we'll just create the uniform upcall segments, which we'll call 'positives'</p>
</div>
......@@ -15582,7 +15538,7 @@ The columns indicate:</p>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[13]:</div>
<div class="prompt input_prompt">In&nbsp;[11]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">positives_train</span> <span class="o">=</span> <span class="n">sl</span><span class="o">.</span><span class="n">select</span><span class="p">(</span><span class="n">annotations</span><span class="o">=</span><span class="n">std_annot_train</span><span class="p">,</span> <span class="n">length</span><span class="o">=</span><span class="mf">3.0</span><span class="p">)</span>
......@@ -15604,7 +15560,7 @@ The columns indicate:</p>
</div>
<div class="cell border-box-sizing code_cell rendered">
<div class="input">
<div class="prompt input_prompt">In&nbsp;[14]:</div>
<div class="prompt input_prompt">In&nbsp;[12]:</div>
<div class="inner_cell">
<div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">positives_train</span>
......@@ -15620,7 +15576,7 @@ The columns indicate:</p>
<div class="output_area">
<div class="prompt output_prompt">Out[14]:</div>
<div class="prompt output_prompt">Out[12]:</div>
......@@ -15661,183 +15617,183 @@ The columns indicate:</p>
<th rowspan="23" valign="top">NOPP6_EST_20090328_000000.wav</th>
<th>0</th>
<td>1</td>
<td>188.062867</td>
<td>191.062867</td>
<td>188.505821</td>
<td>191.505821</td>
</tr>
<tr>
<th>1</th>
<td>1</td>
<td>235.429561</td>
<td>238.429561</td>
<td>235.144067</td>
<td>238.144067</td>
</tr>
<tr>
<th>2</th>
<td>1</td>
<td>398.488177</td>
<td>401.488177</td>
<td>397.974660</td>
<td>400.974660</td>
</tr>
<tr>
<th>3</th>
<td>1</td>
<td>437.644582</td>
<td>440.644582</td>
<td>438.595215</td>
<td>441.595215</td>
</tr>
<tr>
<th>4</th>
<td>1</td>
<td>450.173150</td>
<td>453.173150</td>
<td>450.735524</td>
<td>453.735524</td>
</tr>
<tr>
<th>5</th>
<td>1</td>
<td>565.379455</td>
<td>568.379455</td>
<td>563.750671</td>
<td>566.750671</td>
</tr>
<tr>
<th>6</th>
<td>1</td>
<td>566.279571</td>
<td>569.279571</td>
<td>566.312310</td>
<td>569.312310</td>
</tr>
<tr>
<th>7</th>
<td>1</td>
<td>546.700392</td>
<td>549.700392</td>
<td>545.640917</td>
<td>548.640917</td>
</tr>
<tr>
<th>8</th>
<td>1</td>
<td>548.531091</td>
<td>551.531091</td>
<td>548.141737</td>
<td>551.141737</td>
</tr>
<tr>
<th>9</th>
<td>1</td>
<td>631.100943</td>
<td>634.100943</td>
<td>631.700747</td>
<td>634.700747</td>
</tr>
<tr>
<th>10</th>
<td>1</td>
<td>636.360798</td>
<td>639.360798</td>
<td>636.133811</td>
<td>639.133811</td>
</tr>
<tr>
<th>11</th>
<td>1</td>
<td>641.046331</td>
<td>644.046331</td>
<td>641.762301</td>
<td>644.762301</td>
</tr>
<tr>
<th>12</th>
<td>1</td>
<td>644.778049</td>
<td>647.778049</td>
<td>645.843897</td>
<td>648.843897</td>
</tr>
<tr>
<th>13</th>
<td>1</td>
<td>653.908940</td>
<td>656.908940</td>
<td>652.702845</td>
<td>655.702845</td>
</tr>
<tr>
<th>14</th>
<td>1</td>
<td>672.536066</td>
<td>675.536066</td>
<td>671.911848</td>
<td>674.911848</td>
</tr>
<tr>
<th>15</th>
<td>1</td>
<td>712.403361</td>
<td>715.403361</td>
<td>710.777639</td>
<td>713.777639</td>
</tr>
<tr>
<th>16</th>
<td>1</td>
<td>733.922789</td>
<td>736.922789</td>
<td>733.780307</td>
<td>736.780307</td>
</tr>
<tr>
<th>17</th>
<td>1</td>
<td>711.573563</td>
<td>714.573563</td>
<td>710.129000</td>
<td>713.129000</td>
</tr>
<tr>
<th>18</th>
<td>1</td>
<td>748.483868</td>
<td>751.483868</td>
<td>749.550831</td>
<td>752.550831</td>
</tr>
<tr>
<th>19</th>
<td>1</td>
<td>783.739521</td>
<td>786.739521</td>
<td>784.049950</td>
<td>787.049950</td>
</tr>
<tr>
<th>20</th>
<td>1</td>
<td>857.367479</td>
<td>860.367479</td>
<td>857.816413</td>
<td>860.816413</td>
</tr>
<tr>
<th>21</th>
<td>1</td>
<td>889.871965</td>
<td>892.871965</td>
<td>889.790064</td>
<td>892.790064</td>
</tr>
<tr>
<th>22</th>
<td>1</td>
<td>893.806562</td>
<td>896.806562</td>
<td>894.392944</td>
<td>897.392944</td>
</tr>
<tr>
<th rowspan="7" valign="top">NOPP6_EST_20090328_001500.wav</th>
<th>0</th>
<td>1</td>
<td>37.147647</td>
<td>40.147647</td>
<td>37.238110</td>
<td>40.238110</td>
</tr>
<tr>
<th>1</th>
<td>1</td>
<td>113.635179</td>
<td>116.635179</td>
<td>113.564393</td>
<td>116.564393</td>
</tr>
<tr>
<th>2</th>
<td>1</td>
<td>161.870794</td>
<td>164.870794</td>
<td>161.681734</td>
<td>164.681734</td>
</tr>
<tr>
<th>3</th>
<td>1</td>
<td>261.354113</td>
<td>264.354113</td>
<td>261.538927</td>
<td>264.538927</td>
</tr>
<tr>
<th>4</th>
<td>1</td>
<td>269.736059</td>
<td>272.736059</td>
<td>270.663886</td>
<td>273.663886</td>
</tr>
<tr>
<th>5</th>
<td>1</td>
<td>324.046860</td>
<td>327.046860</td>
<td>324.158069</td>
<td>327.158069</td>
</tr>
<tr>
<th>6</th>
<td>1</td>
<td>334.809472</td>
<td>337.809472</td>
<td>333.854207</td>
<td>336.854207</td>
</tr>
<tr>
<th>...</th>
......@@ -15850,184 +15806,184 @@ The columns indicate:</p>
<th rowspan="11" valign="top">NOPP6_EST_20090329_024500.wav</th>
<th>19</th>
<td>1</td>
<td>583.912659</td>
<td>586.912659</td>
<td>583.597954</td>
<td>586.597954</td>
</tr>
<tr>
<th>20</th>
<td>1</td>
<td>589.160329</td>
<td>592.160329</td>
<td>587.881577</td>
<td>590.881577</td>
</tr>
<tr>
<th>21</th>
<td>1</td>
<td>596.811231</td>
<td>599.811231</td>
<td>597.919677</td>
<td>600.919677</td>
</tr>
<tr>
<th>22</th>
<td>1</td>
<td>612.150588</td>
<td>615.150588</td>
<td>612.647644</td>
<td>615.647644</td>
</tr>
<tr>
<th>23</th>
<td>1</td>
<td>618.591440</td>
<td>621.591440</td>
<td>618.666776</td>
<td>621.666776</td>
</tr>
<tr>
<th>24</th>
<td>1</td>
<td>635.883809</td>
<td>638.883809</td>
<td>636.216577</td>
<td>639.216577</td>
</tr>
<tr>
<th>25</th>
<td>1</td>
<td>670.897073</td>
<td>673.897073</td>
<td>670.453591</td>
<td>673.453591</td>
</tr>
<tr>
<th>26</th>
<td>1</td>
<td>684.913010</td>
<td>687.913010</td>
<td>684.232552</td>
<td>687.232552</td>
</tr>
<tr>
<th>27</th>
<td>1</td>
<td>678.820996</td>
<td>681.820996</td>
<td>678.577175</td>
<td>681.577175</td>
</tr>
<tr>
<th>28</th>
<td>1</td>
<td>806.351744</td>
<td>809.351744</td>
<td>805.907640</td>
<td>808.907640</td>
</tr>
<tr>
<th>29</th>
<td>1</td>
<td>844.598716</td>
<td>847.598716</td>
<td>844.114076</td>
<td>847.114076</td>
</tr>