neurokin.utils.experiments package

Submodules

neurokin.utils.experiments.neural_correlates module

neurokin.utils.experiments.neural_correlates.check_time_cutoff(t_onset, t_end, time_cutoff)

Checks if the difference between t_onset and t_end is lower than the time_cutoff. If not then computes the end edge as t_onset + t_end and returns it.

Parameters:

• t_onset – start of the event

• t_end – end of the event

• time_cutoff – minimum length of the event

Returns:

None if event is too short, t_onset + t_end otherwise

neurokin.utils.experiments.neural_correlates.compute_psd_for_row(row, events_columns, nfft, noverlap, zscore)

Computes Power Spectra Density arrays for all the events columns.

Parameters:

• row – a pd.Dataframe row, containing a list of neural correlates for each event type and fs

• events_columns – which columns contain the lists of neural chunks

• nfft – what number of fft segments to use

• noverlap – the overlap of the fft segments

• zscore – whether to z-score the psd or not

Returns:

Returns a pd.Series containing lists of Power Spectra Density arrays for all the events columns.

neurokin.utils.experiments.neural_correlates.create_exclusion_mask(idxs_to_exclude: List[List[int]], first_frame: int, last_frame: int) → numpy.array

Returns an array representing the region of interest of a run with True values only where there are no events to exclude

Parameters:

• idxs_to_exclude – list of the pairs of indexes to exclude [start, end]

• first_frame – first frame of the region of interest

• last_frame – last frame of the region of interest

Returns:

exclusion mask

neurokin.utils.experiments.neural_correlates.get_csv_first_block_len(csv_path: str) → int

Reads in a csv and returns the len of the first block. This is until a row is empty.

Parameters:

csv_path – path of the file

Returns:

len of block

neurokin.utils.experiments.neural_correlates.get_event_timestamps_freezing_active(df: pandas.DataFrame, timestamp_gait: List[List[float]]) → List[List[float]]

Returns freezing events after gait happened

Parameters:

• df – events dataframe

• timestamp_gait – list of gait timestamps

Returns:

list of timestamps of freezing after gait events

neurokin.utils.experiments.neural_correlates.get_event_timestamps_freezing_rest(df: pandas.DataFrame, timestamp_gait: List[List[float]]) → List[List[float]]

Returns freezing events before gait happened

Parameters:

• df – events dataframe

• timestamp_gait – list of gait timestamps

Returns:

list of timestamps of freezing before gait events

neurokin.utils.experiments.neural_correlates.get_event_timestamps_gait(df: pandas.DataFrame) → List[List[float]]

Returns gait events timestamps

Parameters:

df

Returns:

list of timestamps of gait

neurokin.utils.experiments.neural_correlates.get_event_timestamps_nlm_active(framerate: int, first_frame: int, last_frame: int, ts_to_exclude_fog: List[List[float]], ts_to_exclude_gait: List[List[float]])

Creates a mask representing the region of interest excluding all the passed events, and any event before the first gait frame

Parameters:

• framerate – recording framerate

• first_frame – first frame of the region of interest

• last_frame – last frame of the region of interest

• ts_to_exclude_fog – timestamps of freezing

• ts_to_exclude_gait – timestamps of gait

Returns:

non-locomotion movements event after gait has happened

neurokin.utils.experiments.neural_correlates.get_event_timestamps_nlm_rest(framerate: int, first_frame: int, last_frame: int, ts_to_exclude_fog: List[List[float]], ts_to_exclude_gait: List[List[float]])

Creates a mask representing the region of interest excluding all the passed events, and any event after the first gait frame

Parameters:

• framerate – recording framerate

• first_frame – first frame of the region of interest

• last_frame – last frame of the region of interest

• ts_to_exclude_fog – timestamps of freezing

• ts_to_exclude_gait – timestamps of gait

Returns:

non-locomotion movements event after gait has happened

neurokin.utils.experiments.neural_correlates.get_events_dict(event_path, skiprows, framerate)

