Pipe operator

Description

See documentation of package magrittr for details.

Usage

lhs %>% rhs

Arguments

Shiny app to label recordings

Description

Shiny app to label recordings. Use this app to visualize your training recordings, create annotations and store them in a sqlite database. The app has a sidebar panel with the following buttons/boxes to input required user data:

1. Create database – if no database exists to store the annotations, use this button to create one

2. Choose database – choose the database to store the annotations

3. Butterworth filter – check box to apply filter and indicate low and high frequencies in kHz to filter the recordings

4. Time expanded – only used in recorders specifically intended for bat recordings. Can take any numeric value. If the recording is not time expanded the value must be set to 1. If it is time expanded the numeric value corresponding to the time expansion should be indicated

5. Choose folder – choose the folder containing the training recordings

After the spectrogram is ploted:

1. Select events by clicking in the spectrogram on the middle of the event of interest (bat call, bird song, etc)

2. Insert the correct label in the "Label" box and add any additional notes in the "Observations" box

3. Press 'Set labels' button to add labels to database

4. Repeat above steps if more than one set of events is present in the recording

5. Press 'Next' button to advance to next recording or pick another recording from the dropdown list

The spectrogram can be zoomed by pressing mouse button and dragging to select an area and then double click on it. To unzoom simply double clicking on the spectrogram without an area selected. To adjust visualization settings, in the top right, the tab "Spectrogram options" can be used to:

• Threshold – minimum intensity values to show in the spectrogram. A value of 100 will typically be adequate for the majority of the recorders

• Window length – moving window length in ms. Smaller windows best suited for short calls

• Overlap – overlap between consecutive windows, higher values give best visualization but lower performance

• Resolution – frequency resolution of the spectrogram

Usage

app_label()

Value

Starts the shiny app, no return value.

Author(s)

Bruno Silva

Shiny app to fit a model or run a fitted model

Description

Shiny app to fit a model from training recordings or to run a fitted model to classify new recordings. This app consists of three GUIs, i.e. three main panels, accessible by the tabs at the top:

1. Create train data – create train data from recordings and their respective annotations database

2. Fit model – fit a model from training data

3. Run model – run a fitted model to classify new recordings

1. Create train data

This panel is used to create train data from recordings and their respective annotations database. The sidebar panel has the following buttons/boxes to input required user data:

• Choose folder – choose the folder containing the training recordings

• Choose database – choose the database with the annotations for the training recordings

• Time expanded – choose the correct time expansion factor, normally only used in recorders specifically intended for bat recordings. Can take the values "auto", 1 or 10. If the recording is in real time the value must be 1. If it's time expanded, the value 10 or "auto" can be selected. If "auto" is selected it is assumed that sampling rates < 50kHz corresponds to a value of 10 and sampling rates > 50kHz to corresponds to a value of 1

• Spectrogram parameters – different typologies of sound events require different parameters for computing the spectrograms. The more relevant are: size (in ms), which should be large enough to encompass the duration of the largest sound event in analysis (not only in the training data but also in novel recordings where the classifiers are to be applied) and moving window (in ms), that should be smaller for shorter sound events (to capture the quick changes in time) and larger for longer sound events (to avoid redundant information). The other parameters are more generalist and the same values can be used for different sound events, as they only change the definition of the images created. Please refer to spectro_calls documentation for further details

After entering the required information press the button "Create training data from labels" to generate the training data that will be used for fitting a model. This object is saved in the folder containing the training recordings with the name "train_data.RDATA".

2. Fit model

This panel is used to fit a model from training data. The sidebar panel has the following buttons/boxes to input required user data:

• Choose train data – the file "train_data.RDATA" created in the previous panel

• Choose model – a blank model to be fitted. A custom model is provided but must be copied to an external folder if it is to be used. The model path can be obtained by running the following line at the R console: system.file("model_architectures", "model_vgg_sequential.R", package="soundClass") and should be manually copied to a an external folder

• Model parameters – the train percentage indicates the percentage of data that is used to fit the model while the remaining are used for validation, batch size indicates the number of samples per gradient update, the learning rate indicates the degree of the gradient update, early stop indicates the maximum number of epochs without improvement allowed before training stops and epochs indicate the maximum number of epochs to train. Further information can be found in keras documentation https://keras.io/api/

The model is evaluated during fitting using the validation data. After completion, by reaching the maximum epochs or the early stopping parameters, the fitted model, the fitting log and the model metadata are saved to the folder containing the train data with file names: "fitted_model.hdf5", "fitted_model_log.csv" and "fitted_model_metadata.RDATA" respectively.

3. Run model

This panel is used to run a fitted model to classify new recordings. The sidebar panel has the following buttons/boxes to input required user data:

• Choose folder – choose the folder containing the recordings to be classified

• Choose model – a fitted model to be used for classification

• Choose metadata – the file containing the fitted model metadata

• Time expanded – choose the correct time expansion factor, normally only used in recorders specifically intended for bat recordings. Can take the values "auto", 1 or 10. If the recording is not time expanded the value must be 1. If it's time expanded, the value 10 or "auto" can be selected. If "auto" is selected it is assumed that sampling rates < 50kHz corresponds to a value of 10 and sampling rates > 50kHz to corresponds to a value of 1

• Output file – the name of the files to store the results of the classification

• Irrelevant – does the fitted model includes an irrelevant class?

• Export plots – should a spectrogram of the classified recordings be saved to disk?

The classification results are stored in a folder called "output", created inside the folder containing the recordings. They are stored in a database in sqlite3 format with all the relevant events detected and the respective probability of belonging to a given class. Additionally a file in the csv format is saved to disk, containing summary statistics per recording, i.e. the class with most events detected in each particular recording and the average frequency of maximum energy of the events detected.

Usage

app_model()

Value

Starts the shiny app, no return value.

Author(s)

Bruno Silva

Automatic classification of sound events in recordings

Description

Run automatic classification of sound events on a set of recordings using a fitted model.

Usage

auto_id(model_path, update_progress = NA, metadata,
file_path, out_file, out_dir, save_png = TRUE, win_size = 50,
plot2console = FALSE, remove_noise = TRUE, recursive = FALSE, tx = 1)

Arguments

Details

Runs a classification task on the recordings of a specified folder and saves the results of the analysis.

Value

Nothing.

Author(s)

Bruno Silva

Apply a butterworth filter to sound samples

Description

Apply a butterworth filter, high pass or/and low pass, to sound samples. Based on the function butter

Usage

butter_filter(sound_samples, low = NA, high = NA, fs, tx, order = 10)

Arguments

Details

Butterworth filter

Value

A vector with the filtered sound samples

Author(s)

Bruno Silva

Create a sqlite3 database

Description

Create a sqlite3 database (if a database with the specified name doesn't exist already) with predefined tables. Two types of databases are possible, one to store recordings annotations and another to store the output of the classification.

Usage

create_db(path, db_name = NA, table_name = "labels",
type = "reference")

Arguments

Value

Nothing

Author(s)

Bruno Silva

Examples

## Not run: 
dir_path <- tempdir()
create_db(dir_path,
db_name = "test",
table_name = "labels",
type = "reference")
file.remove(file.path(dir_path, "test.sqlite3"))

## End(Not run)

Detect energy peaks in recordings with non-relevant events

Description

Detects the temporal position of the desired number of energy peaks in a recording exclusively with non-relevant events.

Usage

find_noise(recording, nmax = 1, plot = FALSE)

Arguments

Value

A vector with the temporal position of the identified peak(s), in samples.

Author(s)

Bruno Silva

Examples

# Create a sample wav file in a temporary directory
recording <- tuneR::noise(duration = 44100)
temp_dir <- tempdir()
rec_path <- file.path(temp_dir, "recording.wav")
tuneR::writeWave(recording, filename = rec_path)
# Import the sample wav file
new_rec <- import_audio(rec_path, butt = FALSE, tx = 1)
find_noise(new_rec, nmax = 1, plot = FALSE)
file.remove(rec_path)

Import a recording

Description

Import a "wav" recording. If the recording is stereo it is converted to mono by keeping the channel with overall higher amplitude

Usage

import_audio(path, butt = TRUE, low, high, tx = 1)

Arguments

Value

An object of class "rc". This object is a list with the following components:

• sound_samples – sound samples of the recording

• file_name – name of the recording

• file_time – time of modification of the file (indicated for Pettersson Elektronic detectors, for other manufactures creation time should be preferable but it's not implemented yet)

• fs – sample frequency

• tx – expanded time factor

Author(s)

Bruno Silva

Examples

# Create a sample wav file in a temporary directory
recording <- tuneR::sine(440)
temp_dir <- tempdir()
rec_path <- file.path(temp_dir, "recording.wav")
tuneR::writeWave(recording, filename = rec_path)
# Import the sample wav file
new_rec <- import_audio(rec_path, low = 1, high = 20, tx = 1)
new_rec
file.remove(rec_path)

Convert between time and number of samples in sound files

Description

Convert time to number of samples or vice versa in sound files.

Usage

ms2samples(value, fs = 300000, tx = 1, inv = FALSE)

Arguments

Value

Integer. If inv = TRUE returns number of samples, if inv = FALSE returns time in ms.

Author(s)

Bruno Silva

Examples

ms2samples(150000, fs = 300000, tx = 1, inv = FALSE)
ms2samples(100, fs = 300000, tx = 1, inv = TRUE)

Generate spectrograms from labels

Description

Generate spectrograms from recording labels for classification purposes. The spectrogram parameters are user defined and should be selected depending on the type of sound event to classify.

Usage

spectro_calls(files_path, update_progress = NA,
db_path, spec_size = NA, window_length = NA,
frequency_resolution = 1, overlap = NA,
dynamic_range = NA, freq_range = NA, tx = 1, seed = 1002)

Arguments

Value

A list with the following components:

• data_x – an array with the spectrogram matrices

• data_y – the labels for each matrix in one-hot-encoded format

• parameters – the parameters used to create the matrices

• labels_df – the labels with their respective numeric index

Author(s)

Bruno Silva

Obtain train metadata to run a fitted model

Description

Obtain train metadata from the output of function spectro_calls. Needed to run a fitted model

Usage

train_metadata(train_data)

Arguments

Value

A list with the following components:

• parameters – parameters of the spectrograms

• classes – class names and respective codes

Author(s)

Bruno Silva