Downloading

This is for those using the ethoscope / node system

Setting up

To begin you need three paths saved as variables:

1. the path to the metadata .csv file

2. the web url of the ftp site and folder

3. the path of a local folder to save downloaded .db files

   1. if your .db files are already downloaded then it's the path to the folder containing them

Initialise all scripts by importing ethoscope as etho

import ethoscopy as etho

# Replace with your own file/sever paths

meta_loc = 'user/emperiment_folder/metadata.csv' 
remote = 'ftp://ftpsever/auto_generated_data/ethoscope_results'
local = 'user/ethoscope_results' 

Download from the remote ftp server

etho.downlaod_from_remote_dir(meta_loc, remote, local)

Only run the function etho.download_from_remote_dir() if you have never run it before with the ethoscopes in the metadata. The function searches the given ftp server for ethoscope machines data with the given names and dates, saving them to your given local folder in the same directory structure.

Create a modified metadata DataFrame

meta = etho.link_meta_index(meta_loc, remote, local)

This function creates a modified metadata DataFrame with the paths of the saved .db files and generates a unique id for each experimental individual. This function searches the ftp server for the .db file names, so it won't function without that server.

Load and modify the ethoscope data

The load function takes the raw ethoscope data from its .db format and modifies it into a workable pandas DataFrame format, changing the time (seconds) to be in reference to a given hour (usually lights on). Min and max times can be provided to filter the data to only recordings between those hours. With 0 being in relation to the start of the experiment not the reference hour.

data = etho.load_ethoscope(meta, min_time = 24, max_time = 48, reference_hour = 9.0)

# you can cache the each specimen as the data is loaded for faster load times when run again, just add a file path to a folder of choice, the first time it will save, the second it will search the folder and load straight from there
# However this can take up a lot of memory and it's recommended to save the whole loaded dataset at the end and to load from this each time. See the end of this page

data = etho.load_ethoscope(meta, min_time = 24, max_time = 48, reference_hour = 9.0, cache = 'path/ethoscope_cache/')

Additionally, an analysing function can be also called to modify the data as it is read.

from functools import partial

data = etho.load_ethoscope(meta, reference_hour = 9.0, FUN = partial(etho.sleep_annotation, time_window_length = 60, min_time_immobile = 300))

# time_window_length is the amount of time each row represents. The ethoscope can record multiple times per second, so you can go as low as 10 seconds for this.
# min_time_immobile is your sleep criteria, 300 is 5 mins the general rule of sleep for flies, see Hendricks et al., 2000.

Ethoscopy has 3 general functions that can be called whilst loading:

• max_velocity_detector: Aggregates variables per the given time window, finding their means. Sleeep_annotation uses this function before finding sleep bouts, so use this when you don't need to know the sleep bouts.

• sleep_annotation: Aggregates per time window and generates a new boolean column of sleep, as given by the time immobile argument.

• isolate_activity_lengths: Finds consecutive runs of inactivity or activity, filter by the intervals column and provide a window to contain the variables from prior to the start of the run.

Ethoscopy also has 2 functions for use with mAGO ethoscope module (odour delivery and mechanical stimulation):

• puff_mago: Finds the interaction times and then searches a given window post interaction for movement.

• find motifs: A modifcation of puff_mago, the function finds all interaction times and their response whilst retaining all the previous variables information in a given time window.

See the API reference for detailed information of the functions and arguments

Saving the data

Loading the ethoscope data each time can be a long process depending on the length of the experiment and number of machines. It's recommended to save the loaded/modified DataFrame as a .pkl file. See https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_pickle.html for more information about pandas and pickle saves.

The saved behavpy object can then be loaded in instantly at the start of a new session!

# Save any behavpy or pandas object with the method below

import pandas as pd

df.to_pickle('path/behapvy.pkl') # replace string with your file location/path

# Load the saved pickle file like this. It will retain all the metadata information
df = pd.read_pickle('path/behapvy.pkl')