analysis package

analysis.functions module

Functions used for song & neural analysis

get_note_type(syllables: str, song_db: Dict[str, str]) → List[str]

Return the category of the syllable (e.g, motif, intro notes, calls)

Parameters:

• syllables (str) – syllable in single letter (e.g., ‘a’, ‘i’)

• song_db (Dict[str]) – song database

Returns:

type_str

Return type:

List[str]

demarcate_bout(target, intervals: int)

Demarcate the song bout with an asterisk (*) from a string of syllables

Parameters:

• target (str or np.ndarray) – target sequence to demarcate

• intervals_ms (int) – syllable gap duration in ms

Returns:

bout_labeling – demarcated syllable string (e.g., ‘iiiabc*abckn*’)

Return type:

str

unique_nb_notes_in_bout(note: str, bout: str) → int

Return the unique number of notes within a single bout string

total_nb_notes_in_bout(note: str, bout: str) → int

Return the total number of song notes from a list of song bouts

get_nb_bouts(song_note: str, bout_labeling: str)

Count the number of bouts (only includes those having at least one song note)

Parameters:

• song_note (str) – syllables that are part of a motif (e.g., abcd)

• bout_labeling (str) – syllables that are demarcated by * (bout) (e.g., iiiiiiiiabcd*jiiiabcdji*)

get_snr(avg_wf, raw_neural_trace, filter_crit: Optional[int] = 5)

Calculate signal-to-noise ratio of sorted spike relative to the background neural trace

Parameters:

• avg_wf (np.ndarray) – averaged spike waveform of a neuron

• raw_neural_trace (np.ndarray) – raw neural signal

• filter_crit (int) – filtering criteria

Returns:

snr – signal-to-noise ratio

Return type:

float

get_half_width(wf_ts: ndarray, avg_wf: ndarray)

Find the negative (or positive if inverted) deflection

Parameters:

• wf_ts (np.ndarray) – waveform timestamp

• avg_wf (np.ndarray) – averaged waveform

Returns:

• deflection_range (list)

• half_width (float)

get_psd_mat(data_path, save_path, save_psd=False, update=False, open_folder=False, add_date=False, nfft=1024, fig_ext='.png')

Get matrix of power spectral density

get_basis_psd(psd_list, notes, song_note=None, num_note_crit_basis=30)

Get avg psd from the training set (will serve as a basis)

Parameters:

• psd_list (list) – List of syllable psds

• notes (str) – String of all syllables

• song_note (str) – String of all syllables

• num_note_crit_basis (int (30 by default)) – Minimum number of notes required to be a basis syllable

Returns:

• psd_list_basis (list)

• note_list_basis (list)

get_pre_motor_spk_per_note(ClusterInfo, song_note, save_path, context_selection=None, npy_update=False)

Get the number of spikes in the pre-motor window for individual note

Parameters:

• ClusterInfo (class) –

• song_note (str) – notes to be used for analysis

• save_path (path) –

• context_selection (str) – select data from a certain context (‘U’ or ‘D’)

• npy_update (bool) –

• npy_update – make new .npy file

Returns:

pre_motor_spk_dict

Return type:

dict

get_spectral_entropy(psd_array, normalize=True, mode=None)

Calculate spectral entropy and it variance

get_ff(data, sample_rate, ff_low, ff_high, ff_harmonic=1)

Calculate fundamental frequency (FF) from the FF segment

Parameters:

• data (array) –

• sample_rate (int) – data sampling rate

• ff_low (int) – Lower limit

• ff_high (int) – Upper limit

• ff_harmonic (int (1 by default)) – harmonic detection

Returns:

ff

Return type:

float

normalize_from_pre(df, var_name: str, note: str)

Normalize post-deafening values using pre-deafening values

add_pre_normalized_col(df: DataFrame, col_name_to_normalize, col_name_to_add, save_path=None, csv_name=None, save_csv=False) → DataFrame