Runs trough all the .csv files in the experiment_path and returns a dictionary with the timestamps of each event, sorted by the type.

Parameters:

• event_path – path to the run to be analyzed

• skiprows – how many rows to skip as a header of the .csv

• framerate – frame rate of the acquisition system

Returns:

events dictionary

neurokin.utils.experiments.neural_correlates.get_first_block_df(csv_path: str, skiprows: int = 0) → pandas.DataFrame

Gets the first block from a csv path. That is until the first empty line.

Parameters:

• csv_path – path of the file

• skiprows – how many rows to skip at the beginning

Returns:

pandas dataframe of the first block

neurokin.utils.experiments.neural_correlates.get_first_last_frame_from_csv(csv_path: str) → Tuple[int, int]

Given a csv from Vicon, it will return the first and last frame of the region of interest. This is usually encoded as the first and last row of the second block in the file

Parameters:

csv_path – path of the file

Returns:

neurokin.utils.experiments.neural_correlates.get_freeze_ts_bound(df: pandas.DataFrame) → Tuple[List[float], List[float]]

Returns onset and end of a freezing event in timestamps

Parameters:

df – events dataframe

Returns:

onset and end

neurokin.utils.experiments.neural_correlates.get_idxs_events_to_exclude(framerate: int, last_frame: int, ts_to_exclude_fog: List[List[float]], ts_to_exclude_gait: List[List[float]]) → List[List[int]]

Returns the indexes corresponding to the timestamps to exclude. It merges freezing events and gait events

Parameters:

• framerate – recording framerate

• last_frame – last frame of the region of interest

• ts_to_exclude_fog – timestamps of freezing

• ts_to_exclude_gait – timestamps of gait

Returns:

indexes of frames to be excluded

neurokin.utils.experiments.neural_correlates.get_neural_ch(neural_path: str, ch: int, stream_name: str) → Tuple[numpy.array, float]

Retireves the raw neural signal and the sampling frequency

Parameters:

• neural_path – folder path to TDT recording

• ch – channel number 0 based

• stream_name – name of the Stored listing

Returns:

raw neural single channel and sampling frequency

neurokin.utils.experiments.neural_correlates.get_neural_correlate_psd(raw: numpy.array, fs: float, t_on: float, t_off: float, nfft: int, nov: int, zscore: bool = True) → Tuple[numpy.array, numpy.array]

Takes the beginning and end of an event, retrieves the corresponding chunk of neural data and computes the psd

Parameters:

• raw – raw neural single channel

• fs – sampling frequency

• t_on – beginning of event in seconds

• t_off – end of event in seconds

• nfft – nfft for fourier transform

• nov – overlap for fourier transform

• zscore – how to normalize

Returns:

psd and corresponding frequencies

neurokin.utils.experiments.neural_correlates.get_neural_correlates_dict(neural_path, channel_of_interest, stream_names, events_df, time_cutoff)

Returns a dictionary with the raw neural data corresponding to each event in the input events dictionary, from the selected channel of interest. Events duration is capped at time_cutoff to ensure homogeneity in the duration.

Parameters:

• neural_path – path to the folder with neural data

• channel_of_interest – channel to extract the raw data from

• stream_names – list of possible stream_names where the neural data is stored

• events_df

• time_cutoff

Returns:

neurokin.utils.experiments.neural_correlates.get_psd_single_event_type(raw_neural_list, fs, nfft, noverlap, zscore)

Computes the Power Spectra Density array for all element in the list (corresponding to a single type of event)

Parameters:

• raw_neural_list – list containing neural data arrays

• fs – sampling frequency of the neural data

• nfft – what number of fft segments to use

• noverlap – the overlap of the fft segments

• zscore – whether to z-score the psd or not

Returns:

list of PSDs

neurokin.utils.experiments.neural_correlates.get_single_neural_type(events_df, event_type, time_cutoff, fs, raw)

Fetches the neural chunks corresponding to all the events of a certain type. All events are cut at the time_cutoff, to ensure consistency across different lengths (this implies events shorter than time_cutoff are dropped).

Parameters:

• events_df – dataframe containing all events timestamps

• event_type – type of event to fetch the neural correlates for

• time_cutoff – max length of an event to consider (shorter events are dropped)

• fs – sampling frequency of the neural data

• raw – raw neural data, single channel

Returns:

returns a list of the neural chunks corresponding to the events, cropped to time_cutoff

neurokin.utils.experiments.neural_correlates.get_start_of_gait(framerate: int, ts_gait: List[List[float]]) → int

Returns the first frame of gait

Parameters:

• framerate – recording framerate

• ts_gait – timestamps of gait

Returns:

first frame index of gait

neurokin.utils.experiments.neural_correlates.get_ts_from_exclusion_mask(mask: numpy.array, first_frame: int, framerate: int) → Tuple[List[float], List[float]]

Gets bounds of the exclusion mask and converts it in timestamps

Parameters:

• mask

• first_frame – first frame of the region of interest

• framerate – recording framerate

Returns:

neurokin.utils.experiments.neural_correlates.time_to_frame_in_roi(timestamp: float, fs: float, first_frame: int) → int

Converts the time to frames in the region of interest (i.e. with an offset of the first frame)

Parameters:

• timestamp – time in seconds

• fs – sampling frequency

• first_frame – first frame of the region of interest

Returns:

neurokin.utils.experiments.neural_correlates.transpose_start_of_gait(start_of_gait: int, first_frame: int) → int

Transposes the index of the start of gait where first_frame is 0. Moreover it takes care of small idiosyncrasies when an event appears to start at frame -1

Parameters:

• start_of_gait – start of the first gait event

• first_frame – first frame of the region of interest

Returns:

neurokin.utils.experiments.neural_correlates.traspose_idxs(idxs_to_exclude: List[List[int]], first_frame: int) → List[List[int]]

Transposes the indexes to an array where first_frame is 0. Moreover it takes care of small idiosyncrasies when an event appears to start at frame -1

Parameters:

• idxs_to_exclude – list of indexes to be set to false

• first_frame – first frame of the region of interest

Returns:

indexes transposed, same shape as inut

neurokin.utils.experiments.neural_correlates_plot module

neurokin.utils.experiments.neural_correlates_plot.add_shades(ax, f, df, idx_min, idx_max, color, stat='std')

Helper function to plot shades.

Parameters:

• ax – the ax to plot on

• f – frequencies to use on the x-axis

• df – the data to be plot (array like of states)

• idx_min – minimum frequency index to plot

• idx_max – maximum frequency index to plot

• color – color to plot the shade in, with 0.3 alpha factor

• stat – which statistics to use for shades. “std” for standard deviation, “sem” for standard error of mean, “ci” for confidence interval

Returns:

neurokin.utils.experiments.neural_correlates_plot.plot_psd_single_state(ax, df, group, condition, state, freqs, color, idx_min, idx_max, stat='std', linewidth=3)

Plots the Power Spectral Denisty trace of a single state, on a given ax.

Parameters:

• ax – axis to plot on

• group – which subject group to plot

• condition – which experimental condition to plot

• state – which state to plot

• freqs – frequencies corresponding to the full array of PSD values

• idx_min – index of the minimum frequency to plot

• idx_max – index of the maximum frequency to plot

• color – color of the trace

• stat – which stat to use to compute the shading, default standard deviation

• linewidth – how thick to draw the mean line.

Returns:

neurokin.utils.experiments.neural_states_helper module

neurokin.utils.experiments.neural_states_helper.compute_ci(array)

Computes the confidence interval given hardcoded value of 1.96.

Parameters:

array – array to compute the confidence interval on

Returns:

confidence interval value

neurokin.utils.experiments.neural_states_helper.compute_duration(timestamps_lists)

neurokin.utils.experiments.neural_states_helper.compute_events_percentage(events_dataset)

