Reading TimeSeries Data in Units

This guide shows you how to get the data of a types.core.TimeSeries in the unit of measurement named by its data_unit property.

Stored values are not in data_unit

The data of a types.core.TimeSeries is not necessarily stored in the unit its data_unit property names. The help text of data_unit says so, and points to the two properties that carry the conversion into that unit:

data = rawData * data_conversion + data_offset

Both default to the identity (data_conversion = 1, data_offset = 0), so a file whose writer stored values already in data_unit reads correctly as is. A file whose writer did not is off by whatever data_conversion and data_offset are, and nothing in the array itself says so. An types.core.ElectricalSeries may add a per-channel channel_conversion on top of the global one.

Getting the whole dataset

getDataInUnits reads the dataset and applies the conversion for you:

nwb = nwbRead('myfile.nwb');
timeSeries = nwb.acquisition.raw_signal;

volts = timeSeries.getDataInUnits();

The result is double, or single when the stored data is single. This reads the whole dataset into memory.

Getting a subset of a large dataset

Data read from a file is a DataStub, so indexing it loads only the part you ask for. Pass that part to applyConversion, which scales it the same way:

rawSubset = timeSeries.data(1:1000);
volts = timeSeries.applyConversion(rawSubset);

For an types.core.ElectricalSeries with a per-channel channel_conversion, name the channels the subset holds so that each one gets its own factor:

rawSubset = electricalSeries.data(3:5, 1:30000);
volts = electricalSeries.applyConversion(rawSubset, 'Channels', 3:5);

'Channels' is only needed when the subset holds some of the channels. A subset that holds all of them, or a types.core.TimeSeries with no channel_conversion, does not need it.

Why not multiply by hand

Integer arithmetic in MATLAB rounds and saturates instead of promoting, so scaling stored integers directly keeps them integers. Take a series that stores signed 16-bit integers spanning ±2.5 V:

timeSeries = types.core.TimeSeries( ...
    'data', int16([-32768; 0; 32767]), ...
    'data_unit', 'volts', ...
    'data_conversion', 2.5/32768, ...
    'starting_time', 0, 'starting_time_rate', 30000);
>> timeSeries.data * timeSeries.data_conversion

   -3
    0
    2

>> timeSeries.getDataInUnits()

   -2.5000
         0
    2.4999

Both methods cast the data to a floating point type before applying the conversion.