API Reference
Dive more deeply into the functions and methods of ethoscopy
Loading functions
function download_from_remote_dit(metadata, remote_dir, local_dir): A function to find and download experimental .db files from an FTP server using a .csv metadata file as reference.
Parameters:
meta (string, path object) - The path of the .csv file containing your metadata, see metadata design for more information on the structure.
remote_dir (string) - The web server address of your FTP server folder containing the databases from your ethoscope experiments, e.g. 'ftp:/YOUR_SERVER/auto_generated_data/ethoscope_results
local_dir (string, path object) - The path to the local directory you wish to save the .db files to. Files will be saved using the structure of the ftp server
Returns None
function link_meta_index(metadata, remote_dir, local_dir):
A function to modify the users .csv metadata file with the information in a remote FTP server. It will generate file paths according to local_dir after verification the files exist in the FTP server.
Parameters:
meta (string, path object) - The path of the .csv file containing your metadata, see metadata design for more information on the structure.
remote_dir (string) - The web server address of your FTP server folder containing the databases from your ethoscope experiments, e.g. 'ftp:/YOUR_SERVER/auto_generated_data/ethoscope_results
local_dir (string, path object) - The path to the local directory were your .db files are saved.
Returns pandas DataFrame
function load_ethoscope(metadata, min_time=0, max_time=float('inf'), reference_hour=None, cache=None, FUN=None):
This function takes the metadata pandas DataFrame from link_meta_index and loads each specimen from each database into pandas DataFrame. Basic modifcation to the data time structure will be performed, however specific analysis can be applied with function added to the FUN parameter.
Parameters:
metadata (pd.DataFrame) - the metadata dataframe as returned from link_meta_index
min_time (int, default 0) - the minimum time (hour) from within the experiment you want to load the .db data from with 0 being the experiment start.
max_time (int, default float('inf')) - same as above but for the maximum time to load from
reference_hour (int, float, default None) - the hour at which the day beginds for your dataset (i.e. lights on). If None t0 is from the first recording.
cache (string, path object, default None) - If you wish to save each specimen as its loaded in, then provided the a folder path for the data to be saved (a .pkl save file). If None then nothing is saved. Note: it's preferable to not use the cache if you lack the storage capacity. See the downloading section about saving the final DataFrame instead.
FUN (ethoscopy analysis function, default None) - an addtional function to apply analysis to each specimen as it's loaded. See the analysis functions section next for more details.
Returns pandas DataFrame
Analysing functions
function sleep_annotation(data, time_window_length=10, min_time_immobile=300, motion_detector_FUN=max_velocity_detector, masking_duration=6, velocity_correction_coef=3e-3):
This function first uses a motion classifier to decide whether an animal is moving during a given time window. Then, it defines sleep as contiguous immobility for a minimum duration.
Parameters:
data (pandas DataFrame) - a dataframe containing behavioural variables from one specimen.
time_window_length (int, default 10) - the period of time (seconds) the data is binned to from the data source. Keep greater than your sampling frequency.
min_time_immobile (int, default 300) - immobility bouts (seconds) longer or equal to this value are considered as asleep.
motion_detector_FUN (fucntion, default max_velocity_detector) - the function to curate raw ethoscope data to velocity measurements. It's recommended not to change this.
masking_duration (int, default 6) - the value (seconds) of time after an interaction occurs that movement is ignored.
velocity_correction_coef (float, default 3e-3) - a coefficient to correct the velocity recorded (change for different length tubes/space for specimen)
returns pandas DataFrame
function max_velocity_detector(data, time_window_length=10, masking_duration=6, velocity_correction_coef=3e-3):
This is the function wrapped by sleep_annotation. Use this when you only wish to curate and transform the data from an ethoscope experiment. The velocity data will be transformed to find movement as benchmarked against ground truth experiments. Other variables will be averaged over the input bin time.
Parameters:
data (pandas DataFrame) - a dataframe containing behavioural variables from one specimen.
time_window_length (int, default 10) - the period of time (seconds) the data is binned to from the data source. Keep greater than your sampling frequency.
min_time_immobile (int, default 300) - immobility bouts (seconds) longer or equal to this value are considered as asleep.
masking_duration (int, default 6) - the value (seconds) of time after an interaction occurs that movement is ignored.
velocity_correction_coef (float, default 3e-3) - a coefficient to correct the velocity recorded (change for different length tubes/space for specimen)
returns pandas DataFrame
function isolate_activity_lengths(data, intervals, window, inactive=None, velocity_correction_coef=3e-3):
This function will find consecutive runs of inactivity or activity (according to the parameter inactive). Users inputted intervals (as a list) will determine in minutes what length runs to find, the window is how far back from the end of the interval you want to record. I.e. an interval of 10 with a window of 5 will only record the last 5 minutes of a 10 minute long run. Only runs with measurements per second will be kept.
Parameters:
data (pandas DataFrame) - a dataframe containing behavioural variables from one specimen.
intervals (list of ints) - a list containing integers (minutes) that refer to the length of runs you wish to look at.
window (int) - the time (minutes) you wish to look back from the end of each run. To record the whole run keep the same as the interval in a single item list.
inactive (boolean, default True) - If true then only runs of inactivity will be found. Change to false for bouts of activity.
velocity_correction_coef (float, default 3e-3) - a coefficient to correct the velocity recorded (change for different length tubes/space for specimen)
returns pandas DataFrame
function puff_mago(data, response_window=10, velocity_correction_coef=3e-3):
Only use this function if you have used a mAGO module with your ethoscope for odour delivery to sleeping flies. This function will find interaction times within the experiment and search in a window of time afterwards for movement. If the specimen moves the response is recorded as True.
Parameters:
data (pandas DataFrame) - a dataframe containing behavioural variables from one specimen.
response_window (int, default 10) - the period of time (seconds) after an interaction in which to check for a response.
velocity_correction_coef (float, default 3e-3) - a coefficient to correct the velocity recorded (change for different length tubes/space for specimen)
returns pandas DataFrame
function find_motifs(data, window=300, response_window=10, velocity_correction_coef=3e-3):
Find_motifs is a modification of puff_mago. Rather than just returning whether an interaction occurred or not, the function will find the prior sequence of variables before the interaction, marking whether the response was True or False. Each run is given a unique ID that is a combination of the specimens ID and number per run in the specimen. DO THIS PLEASE.
Parameters:
data (pandas DataFrame) - a dataframe containing behavioural variables from one specimen.
window (int, default 300) - the period of time (seconds) prior to the stimulus you want data from.
response_window (int, default 10) - the period of time (seconds) after an interaction in which to check for a response.
velocity_correction_coef (float, default 3e-3) - a coefficient to correct the velocity recorded (change for different length tubes/space for specimen)
returns pandas DataFrame
Last updated