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_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



Get the dataset type from a given filename.



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

get_dataset_type(filename, dtypes)[source]

Get the dataset type from a given filename.

A dataset type is matched one of two ways:

  1. the filename matches the dataset type filename_pattern;

  2. if filename_pattern is empty, the filename object.attribute matches the dataset type name.

  • filename (str, pathlib.Path) – The filename or filepath.

  • dtypes (iterable) – An iterable of dataset type objects with the attributes (‘name’, ‘filename_pattern’).

Return type:

The matching dataset type object for filename.


ValueError – filename doesn’t match any of the dataset types filename matches multiple dataset types

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', register_files=False, 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.

  • register_files (bool) – If true, register all valid datasets within the session folder.

  • 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_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


pathlib.Path – File paths that match the dataset type patterns in Alyx

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')

The endpoint data if member exists.

Return type:

dict, list of dict

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, exists=True, dry=False, max_md5_size=None, **kwargs)[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.

  • versions (str, list of str) – Optional version tags.

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

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

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

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

  • exists (bool) – Whether the files exist on the repository (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).

  • exists – Whether files exist in the repository. May be set to False when registering files before copying to the repository.

  • **kwargs – Extra arguments directly passed as REST request data to /register-files endpoint.


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

Return type:

list of dicts, dict


  • The registered files may be automatically moved to new revision folders if they are protected on Alyx, therefore it’s important to check the relative paths of the output.

  • Protected datasets are not checked in dry mode.

  • In most circumstances a new revision will be added automatically, however if this fails a 403 HTTP status may be returned.


requests.exceptions.HTTPError – Submitted data not valid (400 status code) Server side database error (500 status code) Revision protected (403 status code)

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: