Data Storage¶

The Datalogger uses a three-tier structure for storing data, comprising of ChannelSets, Channels and DataSets.

                                        ChannelSet
          ___________________________________|_________________________...
         /                       |                       |
     Channel 0                Channel 1               Channel 2        ...
    /         \              /         \             /         \
MetaData    DataSets     MetaData    DataSets     MetaData    DataSets ...
   |        | | | |         |        | | | |         |        | | | |
  ...         ...          ...         ...          ...         ...    ...

DataSets: These are the lowest structure, effectively a vector of values with a name (id_) and units.

Channels: Normally created from one stream of input data, Channels include the original DataSet, any derived DataSets (eg. frequency spectra, sonogram) and metadata about the channel. They also have methods for getting and setting the attributes of the DataSets.

ChannelSets: The main object to interface with, with methods for getting and setting channel and dataset attributes. Each ChannelSet will typically be derived from one set of results or one run of the experiment.

ChannelSet¶

class cued_datalogger.api.channel.ChannelSet(initial_num_channels=0)¶

Bases: object

A group of channels, with methods for setting and getting data.

In theory, a user will only need to interact with the ChannelSet to interact with the channels and data. Each ChannelSet will normally be derived from one set of results, or one run of an experiment, and then the ChannelSet will contain all the information and analysis from that run. ChannelSets can be initialised as empty, and channels added later, or initialised with a number of empty channels, to which DataSets can be added later. Channels are stored in a matlab-style list structure (see MatlabList) which uses tuple indexing, eg. channelset.channels[1, 2, range(5,10)], so that multiple channels can be selected easily.

Attributes

channels	(MatlabList) A list of the channels in this set.
colormap	(ColorMap) A `ColorMap` used for colouring the channels in this set.

Methods

__init__(initial_num_channels=0)¶: Create the ChannelSet with a number of blank channels as given by initial_num_channels.

__len__()¶: Return the number of Channels in this ChannelSet.

add_channel_dataset(channel_index, id_, data=None, units=None)¶: Add a DataSet with id_ to the Channel specified by channel_index. DataSet can be initialised as empty (default) or with data and/or units.

add_channels(num_channels=1)¶: Add a number (num_channels) of new empty Channels to the end of the channel list.

channel_colour(channel_index)¶: Get the RGBA tuple specifying the colour of the Channel at channel_index.

channel_data(channel_index, id_)¶: Return the data from the DataSet given by id_ in the Channel specified by channel_index.

channel_ids(channel_index)¶: Return the ids of all the datasets in the Channel specified by channel_index.

channel_metadata(channel_index, metadata_id=None)¶: Return the metadata (either a specific item given by metadata_id or the full dict of metadata) of the Channel specified by channel_index.

channel_units(channel_index, id_)¶: Return the units from the DataSet given by id_ in the Channel specified by channel_index.

info()¶: Print the information about all of the Channels in this ChannelSet.

set_channel_colour(channel_index)¶: Set the RGBA tuple specifying the colour of the Channel at channel_index to a value determined by its index and the ChannelSet colormap.

set_channel_data(channel_index, id_, data)¶: Set the data of DataSet with id_ to data in the Channel specified by channel_index.

set_channel_metadata(channel_index, metadata_dict)¶: Set metadata of the Channel specified by channel_index using the keys and values given in metadata_dict.

set_channel_units(channel_index, id_, units)¶: Set the units of DataSet with id_ to units in the Channel specified by channel_index.

update_channel_colours()¶: Update the colormap so that the channels are mapped to the full range of colours, and update all the channel colours.

Channel¶

class cued_datalogger.api.channel.Channel(name='', datasets=[], comments='', tags=[], sample_rate=1000, calibration_factor=1, transfer_function_type='displacement', colour=None)¶

Bases: object

Contains a group of DataSets and associated metadata.

