Merge 6a8ac4e into ebeca08

README.md

@@ -16,8 +16,10 @@ waveform and are separated in time.
 
 The thunderfish package provides the following software:
 
-- *fishfinder*: View EOD recordings and detect fish and their EOD frequency on the fly.
+- *fishfinder*: Browse EOD recordings and detect EOD frequencyies on the fly.
 - *thunderfish*: Automatically detect and analyze all fish present in an EOD recording and generate a summary plot and data tables. [Read documentation](doc/thunderfish.md).
+- *collectfish*: Collect data generated by thunderfish. [Read documentation](doc/eodexplorer.md).
+- *eodexplorer*: View and explore properties of EOD waveforms. [Read documentation](doc/eodexplorer.md).
 
 
 ## Algorithms
@@ -29,21 +31,22 @@ Look into the modules for more information.
 
 - *configfile.py*: Configuration file with help texts for analysis parameter.
 - *consoleinput.py*: User input from console.
-- *dataloader.py*: Loading time-series data from files.
+- *dataloader.py*: Load time-series data from files.
 - *tabledata.py*: Read and write tables with a rich hierarchical header including units and formats.
 
 ### Basic data analysis
 
-- *eventdetection.py*: Detecting and handling peaks and troughs as well as threshold crossings in data arrays.
+- *eventdetection.py*: Detect and hande peaks and troughs as well as threshold crossings in data arrays.
 - *powerspectrum.py*: Compute and plot powerspectra and spectrograms for a given minimum frequency resolution.
-- *voronoi.py*: Analysis of Voronoi diagrams based on scipy.spatial.
+- *voronoi.py*: Analyse Voronoi diagrams based on scipy.spatial.
+- *multivariateexplorer.py*: Simple GUI for viewing and exploring multivariate data.
 
 ### EOD analysis
 
 - *bestwindow.py*: Select the region within a recording with the most stable signal of largest amplitude that is not clipped.
 - *checkpulse.py*: Check whether a pulse-type or a wave-type weakly electric fish is present in a recording.
 - *consistentfishes.py*: Create a list of EOD frequencies with fishes present in all provided fish lists.
-- *eodanalysis.py*: Analysis of EOD waveform properties.
+- *eodanalysis.py*: Analyse EOD waveforms.
 - *fakefish.py*: Generate artificial EOD waveforms.
-- *harmonicgroups.py*: Extracting harmonic groups from a power spectrum.
+- *harmonicgroups.py*: Extract harmonic groups from power spectra.
 

doc/collectfish.md

@@ -0,0 +1,53 @@
+# collectfish
+
+ Collect data generated by thunderfish in a wavefish and a pulsefish table.
+
+## Authors
+
+The [Neuroethology-lab](https://uni-tuebingen.de/en/faculties/faculty-of-science/departments/biology/institutes/neurobiology/lehrbereiche/neuroethology/) at the Institute of Neuroscience at the University of Tübingen:
+- Jan Benda
+- Jörg Henninger
+- Juan Sehuanes
+- Till Raab
+
+
+## Command line arguments
+
+```
+collectfish --help
+```
+returns
+```
+usage: collectfish [-h] [--version] [-t {wave,pulse}] [-a] [-c] [-m N]
+                   [-p N:M] [-w N] [-r COLUMN] [-s] [-n NAME] [-o PATH]
+                   [-f {dat,ascii,csv,rtai,md,tex,html,same}]
+                   file [file ...]
+
+Summarize data generated by thunderfish in a wavefish and a pulsefish table.
+
+positional arguments:
+  file                  a *-wavefish.* or *-pulsefish.* file as generated by
+                        thunderfish
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  -t {wave,pulse}       wave-type or pulse-type fish
+  -a                    append the file name as the last column
+  -c                    remove initial common directories from input files
+  -m N                  maximum number of fish to be taken from each recording
+  -p N:M                add properties of peak PN to PM of pulse-type EODs to
+                        the table
+  -w N                  add properties of first N harmonics of wave-type EODs
+                        to the table
+  -r COLUMN             columns to be removed from output table
+  -s                    also write table with statistics
+  -n NAME               name for summary files that is appended to "wavefish"
+                        or "pulsefish"
+  -o PATH               path where to store summary tables
+  -f {dat,ascii,csv,rtai,md,tex,html,same}
+                        file format used for saving summary tables ("same"
+                        uses same format as input files)
+
+version 1.7 by Benda-Lab (2019-2019)
+```

doc/eodexplorer.md

@@ -0,0 +1,80 @@
+# eodexplorer
+
+View and explore properties of EOD waveforms.
+
+## Authors
+
+The [Neuroethology-lab](https://uni-tuebingen.de/en/faculties/faculty-of-science/departments/biology/institutes/neurobiology/lehrbereiche/neuroethology/) at the Institute of Neuroscience at the University of Tübingen:
+- Jan Benda
+
+
+## Command line arguments
+
+```
+eodexplorer --help
+```
+returns
+```
+usage: eodexplorer [-h] [--version] [-l] [-j [JOBS]]
+                   [-D {all,allpower,noise,timing,ampl,relampl,power,relpower,phase,time,width,none}]
+                   [-d COLUMN] [-n MAX] [-w {first,second,ampl,power,phase}]
+                   [-s] [-c COLUMN] [-m CMAP] [-p PATH] [-P PATH]
+                   [-f {dat,ascii,csv,rtai,md,tex,html,same}]
+                   file
+
+View and explore properties of EOD waveforms.
+
+positional arguments:
+  file                  a wavefish.* or pulsefish.* summary file as generated
+                        by collectfish
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  -l                    list all available data columns and exit
+  -j [JOBS]             number of jobs run in parallel for loading waveform
+                        data. Without argument use all CPU cores.
+  -D {all,allpower,noise,timing,ampl,relampl,power,relpower,phase,time,width,none}
+                        default selection of data columns, check them with the
+                        -l option
+  -d COLUMN             data columns to be appended or removed (if already
+                        listed) for analysis
+  -n MAX                maximum number of harmonics or peaks to be used
+  -w {first,second,ampl,power,phase}
+                        add first or second derivative of EOD waveform, or
+                        relative amplitude, power, or phase to the plot of
+                        selected EODs.
+  -s                    save PCA components and exit
+  -c COLUMN             data column to be used for color code or "index"
+  -m CMAP               name of color map
+  -p PATH               path to the analyzed EOD waveform data
+  -P PATH               path to the raw EOD recordings
+  -f {dat,ascii,csv,rtai,md,tex,html,same}
+                        file format used for saving PCA data ("same" uses same
+                        format as input file)
+
+version 1.8 by Benda-Lab (2019-2019)
+
+mouse:
+left click              select data points
+left and drag           rectangular selection and zoom of data points
+shift + left click/drag add data points to selection
+ctrl + left click/drag  add/remove data points to/from selection
+
+key shortcuts:
+l                       list selected EOD waveforms on console
+p,P                     toggle between data columns, PC, and scaled PC axis
+<, pageup               decrease number of displayed data columns/PC axis
+>, pagedown             increase number of displayed data columns/PC axis
+w                       toggle maximized waveform plot
+o, z                    toggle zoom mode on or off
+backspace               zoom back
+ctrl + a                select all
++, -                    increase, decrease pick radius
+0                       reset pick radius
+n, N                    decrease, increase number of bins of histograms
+h                       toggle between scatter plot and 2D histogram
+c, C                    cycle color map trough data columns
+left, right, up, down   show and move magnified scatter plot
+escape                  close magnified scatter plot
+```