Normalize relative to pre-deafening mean

get_bird_colors(birds: list) → dict

Assign different colors for different birds in the input list

Parameters:

birds (list) –

Returns:

bird_color

Return type:

dict

get_spectrogram(timestamp, data, sample_rate: int, freq_range: Optional[list] = [300, 8000])

Calculate spectrogram

align_waveform(spk_wf: ndarray) → ndarray

Shift the individual spike waveforms relative to the max location of the average waveform

Parameters:

spk_wf (np.ndarray) – spike waveform matrix (spike id x waveform)

Returns:

aligned_wf – aligned spike waveforms (spike id x waveform)

Return type:

np.ndarray

analysis.load module

Load data (from .rhd, .txt, .wav, etc)

read_not_mat(notmat, unit='ms')

Read from .not.mat files generated from uisonganal.m

Parameters:

• notmat (path) – Name of the .not.mat file (path)

• unit ({'ms', 'second'}) – timescale

Returns:

• onsets (np.ndarray) – time stamp for syllable onset (in ms)

• offsets (np.ndarray) – time stamp for syllable offset (in ms)

• intervals (np.ndarray) – temporal interval between syllables (i.e. syllable gaps) (in ms)

• durations (np.ndarray) – durations of each syllable (in ms)

• syllables (str) – song syllables

• contexts (str) – social context (‘U’ for undirected and ‘D’ for directed)

read_spk_txt(spk_txt_file, *unit_nb, time_unit='second')

Read the output .txt from the Offline Sorter. column header of the input .txt -> [‘Channel’, ‘Unit’, ‘Timestamp’] disregard the first column since it is always 1 column 3 to 35 stores waveforms

Parameters:

• spk_txt_file (str) – Name of the spk txt file

• unit_nb (int) – Number of the sorted unit. If not specified (default), it will read data from all recorded units.

• time_unit –

Returns:

• spk_ts (np.ndarray) – Spike timestamps

• spk_waveform (np.ndarray) – Spike waveform (spk id x waveform)

• nb_spk (int) – Number of spikes

read_rhd(filename)

Reads Intan Technologies RHD2000 data file generated by evaluation board GUI.

Data are returned in a dictionary, for future extensibility.

load_song(data_path, format='wav') → dict

Obtain event info & serialized timestamps for song & neural analysis

Search all files in the sub-directory and read from the associated .not.mat files to add the info into a single files

Parameters:

• data_path (path) –

• format (str) – file extension (e.g., ‘.wav’)

load_audio(data_path, format='wav') → dict

Load and concatenate all audio files (e.g., .wav) in the input dir (path)

Parameters:

• data_path (path) –

• format (str) – file extension (e.g., ‘.wav’)

Returns:

audio_info

Return type:

dict

analysis.parameters module

Store key parameters for data analysis.

Only the parameters that are used routinely are listed here, but can be changed.

Please note that the changed parameter affect values in other programs.

If one were to play with a range of different parameters, take it out and use it as a local variable in a script.

analysis.song module

Module for song analysis

class SongInfo(path, name=None, update=False)

Bases: object

Class object for analyzing song data

list_files(ext='.wav')

property open_folder

property nb_files: int

Number of files

nb_bouts(song_note: str)

Return the number of bouts

Parameters:

song_note (str) – song notes (e.g., ‘abcd’)

Returns:

nb_bouts

Return type:

dict

nb_motifs(motif)

mean_nb_intro(intro_note, song_note)

Return the mean number of intro notes per song bout only counts from bouts having at least one song note

song_call_prop(call: str, song_note: str)

Calculate the proportion of call notes per song bout Get the proportion per bout and then average only counts from bouts having at least one song note

get_motif_info(motif: str)

Get information about song motif for the songs recorded in the session

class BoutInfo(path, song_note, name=None, update=False)

Bases: SongInfo

Get song & spike information for a song bout

Child class of SongInfo

print_name()

