CLASS ndr.reader

 READER - Create a new Neuroscience Data Reader (NDR) object.

    NDR_READER_OBJ = ndr.reader(NDR_READER_TYPE)

    Creates a Neuroscience Data Reader object capable of reading a 
    specific data format identified by NDR_READER_TYPE. This object 
    acts as a high-level interface, utilizing an underlying specific 
    reader object (subclass of ndr.reader.base) to handle the details
    of the file format.

    Inputs:
        NDR_READER_TYPE - A string specifying the data format to read.
                          Valid types are defined in 
                          'ndr_reader_types.json' and can include
                          short names (e.g., 'rhd', 'smr', 'rec', 'abf', 
                          'sev', 'neo', 'whitematter') or longer aliases.

    Outputs:
        NDR_READER_OBJ  - The created ndr.reader object handle.

    Example:
        % Create a reader for Intan RHD files
        intan_reader = ndr.reader('intan'); 

        % Create a reader for SpikeGadgets REC files
        rec_reader = ndr.reader('rec');

  See also: ndr.reader.base, ndr.fun.ndrresource, ndr.known_readers

Superclasses

none

Properties

Property	Description
ndr_reader_base	The specific ndr.reader.base object that actually reads the files

Methods

Method	Description
epochclock	Return the ndr.time.clocktype objects for an epoch.
getchannelsepoch	List the channels available for a given epoch.
read	Read data or time information from specified channels and epoch.
readchannels_epochsamples	Read regularly sampled data channels.
reader	Create a new Neuroscience Data Reader (NDR) object.
readevents_epochsamples	Read event/marker data or derive events from digital channels.
readevents_epochsamples_native	Read native event/marker channels.
samplerate	Get the sample rate for specific regularly-sampled channels.
t0_t1	Return the beginning and end times for an epoch.
underlying_datatype	Get the native data type for specified channels.

Methods help

epochclock - Return the ndr.time.clocktype objects for an epoch.

EC = EPOCHCLOCK(NDR_READER_OBJ, EPOCHSTREAMS, EPOCH_SELECT)

    Returns the clock types available for the specified epoch as a 
    cell array of ndr.time.clocktype objects (or subclasses). 
    This function calls the corresponding method of the underlying 
    specific reader object (`ndr_reader_base`).

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        EPOCHSTREAMS   - Cell array of filenames for the epoch.
        EPOCH_SELECT   - The epoch index (default: 1).

    Outputs:
        EC             - Cell array of ndr.time.clocktype objects.

  See also: ndr.time.clocktype, ndr.reader.base/epochclock

---

getchannelsepoch - List the channels available for a given epoch.

CHANNELS = GETCHANNELSEPOCH(NDR_READER_OBJ, EPOCHSTREAMS, EPOCH_SELECT)

    Returns a structure list of all channels available in the specified epoch.
    This function calls the corresponding method of the underlying 
    specific reader object (`ndr_reader_base`).

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        EPOCHSTREAMS   - Cell array of filenames for the epoch.
        EPOCH_SELECT   - The epoch index (default: 1).

    Outputs:
        CHANNELS       - Structure array with fields:
          'name'         : Channel name (e.g., 'ai1', 't1').
          'type'         : Channel type (e.g., 'analog_in', 'time').
          'time_channel' : (Optional) Index of the associated time channel.

  See also: ndr.reader.base/getchannelsepoch

---

read - Read data or time information from specified channels and epoch.

[DATA, TIME] = READ(NDR_READER_OBJ, EPOCHSTREAMS, CHANNELSTRING, Name, Value, ...)

    Reads data and corresponding time information from the specified 
    channels within a given epoch. This function determines the 
    appropriate underlying read method (e.g., readchannels_epochsamples 
    or readevents_epochsamples) based on the channel type derived 
    from CHANNELSTRING.

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        EPOCHSTREAMS   - A cell array of full path file names or remote
                         access streams that comprise the epoch of data.
        CHANNELSTRING  - Specifies the channels to read. Format depends
                         on the underlying reader:
                           - Standard NDR format: A string combining prefixes 
                             and numbers (e.g., 'ai1-3,5', 'ai1+di1'). 
                             See ndr.string.channelstring2channels.
                           - Intan Reader: Accepts standard NDR format OR 
                             Intan native names (e.g., 'A000+A001').
                           - Neo Reader: Expects a cell array of native 
                             channel names (e.g., {'A-000', 'A-001'}).

    Name-Value Pair Arguments:
        't0' (-Inf)           : Start time for reading (seconds). -Inf reads 
                                from the earliest available sample.
        't1' (Inf)            : Stop time for reading (seconds). Inf reads 
                                to the last available sample.
        'epoch_select' (1)    : The epoch index within EPOCHSTREAMS to read.
                                Usually 1, as most formats have one epoch per file.
        'useSamples' (0)      : If 1, interpret 's0' and 's1' as sample 
                                numbers instead of times. (logical).
        's0' (NaN)            : Start sample number (1-based) if useSamples is 1.
        's1' (NaN)            : Stop sample number (1-based) if useSamples is 1.

    Outputs:
        DATA - Data read from the specified channels. Format depends on 
               channel type:
                 - Regularly sampled (e.g., 'ai'): N x C matrix (double), 
                   where N is samples, C is channels.
                 - Events/Markers: N x C matrix or cell array, format depends 
                   on event type (see readevents_epochsamples).
        TIME - N x 1 vector (double) of time points (seconds) corresponding 
               to the samples/events in DATA. For events/markers, format
               matches DATA (N x C matrix or cell array).

    Example:
        r = ndr.reader('intan');
        filenames = {'/path/to/mydata.rhd'};
        % Read analog input channels 1 and 2 from time 10s to 15s
        [analogData, timeVec] = r.read(filenames, 'ai1-2', 't0', 10, 't1', 15);
        % Read samples 1000 to 2000 for channel 'A000' (Intan specific)
        [sampleData, sampleTime] = r.read(filenames, 'A000', 'useSamples', 1, 's0', 1000, 's1', 2000); 

  See also: ndr.reader/readchannels_epochsamples, ndr.reader/readevents_epochsamples, 
            ndr.string.channelstring2channels, ndr.reader.base/daqchannels2internalchannels

