Library API

Structure

The library exports classes:

Sessions control the sequence of events during a training session and track training data throughout the session. They can then be used after a session has completed for analysis of this training data. Sessions must be provided with a Backend or a subclass thereof to control during training. See Behavioural Training for how to do this.

Mouse instances handle and manipulate a list of Sessions, and read/write their data to and from the mouse’s training JSON file. They provide access to basic results across sessions for a single mouse.

Cohorts handle and manipulate a list of Mouse instances and are intended to be used for post-training analysis of behavioural data in user scripts. See scripts/plotting/cohort_reaction_times.py for an example.

reach.Session

class reach.Session(data=None)

Controls a single training session and its behavioural data.

Parameters

data (dict, optional) – A dictionary of additional or pre-filled data to be added to the session’s training data.

classmethod init_all_from_file(data_file)

Generate a list of Session objects from data stored in a Training JSON.

Parameters

data_file (str) – Full path to file containing existing training data.

Returns

list – List of Session instances.

add_data(data)

Manually add data to the Session’s data.

Parameters

data (dict) – Dictionary of values to add into the session’s data.

run(backend, duration=None, intertrial_interval=None, previous_data=None, hook=None, timeout=None, initial_spout=None, advance_with_incorrects=False)

Begin a training session.

Parameters

  • backend (class) – An instance of a Backend subclass.

  • duration (int, optional) – Duration of the training session in seconds. Default: 1800 seconds.

  • intertrial_interval (tuple of 2 ints, optional) – Minimum and maximum duration in milliseconds for use for the inter-trial interval. Default: (4000, 6000).

  • previous_data (dict of training data, optional) – Training data from the previous session, which if provided will be used when calculating initial cue duration and spout position.

  • hook (callable, optional) – An object that will be called at the end of every trial.

  • timeout (int, optional) – Duration in milliseconds of a timeout to wait after an incorrect trial.

  • initial_spout (int, optional) – Initial spout to use for session. Default: None; initial spout is randomly selected.

  • advance_with_incorrects (bool, optional) – If True, advancements between trials in spout position and cue duration can happen as long as the mouse is touch any reach target consistently, rather than reaching only to the current target.

on_iti_lift(side)

To be executed when the inter-trial interval is broken when the mouse prematurely lifts either paw from the paw rests.

Parameters

side (int) – Which paw was lifted: 0 for left, 1 for right

on_iti_grasp(side)

To be executed when a spontaneous reach is made during the inter-trial interval.

Parameters

side (int) – Which spout was grasped: 0 for left, 1 for right.

on_trial_lift(side)

To be executed when the first paw lift occurs during each trial.

Parameters

side (int) – Which spout side paw was lifted: 0 for left, 1 for right.

on_trial_correct()

To be executed upon successful grasp of the reach target during each trial.

on_trial_incorrect()

To be executed upon grasp of the incorrect reach target during each trial.

set_spout(spout)

Set the current spout for the next trial.

Parameters

spout (int) – The spout to use. If the value provided is -1, instead invert the choice from the current spout.

get_recent_trials(spout=None)

Get last few trials that used a given spout.

Parameters

spout (int, optional) – The spout to get trials for. By default, get the recent trials for the current spout.

get_trials()

Get trial data for this session.

Returns

list of dicts – Chronological list of dicts, where each dict contains information about the nth trial.

get_d_prime()

Get the d’ value for this session.

d’ is calculated as: d’ = z(FA) - z(H) where “hits” (H) is success rate of left-target trials that involved reaching movements, and “false alarms” (FA) is incorrect rate of right-target trials that involved reaching movements. This metric does not account for miss trials where no reaches were made. A loglinear correction is used to account for extreme values (Hautus, 1995).

get_results()

Get the high-level results for this session.

Returns

dict – containing basic metrics of the session, and any other metadata found in Session.data.

get_spontaneous_reaches()

Get the list of spontaneous reach timings and locations.

Returns

list – A list of (time, location) tuples, where location is equal to Targets.LEFT or Targets.RIGHT.

reach.backends

class reach.backends.Backend

This base class is the basis for all backends and is not intended for direct use by a training session. See Backends for information on how to use.

Spout number can be 0 for the left spout or 1 for the right spout.

configure_callbacks(session)

Configure callback functions passed from the session. Callback functions should be executed during the intertrial-interval or trial at specific events, as per their name. The callbacks should be enabled in backend.start_iti and backend.start_trial, so these should have access to the session functions. The functions can be modified/wrapped to meet the specific needs of the backend. These are required for base functionality:

  • session.on_iti_lift

  • session.on_iti_grasp

  • session.on_trial_lift

  • session.on_trial_correct

  • session.on_trial_incorrect

wait_to_start()

Called once before the training session begins.

position_spouts(position, spout_number=None)

Called to move one or both spouts to a specified position.

Parameters

  • position (int) – Millimetres from the mouse: integers from 1 to 7 inclusive.

  • spout_number (int, optional) – The spout to move. By default, both are moved.

wait_for_rest()

Called to wait for the mouse to remain still during the inter-trial interval before counting down to the start of a trial. Must return True, or False due to a session cancellation.

start_iti()

Assign session.on_iti_lift and session.on_iti_grasp callbacks to events.

start_trial(spout_number)

Assign session.on_trial_lift, session.on_trial_correct and session.on_trial_incorrect callbacks to events.

This begins a trial: this can be used to the handle cue(s), record the time etc.

Parameters

spout_number (int) – The spout number corresponding to this trial’s reach target.

give_reward(spout_number)

Give a reward.

Parameters

spout_number (int) – The spout number to give reward from.

miss_trial()

Called on a miss trial: when the trial ends and no spouts have been grasped. Note this is distinct from an incorrect trial, when the wrong spout was grasped.

end_trial()

Called at the end of each trial.

cleanup()

Called once at the end of the session.

reach.Mouse

class reach.Mouse(mouse_id=None, data=None)

This class represents a single experimental mouse. Mouse instances can be instantiated either by providing training data manually, or with Mouse.init_from_file to use training data stored in a file.

Training data is stored as a list of Session instances.

mouse_id

The mouse’s ID.

Type

str, optional

data

The mouse’s training data.

Type

list of Session instances.

classmethod init_from_file(data_dir, mouse_id)

Initialise Mouse object using pre-existing training data stored within a training JSON.

Parameters

  • data_dir (str) – Directory containing training data.

  • mouse_id (str) – Mouse ID to pass to Mouse instance. Will be used to find JSON if json_path is a folder.

train(backend, additional_data=None, **kwargs)

Create a new Session and run it, appending its newly-collected data to the Mouse’s training data.

Parameters

  • backend (class) – An instance of a Backend subclass.

  • additional_data (dict, optional) – Extra data that should be saved into the new session’s data.

  • **kwargs (Additional keyword arguments are forwarded to Session.run()) –

save_data_to_file(data_dir)

Save all training data to training JSON file.

Parameters

data_dir (str) – Directory into which to save training data.

get_trials(collapse_days: bool = True)

Get trial data for all sessions.

This can easily be turned into a useful pandas DataFrame: >>> trials = pd.DataFrame(mouse.get_trials())

collapse_days, if True, will merge the results of consecutive days if they share a date.

get_results(collapse_days: bool = True)

Get the high-level results for all sessions.

This can easily be turned into a useful pandas DataFrame: >>> results = pandas.DataFrame(mouse.get_results())

collapse_days, if True, will merge the results of consecutive days if they share a date. WARNING: if this occurs, d’ values for collapsed days would be invalid, and so are replaced with None for those days. These need to be re-calculated with the trials returned from get_trials().

get_spontaneous_reaches()

Get the data on spontaneous reach timings and locations for all sessions.

This can easily be turned into a useful pandas DataFrame: >>> spontaneous_reaches = pd.DataFrame(mouse.get_spontaneous_reaches())

reach.Cohort

class reach.Cohort(mice=None, mouse_ids=None)

Bases: collections.abc.Sequence

Represents a cohort of multiple mice who have undergone behavioural training. These can be indexed to easily access a specific mouse.

Parameters

  • mice (list of Mouse instances, optional) – A list containing a Mouse intance for each mouse in the cohort.

  • mouse_ids (list of strs, optional) – A list of mouse IDs.

classmethod init_from_files(data_dir, mouse_ids)

Initialise the cohort of mice using training files stored within the same folder.

Parameters

  • data_dir (str) – Directory containing the training data files.

  • mouse_ids (list of strs) – IDs for the mice to be handled within the cohort.

get_trials(collapse_days: bool = True)

Get trial data for all mice across all sessions.

This can easily be turned into a useful pandas DataFrame: >>> trials = pd.DataFrame(cohort.get_trials())

get_results(collapse_days: bool = True)

Get the high-level results for all training sessions for all mice.

This can easily be turned into a useful pandas DataFrame: >>> results = pd.DataFrame(cohort.get_results())

get_spontaneous_reaches()

Get the data on spontaneous reach timings and locations for all mice.

This can easily be turned into a useful pandas DataFrame: >>> spontaneous_reaches = pd.DataFrame(cohort.get_spontaneous_reaches())