Python API

Module contents

Lab specific code. Depends of on our schema

flexiznam.main module

flexiznam.main.add_dataset(parent_id, dataset_type, created, path, is_raw='yes', project_id=None, flexilims_session=None, dataset_name=None, attributes=None, strict_validation=False, conflicts='append')

Add a dataset as a child of a recording, session, or sample

Parameters

• parent_id (str) – hexadecimal ID of the parent (session or recording)

• dataset_type (str) – dataset_type, must be a type define in the config file

• created (str) – date of creation as text, usually in this format: ‘2021-05-24 14:56:41’

• path (str) – path to the data relative to the project folder

• is_raw (str) – yes or no, used to find the root directory

• project_id (str) – hexadecimal ID or name of the project

• flexilims_session (flexilims.Flexilims) – authentication session for flexilims

• dataset_name (str) – name of the dataset, will be autogenerated if not provided

• attributes (dict) – optional attributes

• strict_validation (bool) – default False, if True, only attributes in lab settings are allowed

• conflicts (str) – abort, skip, append, what to do if a dataset with this name already exists? abort to crash, skip to ignore and return the online version, append to increment name and create a new dataset.

Returns

the flexilims response

flexiznam.main.add_entity(datatype, name, origin_id=None, attributes={}, other_relations=None, flexilims_session=None, project_id=None)

Add a new entity on flexilims. Name must be unique

Parameters

• datatype (str) – flexilims type

• name (str) – name on flexilims

• origin_id (str or None) – hexadecimal id of the origin

• attributes (dict or None) – attributes to update

• other_relations (str or list of str) – hexadecimal ID(s) of custom entities link to the entry to update

• project_id (str) – text name of the project

• flexilims_session (flexilims.Flexilims) – Flexylims session object

Returns

flexilims reply

flexiznam.main.add_experimental_session(mouse_name, date, attributes={}, session_name=None, other_relations=None, flexilims_session=None, project_id=None, conflicts='abort')

Add a new session as a child entity of a mouse

Parameters

• mouse_name (str) – name of the mouse. Must exist on flexilims

• date (str) – date of the session. If session_name is not provided, will be used as name

• attributes (dict) – dictionary of additional attributes (on top of date)

• session_name (str or None) – name of the session, usually in the shape S20210420.

• conflicts (str) – What to do if a session with that name already exists? Can be skip for skiping creation and returning the session from flexilims or abort to crash

• other_relations – ID(s) of custom entities related to the session

• flexilims_session (flexilims.Flexilims) – flexilims session

• project_id (str) – name of the project or hexadecimal project id (needed if session is not provided)

Returns

flexilims reply

flexiznam.main.add_mouse(mouse_name, project_id, flexilims_session=None, mcms_animal_name=None, flexilims_username=None, mcms_username=None, flexilims_password=None)

Check if a mouse is already in the database and add it if it isn’t

Parameters

• mouse_name –

• project_id –

• flexilims_session (flexilims.Flexilims) –

• mcms_animal_name –

• mcms_username –

Returns

flexilims reply

flexiznam.main.add_recording(session_id, recording_type, protocol, attributes=None, recording_name=None, conflicts='abort', other_relations=None, flexilims_session=None, project_id=None)

Add a recording as a child of an experimental session

Parameters

• session_id (str) – hexadecimal ID of the session. Must exist on flexilims

• recording_type (str) – one of [two_photon, widefield, intrinsic, ephys, behaviour]

• protocol (str) – experimental protocol (retinotopy for instance)

• attributes (dict) – dictionary of additional attributes (on top of protocol and recording_type)

• recording_name (str or None) – name of the recording, usually in the shape R152356.

• conflicts (str) – skip or abort: how to handle conflicts

• other_relations – ID(s) of custom entities related to the session

• flexilims_session (flexilims.Flexilims) – flexilims session

• project_id (str) – name of the project or hexadecimal project id (needed if session is not provided)

Returns

flexilims reply

flexiznam.main.add_sample(parent_id, attributes=None, sample_name=None, conflicts='skip', other_relations=None, flexilims_session=None, project_id=None)

Add a sample as a child of a mouse or another sample

Default conflict behaviour for samples is skip, as we will often add from the same sample multiple occasions.

Parameters

• parent_id (str) – hexadecimal ID of the parent entity. Must exist on flexilims.

