one.alf.path

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/ONE/alf_intro.html

ALFPath differences

ALFPath.iter_datasets returns full paths (close the pathlib.Path.iterdir), whereas alf.io.iter_datasets returns relative paths as POSIX strings (TODO).

ALFPath.parse_* methods return a dict by default, whereas parse_* functions return tuples by default. Additionally, the parse_* functions raise ALFInvalid errors by default if the path can’t be parsed. ALFPath.parse_* methods have no validation option.

ALFPath properties return empty str instead of None if ALF part isn’t present..

Functions

`add_uuid_string`	Add a UUID to the filename of an ALF path.
`ensure_alf_path`	Ensure path is a PureALFPath instance.
`filename_parts`	Return the parsed elements of a given ALF filename.
`folder_parts`	Parse all folder parts, including session, collection and revision.
`full_path_parts`	Parse all filename and folder parts.
`get_alf_path`	Returns the ALF part of a path or filename.
`get_session_path`	Returns the session path from any filepath if the date/number pattern is found, including the root directory.
`padded_sequence`	Ensures a file path contains a zero-padded experiment sequence folder.
`rel_path_parts`	Parse a relative path into the relevant parts.
`remove_uuid_string`	Remove UUID from a filename of an ALF path.
`session_path_parts`	Parse a session path into the relevant parts.
`without_revision`	Return file path without a revision folder.

Classes

`ALFPath`	Base class for manipulating Alyx file (ALF) paths with system calls.
`PosixALFPath`	ALFPath subclass for non-Windows systems.
`PureALFPath`	Base class for manipulating Alyx file (ALF) paths without I/O.
`PurePosixALFPath`	PureALFPath subclass for non-Windows systems.
`PureWindowsALFPath`	PureALFPath subclass for Windows systems.
`WindowsALFPath`	ALFPath subclass for Windows systems.

class ALFPath(*args)[source]

Bases: PureALFPath

Base class for manipulating Alyx file (ALF) paths with system calls.

Similar to a pathlib Path object but with methods for validating, parsing, and replacing ALF path parts. This class also contains methods that work on system files.

Parameters:: args (str, pathlib.PurePath) – One or more pathlike objects to combine into an ALF path object.

is_dataset() → bool[source]

Determine if path is an ALF dataset, rather than a folder.

Unlike pathlib and PureALFPath methods, this will return False if the path exists but is a folder, otherwise this simply tests the path name, whether it exists or not.

Returns:: True if filename is ALF dataset.
Return type:: bool

is_session_path() → bool[source]

Check if path is a valid ALF session path.

This returns true if the input path matches the ALF session path specification. This method can be used as a static method with any pathlike input, or as an instance method.

Unlike the PureALFPath method, this will return false if the path matches but is in fact a file on disk.

Parameters:: path (str, pathlib.PurePath) – A session path to check the validity of.
Returns:: True if the path is recognized as a valid ALF session path.
Return type:: bool

Examples

>>> ALFPath('/home/foo/2020-01-01/001').is_session_path()
True

>>> ALFPath('/home/foo/2020-01-01/001/alf/spikes.times.npy').is_session_path()
False

>>> ALFPath.is_session_path('_ibl_wheel.timestamps.npy')
False

>>> ALFPath.is_valid_alf('lab/Subjects/foo/2020-01-01/001')
True

See also

PureALFPath.is_valid_alf, PureALFPath.session_path_parts

is_valid_alf() → bool[source]

Check if path is a valid ALF path.

This returns true if the input path matches any part of the ALF path specification. This method can be used as a static method with any pathlike input, or as an instance method. This will validate both directory paths and file paths.

Unlike the PureALFPath method, this one will return false if the path matches a dataset file pattern but is actually a folder on disk, or if the path matches as a file but is is a folder on disk.

Parameters:: path (str, pathlib.PurePath) – A path to check the validity of.
Returns:: True if the path is recognized as a valid ALF path.
Return type:: bool

Examples

>>> ALFPath('/home/foo/2020-01-01/001').is_valid_alf()
True

>>> ALFPath('/home/foo/2020-01-01/001/alf/spikes.times.npy').is_valid_alf()
True

>>> ALFPath.is_valid_alf('_ibl_wheel.timestamps.npy')
True

>>> ALFPath.is_valid_alf('foo.bar')
False

See also

PureALFPath.is_dataset, full_path_parts

iter_datasets(recursive=False)[source]

Iterate over all files in path, and yield relative dataset paths.

Parameters:: recursive (bool) – If true, yield datasets in subdirectories.
Yields:: ALFPath – The next valid dataset path in lexicographical order.

See also

one.alf.io.iter_datasets: paths relative to the input path.

class PureALFPath(*args)[source]

Bases: PurePath

Base class for manipulating Alyx file (ALF) paths without I/O.

Similar to a pathlib PurePath object but with methods for validating, parsing, and replacing ALF path parts.

Parameters:: args (str, pathlib.PurePath) – One or more pathlike objects to combine into an ALF path object.

is_dataset()[source]

Determine if path is an ALF dataset, rather than a folder.

Returns:: True if filename is ALF dataset.
Return type:: bool

is_valid_alf() → bool[source]

Check if path is a valid ALF path.

This returns true if the input path matches any part of the ALF path specification. This method can be used as a static method with any pathlike input, or as an instance method. This will validate both directory paths and file paths.

Parameters:: path (str, pathlib.PurePath) – A path to check the validity of.
Returns:: True if the path is recognized as a valid ALF path.
Return type:: bool

Examples

>>> ALFPath('/home/foo/2020-01-01/001').is_valid_alf()
True

>>> ALFPath('/home/foo/2020-01-01/001/alf/spikes.times.npy').is_valid_alf()
True

>>> ALFPath.is_valid_alf('_ibl_wheel.timestamps.npy')
True

>>> ALFPath.is_valid_alf('foo.bar')
False

See also

PureALFPath.is_dataset, full_path_parts

is_session_path() → bool[source]

Check if path is a valid ALF session path.

This returns true if the input path matches the ALF session path specification. This method can be used as a static method with any pathlike input, or as an instance method.

Parameters:: path (str, pathlib.PurePath) – A session path to check the validity of.
Returns:: True if the path is recognized as a valid ALF session path.
Return type:: bool

Examples

>>> ALFPath('/home/foo/2020-01-01/001').is_session_path()
True

>>> ALFPath('/home/foo/2020-01-01/001/alf/spikes.times.npy').is_session_path()
False

>>> ALFPath.is_session_path('_ibl_wheel.timestamps.npy')
False

>>> ALFPath.is_valid_alf('lab/Subjects/foo/2020-01-01/001')
True

See also

PureALFPath.is_valid_alf, PureALFPath.session_path_parts

session_path()[source]

Extract the full session path.

Returns the session path from the filepath if the date/number pattern is found, including the root directory.

Returns:: The session path part of the input path or None if path invalid.
Return type:: PureALFPath

Examples

>>> ALFPath('/mnt/sd0/Data/lab/Subjects/subject/2020-01-01/001').session_path()
ALFPath('/mnt/sd0/Data/lab/Subjects/subject/2020-01-01/001')

>>> ALFPath('C:\Data\subject\2020-01-01\1\trials.intervals.npy').session_path()
ALFPath('C:/Data/subject/2020-01-01/1')

session_path_short(include_lab=False) → str[source]

Return only the ALF session path as a posix str.

Params

include_labbool: If true, the lab/subject/date/number is returned, otherwise the lab part is dropped.

returns:: The session path part of the input path or None if path invalid.
rtype:: str

Examples

>>> ALFPath('/mnt/sd0/Data/lab/Subjects/subject/2020-01-01/001').session_path_short()
'subject/2020-01-01/001'

>>> alfpath = ALFPath('/mnt/sd0/Data/lab/Subjects/subject/2020-01-01/001')
>>> alfpath.session_path_short(include_lab=True)
'lab/subject/2020-01-01/001'

>>> ALFPath('C:\Data\subject\2020-01-01\1\trials.intervals.npy').session_path_short()
'subject/2020-01-01/1'

without_lab() → PureALFPath[source]

Return path without the <lab>/Subjects/ part.

If the <lab>/Subjects pattern is not found, the same path is returned.

Returns:: The same path without the <lab>/Subjects part.
Return type:: PureALFPath

relative_to_lab() → PureALFPath[source]

Return path relative to <lab>/Subjects/ part.

Returns:: The same path, relative to the <lab>/Subjects/ part.
Return type:: PureALFPath
Raises:: ValueError – The path doesn’t contain a <lab>/Subjects/ pattern.

relative_to_session()[source]

Return path relative to session part.

Returns:: The same path, relative to the <lab>/Subjects/<subject>/<date>/<number> part.
Return type:: PureALFPath
Raises:: ValueError – The path doesn’t contain a <lab>/Subjects/ pattern.

parse_alf_path(as_dict=True)[source]

Parse all filename and folder parts.

Parameters:: as_dict (bool) – When true a dict of matches is returned.
Returns:: A dict if as_dict is true, or a tuple of parsed values.
Return type:: OrderedDict, tuple

Examples

>>> alfpath = PureALFPath(
...     'lab/Subjects/subject/2020-01-01/001/collection/#revision#/'
...     '_namespace_obj.times_timescale.extra.foo.ext')
>>> alfpath.parse_alf_path()
{'lab': 'lab',
'subject': 'subject',
'date': '2020-01-01',
'number': '001',
'collection': 'collection',
'revision': 'revision',
'namespace': 'namespace',
'object': 'obj',
'attribute': 'times',
'timescale': 'timescale',
'extra': 'extra.foo',
'extension': 'ext'}

>>> PureALFPath('_namespace_obj.times_timescale.extra.foo.ext').parse_alf_path()
(None, None, None, None, None, None, 'namespace',
'obj', 'times','timescale', 'extra.foo', 'ext')

parse_alf_name(as_dict=True)[source]

Return the parsed elements of a given ALF filename.

Parameters:

as_dict (bool) – When true a dict of matches is returned.

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

>>> alfpath = PureALFPath(
...     'lab/Subjects/subject/2020-01-01/001/collection/#revision#/'
...     '_namespace_obj.times_timescale.extra.foo.ext')
>>> alfpath.parse_alf_name()
{'namespace': 'namespace',
'object': 'obj',
'attribute': 'times',
'timescale': 'timescale',
'extra': 'extra.foo',
'extension': 'ext'}

>>> PureALFPath('spikes.clusters.npy', as_dict=False)
(None, 'spikes', 'clusters', None, None, npy)

property dataset_name_parts

the dataset name parts, with empty strings for missing parts.

Type:: tuple of str

property session_parts

the session path parts, with empty strings for missing parts.

Type:: tuple of str

property alf_parts

the full ALF path parts, with empty strings for missing parts.

Type:: tuple of str

property namespace

The namespace part of the ALF name, or and empty str if not present.

Type:: str

property object

The object part of the ALF name, or and empty str if not present.

Type:: str

property attribute

The attribute part of the ALF name, or and empty str if not present.

Type:: str

property timescale

The timescale part of the ALF name, or and empty str if not present.

Type:: str

property extra

The extra part of the ALF name, or and empty str if not present.

Type:: str

with_object(obj)[source]

Return a new path with the ALF object changed.

Parameters:: obj (str) – An ALF object name part to use.
Returns:: The same file path but with the object part replaced with the input.
Return type:: PureALFPath
Raises:: ALFInvalid – The path is not a valid ALF dataset (e.g. doesn’t have a three-part filename, or contains invalid characters).

with_namespace(ns)[source]

Return a new path with the ALF namespace added or changed.

Parameters:: namespace (str) – An ALF namespace part to use.
Returns:: The same file path but with the namespace part added/replaced with the input.
Return type:: PureALFPath
Raises:: ALFInvalid – The path is not a valid ALF dataset (e.g. doesn’t have a three-part filename, or contains invalid characters).

with_attribute(attr)[source]

Return a new path with the ALF attribute changed.

Parameters:: attribute (str) – An ALF attribute part to use.
Returns:: The same file path but with the attribute part replaced with the input.
Return type:: PureALFPath
Raises:: ALFInvalid – The path is not a valid ALF dataset (e.g. doesn’t have a three-part filename, or contains invalid characters).

with_timescale(timescale)[source]

Return a new path with the ALF timescale added or changed.

Parameters:: timescale (str) – An ALF timescale part to use.
Returns:: The same file path but with the timescale part added/replaced with the input.
Return type:: PureALFPath
Raises:: ALFInvalid – The path is not a valid ALF dataset (e.g. doesn’t have a three-part filename, or contains invalid characters).

with_extra(extra, append=False)[source]

Return a new path with extra ALF parts added or changed.

Parameters:

extra (str, list of str) – Extra ALF parts to add/replace.
append (bool) – When false (default) any existing extra parts are replaced instead of added to.

Returns:

The same file path but with the extra part(s) replaced or appended to with the input.

Return type:

PureALFPath

Raises:

ALFInvalid – The path is not a valid ALF dataset (e.g. doesn’t have a three-part filename, or contains invalid characters).

with_extension(ext)[source]

Return a new path with the ALF extension (suffix) changed.

Note that unlike PurePath’s with_suffix method, this asserts that the filename is a valid ALF dataset and the ext argument should be without the period.

Parameters:: ext (str) – An ALF extension part to use (sans period).
Returns:: The same file path but with the extension part replaced with the input.
Return type:: PureALFPath
Raises:: ALFInvalid – The path is not a valid ALF dataset (e.g. doesn’t have a three-part filename, or contains invalid characters).

with_padded_sequence()[source]

Ensures a file path contains a zero-padded experiment sequence folder.

Parameters:: path (str pathlib.PurePath) – A session or file path to convert.
Returns:: The same path but with the experiment sequence folder zero-padded. If a PurePath was passed, a PurePath will be returned, otherwise a Path object is returned.
Return type:: ALFPath, PureALFPath

Examples

Supports calling as static function

>>> file_path = '/iblrigdata/subject/2023-01-01/1/_ibl_experiment.description.yaml'
>>> ALFPath.with_padded_sequence(file_path)
ALFPath('/iblrigdata/subject/2023-01-01/001/_ibl_experiment.description.yaml')

Supports folders and will not affect already padded paths

>>> ALFPath('subject/2023-01-01/001').with_padded_sequence(file_path)
ALFPath('subject/2023-01-01/001')

with_revision(revision)[source]

Return a new path with the ALF revision part added/changed.

Parameters:: revision (str) – An ALF revision part to use (NB: do not include the pound sign ‘#’).
Returns:: The same file path but with the revision part added or replaced with the input.
Return type:: PureALFPath

Examples

If not in the ALF path, one will be added

>>> ALFPath('/subject/2023-01-01/1/alf/obj.attr.ext').with_revision('revision')
ALFPath('/subject/2023-01-01/1/alf/#xxx#/obj.attr.ext')

If a revision is already in the ALF path it will be replaced

>>> ALFPath('/subject/2023-01-01/1/alf/#revision#/obj.attr.ext').with_revision('xxx')
ALFPath('/subject/2023-01-01/1/alf/#xxx#/obj.attr.ext')

Raises:

ALFInvalid – The ALF path is not valid or is relative to the session path. The path must include the session parts otherwise the path is too ambiguous to determine validity.
ALFInvalid – The revision provided does not match the ALF specification pattern.

See also

PureALFPath.without_revision

without_revision()[source]

Return a new path with the ALF revision part removed.

Returns:: The same file path but with the revision part removed.
Return type:: PureALFPath

Examples

If not in the ALF path, no change occurs

>>> ALFPath('/subject/2023-01-01/1/alf/obj.attr.ext').with_revision('revision')
ALFPath('/subject/2023-01-01/1/alf/obj.attr.ext')

If a revision is in the ALF path it will be removed

>>> ALFPath('/subject/2023-01-01/1/alf/#revision#/obj.attr.ext').without_revision()
ALFPath('/subject/2023-01-01/1/alf/obj.attr.ext')

Raises:: ALFInvalid – The ALF path is not valid or is relative to the session path. The path must include the session parts otherwise the path is too ambiguous to determine validity.

See also

PureALFPath.with_revision

with_uuid(uuid)[source]

Return a new path with the ALF UUID part added/changed.

Parameters:: uuid (str, uuid.UUID) – The UUID to add.
Returns:: A new ALFPath object with a UUID in the filename.
Return type:: PureALFPath

Examples

>>> uuid = 'a976e418-c8b8-4d24-be47-d05120b18341'
>>> ALFPath('/path/to/trials.intervals.npy').with_uuid(uuid)
ALFPath('/path/to/trials.intervals.a976e418-c8b8-4d24-be47-d05120b18341.npy')

Raises:

ValueError – uuid must be a valid hyphen-separated hexadecimal UUID.
ALFInvalid – Path is not a valid ALF file path.

without_uuid()[source]

Return a new path with the ALF UUID part removed.

Returns:: A new ALFPath object with a UUID removed from the filename, if present.
Return type:: PureALFPath

Examples

>>> alfpath = ALFPath('/path/to/trials.intervals.a976e418-c8b8-4d24-be47-d05120b18341.npy')
>>> alfpath.without_uuid(uuid)
ALFPath('/path/to/trials.intervals.npy')

>>> ALFPath('/path/to/trials.intervals.npy').without_uuid(uuid)
ALFPath('/path/to/trials.intervals.npy')

class WindowsALFPath(*args, **kwargs)[source]

Bases: WindowsPath, ALFPath

ALFPath subclass for Windows systems.

class PosixALFPath(*args, **kwargs)[source]

Bases: PosixPath, ALFPath

ALFPath subclass for non-Windows systems.

class PureWindowsALFPath(*args)[source]

Bases: PureWindowsPath, PureALFPath

PureALFPath subclass for Windows systems.

class PurePosixALFPath(*args)[source]

Bases: PurePosixPath, PureALFPath

PureALFPath subclass for non-Windows systems.