class MotifInfo(motif_info, motif)

Bases: object

get_motif_duration()

Get mean motif duration and its cv per context

class AudioInfo(filepath, format='.wav')

Bases: object

Create an audio object from a single audio file (e.g., .wav)

load_notmat()

Load the .not.mat file

property open_folder

extract(time_range)

Extracts data from the specified range

Parameters:

time_range (list) – list of time stamps [start, end]

Returns:

• timestamp (np.ndarray)

• data (np.ndarray)

spectrogram(timestamp, data, freq_range=[300, 8000])

Calculate spectrogram

get_spectral_entropy(spect, normalize=True, mode=None)

Calculate spectral entropy

Parameters:

• normalize (bool) – Get normalized spectral entropy

• mode (str) – Select one from the following {‘spectral’, ‘’spectro_temporal’}

Return type:

array of spectral entropy

class FundamentalFreq

Bases: object

Class object for analyzing fundamental frequency of a syllable

load_from_db(birdID, ff_note)

Load info from the database if exists

get_ts(note_onset, note_offset)

Get onset and offset timestamp of FF portion based on note onset & offset

class SyllableNetwork

Bases: object

analysis.spike module

Module for neural analysis

get_isi(spk_ts_list: list)

Get inter-analysis interval of spikes

Parameters:

spk_ts_list (list) –

Returns:

isi – class object for inter-spike intervals

Return type:

class object

get_peth(evt_ts_list: list, spk_ts_list: list, pre_evt_buffer=None, duration=None, bin_size=None, nb_bins=None)

Get peri-event histogram & firing rates

Parameters:

• evt_ts_list (list) – Timestamps for behavioral events (e.g., syllable onset/offsets)

• spk_ts_list (list) – Spike timestamps

• pre_evt_buffer (int, default=None) – Size of buffer window prior to the first event (in ms)

• duration (int, optional) – Duration of the peth (in ms). Truncate the

• bin_size (int, default=None) – Time bin size

• nb_bins (int, default=None) – Number of bins

Returns:

• peth (np.ndarray) – Peri-event time histograms

• time_bin (np.ndarray) – Time bin vector

• parameter (dict) – Parameters for draw peth

Notes

If pre_evt_buffer, bin_size, nb_bins not specified, take values from analysis ..analysis.parameters

get_pcc(fr_array: ndarray) → dict

Get pairwise cross-correlation

Parameters:

fr_array (np.ndarray) – (trial x time_bin)

Returns:

pcc_dict

Return type:

dict

jitter_spk_ts(spk_ts_list, shuffle_limit, reproducible=True)

Add a random temporal jitter to the spike

Parameters:

reproducible (bool) – Make the results reproducible by setting the seed as equal to index

pcc_shuffle_test(ClassObject, PethInfo, plot_hist=False, alpha=0.05)

Run statistical test to see if baseline pairwise cross-correlation obtained by spike time shuffling is significant

Parameters:

• ClassObject (class object (e.g., NoteInfo, MotifInfo)) –

• PethInfo (peth info class object) –

• plot_hist (bool) – Plot histogram of bootstrapped pcc values (False by default)

Returns:

p_sig – True if the pcc is significantly above the baseline

Return type:

dict

class ClusterInfo(path, channel_nb, unit_nb, format='rhd', *name, update=False, time_unit='ms')

Bases: object

list_files(ext: str)

analyze_waveform(align_wf=True, interpolate=True, interp_factor=None)

Perform waveform analysis

Parameters:

• align_wf (bool) – align all spike waveforms relative to the max location

• interpolate (bool) – Set to true if waveform interpolation is needed

• interp_factor (int) – Factor by which to increase the sampling frequency of the waveform e.g., 100 if you want to increase the data points by 100 fold

get_conditional_spk() → dict

Get spike timestamps from different contexts

get_correlogram(ref_spk_list, target_spk_list, normalize=False) → dict

Get auto- or cross-correlogram