Channels are the basic structure used throughout the CUED DataLogger. Channels may contain many DataSets, but each must have a unique id_ (ie. cannot have two ‘time’ DataSets). Typically a Channel will be initialised with just ‘time_series’ data, and other DataSets will be added as analysis is performed - eg. a Fourier Transform produces a ‘spectrum’ DataSet. Channels also contain metadata about the data.

Attributes

name	(str) A human-readable string identifying this channel (eg. `'Input 0'`, or `'Left Accelerometer'`).
datasets	(list) A list of this Channel’s DataSets.
comments	(str) A string for any additional comments.
tags	(list) A list of tags (eg. [‘accelerometer’, ‘input’]) for quick selection and sorting.
sample_rate	(float) The rate (in Hz) that the data was sampled at.
calibration_factor	(float) #TODO#
transfer_function_type	(str) Either ‘None’, ‘displacement’, ‘velocity’, or ‘acceleration’- indicates what type of transfer function is stored.
colour	(tuple) An RGBA tuple for this channel’s colour - usually set by its parent ChannelSet

Methods

__init__(name='', datasets=[], comments='', tags=[], sample_rate=1000, calibration_factor=1, transfer_function_type='displacement', colour=None)¶: Create a new Channel. Can be initialised as empty, or with given metadata and/or with given DataSets.

add_dataset(id_, units=None, data=[])¶: Create a new dataset in this channel with id_, units, data. If a dataset given by id_ exists set its units and data.

data(id_)¶: Return the data from the DataSet given by id_.

dataset(id_)¶: Return the DataSet in this channel with id_.

ids()¶: Return a list of the DataSet ids that this channel has.

info()¶: Print this Channel’s attributes, including DataSet ids and metadata.

is_dataset(id_)¶: Return a boolean of whether the dataset given by id_ exists with data already.

metadata(metadata_id=None)¶: Return the value of this channel’s metadata associated with metadata_id. If none given, returns all of this channel’s metadata in a dictionary.

set_data(id_, data)¶: Set the data in dataset id_ to data.

set_metadata(metadata_dict)¶: Set the channel metadata to the metadata given in metadata_dict.

set_units(id_, units)¶: Set the units of dataset id_ to units.

units(id_)¶: Return the units from the DataSet given by id_.

update_autogenerated_datasets()¶: Regenerate the values in the automatically generated DataSets.

DataSet¶

class cued_datalogger.api.channel.DataSet(id_, units=None, data=array([], dtype=float64))¶

Bases: object

A DataSet is the basic unit for data storage - a named 1d vector with units.

Notes

Permitted values for the DataSet id_ are:

"time_series" - The raw input time series data
"time"* - Calculated from the sample rate and number of samples (units 's')
"frequency"* - Calculated from the sample rate and number of samples (units 'Hz')
"omega"* - Angular frequency (units 'rad'), calculated from the sample rate and number of samples
"spectrum" - The complex spectrum given by the Fourier Transform
"sonogram" - The complex sonogram array, with shape (number of FFTs, frequencies)
"sonogram_frequency"* - The frequency bins (Hz) used in plotting the sonogram. Calculated from the sonogram parameters.
"sonogram_omega"* - The frequency bins (rad) used in plotting the sonogram. Calculated from the sonogram parameters.
"coherence"
"transfer_function"

(* indicates that this DataSet is auto-generated by the Channel)

Attributes

id_	(str) A lower-case string containing the name of the data stored in the vector. See Notes for permitted values.
units	(str) The SI unit in which the data is measured.
data	(ndarray) A numpy array of data points associated with id_.

Methods

__init__(id_, units=None, data=array([], dtype=float64))¶: Create a new DataSet with unique id_. Can either be initialised as empty, or with units and/or data.

set_data(data)¶: Set the DataSet’s data array to data.

set_id(id_)¶: Set the DataSet’s id_ to id_.

set_units(units)¶: Set the DataSet’s units to units.

Widgets¶

See ChannelSelectWidget and ChannelMetadataWidget for widgets to interact with ChannelSets.