---

readchannels_epochsamples - Read regularly sampled data channels.

DATA = READCHANNELS_EPOCHSAMPLES(NDR_READER_OBJ, CHANNELTYPE, ...
        CHANNEL, EPOCHSTREAMS, EPOCH_SELECT, S0, S1)

    Reads data for regularly sampled channels (e.g., analog, digital) 
    between sample S0 and sample S1 (inclusive, 1-based). This function 
    calls the corresponding method of the underlying specific reader 
    object (`ndr_reader_base`).

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        CHANNELTYPE    - String specifying the type (e.g., 'ai', 'di', 'time').
        CHANNEL        - Vector of channel numbers.
        EPOCHSTREAMS   - Cell array of filenames for the epoch.
        EPOCH_SELECT   - The epoch index.
        S0             - Start sample number (1-based).
        S1             - End sample number (1-based).

    Outputs:
        DATA           - N x C matrix of data (double or native type), or 
                         N x 1 vector for 'time'.

  See also: ndr.reader.base/readchannels_epochsamples

---

reader - Create a new Neuroscience Data Reader (NDR) object.

NDR_READER_OBJ = ndr.reader(NDR_READER_TYPE)

    Creates a Neuroscience Data Reader object capable of reading a 
    specific data format identified by NDR_READER_TYPE. This object 
    acts as a high-level interface, utilizing an underlying specific 
    reader object (subclass of ndr.reader.base) to handle the details
    of the file format.

    Inputs:
        NDR_READER_TYPE - A string specifying the data format to read.
                          Valid types are defined in 
                          'ndr_reader_types.json' and can include
                          short names (e.g., 'rhd', 'smr', 'rec', 'abf', 
                          'sev', 'neo', 'whitematter') or longer aliases.

    Outputs:
        NDR_READER_OBJ  - The created ndr.reader object handle.

    Example:
        % Create a reader for Intan RHD files
        intan_reader = ndr.reader('intan'); 

        % Create a reader for SpikeGadgets REC files
        rec_reader = ndr.reader('rec');

  See also: ndr.reader.base, ndr.fun.ndrresource, ndr.known_readers

    Documentation for ndr.reader/reader
       doc ndr.reader

---

readevents_epochsamples - Read event/marker data or derive events from digital channels.

[TIMESTAMPS, DATA] = READEVENTS_EPOCHSAMPLES(NDR_READER_OBJ, ...
        CHANNELTYPE, CHANNEL, EPOCHSTREAMS, EPOCH_SELECT, T0, T1)

    Reads event or marker data occurring between time T0 and T1 (seconds). 
    This function handles both reading native event/marker channel types 
    (like 'event', 'marker', 'text') by calling 
    `readevents_epochsamples_native`, and deriving events from digital 
    channels (types 'dep', 'den', 'dimp', 'dimn') by reading the 
    digital data and detecting transitions.

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        CHANNELTYPE    - Cell array of strings specifying the type for each 
                         channel in CHANNEL. Valid types include:
                           'event': Timestamps of occurrences (data is 1).
                           'marker': Timestamps and associated marker codes (double).
                           'text': Timestamps and associated text (cellstr).
                           'dep': Events at positive digital transitions (0->1).
                           'den': Events at negative digital transitions (1->0).
                           'dimp': Events at positive impulses (0->1->0).
                           'dimn': Events at negative impulses (1->0->1).
        CHANNEL        - Vector of channel numbers corresponding to CHANNELTYPE.
        EPOCHSTREAMS   - Cell array of filenames for the epoch.
        EPOCH_SELECT   - The epoch index.
        T0             - Start time (seconds).
        T1             - End time (seconds).

    Outputs:
        TIMESTAMPS     - Timestamps of events/markers (seconds). Format matches DATA.
                         If 1 channel, N x 1 double vector.
                         If >1 channel, 1 x C cell array of N x 1 double vectors.
        DATA           - Data associated with events/markers. Format depends on type.
                         If 1 channel, N x D matrix or N x 1 cellstr.
                         If >1 channel, 1 x C cell array.

  See also: ndr.reader/readevents_epochsamples_native, ndr.reader.base/readevents_epochsamples_native

  Step 1: check to see if the user is requesting a "native" type of event (event,marker,text) or a "derived" type of event
        (like dep, den, dimp, dimn, which are derived from the data of sampled digital channels)
        If the user does request a derived event type, then compute it

