allensdk.brain_observatory.sync_dataset module

dataset.py

Dataset object for loading and unpacking an HDF5 dataset generated by

sync.py

@author: derricw

Allen Institute for Brain Science

Dependencies

numpy http://www.numpy.org/ h5py http://www.h5py.org/

class allensdk.brain_observatory.sync_dataset.Dataset(path)

Bases: object

A sync dataset. Contains methods for loading

and parsing the binary data.

Parameters:

path : str

Path to HDF5 file.

Examples

>>> dset = Dataset('my_h5_file.h5')
>>> logger.info(dset.meta_data)
>>> dset.stats()
>>> dset.close()

>>> with Dataset('my_h5_file.h5') as d:
...     logger.info(dset.meta_data)
...     dset.stats()

The sync file documentation from MPE can be found at sharepoint > Instrumentation > Shared Documents > Sync_line_labels_discussion_2020-01-27-.xlsx # NOQA E501 Direct link: https://alleninstitute.sharepoint.com/:x:/s/Instrumentation/ES2bi1xJ3E9NupX-zQeXTlYBS2mVVySycfbCQhsD_jPMUw?e=Z9jCwH

BEHAVIOR_TRACKING_KEYS = ('beh_frame_received', 'cam1_exposure', 'behavior_monitoring')

DEPRECATED_KEYS = {}

EYE_TRACKING_KEYS = ('eye_frame_received', 'cam2_exposure', 'eyetracking', 'eye_tracking')

FRAME_KEYS = ('frames', 'stim_vsync')

OPTOGENETIC_STIMULATION_KEYS = ('LED_sync', 'opto_trial')

PHOTODIODE_KEYS = ('photodiode', 'stim_photodiode')

analog_meta_data

close(self)

Closes the dataset.

duty_cycle(self, line)

Doesn’t work right now. Freezes python for some reason.

Returns the duty cycle of a line.

frequency(self, line, edge='rising')

Returns the average frequency of a line.

get_all_bits(self)

Returns the data for all bits.

get_all_events(self)

Returns all counter values and their cooresponding IO state.

get_all_times(self, units='samples')

Returns all counter values.

Parameters:

units : str

Return times in ‘samples’ or ‘seconds’

get_analog_channel(self, channel, start_time=0.0, stop_time=None, downsample=1)

Returns the data from the specified analog channel between the

timepoints.

Args:

channel (int, str): desired channel index or label start_time (Optional[float]): start time in seconds stop_time (Optional[float]): stop time in seconds downsample (Optional[int]): downsample factor

Returns:

ndarray: slice of data for specified channel

Raises:

KeyError: no analog data present

get_analog_meta(self)

Returns the metadata for the analog data.

get_bit(self, bit)

Returns the values for a specific bit.

Parameters:

bit : int

Bit to return.

get_bit_changes(self, bit)

Returns the first derivative of a specific bit.

Data points are 1 on rising edges and 255 on falling edges.

Parameters:

bit : int

Bit for which to return changes.

get_edges(self, kind: str, keys: Union[str, Sequence[str]], units: str = 'seconds', permissive: bool = False) → Union[numpy.ndarray, NoneType]

Utility function for extracting edge times from a line

Parameters:

kind : One of “rising”, “falling”, or “all”. Should this method return

timestamps for rising, falling or both edges on the appropriate line

keys : These will be checked in sequence. Timestamps will be returned

for the first which is present in the line labels

units : one of “seconds”, “samples”, or “indices”. The returned

“time”stamps will be given in these units.

raise_missing : If True and no matching line is found, a KeyError will

be raised

Returns:

An array of edge times. If raise_missing is False and none of the keys

were found, returns None.

Raises:

KeyError : none of the provided keys were found among this dataset’s

line labels

get_events_by_bit(self, bit, units='samples')

Returns all counter values for transitions (both rising and falling)

for a specific bit.

Parameters:

bit : int

Bit for which to return events.

get_events_by_line(self, line, units='samples')

Returns all counter values for transitions (both rising and falling)

for a specific line.

Parameters:

line : str

Line for which to return events.

get_falling_edges(self, line, units='samples')

Returns the counter values for the falling edges for a specific bit

or line.

Parameters:

line : str

Line for which to return edges.

get_line(self, line)

Returns the values for a specific line.

Parameters:

line : str

Line to return.

get_line_changes(self, line)

Returns the first derivative of a specific line.

Data points are 1 on rising edges and 255 on falling edges.

Parameters:

line : (str)

Line name for which to return changes.

get_nearest(self, source, target, source_edge='rising', target_edge='rising', direction='previous', units='indices')

For all values of the source line, finds the nearest edge from the

target line.

By default, returns the indices of the target edges.

Args:

source (str, int): desired source line target (str, int): desired target line source_edge [Optional(str)]: “rising” or “falling” source edges target_edge [Optional(str): “rising” or “falling” target edges direction (str): “previous” or “next”. Whether to prefer the

previous edge or the following edge.

units (str): “indices”

get_rising_edges(self, line, units='samples')

Returns the counter values for the rizing edges for a specific bit or

line.

Parameters:

line : str

Line for which to return edges.

line_stats(self, line, print_results=True)

Quick-and-dirty analysis of a bit.

##TODO: Split this up into smaller functions.

load(self, path)

Loads an hdf5 sync dataset.

Parameters:

path : str

Path to hdf5 file.

period(self, line, edge='rising')

Returns a dictionary with avg, min, max, and st of period for a line.

plot_all(self, start_time, stop_time, auto_show=True)

Plot all active bits.

Yikes. Come up with a better way to show this.

plot_bit(self, bit, start_time=0.0, end_time=None, auto_show=True, axes=None, name='')

Plots a specific bit at a specific time period.

plot_bits(self, bits, start_time=0.0, end_time=None, auto_show=True)

Plots a list of bits.

plot_line(self, line, start_time=0.0, end_time=None, auto_show=True)

Plots a specific line at a specific time period.

plot_lines(self, lines, start_time=0.0, end_time=None, auto_show=True)

Plots specific lines at a specific time period.

sample_freq

stats(self)

Quick-and-dirty analysis of all bits. Prints a few things about each

bit where events are found.

allensdk.brain_observatory.sync_dataset.get_bit(uint_array, bit)

Returns a bool array for a specific bit in a uint ndarray.

Parameters:

uint_array : (numpy.ndarray)

The array to extract bits from.

bit : (int)

The bit to extract.

allensdk.brain_observatory.sync_dataset.unpack_uint32(uint32_array, endian='L')

Unpacks an array of 32-bit unsigned integers into bits.

Default is least significant bit first.

*Not currently used by sync dataset because get_bit is better and does

basically the same thing. I’m just leaving it in because it could potentially account for endianness and possibly have other uses in the future.