LICENSE under LGPL 3.0. Some minor documentation cleanup.

README.md

@@ -21,13 +21,13 @@ We record the bird, and create a bunch of audio files that contain vocalisations
 
   2. Add to your MATLAB path
 
-  3. Learn how to use it
+  3. Learn how to use it. The procedure is somewhat automated in `timewarp_process_directory', which you probably should read through and then use. Here's what it does:
 
-    1. Create a song template, perhaps using `make_template`
+    1. Create a song template using `make_template`
 
     2. Run `threshold_for_find_audio` to get a threshold
 
-    3. Run `process_directory(template, threshold)
+    3. Run find_audio on each audio file in the directory.
 
   4. This will spit out a `song.mat` file as required below.
 
@@ -42,13 +42,15 @@ When `learn_detector` is run, it performs all operations in the current director
   * `nonsong`: an MxP array of doubles, with M samples per song (same M as above) and P segments of non-song (silence, cage noise, white noise, etc).  Alignment here is irrelevant.
   * `fs`: the sampling frequency in Hz
 
-Run `learn_detector`.  It will open `./song.mat`.  If you have not completed the next step (below), it should think for a while, pop up an aggregate spectrogram of all your aligned songs, and then stop (with a harmless error message), telling you to complete the next step:
+Run `learn_detector`.  It will open `./song.mat`.  If you have not completed the next step (below), it should think for a while, pop up an aggregate spectrogram of all your aligned songs, and then stop after telling you to complete the next step:
 
 Create a MATLAB script file (`params.m`, also in the current directory, containing configuration and training parameters:
   * If it doesn't exist, or is empty, `learn_detector` will pop up the spectrograms and then stop.
     * Add the line "times_of_interest_ms = [x y z ...]" for trigger times at x, y, and z (etc) milliseconds.  You need at least one time _x_.
   * `params.m` can also override any of the other parameters whose defaults are in the Configuration section at the top of `learn_detector.m`.
 
-Run `learn_detector` again.  It will produce two files:
+Alternatively, you can pass parameters to the learner in the standard MATLAB manner, such as (for example) `learn_detector('times_of_interest_ms', [137 291], 'nruns', 20, 'time_window_ms', 80)'.
+
+When `learn_detector` is run with `times_of_interest_ms` defined.  It will produce two files:
 * `detector_<times_of_interest>_<other information>.mat`, the network file.
 * `songs_<nsongs>_<times_of_interest_1>.wav`, an audio test file containing all the provided songs in the left channel and short pulses on the right channel at `times_of_interest(1)` for each provided song.  This may be used for testing the realtime detector.

create_training_set.m

@@ -1,6 +1,24 @@
 % Create the training set. But that is actually a bit of a misnomer: it takes all songs and nonsongs and aligns the relevant bits
 % of their spectrograms with the correct Y training value. Training and testing will then use disjoint subsets of nnset[XY].
 
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
+
 function [ nnsetX nnsetY ] = create_training_set(spectrograms, ...
     tsteps_of_interest, ...
     target_offsets, ...

get_target_offsets.m

@@ -1,5 +1,23 @@
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 function [ target_offsets ] = get_target_offsets(MIC_DATA, times_of_interest, fs, timestep_length_ds, canonical_songs);
 
+
 % How big a window is 20ms?
 window_halfsize = floor(0.03 * fs);
 

get_target_offsets_jeff.m

@@ -49,4 +49,4 @@
 sample_offsets = sample_offsets - sample_of_interest;
 target_offsets = round( (  ( sample_offsets ) / fs ) / timestep_length_ds );
 %target_offsets = round( (  ( sample_offsets - sample_of_interest  ) / fs ) / timestep_length_ds );
-%a(0)
+%a(0)

learn_detector.m

@@ -1,35 +1,38 @@
-function learn_detector(varargin)
-%    learn_detector: train a neural network to detect zebra finch syllables.
+% learn_detector: train a neural network to detect zebra finch syllables.
 %
 %        Requires data in (by default) 'song.mat', and training configuration
 %        in 'params.m' and/or parameters given as 
 %        learn_detector('parameter', value) pairs. See README.md for
 %        instructions.
 %
-%    Copyright (C) 2017  Ben Pearre
-
-%    This program is free software: you can redistribute it and/or modify
-%    it under the terms of the GNU General Public License as published by
-%    the Free Software Foundation, either version 3 of the License, or
-%    (at your option) any later version.
-
-%    This program is distributed in the hope that it will be useful,
-%    but WITHOUT ANY WARRANTY; without even the implied warranty of
-%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-%    GNU General Public License for more details.
-
-%    You should have received a copy of the GNU General Public License
-%    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 
+function learn_detector(varargin)
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%% Configuration %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 %% These are defaults.  If you want to change them, do so in params.m
-times_of_interest_ms = NaN;                      % Milliseconds at which to trigger. Exists here just to define it as valid.
+times_of_interest_ms = NaN;                      % Milliseconds at which to trigger. Exists here just to define it as a valid parameter.
 nhidden_per_output = 4;                          % How many hidden units per syllable?  2 works and trains fast.  4 works ~20% better...
-fft_time_shift_seconds_target = 0.0015;          % FFT frame rate (seconds).  Paper mostly used 0.0015 s: great for timing, but slow to train
+fft_time_shift_seconds_target = 0.0015;          % FFT frame rate (seconds).  Paper mostly used 0.0015 s: great for timing, but slow to train.
 use_jeff_realignment_train = false;              % Micro-realign at each detection point using Jeff's time-domain code?  Don't do this.
 use_jeff_realignment_test = false;               % Micro-realign test data only at each detection point using Jeff's time-domain code.  Nah.
 use_nn_realignment_test = false;                 % Try using the trained network to realign test songs (reduce jitter?)
@@ -42,9 +45,9 @@ function learn_detector(varargin)
 use_pattern_net = false;                         % Use MATLAB's pattern net (fine, but no control over false-pos vs false-neg cost)
 do_not_randomise = false;                        % Use songs in original order?
 separate_network_for_each_syllable = true;       % Train a separate network for each time of interest?  Or one network with multiple outs?
-nruns = 1;                                       % Perform a few training runs and create beeswarm plot (paper figure 3 used 100)?
-freq_range = [1000 8000];                        % Frequencies of the song to examine
-time_window_ms = 50;                             % How many seconds long is the detection sliding-time-window?
+nruns = 1;                                       % Perform a few training runs and create beeswarm plot? (paper figure 3 used 100)
+freq_range = [1000 8000];                        % Frequencies of the song to examine.
+time_window_ms = 50;                             % How many seconds long is the detection sliding-time-window? Useful range is about 30-100.
 false_positive_cost = 1;                         % Cost of false positives is relative to that of false negatives.
 create_song_test_file = -1;                      % Big, and take some time to save.  1: always, 0: never, -1: only if nruns == 1
 song_crop_region = [-Inf Inf];                   % Crop the ends off the aligned song (milliseconds).  [] or [-Inf Inf] for no crop.  YOU MAY (OR MAY NOT?) WANT TO ADJUST TIMES OF INTEREST: times_of_interest_ms = [ 550 660 ] - song_crop_region(1)

load_params.m

@@ -1,5 +1,23 @@
 % Place all params from the param file into an output struct. This lets us make sure they're all valid before importing them into
 % the real workspace.
+
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 function [ p ] = load_params(params_file);
 
     if ~exist(strcat(params_file, '.m'), 'file')

load_roboaggregate_file.m

@@ -1,6 +1,23 @@
 % Load data from an aggregate file (song.mat). Loads all the song data, and then only as much nonsong as is needed for the
 % specified nonsinging_fraction.
 
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 function [ mic_data, spectrograms, nsamples_per_song, nmatchingsongs, nsongsandnonsongs, nonsinging_fraction, timestamps, nfreqs, freqs, ntimes, times, fft_time_shift_seconds, spectrogram_avg_img, power_img, freq_range_ds, time_window_steps, layer0sz, nwindows_per_song, noverlap] ...
     = load_roboaggregate_file(data_file, ...
     fft_time_shift_seconds_target, ...

optimise_network_output_unit_trigger_thresholds.m

@@ -1,3 +1,23 @@
+% Search for optimal thresholds given false-positive vs
+% false-negagive weights (the latter := 1).
+
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 function [ optimal_thresholds optimal_thresholds_c ] = optimise_network_output_unit_trigger_thresholds(...
         testout, ...
         nwindows_per_song, ...
@@ -10,8 +30,6 @@
         songs_with_hits, ...
         midpoint);
 
-% Search for optimal thresholds given false-positive vs
-% false-negagive weights (the latter := 1).
 
 % The onset has to be no more than ACTIVE_TIME_BEFORE before the baseline
 % training signal. 

replot_accuracies_concatanated.m

@@ -1,13 +1,32 @@
 %% Plot the figure of errors for all networks over all trials...
+% The input file is created in show_confusion.m.  No effort is made to
+% ensure that it doesn't contain values for different configurations,
+% or even different-sized columns! So if you want to use it, best make
+% sure you start by deleting the previous confusion_log_perf.txt.  Keep
+% it in order to allow restart of partially completed jobs, since 10
+% syllables, 100 runs, 3000 training songs, convolutional networks,
+% etc., can take a long time to complete.
+
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
+
 function [] = replot_accuracies_concatanated(varargin)
 
-    % The input file is created in show_confusion.m.  No effort is made to
-    % ensure that it doesn't contain values for different configurations,
-    % or even different-sized columns! So if you want to use it, best make
-    % sure you start by deleting the previous confusion_log_perf.txt.  Keep
-    % it in order to allow restart of partially completed jobs, since 10
-    % syllables, 100 runs, 3000 training songs, convolutional networks,
-    % etc., can take a long time to complete.
 
     real_bird_names = NaN;
     real_times = false;

show_confusion.m

@@ -1,3 +1,20 @@
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 function [ ] = show_confusion(...
         testout, ...
         nwindows_per_song, ...

suggest_moments_of_interest.m

@@ -1,3 +1,20 @@
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 function [ tstep_of_interest ] = suggest_moments_of_interest(ntsteps, ...
                                              spectrogram_avg_img, ...
                                              time_window_steps, ...

trigger.m

@@ -1,3 +1,20 @@
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 function [ trigger_now ] = trigger(responses, threshold, schmidt_trigger_down, timestep);
 
 % De-bounce the signal

trigger_all.m

@@ -1,3 +1,20 @@
+% Copyright (C) 2017  Ben Pearre
+%
+% This file is part of the Zebra Finch Syllable Detector, syllable-detector-learn.
+% 
+% The Zebra Finch Syllable Detector is free software: you can redistribute it and/or
+% modify it under the terms of the GNU Lesser General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or (at your option)
+% any later version.
+% 
+% The Zebra Finch Syllable Detector is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
+% more details.
+% 
+% You should have received a copy of the GNU Lesser General Public License
+% along with the Zebra Finch Syllable Detector.  If not, see
+% <http://www.gnu.org/licenses/>.
 function [ trigger_now ] = trigger(responses, threshold, schmidt_trigger_down, timestep);
 
 % De-bounce the signal