one.registration

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

Functions

get_dataset_type

Get the dataset type from a given filename.

Classes

RegistrationClient

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.

Parameters:

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

Raises:

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.

Parameters:

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

Returns:

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

Parameters:

  • 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, datetime.date, 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.

Returns:

  • pathlib.Path – New local session path.

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

Examples

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')
find_files(session_path)[source]

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

Parameters:

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

Yields:

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.

Parameters:

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

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

Examples

>>> client.assert_exists('ALK_036', 'subjects')
>>> client.assert_exists('user_45', 'users')
>>> client.assert_exists('local_server', 'repositories')
Raises:
Returns:

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

Parameters:

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

Returns:

The datetime as an ISO 8601 string

Return type:

str

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.

Parameters:

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

Returns:

  • dict – An Alyx session record

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

Raises:

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

prepare_files(file_list, versions=None)[source]

Validates file list for registration and splits files into a list of files per session path.

Parameters:

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

Returns:

  • list of dicts – A dict containing a list of files for each session

  • list of dicts – A dict containg a list of versions for each session

  • list – A list of files converted to paths

  • bool – A boolean indicating if input was a single file

check_protected_files(file_list, created_by=None)[source]

Check whether a set of files associated to a session are protected

Parameters:

  • 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).

Returns:

A status for each session whether any of the files specified are protected datasets or not.If none of the datasets are protected, a response with status 200 is returned, if any of the files are protected a response with status 403 is returned.

Return type:

list of dicts, dict

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.

Parameters:

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

Returns:

A list of newly created Alyx dataset records or the registration data if dry. If a single file is passed in, a single dict is returned.

Return type:

list of dicts, dict

Notes

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

Raises:

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

Parameters:

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

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

  • date_time (str, datetime.datetime, datetime.date) – 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

Returns:

A water administration record

Return type:

dict

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

Register a subject weight to Alyx.

Parameters:

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

  • weight (float) – The subject weight in grams.

  • date_time (str, datetime.datetime, datetime.date) – 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.

Returns:

An Alyx weight record

Return type:

dict

Raises: