Scikit-maad

New examples
--------
- add a new example to use multiCPU functionality to compute indices

New functionalities
-------------------
**In module util :**

Audio metadata utilities with new functions :
- check_file_format : Check Wave file consistency. Check if WAVE format is correct and if file name follows standard format. The standard format is SITENAME_DATE_TIME.WAV, with DATE as YYYYMMDD and TIME as HHMMSS
- audio_header : Get audio header information from WAVE file. Header information includes, sample rate, bit depth, number of channels, number of samples, file size and duration.
- filename_info : Get information from filename when using standard format. The standard format is SITENAME_DATE_TIME.WAV, with DATE as YYYYMMDD and TIME as HHMMSS.
- get_metadata_file : Get metadata asociated with audio recordings in audio file. Metadata includes basic information of the audio file format (sample rate, number of channels, bit depth and file size), and date information from the filename. Note however, that this function is intended for use only with audio files with a self-describing header.
- get_metadata_dir : Get metadata asociated with audio recordings in a directory. Metadata includes basic information of the audio file format (sample rate, number of channels, bit depth and file size), and date information from the filename. Note however, that this function is intended for use only with audio files with a self-describing header.

Parser
- read_raven_annot : Read raven annotations file (or labeling file) and return a Pandas Dataframe with the bounding box and the label of each region of interest (ROI). If the file exists but has no annotations, the function returns and empty dataframe.
- write_raven_annot : Write audio segmentation to text file in Audacity format, a file that can be imported and modified with Audacity. If the dataframe has no frequency delimiters, annotations are saved with standard Audacity format (temporal segmentation). If the dataframe has temporal and frequencial delimiters, the annotations are saved as spectral selection style (spectro-temporal selection). If the dataframe is empty, the function saves an empty file.

**In module sound :**

Transform the signal
- gain : Apply amplification or attenuation to the audio signal.

Minor changes
-------------------
- fix a bug in format_features
- add an argument in rand_cmap to change the seed
- fix a bug in entropy (when only zeros, entropy is 1)
- fix a bug in ADI and AEI calculation. The result is now similar to soundecology R package (see more details here :[https://github.com/scikit-maad/scikit-maad/issues/43]).
- add an optional argument to spectrogram to allow detrend to be off. This is interesting only when computing ADI and AEI
- update xeno-canto functions in order to be compliant with the new API.
- add an argument to overlay_rois in order to adapt the edge_color to the number of unique labels
- add warning in region_of_interest_index. default parameters are deprecated
- add new argument max_ratio_xy in region_of_interest_index. it defines the maximum ratio between the vertical axis (y) and horizontal axis (x) that is allowed for a ROI. This is very convenient to remove vertical spikes (e.g. rain). 10 seems a reasonable value to remove most of spikes due to light to medium rainfall.

This release contains new functions and new functionalities for some functions :

List of new functions :
- in the module sound :
> normalize : Normalize audio signal to desired amplitude or decibell full scale value (dBFS).
> trim : Slices a time series, from a initial time `min_t` to an ending time `max_t`.
- in the module util : xeno-canto scraper
> xc_query : Collect metadata from xeno-canto depending on the search terms and store them in a dataframe
> xc_multi_query : Performs multiple queries to xeno-canto
> xc_selection : Select a maximum number of recordings depending on their quality and duration in order to create a homogeneous dataset
> xc_download : Download audio files from xeno-canto. It will create directories for each species if needed
- in the module spl : active or detection distance estimation
> attenuation_dB : Compute the attenuation in decibels taking into account the geometric, atmospheric and habitat attenuation contributions.
> dBSPL_per_bin : Function to spread the sound pressure level (Energy in dB) along a frequency vector (bins).
> detection_distance : Compute the detection distance also known as detection range or detection radius or active space.
> pressure_at_r0 : Estimate the pressure p0 at distance r0 from pressure p measured at distance r. This function takes into account the geometric, atmospheric and habitat attenuations.
> dBSPL_at_r0 : Estimate the sound pressure level L0 (dB SPL) at distance r0 from sound pressure level L measured at distance r. This function takes into account the geometric, atmospheric and habitat attenuations.
> apply_attenuation : Apply attenuation of a temporal signal p0 after propagation between the reference distance r0 and the final distance r taken into account the geometric, atmospheric and habitat attenuation contributions.

List of functions with new functionalities :
- in module util :
> we modified the function overlay_rois in order to add the possibility to display the bounding box with text label
> we modified the function read_audacity_annot in order to be able to extract 2D annotations (time-frequency segmentation) as well as 1D annotations (only time segmentation).
- in module features :
> Change in acoustic_eveness_index and acoustic_diversity_index in order to be compliant with R package Soundecology
- in module rois :
> we added functionalities to find_rois_cwt and to plot_shape

List of new examples :
> plot_wookpecker_drumming_characteristics.py : download audio files from Xeno-Canto and automatically extract characteristics
> plot_xenocanto_wookpecker_activities.py : download metadata from Xeno-Canto to infer species activities
> plot_sound_degradation_due_to_attenuation.py : simulation of sound degradation due to geometric, atmospheric and habitat attenuation

And the documentation is still here : [scikit-maad.github.io/](https://scikit-maad.github.io/)

This release contains all the functions that are described in the paper that was submitted in April 2021 to the journal Methods in Ecology and Evolution.

Contents : modules
. sound : The module sound is an ensemble of functions to load and preprocess audio signals.
. rois : The module rois has a collection of functions to segment and find regions of interest in audio and spectrograms.
. features : The module features is an ensemble of functions to characterize audio signals using temporal and spectral features, and ecoacoustic indices.
. spl : The module spl is a collection of functions used to describe the physics of acoustic waves.
. utils: The module utils has a handfull of useful set of tools used in the audio analysis framework (parser, plot, math, conversion...)

Documentation is here : https://scikit-maad.github.io/

Last release of the first version of Scikit-MAAD that was released for the first time in 2018.
This release is ready for production but it's better to wait for the next version of Scikit-MAAD that will be soon available (January 2021)

Contents : subpackages
- sound : functions to load, process and transform an audio into a spectrogram
- rois : functions to segment regions of interest (ROI)
- features : functions to extract shape features and centroids corresponding to the ROIs
- ecoacoustics : functions to compute ecoacoustics indices
- cluster : do_PCA and hdda functions. (will be deprecated for v2)
- util : bunch of functions