one.alf.files¶

Module for identifying and parsing ALF file names.

An ALF file has the following components (those in brackets are optional):: (_namespace_)object.attribute(_timescale)(.extra.parts).ext
Note the following:: Object attributes may not contain an underscore unless followed by ‘times’ or ‘intervals’. A namespace must not contain extra underscores (i.e. name_space and __namespace__ are not valid) ALF files must always have an extension
For more information, see the following documentation:: https://int-brain-lab.github.io/iblenv/one_docs/one_reference.html#alf # FIXME Change link

Created on Tue Sep 11 18:06:21 2018

@author: Miles

Functions

`add_uuid_string`	Add a UUID and an extra part to the filename of an ALF path
`filename_parts`	Return the parsed elements of a given ALF filename.
`folder_parts`
`get_alf_path`	Returns the ALF part of a path or filename Attempts to return the first valid part of the path, first searching for a session path, then relative path (collection/revision/filename), then just the filename.
`get_session_path`	Returns the session path from any filepath if the date/number pattern is found
`path_parts`
`rel_path_parts`	Parse a relative path into the relevant parts.
`session_path_parts`	Parse a session path into the relevant parts

rel_path_parts(rel_path, as_dict=False, assert_valid=True)[source]¶

Parse a relative path into the relevant parts. A relative path follows the pattern (collection/)(#revision#/)_namespace_object.attribute_timescale.extra.extension

Parameters

rel_path (str) – A relative path string
as_dict (bool) – If true, an OrderedDict of parts are returned with the keys (‘lab’, ‘subject’, ‘date’, ‘number’), otherwise a tuple of values are returned
assert_valid (bool) – If true a ValueError is raised when the session cannot be parsed, otherwise an empty dict of tuple of Nones is returned

Returns

Return type

An OrderedDict if as_dict is true, or a tuple of parsed values

session_path_parts(session_path: str, as_dict=False, assert_valid=True)[source]¶

Parse a session path into the relevant parts

Parameters

session_path (str) – A session path string
as_dict (bool) – If true, an OrderedDict of parts are returned with the keys (‘lab’, ‘subject’, ‘date’, ‘number’), otherwise a tuple of values are returned
assert_valid (bool) – If true a ValueError is raised when the session cannot be parsed, otherwise an empty dict of tuple of Nones is returned

Returns

Return type

An OrderedDict if as_dict is true, or a tuple of parsed values

filename_parts(filename, as_dict=False, assert_valid=True)[source]¶

Return the parsed elements of a given ALF filename.

Parameters

filename (str) – The name of the file
as_dict (bool) – When true a dict of matches is returned
assert_valid (bool) – When true an exception is raised when the filename cannot be parsed

Returns

namespace (str) – The _namespace_ or None if not present
object (str) – ALF object
attribute (str) – The ALF attribute
timescale (str) – The ALF _timescale or None if not present
extra (str) – Any extra parts to the filename, or None if not present
extension (str) – The file extension

Examples

>>> filename_parts('_namespace_obj.times_timescale.extra.foo.ext')
('namespace', 'obj', 'times', 'timescale', 'extra.foo', 'ext')
>>> filename_parts('spikes.clusters.npy', as_dict=True)
{'namespace': None,
 'object': 'spikes',
 'attribute': 'clusters',
 'timescale': None,
 'extra': None,
 'extension': 'npy'}
>>> filename_parts('spikes.times_ephysClock.npy')
(None, 'spikes', 'times', 'ephysClock', None, 'npy')
>>> filename_parts('_iblmic_audioSpectrogram.frequencies.npy')
('iblmic', 'audioSpectrogram', 'frequencies', None, None, 'npy')
>>> filename_parts('_spikeglx_ephysData_g0_t0.imec.wiring.json')
('spikeglx', 'ephysData_g0_t0', 'imec', None, 'wiring', 'json')
>>> filename_parts('_spikeglx_ephysData_g0_t0.imec0.lf.bin')
('spikeglx', 'ephysData_g0_t0', 'imec0', None, 'lf', 'bin')
>>> filename_parts('_ibl_trials.goCue_times_bpod.csv')
('ibl', 'trials', 'goCue_times', 'bpod', None, 'csv')

path_parts(file_path: str) → dict[source]¶

folder_parts(folder_path: str) → dict[source]¶

get_session_path(path: Union[str, pathlib.Path]) → Optional[pathlib.Path][source]¶: Returns the session path from any filepath if the date/number pattern is found

get_alf_path(path: Union[str, pathlib.Path]) → str[source]¶

Returns the ALF part of a path or filename Attempts to return the first valid part of the path, first searching for a session path, then relative path (collection/revision/filename), then just the filename. If all invalid, None is returned.

NB: There is no way to discern between lab/Subjects/subject/date/number and irrelevant/subject/date/number

Parameters: path (str, pathlib.Path) – A path to parse
Returns
Return type: A string containing the full ALF path, session path, relative path or filename

Examples

get_alf_path(‘etc/etc/lab/subj/2021-01-21/001’) ‘lab/subj/2021-01-21/001/collection/file.attr.ext’

get_alf_path(‘subj/2021-01-21/001/collection/file.attr.ext’) ‘file.attr.ext’

get_alf_path(‘collection/file.attr.ext’) ‘collection/file.attr.ext’

add_uuid_string(file_path, uuid)[source]¶

Add a UUID and an extra part to the filename of an ALF path

Parameters

file_path (str, pathlib.Path) – An ALF path to add the UUID to
uuid (str, uuid.UUID) – The UUID to add

Returns

Return type

A new Path object with a UUID in the filename