Acquiring Data

Table of Contents

• Overview of a recording workflow
  • 1. Create the I/O object.
  • 2. Create the RecordingContainer object.
  • 3. Create the NWBFile
  • 4. Create the recording metadata
    • Create the extracellular recording metadata
  • 5. Create datasets and add to RecordingContainers.
  • 6. Start the recording.
  • 7. Write data.
  • 8. Stop the recording and finalize the file.

Overview of a recording workflow

For users wanting to integrate NWB with a particular data acquisition software, here we outline the steps for a single recording from file creation to saving.

1. Create the I/O object (e.g,. HDF5IO) used for writing data to the file on disk.
2. Create the RecordingContainers object used for managing Container objects for storing recordings.
3. Create the NWBFile object used for managing and creating NWB file contents.
4. Create the recording metadata stored in /general in NWB, e.g., the
   ElectrodeTable object used for saving electrodes information.
5. Create the Container objects (e.g., ElectricalSeries) used for recording and add them to the RecordingContainers.
6. Start the recording.
7. Write data.
8. Stop the recording and close the NWBFile.

Below, we walk through these steps in more detail.

1. Create the I/O object.

First, create an I/O object (e.g., HDF5IO) used for writing data to the file. AqNWB provides the convenience method, createIO to create this object using one of the supported backends. For more fine-grained control of different backend parameters, you can create your own std::shared_ptr using any of the derived BaseIO classes.

    std::shared_ptr<BaseIO> io = createIO("HDF5", path);
    io->open();
    REQUIRE(io->isOpen());

2. Create the RecordingContainer object.

Next, create a RecordingContainers object to manage the different Container objects with the datasets that you would like to write data to.

    std::unique_ptr<NWB::RecordingContainers> recordingContainers =
        std::make_unique<NWB::RecordingContainers>();

3. Create the NWBFile

Next, constructs the NWBFile object, using the I/O object as an input. Then, initialize the object to create the basic file structure of the NWBFile.

    std::unique_ptr<NWB::NWBFile> nwbfile = std::make_unique<NWB::NWBFile>(io);
    Status initStatus = nwbfile->initialize(generateUuid());
    REQUIRE(initStatus == Status::Success);

4. Create the recording metadata

Create the extracellular recording metadata

Next, construct the ElectrodeTable object, using the recordingArrays as an input. Note that in many cases, you will be recording from all electrodes detected by the device and this recordingArrays structure will be the same as is used to create the ElectricalSeries. However in some cases (e.g. when using Neuropixels or multiple probes), you may be recording from a subset of all available electrodes as part of a single ElectricalSeries. In this case, you should create the ref AQNWB::NWB::ElectrodesTable "ElectrodesTable" with all electrodes detected by the acquisition system, not just those being actively recorded from. This approach is critical for mapping information about which ElectricalSeries were recorded from which electrodes.

    Status elecTableStatus =
        nwbfile->createElectrodesTable(mockRecordingArrays);
    REQUIRE(elecTableStatus == Status::Success);

5. Create datasets and add to RecordingContainers.

Next, create the different data types (e.g. ElectricalSeries or other AQNWB::NWB::TimeSeries "TimeSeries") that you would like to write data into. After creation, these objects are added to the RecordingContainers object so that it can mana ge access and data writing during the recording process. When adding containers, ownership of the Container is transferred to the RecordingContainers object, so that we can access it again via its index. New containers will always be appended to the end of the private member RecordingContainers::m_containers object and their index can be tracked using the RecordingContainers.size of the input recordingArrays.

    std::vector<SizeType> containerIndexes;
    Status elecSeriesStatus =
        nwbfile->createElectricalSeries(mockRecordingArrays,
                                        mockChannelNames,
                                        BaseDataType::I16,
                                        recordingContainers.get(),
                                        containerIndexes);
    REQUIRE(elecSeriesStatus == Status::Success);

6. Start the recording.

Then, start the recording process with a call to the startRecording function of the I/O object.

Note

When using HDF5IO for writing to HDF5, calling startRecording will by default enable SWMR mode to ensure file integrity and support concurrent read. As a result, no additional datasets or groups can be added to the file once a recording has been started unless the file is is closed and reopened.

    Status startRecordingStatus = io->startRecording();
    REQUIRE(startRecordingStatus == Status::Success);

7. Write data.

During the recording process, use the RecordingContainers as an interface to access the various Container object and corresponding datasets and write blocks of data to the file. Calling flush() on the I/O object at any time will ensure the data is moved to disk.

          recordingContainers->writeTimeseriesData(containerIndexes[i],
                                                   channel,
                                                   dataShape,
                                                   positionOffset,
                                                   intBuffer.get(),
                                                   timestampsBuffer.data());
          io->flush();

8. Stop the recording and finalize the file.

When the recording process is finished, call stopRecording from the I/O object to flush any data and close the file.

    io->stopRecording();
    nwbfile->finalize();
    io->close();