---

readevents_epochsamples_native - Read native event/marker channels.

[TIMESTAMPS, DATA] = READEVENTS_EPOCHSAMPLES_NATIVE(NDR_READER_OBJ, ...
        CHANNELTYPE, CHANNEL, EPOCHSTREAMS, EPOCH_SELECT, T0, T1)

    Reads event or marker data directly as stored in the file format, 
    occurring between time T0 and T1 (seconds). This function calls the 
    corresponding method of the underlying specific reader object 
    (`ndr_reader_base`). It cannot handle derived event types 
    ('dep', 'den', 'dimp', 'dimn'); use `readevents_epochsamples` for those.

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        CHANNELTYPE    - Cell array of strings specifying the native type 
                         for each channel ('event', 'marker', 'text').
        CHANNEL        - Vector of channel numbers.
        EPOCHSTREAMS   - Cell array of filenames for the epoch.
        EPOCH_SELECT   - The epoch index.
        T0             - Start time (seconds).
        T1             - End time (seconds).

    Outputs:
        TIMESTAMPS     - Timestamps of events/markers (seconds). Format matches DATA.
        DATA           - Data associated with events/markers. Format depends on type.

  See also: ndr.reader/readevents_epochsamples, ndr.reader.base/readevents_epochsamples_native

---

samplerate - Get the sample rate for specific regularly-sampled channels.

SR = SAMPLERATE(NDR_READER_OBJ, EPOCHSTREAMS, EPOCH_SELECT, CHANNELTYPE, CHANNEL)

    Returns the sampling rate(s) in Hz for the specified regularly-sampled 
    channels. This function calls the corresponding method of the 
    underlying specific reader object (`ndr_reader_base`).

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        CHANNELTYPE    - Cell array of strings specifying the channel type 
                         (e.g., {'ai','ai'}, {'di'}). Must be a regularly-sampled type.
        CHANNEL        - Vector of channel numbers.
        EPOCHSTREAMS   - Cell array of filenames for the epoch.
        EPOCH_SELECT   - The epoch index.

    Outputs:
        SR             - Vector of sampling rates (Hz) corresponding to each 
                         channel requested. Returns NaN for channels that are 
                         not regularly sampled (e.g., events).

  See also: ndr.reader.base/samplerate

---

t0_t1 - Return the beginning and end times for an epoch.

T0T1 = T0_T1(NDR_READER_OBJ, EPOCHSTREAMS, EPOCH_SELECT)

    Returns the beginning (t0) and end (t1) times (in seconds) of 
    the epoch defined by EPOCHSTREAMS and EPOCH_SELECT, relative to 
    the clock type specified by EPOCHCLOCK. This function calls the 
    corresponding method of the underlying specific reader object 
    (`ndr_reader_base`).

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        EPOCHSTREAMS   - Cell array of filenames for the epoch.
        EPOCH_SELECT   - The epoch index (default: 1).

    Outputs:
        T0T1           - Cell array containing a 1x2 vector [t0 t1] 
                         for each clock type returned by EPOCHCLOCK.

  See also: ndr.reader/epochclock, ndr.reader.base/t0_t1

---

underlying_datatype - Get the native data type for specified channels.

[DATATYPE, P, DATASIZE] = UNDERLYING_DATATYPE(NDR_READER_OBJ, ...
        EPOCHSTREAMS, EPOCH_SELECT, CHANNELTYPE, CHANNEL)

    Returns information about the underlying data type as stored in the file
    for the specified channels. This function calls the corresponding 
    method of the underlying specific reader object (`ndr_reader_base`).

    Inputs:
        NDR_READER_OBJ - The ndr.reader object.
        EPOCHSTREAMS   - Cell array of filenames for the epoch.
        EPOCH_SELECT   - The epoch index.
        CHANNELTYPE    - String specifying the type of channels (e.g., 'ai').
        CHANNEL        - Vector of channel numbers.

    Outputs:
        DATATYPE       - String representing the native data type (e.g., 
                         'int16', 'float32'). Suitable for FREAD/FWRITE.
        P              - Polynomial coefficients [offset scale] for converting 
                         raw data to the units returned by readchannels. 
                         Typically [0 1] if raw data is returned.
        DATASIZE       - Size of the data type in bits (e.g., 16, 32, 64).

  See also: ndr.reader.base/underlying_datatype, fread, fwrite

---