Core Bark library functions

This is BARK, a python library for storing and accessing audio and ephys data in directories and simple file formats.

Library versions:
bark: 0.2
bark.template_columns(fields)

Produces a template columns dict for use in a meta file.

Parameters:fields (sequence of str) – sequence of column names
Returns:minimal template columns dictionary
Return type:dict
bark.event_columns(dataframe, columns=None)

Produces a columns dict for event data, for use in a meta file.

Parameters:
  • dataframe (Pandas DataFrame) – dataframe containing event data
  • columns (dict) – existing columns dict to bring into register with dataframe‘s columns
Returns:

Columns dictionary for dataframe
Return type:

dict
bark.sampled_columns(data, columns=None)

Produces a columns dict for sampled data, for use in a meta file.

If columns is None, create new columns dict; otherwise, verify columns.

Parameters:
  • data (sequence) – time series data of at most 2 dimensions
  • columns (dict) – existing columns dict to bring into register with shape of data
Returns:

Columns dictionary for data
Return type:

dict
Raises:

ValueError – if the keys in columns don’t match up with data
bark.write_sampled(datfile, data, sampling_rate, **params)

Writes a sampled dataset to disk as a raw binary file, plus a meta file.

Parameters:
  • datfile (str) – path to file to write to. If the file exists, it is overwritten.
  • data (sequence) – time series data of at most 2 dimensions
  • sampling_rate (int or float) – sampling rate of data
  • **params – all other keyword arguments are treated as dataset attributes, and added to the meta file
Returns:

sampled dataset containing data
Return type:

SampledData
bark.read_sampled(datfile, mode='r')

Loads raw binary file and associated metadata into a sampled dataset.

Parameters:
  • datfile (str) – path to raw binary file to read from
  • mode – may be “r” or “r+”; use “r+” for modifying the data (not recommended)
Returns:

sampled dataset containing datfile‘s data
Return type:

SampledData
bark.write_events(eventsfile, data, **params)

Writes an event dataset and its metadata to disk.

Parameters:
  • eventsfile (str) – path to file to write to. If the file exists, it is overwritten.
  • data (Pandas DataFrame) – event data; one column must be named ‘start’
  • **params – all other keyword arguments are treated as dataset attributes, and added to the meta file
Returns:

event dataset containing data
Return type:

EventData
bark.read_events(eventsfile)

Loads event data file and associated metadata into an event dataset.

Parameters:eventsfile (str) – path to file to read from
Returns:event dataset containing eventsfile‘s data
Return type:EventData
bark.read_dataset(fname)

Loads a file as a sampled or event dataset, as appropriate.

Parameters:fname (str) – path to file to load
Returns:dataset containing fname‘s data
Return type:Data
bark.read_metadata(path, meta='.meta.yaml')

Loads metadata for a dataset.

Parameters:
  • path (str) – path to dataset (not meta file) whose metadata is to be loaded
  • meta (str) – suffix identifying the dataset’s meta file
Returns:

the loaded metadata
Return type:

dict
Raises:
  • FileNotFoundError – if either path or its metafile do not exist.
  • ValueError – if path is a metafile instead of a data file
bark.write_metadata(path, meta='.meta.yaml', **params)

Writes metadata for a dataset.

Parameters:
  • path (str) – path to dataset (not meta file) whose metadata is to be written. If the meta file already exists, it will be overwritten.
  • meta (str) – suffix identifying the dataset’s meta file
  • **params – all other keyword arguments are treated as dataset attributes, and added to the meta file
bark.read_root(name)

Constructs a Root object from a directory.

Parameters:name (str) – path to a directory containig zero or more entries.
Returns:a Root object containing all entries below name
Return type:Root
bark.create_entry(name, timestamp, parents=False, **attributes)

Creates a new Bark Entry, setting required attributes.

An entry is an abstract collection of data which all refer to the same time frame. Data can include physiological recordings, sound recordings, and derived data such as spike times and labels.

Parameters:
  • name (str) – path to the entry directory
  • timestamp – timestamp of entry; see timestamp_to_datetime() for supported types
  • parents (bool) – if True, no error is raised if directory name already exists, and metadata is overwritten
  • **attributes – additional keyword arguments are set as attributes on the created entry
Returns:

newly-created Entry object
Return type:

Entry
Raises:

IOError – if parents is False and directory name already exists
bark.read_entry(name, meta='.meta.yaml')

Reads a Bark Entry from a directory.

Parameters:
  • name (str) – path to Entry
  • meta (str) – suffix identifying the entry’s meta file
Returns:

Entry containing all datasets in name
Return type:

Entry
bark.convert_timestamp(obj, default_tz='America/Chicago')

Makes a Bark timestamp from an object.

If the object is not timezone-aware, the timezone is set to be default_tz.

Parameters:
  • obj – time object; see timestamp_to_datetime() for supported types
  • default_tz (str) – timezone to use if obj is timezone-naive; must be a string from the tz database.
Returns:

Bark timestamp
Return type:

Arrow
bark.timestamp_to_datetime(obj)

Converts an object to a datetime.datetime object.

Note that because floating point values are approximate, some conversions may not be reversible.

Parameters:obj –

may be any of the following:

  1. datetime.datetime object
  2. Arrow object
  3. ISO 8601 string
  4. time.struct_time object
  5. integer (epoch time)
  6. float (epoch time)
  7. 2-tuple of integers (seconds and microseconds, epoch time)
Returns:(local) timezone-aware object
Return type:datetime.datetime
Raises:TypeError – if obj cannot be interpreted according to the list above
bark.timestamp_to_float(timestamp)

Converts a time object to a floating point value (epoch time).

Parameters:obj – time object; see timestamp_to_datetime() for supported types
Returns:epoch time representation of timestamp
Return type:float