jitter_spk_ts(shuffle_limit, reproducible=True)

Add a random temporal jitter to the spike

Parameters:

• shuffle_limit (int) – shuffling limit (in ms) e.g., If set to 5, any integer values between -5 to 5 drawn from uniform distribution will be added to the spike timestamp

• reproducible (bool) – make the results reproducible by setting the seed as equal to index

get_jittered_corr() → dict

Get spike correlogram from time-jittered spikes

get_isi(add_premotor_spk=False)

Get inter-spike interval

Parameters:

add_premotor_spk (bool) – Add spikes from the premotor window for calculation

property nb_files: dict

Return the number of files per context

Returns:

nb_files – Number of files per context (‘U’, ‘D’, ‘All’)

Return type:

dict

nb_bouts(song_note: str) → dict

Return the number of bouts per context

Parameters:

song_note (str) – song motif syllables

Returns:

nb_bouts

Return type:

dict

nb_motifs(motif: str) → dict

Return the number of motifs per context

Parameters:

motf (str) – Song motif (e.g., ‘abcd’)

Returns:

nb_motifs

Return type:

dict

get_note_info(target_note, pre_buffer=0, post_buffer=0)

Obtain a class object (NoteInfo) for individual note spikes will be collected from note onset (+- pre_buffer) to offset (+- post_buffer)

Parameters:

• target_note (str) – Get information from this note

• pre_buffer (int) – Amount of time buffer relative to the event onset (e.g., syllable onset)

• post_buffer (int) – Amount of time buffer relative to the event offset (e.g., syllable onset)

Returns:

NoteInfo

Return type:

class object

property open_folder

class NoteInfo(note_dict)

Bases: object

Class for storing information about a single note syllable and its associated spikes

select_index(index) → None

Select only the notes with the matching index

Parameters:

index (np.array or list) – Note indices to keep

select_context(target_context: str, keep_median_duration=True) → None

Select one context

Parameters:

• target_context (str) – ‘U’ or ‘D’

• keep_median_duration (bool) – Normally medial note duration is calculated using all syllables regardless of the context one may prefer to use this median to reduce variability when calculating pcc if set False, new median duration will be calculated using the selected notes

get_entropy(normalize=True, mode='spectral')

Calculate syllable entropy from all renditions and get the average Two versions : spectro-temporal entropy & spectral entropy

get_note_peth(time_warp=True, shuffle=False, pre_evt_buffer=None, duration=None, bin_size=None, nb_bins=None)

Get peri-event time histograms for single syllable

Parameters:

• time_warp (perform piecewise linear transform) –

• shuffle (add jitter to spike timestamps) –

• duration (duration of the peth) –

• bin_size (size of single bin (in ms) (take values from peth_parm by default)) –

• nb_bins (number of time bins (take values from peth_parm by default)) –

Returns:

PethInfo

Return type:

class object

jitter_spk_ts(shuffle_limit)

Add a random temporal jitter to the spike This version limit the jittered timestamp within the motif window

property nb_note: dict

Return number of notes per context

property mean_fr: dict

Return mean firing rates for the note (includes pre-motor window) per context

class MotifInfo(path, channel_nb, unit_nb, motif, format='rhd', *name, update=False)

Bases: ClusterInfo

Class object for motif information child class of ClusterInfo

select_context(target_context: str, keep_median_duration=True) → None

Select one context

Parameters:

• target_context (str) – ‘U’ or ‘D’

• keep_median_duration (bool) –

  Normally medial note duration is calculated using all syllables regardless of the context.

  One may prefer to use this median to reduce variability when calculating pcc.

  IF set False, new median duration will be calculated using the selected notes.

get_note_duration()

Calculate note & gap duration per motif

piecewise_linear_warping()

Performs piecewise linear warping on raw analysis timestamps Based on each median note and gap durations

get_mean_fr(add_pre_motor=False)

Calculate mean firing rates during motif

Parameters:

add_pre_motor (bool) – Set True if you want to include spikes from the pre-motor window for calculating firing rates (False by default)

jitter_spk_ts(shuffle_limit: int, **kwargs)

Add a random temporal jitter to the spike This version limit the jittered timestamp within the motif window

get_peth(time_warp=True, shuffle=False)

Get peri-event time histogram & raster during song motif

Parameters:

• time_warp (bool) – perform piecewise linear transform

• shuffle (bool) – add jitter to spike timestamps

Returns:

PethInfo

Return type:

class object

property open_folder

Open the data folder

class PethInfo(peth_dict: dict)

Bases: object

get_fr(gaussian_std=None, smoothing=True)

Get trials-by-trial firing rates by default

Parameters:

• gaussian_std (int) – gaussian smoothing parameter. If not specified, read from analysis.parameters

• smoothing (bool) – performs gaussian smoothing on the firing rates

get_pcc()

Get pairwise cross-correlation

get_fr_cv()

Get coefficient of variation (CV) of firing rates

get_sparseness(bin_size=None)

Get sparseness index

Parameters:

bin_size (int) – By default, it uses the same time bin size used in peth calculation (in ms)

Returns:

sparseness

Return type:

dict

get_spk_count()

Calculate the number of spikes within a specified time window

class BoutInfo(path, channel_nb, unit_nb, song_note, format='rhd', *name, update=False)

Bases: ClusterInfo

Get song & spike information for a song bout Child class of ClusterInfo

plot()

class BaselineInfo(path, channel_nb, unit_nb, format='rhd', *name, update=False)

Bases: ClusterInfo

get_correlogram(ref_spk_list, target_spk_list, normalize=False)

Override the parent method

Combine correlogram from undir and dir since no contextual differentiation is needed in baseline

get_jittered_corr() → ndarray

Get spike correlogram from time-jittered spikes

get_isi()

Get inter-spike interval

property mean_fr

Mean firing rates

class AudioData(path, format='.wav', update=False)

Bases: object

Create an object that has concatenated audio signal and its timestamps

Get all data by default; specify time range if needed

property open_folder

extract(time_range: list)

Extracts data from the specified range

Parameters:

time_range (list) –

spectrogram(timestamp, data, freq_range=[300, 8000])

Calculate spectrogram

get_spectral_entropy(spect, normalize=True, mode=None)

Calculate spectral entropy

Parameters:

• normalize (bool) – Get normalized spectral entropy

• mode ({'spectral', ''spectro_temporal'}) –

Return type:

array of spectral entropy

class NeuralData(path, channel_nb, format='rhd', update=False)

Bases: object

load_neural_data()

Load and concatenate all neural data files (e.g., .rhd) in the input dir (path)

extract(time_range: list)

Extracts data from the specified range

Parameters:

time_range (list) – list of time stamps [start, end]

Returns:

• timestamp (arr)

• data (arr)

property open_folder

class Correlogram(correlogram)

Bases: object

Class for correlogram analysis

category(correlogram_jitter: ndarray) → str

Get bursting category of a neuron based on autocorrelogram

Parameters:

correlogram_jitter (np.ndarray) – Random time-jittered correlogram for baseline setting

Return type:

Category of a neuron (‘Bursting’ or ‘Nonbursting’)

plot_corr(ax, time_bin, correlogram, title, xlabel=None, ylabel=None, font_size=10, peak_line_width=0.8, normalize=False, peak_line=True, baseline=True)

Plot correlogram

Parameters:

• ax (axis object) – axis to plot the figure

• time_bin (np.ndarray) –

• correlogram (np.ndarray) –

• title (str) –

• font_size (int) – title font size

• normalize (bool) – normalize the correlogram

class BurstingInfo(ClassInfo, *input_context)

Bases: object

class ISI(isi)

Bases: object

Class object for inter-spike interval analysis

plot(ax, *title, font_size=10)

analysis.waveform module