# p_discolor_auditory_feedback

Acoustic parameters of P. discolor vocalisations, auditory brainstem
responses, and data analysis programs for Lattenkamp et al., “Learning
how to call: the vocal development of the pale spear-nosed bat is
dependent on auditory feedback”.

## Vocalisations

The `vocalisations` directory provides data in four CSV files:

* `pup_calls.csv`, `adult_calls.csv`: Acoustic call parameters of the
  vocalisations recorded from six bats, three of which were deafened
  after the first recording session.  In `pup_calls.csv`, these bats
  were up to half a year old; in `adult_calls.csv`, the same individuals
  were 2 years old.  The juvenile recordings were acquired with pairs of
  bats: (deafened or normal-hearing) juveniles and their (always
  normal-hearing) respective mothers, as well as with pairs of one
  deafened and one normal-hearing juvenile.  The adult recordings were
  acquired from groups of two or three bats such that within each
  recording session, all were either deafened or of normal hearing.

  `pup_calls.csv` includes the vocalisations from the juvenile bats’
  respective mothers which were placed in the recording chamber with
  their offspring in some of the sessions.  These data have not been
  analysed further by the authors.

* `pup_sessions.csv`, `adult_sessions.csv`: Metadata for the recording
  sessions.

### Acoustic call parameters

Each row of `*_calls.csv` corresponds to one extracted vocalisation from
one bat.  The columns are:

* `session_id`: ID of the recording session in which this vocalisation
  occurred, for lookup in the corresponding `*_sessions.csv` file.
* `call_id`: Sequence number of the vocalisation within the recording
  session.  The pairs (`session_id`, `call_id`) are unique within each
  CSV file.
* `start_sample`: Sample index in the microphone buffer where the
  extracted vocalisation started.
* `start_time`: Absolute time in Central European (Summer) Time at which
  the extracted vocalisation started. Can be calculated from
  `start_sample` and the metadata in `*_sessions.csv`, based on the
  sampling rate of 192 kHz.
* `calling_bat` (`pup_calls.csv`): Identifier of the animal which
  emitted the vocalisation.  This can be determined by comparing levels
  in the microphone array in the recording chamber, as the position of
  the bats within the chamber was known and fixed.  This column is empty
  in `adult_calls.csv`, where the recording setup did not facilitate
  this analysis.
* `other_bat` (`pup_calls.csv`): Identifier of the animal which was in
  the recording chamber with the calling bat, but did not emit the
  vocalisation.  Empty in `adult_calls.csv`, where this information is
  unknown.
* `calling_bat_deaf`: 1 if the calling bat was deafened, 0 otherwise.
  Note that in `pup_calls.csv`, the first session of each
  juvenile–mother pairing was recorded before deafening, yet
  `calling_bat_deaf` is 1 even in those sessions.
* `before_deafening`: 1 if this vocalisation occurred in the first
  session of a juvenile (before any deafening), 0 otherwise.
* `calling_bat_mother`: 1 if the calling bat was a mother, 0 otherwise.
* `level_difference` (`pup_calls.csv`; in dB): Difference between the
  root-mean-square vocalisation levels of the microphones closer to one
  bat vs. the microphones closer to the other bat.  Used to determine
  `calling_bat` and `other_bat` in sessions with juveniles.
* `call_rms` (in dB): Root-mean-square sound pressure of the
  vocalisation at the microphone were it was loudest, relative to an
  arbitrary reference which was constant across sessions in
  `pup_calls.csv` and `adult_calls.csv`, but not the same in both.
* `call_duration` (in s): Duration of the vocalisation.
* `mean_aperiodicity`: Aperiodicity value extracted with the YIN
  algorithm for fundamental frequency estimation.
* `f0_mean`, `f0_min`, `f0_max`, `f0_start`, `f0_end`, `f0_slope` (in
  Hz): Mean, minimum, maximum, initial and final fundamental frequencies
  of the vocalisation, respectively, as estimated with the YIN
  algorithm.
* `spectral_centroid` (in Hz): The center of mass of the frequency
  spectrum of the vocalisation.

### Session files

`pup_sessions.csv` contains the session IDs (`session_id`), start times
in Central European (Summer) Time (`start_time`), the IDs of the two
individuals which were placed in the recording chamber together in each
session (`animal1` and `animal2`), and `before_deafening` indicating
whether a recording was the first of a juvenile.  `adult_sessions.csv`
is structured similarly, but replaces the two `animalX` columns with
`group`, which is either `deaf` or `hearing`, and does not contain
`before_deafening`.

### Animals

The individuals referred to in the data files were:

* `b2`, born on 2017/01/26, never deafened.
* `b3`, born on 2017/01/29, deafened after the first recording session.
* `b4`, born on 2017/01/30, never deafened.
* `b5`, born on 2017/02/02, deafened after the first recording session.
* `b7`, born on 2017/02/08, never deafened.
* `b8`, born on 2017/02/08, deafened after the first recording session.
* `mh`, `mt`, `mb`, `my` and `mp`, the mothers of these six bats.

### Scripts

`scripts` contains the Jupyter notebook which was used to create the
figures and tables included in the publication.

`scripts_for_reference` is of documentary nature and contains the MATLAB
and Python code which was used to extract the acoustic parameters and
generate the CSV files from the raw microphone data (which is not
included in this repository for reasons of space).  The YIN
implementation used by some of the MATLAB scripts is available from
http://audition.ens.fr/adc/sw/yin.zip (de Cheveigné & Kawahara, JASA
111:1917:1930, 2002, doi:10.1121/1.1458024).

## Auditory brainstem responses

The `abr_analysis_results.mat` file in the `ABR` directory is a MATLAB
data file with three variables:

* `dates`: Recording dates of each ABR measurement sessions, formatted
  as YYYYMMDD strings.
* `bats`: Identity of the animal in each ABR measurement session.  Note
  that the first (earliest) recording for each bat was acquired before
  any deafening.
* `allCONFI`: A structure array, indexed on ABR measurement session
  number and containing three matrices, namely
  - `frequencies`, the frequencies of the stimulation tone pips in Hz,
  - `levels`, the tested sound levels in dB, and
  - `confidences`, a confidence value for whether the tone pip specified
    by frequency and level evoked an auditory brainstem response, based
    on a bootstrap analysis.
* `resultTHRES`: A structure array, indexed on ABR measurement session
  number and containing two matrices, namely
  - `uniqueFrequencies`, the unique frequencies of the stimulation tone
    pips in Hz, and
  - `bootstrapThresholds`, the lowest sound level for the corresponding
    frequency for which an auditory brainstem response was obtained with
    a confidence value of 0.95 or greater, or NaN if there is no such
    level.

`abr_data_analysis.m`, provided for reference, is the MATLAB script by
which these data were extracted from the raw ABR measurements.
`abr_data_plot.m` was used to generate the supplementary ABR audiometry
figure.