• attributes (dict) – dictionary of additional attributes.

• sample_name (str or None) – name of the sample.

• conflicts (str) – skip or abort: how to handle conflicts.

• other_relations – ID(s) of custom entities related to the sample.

• flexilims_session (flexilims.Flexilims) – flexilims session.

• project_id (str) – name of the project or hexadecimal project id (required if session is not provided).

Returns

flexilims reply

flexiznam.main.format_results(results)

Make request output a nice DataFrame

This will crash if any attribute is also present in the flexilims reply, i.e. if an attribute is named: ‘id’, ‘type’, ‘name’, ‘incrementalId’, ‘createdBy’, ‘dateCreated’, ‘origin_id’, ‘objects’, ‘customEntities’, or ‘project’

Parameters

results (list of dict) – Flexilims reply

Returns

Reply formatted as a DataFrame

Return type

pandas.DataFrame

flexiznam.main.generate_name(datatype, name, flexilims_session=None, project_id=None)

Generate a number for incrementally increasing the numeric suffix

flexiznam.main.get_children(parent_id, children_datatype, project_id=None, flexilims_session=None)

Get all entries belonging to a particular parent entity

Parameters

• parent_id (str) – hexadecimal id of the parent entity

• children_datatype (str) – type of child entities to fetch

• project_id (str) – text name of the project

• flexilims_session (flexilims.Flexilims) – Flexylims session object

Returns

containing all the relevant child entitites

Return type

DataFrame

flexiznam.main.get_datasets(origin_id, recording_type=None, dataset_type=None, project_id=None, flexilims_session=None)

Recurse into recordings and get paths to child datasets of a given type.

For example, this is useful if you want to retrieve paths to all scanimage datasets associated with a given session.

Parameters

• origin_id (str) – hexadecimal ID of the origin session.

• recording_type (str) – type of the recording to filter by. If None, will return datasets for all recordings.

• dataset_type (str) – type of the dataseet to filter by. If None, will return all datasets.

• project_id (str) – text name of the project. Not required if flexilims_session is provided.

• flexilims_session (flexilims.Flexilims) – Flexylims session object

Returns

Dictionary with recording names as keys containing lists of associated dataset paths.

Return type

dict

flexiznam.main.get_datatype(name=None, id=None, project_id=None, flexilims_session=None)

Loop through possible datatypes and return the first with a matching name.

Warning

If there are multiple matches, will return only the first one found!

Parameters

• name (str) – (optional, if id is provided) name of the entity

• id (str) – (optional, if name is provided) hexadecimal id of the entity

• project_id (str) – (optional, if flexilims_session is provided) text name of the project

• flexilims_session (flexilims.Flexilims) – (optional, if project_id is provided) Flexylims session object

Returns

datatype of the matching entity.

Return type

str

flexiznam.main.get_entities(datatype='mouse', query_key=None, query_value=None, project_id=None, flexilims_session=None, name=None, origin_id=None, id=None, format_reply=True)

Get entities of a given type and format results.

Entities can be filtered by name, id, origin, or attribute (using the query_key / query_value arguments).

Parameters

• datatype (str) – type of Flexylims entity to fetch, e.g. ‘mouse’, ‘session’, ‘recording’, or ‘dataset’. This is the only mandatory argument.

• query_key (str) – attribute to filter by.

• query_value (str) – attribute value to select

• project_id (str) – text name of the project. Either project_id or flexilims_session must be provided.

• flexilims_session (flexilims.Flexilims) – Flexylims session object. This is preferred to providing project_id as it avoids creating new authentication tokens.

• name (str) – filter by name

• origin_id (str) – filter by origin / parent

• id (str) – filter by hexadecimal id

• format_reply (bool) – (default True) whether to format the reply into a Dataframe. If this is set to false, a list of dictionaries will be returned instead.

Returns

containing all matching entities

Return type

pandas.DataFrame

flexiznam.main.get_entity(datatype=None, query_key=None, query_value=None, project_id=None, flexilims_session=None, name=None, origin_id=None, id=None, format_reply=True)

Get one entity and format result.

Calls flexiznam.main.get_entities() but expects only one result and returns a pandas.Series instead of a pandas.DataFrame. If multiple entities on the database match the query, raise a flexiznam.errors.NameNotUniqueError, if nothing matches returns None.

Parameters

• datatype (str) – type of Flexylims entity to fetch, e.g. ‘mouse’, ‘session’, ‘recording’, or ‘dataset’. This is the only mandatory argument.

• query_key (str) – attribute to filter by.

• query_value (str) – attribute value to select

• project_id (str) – text name of the project. Either project_id or flexilims_session must be provided.

• flexilims_session (flexilims.Flexilims) – Flexylims session object. This is preferred to providing project_id as it avoids creating new authentication tokens.

• name (str) – filter by name

• origin_id (str) – filter by origin / parent

• id (str) – filter by hexadecimal id

• format_reply (bool) – (default True) whether to format the reply into a Dataframe. If this is set to false, a list of dictionaries will be returned instead.

Returns

containing the entity or dictionary if format_reply is False

Return type

pandas.Series

flexiznam.main.get_experimental_sessions(project_id=None, flexilims_session=None, mouse=None)

Get all sessions from a given mouse

flexiznam.main.get_flexilims_session(project_id, username=None, password=None)

Open a new flexilims session by creating a new authentication token.

Parameters

• project_id (str) – name of the project. Automatically converted to the corresponding hexadecimal ID by looking up the config file.

• username (str) – (optional) flexilims username. If not provided, it is read from the config file.

• password (str) – (optional) flexilims password. If not provided, it is read from the secrets file, or failing that triggers an input prompt.

Returns

Flexilims session object.

Return type

flexilims.Flexilims

flexiznam.main.get_id(name, datatype='mouse', project_id=None, flexilims_session=None)

Get database ID for entity by name

flexiznam.main.get_path(name, datatype='mouse', project_id=None, flexilims_session=None)

Get database ID for entity by name

flexiznam.main.update_entity(datatype, name=None, id=None, origin_id=None, mode='overwrite', attributes={}, other_relations=None, flexilims_session=None, project_id=None)

Update one entity identified with its datatype and name or id

Parameters

• datatype (str) – flexilims type

• name (str) – name on flexilims

• origin_id (str or None) – hexadecimal id of the origin

• mode (str) –

  what to do with attributes that are not explicitly specified.

  overwrite

  (default) all attributes that already exist on flexilims but are not specified in the function call are set to ‘null’.

  update

  update the attributes given in this call and do not change the others.

• attributes (dict or None) – attributes to update

• project_id (str) – text name of the project

• flexilims_session (flexilims.Flexilims) – Flexylims session object

Returns

flexilims reply

flexiznam.errors module

exception flexiznam.errors.ConfigurationError

Bases: Exception

The configuration file cannot be loaded

exception flexiznam.errors.DatasetError

Bases: Exception

Cannot automatically deal with this dataset

exception flexiznam.errors.FlexilimsError

Bases: Exception

I cannot do that on flexilims

exception flexiznam.errors.NameNotUniqueError

Bases: Exception

Mouse name does not correspond to exactly 1 entry

exception flexiznam.errors.SyncYmlError

Bases: Exception

The YAML file used for synchronisation is invalid

flexiznam.utils module

flexiznam.utils.clean_dictionary_recursively(dictionary, keys=(), path2string=True, format_dataset=False)

Recursively clean a dictionary inplace

Parameters

• dictionary – dict (of dict)

• keys (list) – list of keys to pop from the dictionary

• path2string (bool) – replace pathlib.Path object by their string representation (default True)

• format_dataset (bool) – replace flexiznam.schema.Dataset instances by their yaml representation (default False)

flexiznam.utils.compare_series(first_series, second_series, series_name=('first', 'second'))

Compare two series and return a dataframe of differences

Parameters

• first_series – first pandas.Series

• second_series – second pandas.Series

• series_name – tuple of name for the two series.

Returns

DataFrame of differences

Return type

pandas.DataFrame

Subpackages

• flexiznam.camp package
  • Module contents
  • flexiznam.camp.sync_data module
• flexiznam.config package
  • Module contents
  • flexiznam.config.config_tools module
  • flexiznam.config.default_config module
• flexiznam.mcms package
  • Module contents
  • flexiznam.mcms.main module
• flexiznam.schema package
  • Module contents
    • Usage
  • flexiznam.schema.datasets module
  • flexiznam.schema.camera_data module
  • flexiznam.schema.harp_data module
  • flexiznam.schema.scanimage_data module
  • flexiznam.schema.microscopy_data module