Session creation and datasets registration

The RegistrationClient provides an high-level API for creating experimentation sessions on Alyx and registering associated datasets.

Summary of methods

create_new_session - Create a new local session folder and optionally create session record on Alyx create_session - Create session record on Alyx from local path, without registering files create_sessions - Create sessions and register files for folder containing a given flag file register_session - Create a session on Alyx from local path and register any ALF datasets present register_files - Register a list of files to their respective sessions on Alyx



Object that keeps the ONE instance and provides method to create sessions and register data.

class RegistrationClient(one=None)[source]

Bases: object

Object that keeps the ONE instance and provides method to create sessions and register data.

create_sessions(root_data_folder, glob_pattern='**/create_me.flag', dry=False)[source]

Create sessions looking recursively for flag files

  • root_data_folder (str, pathlib.Path) – Folder to look for sessions

  • glob_pattern (str) – Register valid sessions that contain this pattern

  • dry (bool) – If true returns list of sessions without creating them on Alyx


  • list of pathlib.Paths – Newly created session paths

  • list of dicts – Alyx session records

create_session(session_path, **kwargs) dict[source]

Create a remote session on Alyx from a local session path, without registering files

  • session_path (str, pathlib.Path) – The path ending with subject/date/number.

  • **kwargs – Optional arguments for RegistrationClient.register_session.


Newly created session record.

Return type


create_new_session(subject, session_root=None, date=None, register=True, **kwargs)[source]

Create a new local session folder and optionally create session record on Alyx

  • subject (str) – The subject name. Must exist on Alyx.

  • session_root (str, pathlib.Path) – The root folder in which to create the subject/date/number folder. Defaults to ONE cache directory.

  • date (datetime.datetime,, str) – An optional date for the session. If None the current time is used.

  • register (bool) – If true, create session record on Alyx database

  • **kwargs – Optional arguments for RegistrationClient.register_session.


  • pathlib.Path – New local session path

  • uuid.UUID – The experiment UUID if register is True


Create a local session only

>>> session_path, _ = RegistrationClient().create_new_session('Ian', register=False)

Register a session on Alyx in a specific location

>>> session_path, eid = RegistrationClient().create_new_session('Sy', '/data/lab/Subjects')

Create a session for a given date

>>> session_path, eid = RegistrationClient().create_new_session('Ian', date='2020-01-01')

Returns an generator of file names that match one of the dataset type patterns in Alyx


session_path (str, pathlib.Path) – The session path to search


Iterable of file paths that match the dataset type patterns in Alyx

Return type


assert_exists(member, endpoint)[source]

Raise an error if a given member doesn’t exist on Alyx database

  • member (str, uuid.UUID, list) – The member ID(s) to verify

  • endpoint (str) – The endpoint at which to look it up


>>> client.assert_exists('ALK_036', 'subjects')
>>> client.assert_exists('user_45', 'users')
>>> client.assert_exists('local_server', 'repositories')
static ensure_ISO8601(date) str[source]

Ensure provided date is ISO 8601 compliant


date (str, None,, datetime.datetime) – An optional date to convert to ISO string. If None, the current datetime is used.


The datetime as an ISO 8601 string

Return type


register_session(ses_path, users=None, file_list=True, **kwargs)[source]

Register session in Alyx

NB: If providing a lab or start_time kwarg, they must match the lab (if there is one) and date of the session path.

  • ses_path (str, pathlib.Path) – The local session path

  • users (str, list) – The user(s) to attribute to the session

  • file_list (bool, list) – An optional list of file paths to register. If True, all valid files within the session folder are registered. If False, no files are registered

  • location (str) – The optional location within the lab where the experiment takes place

  • procedures (str, list) – An optional list of procedures, e.g. ‘Behavior training/tasks’

  • n_correct_trials (int) – The number of correct trials (optional)

  • n_trials (int) – The total number of completed trials (optional)

  • json (dict, str) – Optional JSON data

  • projects (str, list) – The project(s) to which the experiment belongs (optional)

  • type (str) – The experiment type, e.g. ‘Experiment’, ‘Base’

  • task_protocol (str) – The task protocol (optional)

  • lab (str) – The name of the lab where the session took place. If None the lab name will be taken from the path. If no lab name is found in the path (i.e. no <lab>/Subjects) the default lab on Alyx will be used.

  • start_time (str, datetime.datetime) – The precise start time of the session. The date must match the date in the session path.

  • end_time (str, datetime.datetime) – The precise end time of the session.


  • dict – An Alyx session record

  • list, None – Alyx file records (or None if file_list is False)

  • AssertionError – Subject does not exist on Alyx or provided start_time does not match date in session path.

  • ValueError – The provided lab name does not match the one found in the session path or start_time/end_time is not a valid ISO date time.

  • requests.HTTPError – A 400 status code means the submitted data was incorrect (e.g. task_protocol was an int instead of a str); A 500 status code means there was a server error.

  • ConnectionError – Failed to connect to Alyx, most likely due to a bad internet connection.

register_files(file_list, versions=None, default=True, created_by=None, server_only=False, repository=None, dry=False, max_md5_size=None)[source]

Registers a set of files belonging to a session only on the server

  • file_list (list, str, pathlib.Path) – A filepath (or list thereof) of ALF datasets to register to Alyx

  • created_by (str) – Name of Alyx user (defaults to whoever is logged in to ONE instance)

  • repository (str) – Name of the repository in Alyx to register to

  • server_only (bool) – Will only create file records in the ‘online’ repositories and skips local repositories

  • versions (list of str) – Optional version tags

  • default (bool) – Whether to set as default revision (defaults to True)

  • dry (bool) – When true returns POST data for registration endpoint without submitting the data

  • max_md5_size (int) – Maximum file in bytes to compute md5 sum (always compute if None)


A list of newly created Alyx dataset records or the registration data if dry

Return type

list of dicts, dict

register_water_administration(subject, volume, **kwargs)[source]

Register a water administration to Alyx for a given subject

  • subject (str) – A subject nickname that exists on Alyx

  • volume (float) – The total volume administrated in ml

  • date_time (str, datetime.datetime, – The time of administration. If None, the current time is used.

  • water_type (str) – A water type that exists in Alyx; default is ‘Water’

  • user (str) – The user who administrated the water. Currently logged-in user is the default.

  • session (str, UUID, pathlib.Path, dict) – An optional experiment ID to associate

  • adlib (bool) – If true, indicates that the subject was given water ad libitum


A water administration record

Return type


register_weight(subject, weight, date_time=None, user=None)[source]

Register a subject weight to Alyx

  • subject (str) – A subject nickname that exists on Alyx

  • weight (float) – The subject weight in grams

  • date_time (str, datetime.datetime, – The time of weighing. If None, the current time is used.

  • user (str) – The user who performed the weighing. Currently logged-in user is the default.


An Alyx weight record

Return type