Computes the average percentage of time spent in each state for each animal. It normalizes every state duration to the total length of the run, then takes the average across all the runs available for that condition.

Parameters:

events_dataset – dataset with event timestamps

Returns:

dataframe containing condition, animal and event containing the average time spent in each state

neurokin.utils.experiments.neural_states_helper.compute_percentage(array)

neurokin.utils.experiments.neural_states_helper.condense_distribution_event_types(percentage_states_df)

Condenses from the dataset five categories analysis [“fog_active”, “fog_rest”, “nlm_active”, “nlm_rest”, gait] to only three categories [“fog”, “nlm”, “gait”]

Parameters:

cond_animal_event_dict – states dictionary structured as condition, animal, events.

Returns:

same dictionary with 3 conditions instead of 5

neurokin.utils.experiments.neural_states_helper.get_group_split(test_sbj_list, df)

Splits the dataset in two groups depending on which subjects are in the test group and which not (control)

Parameters:

• test_sbj_list – list of subject IDs that belong to teh test group

• animals_avg_dataset – dictionary containing the psds organized by condition, animal and event

Returns:

split dictionary between test_group and sham_group

neurokin.utils.experiments.neural_states_helper.get_per_animal_psds_df(psds_dataset, condense=False)

Given the overall psds dataset, computes the average values, per state, per animal

Parameters:

• psds_dataset – overall dataset

• condense – wheter to condense to the 3 states format or keep the 5 format

Returns:

grouped-by-animal dataset

neurokin.utils.experiments.neural_states_helper.get_runs_list(experiment_structure, skip_subjects, skip_conditions)

Retrieves all the runs unique strings identifying day, subject, condition and run number

Parameters:

• experiment_structure – dictionary containing the experiment structure

• skip_subjects – which subjects to skip

• skip_conditions – which condition to skip

Returns:

flat list with all the unique strings identifying runs

neurokin.utils.experiments.neural_states_helper.get_state_graph_stats(group_cond_df, stat='std')

Takes the group dataset and returns a dataframe with mean, upper bound and lower bound to be used to graph.

Parameters:

• group_cond_df

• stat – which statistic to use to compute the upper and lowe bounds. Takes “std” for standard deviation, “sem” for standard error of mean and “ci” for confidence interval.

Returns:

df

neurokin.utils.experiments.neural_states_helper.load_dataset(dataset_path)

Load existing dataset dictionary, avoiding waiting time for processing

Parameters:

dataset_path – path including filename to the dataset. Expects pickle files

Returns:

neurokin.utils.experiments.neural_states_helper.mean_psds(psds_list)

Returns mean psds if the list is full

Parameters:

psds_list – list of power spectral density arrays

Returns:

mean on axis 0

neurokin.utils.experiments.neural_states_helper.save_data(data, filename)

Saves data to pickle files, if the data is not empty. Else returns a ValueError. :param data: :param filename: filename with path. :return:

neurokin.utils.experiments.spider_factory module

neurokin.utils.experiments.spider_factory.get_polygon_corners(theta, bottom, top)

Retrieves the corners of a polygon encompassed by the shades borders to allow for proper shading

Parameters:

• theta – radius reference

• bottom – lower border of the shading. y values

• top – upper border of the shading. y values

Returns:

x and y values of the polygon encompassed by the borders

neurokin.utils.experiments.spider_factory.plot_spider_single_trace(ax, data, color, theta, zorder=0)

Plots a single trace on a spider plot (radar plot)

Parameters:

• ax – axis to plot on

• data – dataset to plot

• color – color to use to plot

• theta – radius reference

• zorder – z-order for stacking

Returns:

neurokin.utils.experiments.spider_factory.spider_factory(num_vars, frame='circle')

Taken from https://matplotlib.org/stable/gallery/specialty_plots/radar_chart.html Create a radar chart with num_vars axes.

This function creates a RadarAxes projection and registers it.

Parameters

num_varsint

Number of variables for radar chart.

frame{‘circle’, ‘polygon’}

Shape of frame surrounding axes.

Module contents