READ Reads data from a WhiteMatter LLC (WM) binary data file.
[D, t, t0_t1] = whitematter.read(FNAME, T0, T1, OPTIONS) reads data from the
binary file specified by FNAME. It returns the data in the matrix D,
where each row represents a sample and each column represents a channel.
By default, all channels are read. Use the 'channels' option to specify
a subset of channels.
The data is read from time T0 to T1 (inclusive, in seconds).
The time vector corresponding to the samples in D is returned in t.
The entire recording time window available in the file is returned
in t0_t1 as a 1x2 vector [startTime endTime].
This function utilizes ndr.format.binarymatrix.read for efficient data reading.
Inputs:
FNAME - Path to the WM data file (char row vector).
The file must exist. It is assumed to contain an
8-byte header followed by interleaved int16 data.
T0 - Start time for data reading (in seconds, double scalar).
Use -Inf to start from the beginning of the file.
T1 - End time for data reading (in seconds, double scalar).
Use Inf to read until the end of the file.
OPTIONS:
numChans - Total number of channels interleaved in the data file
(positive integer scalar, default: 64). This must be the
*total* number, even if reading a subset.
SR - Sampling rate of the data in Hz
(positive double scalar, default: 20000).
byteOrder - Byte order of the binary data file
('ieee-le' or 'ieee-be', char row vector, default: 'ieee-le').
channels - Vector of channel indices (1-based) to read. Channels
must be within the range [1, numChans].
(numeric vector, default: [] which means read all channels).
Outputs:
D - N x C matrix containing the read data, where N is the
number of samples read and C is the number of channels
specified in the 'channels' option (or numChans if 'channels'
is empty). Data is returned as int16.
t - N x 1 vector of time points (in seconds) corresponding
to the samples in D. Returned as double.
t0_t1 - 1x2 vector [startTime endTime] indicating the total
time window available for reading in the file (seconds).
Returned as double.
Examples:
% Read all 64 channels from 'mydata_wm.dat' from 10s to 20s
[D_all, t_all, time_range_all] = whitematter.read('mydata_wm.dat', 10, 20);
disp(['Total time available: ' num2str(time_range_all(2)) ' seconds']);
disp(['Data size: ' mat2str(size(D_all))]); % Should be samples x 64
% Read only channels 1, 5, and 10 from 'mydata_wm.dat' from 10s to 20s
[D_sub, t_sub, time_range_sub] = whitematter.read('mydata_wm.dat', 10, 20, 'channels', [1, 5, 10]);
disp(['Data size: ' mat2str(size(D_sub))]); % Should be samples x 3
figure;
plot(t_sub, double(D_sub(:,2))); % Plot channel 5 (second column requested)
xlabel('Time (s)'); ylabel('Raw Value (int16)');
title('Data Channel 5');
See also: ndr.format.binarymatrix.read, ndr.time.fun.times2samples, ndr.time.fun.samples2times