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://docs.internationalbrainlab.org/en/latest/04_reference.html#alf

Created on Tue Sep 11 18:06:21 2018

@author: Miles

Functions

alf_parts

Return the parsed elements of a given ALF filename.

filter_by

Given a path and optional filters, returns all ALF files and their associated parts.

is_valid

Returns a True for a given file name if it is an ALF file, otherwise returns False

to_alf

Given a set of ALF file parts, return a valid ALF file name.
is_valid(filename)[source]

Returns a True for a given file name if it is an ALF file, otherwise returns False

Examples

>>> is_valid('trials.feedbackType.npy')
True
>>> is_valid('_ns_obj.attr1.2622b17c-9408-4910-99cb-abf16d9225b9.metadata.json')
True
>>> is_valid('spike_train.npy')
False
>>> is_valid('channels._phy_ids.csv')
False
Parameters

filename (str) – The name of the file

Returns

bool

alf_parts(filename, as_dict=False)[source]

Return the parsed elements of a given ALF filename.

Examples

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

  • filename (str) – The name of the file

  • as_dict (bool) – when True a dict of matches is returned

Returns

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

Return type

namespace (str)

to_alf(object, attribute, extension, namespace=None, timescale=None, extra=None)[source]

Given a set of ALF file parts, return a valid ALF file name. Essential periods and underscores are added by the function.

Parameters

  • object (str) – The ALF object name

  • attribute (str) – The ALF object attribute name

  • extension (str) – The file extension

  • namespace (str) – An optional namespace

  • timescale (str) – An optional timescale

  • extra (str, tuple) – One or more optional extra ALF attributes

Returns

a file name string built from the ALF parts

Return type

filename (str)

Examples: >>> to_alf(‘spikes’, ‘times’, ‘ssv’) ‘spikes.times.ssv’ >>> to_alf(‘spikes’, ‘times’, ‘ssv’, namespace=’ibl’) ‘_ibl_spikes.times.ssv’ >>> to_alf(‘spikes’, ‘times’, ‘ssv’, namespace=’ibl’, timescale=’ephysClock’) ‘_ibl_spikes.times_ephysClock.ssv’ >>> to_alf(‘spikes’, ‘times’, ‘npy’, namespace=’ibl’, timescale=’ephysClock’, extra=’raw’) ‘_ibl_spikes.times_ephysClock.raw.npy’ >>> to_alf(‘wheel’, ‘timestamps’, ‘npy’, ‘ibl’, ‘bpod’, (‘raw’, ‘v12’)) ‘_ibl_wheel.timestamps_bpod.raw.v12.npy’

filter_by(alf_path, **kwargs)[source]

Given a path and optional filters, returns all ALF files and their associated parts. The filters constitute a logical AND.

Parameters

  • alf_path (str) – A Path to a directory containing ALF files

  • object (str) – filter by a given object (e.g. ‘spikes’)

  • attribute (str) – filter by a given attribute (e.g. ‘intervals’)

  • extension (str) – filter by extension (e.g. ‘npy’)

  • namespace (str) – filter by a given namespace (e.g. ‘ibl’) or None for files without one

  • timescale (str) – filter by a given timescale (e.g. ‘bpod’) or None for files without one

  • extra (str, list) – filter by extra parameters (e.g. ‘raw’) or None for files without extra parts. NB: Wild cards not permitted here.

Returns

list of ALF files and tuples of their parts attributes (list of dicts): list of parsed file parts

Return type

alf_files (list)

Examples

# Filter files with universal timescale filter_by(alf_path, timescale=None)

# Filter files by a given ALF object filter_by(alf_path, object=’wheel’)

# Filter using wildcard, e.g. ‘wheel’ and ‘wheelMoves’ ALF objects filter_by(alf_path, object=’wh*’)

# Filter all intervals that are in bpod time filter_by(alf_path, attribute=’intervals’, timescale=’bpod’)