Commit def9139c authored by Oliver Kirsebom's avatar Oliver Kirsebom
Browse files

updated readme

parent 7d0ed465
Boat detector scripts for Urban Sharks project
# MERIDIAN Acoustic Boat Detector
Using the [Ketos](https://docs.meridian.cs.dal.ca/ketos/) package we have created a little command-line tool for processing hydrophone data and searching for the acoustic signature of motorized vessels. In other words, a boat detector!
# Installation
```terminal
pip install -r requirements.txt
python setup sdist
pip install dist/boat_detector-1.0.0.tar.gz
```
# Windows users
See [here](wikis/Step-by-step-guide-for-Windows-users)
\ No newline at end of file
See the [Step-by-step guide for Windows users](https://gitlab.meridian.cs.dal.ca/data_analytics_dal/projects/boat_detector/wikis/Step-by-step-guide-for-Windows-users).
# Usage example
To illustrate the usage of the boat detector, we have included an example data set, which
consists of 60 short audio recordings, each lasting no more than approximately 10 seconds.
The recordings were made in the span of 1 hour using a broadband hydrophone with a sampling
rate of 20 kHz. The hydrophone was deployed in a shallow bay that is busy with recreational
boating. The data were kindly shared with us by Mitchell Rider from the Rosenstiel School
of Marine & Atmospheric Science in the U.S. To save space the audio files have been
downsampled to 4 kHz. The start time of each audio file is encoded into the file name using
the format `HMS_%H_%M_%S__DMY_%d_%m_%y` where `%H` is the hour, `%M` is the minute, `%S`
is the second, `%d` is the day, `%m` is the month, and `%y` is the year.
The boat detection program has two steps, data pre-processing and signal detection:
## Step I: Pre-processing
Pre-process the audio files in the `assets/` directory with the command
```terminal
$ boat-preproc -c settings.json -i assets/ -v
```
This should produce the following output,
```terminal
Found 60 files
Processing batch #1 ...
Processing batch #2 ...
Processing batch #3 ...
Successfully processed 60 files
Processed data saved to: output.csv
Time table saved to: output_time_table.csv
Elapsed time: 00:00:07
```
## Step II: Detection
Search for acoustic signatures of boats in the preprocessed data
```terminal
$ boat-detect -c settings.json -i output.csv -S
```
This should produce the following output,
```terminal
7 boats detected
Detection report saved to: detections.csv
```
and this figure:
![](assets/boat_detections.png)
# Options
## Pre-processing script
```terminal
$ boat-preprocess -h
usage: boat-preprocess [-h] [-c CONFIG_FILE] [-i INPUT] [-o OUTPUT_FILE] [-r]
[-v]
Split audio signal into frequency bands and produce a time series of the noise
magnitude in each band.
optional arguments:
-h, --help show this help message and exit
-c CONFIG_FILE, --config_file CONFIG_FILE
path to json configuration file.
-i INPUT, --input INPUT
path to the wav file to be analyzed or directory
containing multiple wav files.
-o OUTPUT_FILE, --output_file OUTPUT_FILE
path to output csv file
-r, --recursive_search
Include subdirectories in search for wav files
-v, --verbose Print progress updates during processing
```
## Detection script
```terminal
$ boat-detect -h
usage: boat-detect [-h] [-c CONFIG_FILE] [-i INPUT_FILE] [-o OUTPUT_FILE] [-S]
Perform outlier- and peak analysis of time-series data.
optional arguments:
-h, --help show this help message and exit
-c CONFIG_FILE, --config_file CONFIG_FILE
path to json configuration file.
-i INPUT_FILE, --input_file INPUT_FILE
.csv file containing time-series data to be analyzed.
-o OUTPUT_FILE, --output_file OUTPUT_FILE
.csv file where analysis report will be outputted.
-S, --show_graph Show time-series data
```
# Configuration files
## Main configuration file (settings.json)
The main configuration file informs the program about 1) the date-time filename
labeling convetion, 2) the maximum amount of audio data to be processed in a single
batch, and 3) the path to the detector configuration file. In the example above:
```termina
$ more settings.json
{
"date_time_format": "HMS_%H_%M_%S__DMY_%d_%m_%y",
"batch_size": "5E6",
"detector": "detectors/fav.json"
}
```
## Detector configuration file
The
# A little background on the algorithms
"To detect the presence of a boat, we will exploit the fact that the frequency spectrum of a boat often contains several narrow peaks. These peaks occur at frequencies ranging from tens of Hz to several hundred Hz. Thus, our approach will be to compute the frequency spectrum of the audio data, search for narrow peaks, and report a boat detection if a few such peaks are found. We will use a search algorithm similar to the one described in [this paper](https://doi.org/10.1111/2041-210X.13245). Below, you see the spectrogram of a 10-second long audio recordering containing noise from a boat. Narrow peaks in the frequency spectrum are seen as sharp horizontal lines in the spectrogram, visible at about 20 Hz, 50 Hz, 95 Hz, and 145 Hz."
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment