alf.io

Generic ALF I/O module. Provides support for time-series reading and interpolation as per the specifications For a full overview of the scope of the format, see: https://ibllib.readthedocs.io/en/develop/04_reference.html#alf

class alf.io.AlfBunch(*args, **kwargs)
append(b, inplace=False)

Appends one bunch to another, key by key :param bunch: :return: Bunch

to_df()

Attempts to returns a pandas.DataFrame if all elements are arrays of the same length Returns the original bunch if it can’t

alf.io.check_dimensions(dico)

Test for consistency of dimensions as per ALF specs in a dictionary. Raises a Value Error.

Alf broadcasting rules: only accepts consistent dimensions for a given axis a dimension is consistent with another if it’s empty, 1, or equal to the other arrays dims [a, 1], [1, b] and [a, b] are all consistent, [c, 1] is not

Parameters:dico – dictionary containing data
Returns:status 0 for consistent dimensions, 1 for inconsistent dimensions
alf.io.dataframe(adict)

Converts an Bunch conforming to size conventions into a pandas Dataframe For 2-D arrays, stops at 10 columns per attribute :return: pandas Dataframe

alf.io.exists(alfpath, object, attributes=None, **kwargs)

Test if ALF object and optionally specific attributes exist in the given path :param alfpath: str or pathlib.Path of the folder to look into :param object: str ALF object name :param attributes: list or list of strings for wanted attributes :return: bool. For multiple attributes, returns True only if all attributes are found

alf.io.get_session_path(path: Union[str, pathlib.Path]) → pathlib.Path

Returns the session path from any filepath if the date/number pattern is found

alf.io.is_session_path(path_object)
Checks if the syntax corresponds to a session path. Note that there is no physical check
about existence nor contents
Parameters:path_object
Returns:
alf.io.is_uuid_string(string: str) → bool

Bool test for uuid version 4

alf.io.load_file_content(fil)

Returns content of files. Designed for very generic file formats: so far supported contents are json, npy, csv, tsv, ssv, jsonable

Parameters:fil – file to read

:return:array/json/pandas dataframe depending on format

alf.io.load_object(alfpath, object=None, short_keys=False, **kwargs)

Reads all files (ie. attributes) sharing the same object. For example, if the file provided to the function is spikes.times, the function will load spikes.time, spikes.clusters, spikes.depths, spike.amps in a dictionary whose keys will be time, clusters, depths, amps Full Reference here: https://docs.internationalbrainlab.org/en/latest/04_reference.html#alf Simplified example: _namespace_object.attribute_timescale.part1.part2.extension

Parameters:
  • alfpath – any alf file pertaining to the object OR directory containing files
  • object – if a directory is provided and object is None, all valid ALF files returned
  • short_keys – by default, the output dictionary keys will be compounds of attributes, timescale and any eventual parts separated by a dot. Use True to shorten the keys to the attribute and timescale.
Returns:

a dictionary of all attributes pertaining to the object

Examples:

# Load spikes object spikes = ibllib.io.alf.load_object(‘/path/to/my/alffolder/’, ‘spikes’)

# Load trials object under the ibl namespace trials = ibllib.io.alf.load_object(session_path, ‘trials’, namespace=’ibl’)

alf.io.read_ts(filename)

Load time-series from ALF format t, d = alf.read_ts(filename)

alf.io.remove_uuid_file(file_path, dry=False)

Renames a file without the UUID and returns the new pathlib.Path object

alf.io.remove_uuid_recursive(folder, dry=False)

Within a folder, recursive renaming of all files to remove UUID

alf.io.save_metadata(file_alf, dico)

Writes a meta data file matching a current alf file object. For example given an alf file clusters.ccfLocation.ssv this will write a dictionary in json format in clusters.ccfLocation.metadata.json Reserved keywords:

  • columns: column names for binary tables.
  • row: row names for binary tables.
  • unit
Parameters:
  • file_alf – full path to the alf object
  • dico – dictionary containing meta-data.
Returns:

None

alf.io.save_object_npy(alfpath, dico, object, parts=None, namespace=None, timescale=None)

Saves a dictionary in alf format using object as object name and dictionary keys as attribute names. Dimensions have to be consistent. Reference here: https://github.com/cortex-lab/ALF Simplified example: _namespace_object.attribute.part1.part2.extension

Parameters:
  • alfpath – path of the folder to save data to
  • dico – dictionary to save to npy; keys correspond to ALF attributes
  • object – name of the object to save
  • parts – extra parts to the ALF name
  • namespace – the optional namespace of the object
  • timescale – the optional timescale of the object
Returns:

List of written files

example: ibllib.io.alf.save_object_npy(‘/path/to/my/alffolder/’, spikes, ‘spikes’)