Restructure classes and workflow

CMakeLists.txt

@@ -23,7 +23,7 @@ add_library(
     src/Channel.cpp
     src/hdf5/HDF5IO.cpp
     src/nwb/NWBFile.cpp
-    src/nwb/NWBRecording.cpp
+    src/nwb/RecordingContainers.cpp
     src/nwb/base/TimeSeries.cpp
     src/nwb/device/Device.cpp
     src/nwb/ecephys/ElectricalSeries.cpp

docs/pages/1_userdocs.dox

@@ -5,5 +5,6 @@
  * with a particular data acquisition software via AqNWB.
  *
  * - \subpage user_install_page
+ * - \subpage workflow
  * - \subpage hdf5io
  */

docs/pages/userdocs/workflow.dox

@@ -0,0 +1,83 @@
+/**
+ * \page workflow AqNWB Workflow
+ *
+ * \tableofcontents
+ *
+ * \section recording_workflow 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.
+ * 2. Create the `RecordingContainers` object. 
+ * 3. Create the `NWBFile` object.
+ * 4. Create datasets and add to RecordingContainers.
+ * 5. Start the recording.
+ * 6. Write data.
+ * 7. Stop the recording and close the NWBFile.
+ * 
+ * Below, we walk through these steps in more detail.
+ * 
+ * 
+ * \subsection create_io 1. Create the I/O object.
+ * 
+ * First, create an I/O object. We provide a convenience method, `createIO`
+ * to create this object using one of our 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.
+ * 
+ * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_io_snippet
+ *
+ *
+ * \subsection create_recording_container 2. Create the RecordingContainer object.
+ * 
+ * Next, create a RecordingContainer object to manage the different datasets 
+ * that you would like to write data to.
+ * 
+ * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_recording_containers_snippet
+ * 
+ *
+ * \subsection create_nwbfile 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.
+ *
+ * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_nwbfile_snippet
+ *
+ * 
+ * \subsection create_datasets 4. Create datasets and add to RecordingContainers.
+ *
+ * Next, create the different data types (e.g. `ElectricalSeries`, other `TimeSeries`)
+ * that you would like to write data into. After creation, these objects are moved
+ * to the RecordingContainers object so that it can manage access and data writing
+ * during the recording process. 
+ * 
+ * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_datasets_snippet
+ *
+ *
+ * \subsection start_recording 5. Start the recording.
+ *
+ * Then, start the recording process with a call to the I/O object. By default for
+ * HDF5 files, this will enable SWMR mode and no additional datasets or groups can be added
+ * to the file unless it is closed and reopened.
+ *
+ * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_start_snippet
+ *
+ * 
+ * \subsection write_data 6. Write data.
+ *
+ * During the recording process, use the RecordingContainers as an interface
+ * to access the various datasets and write blocks of data to the file. 
+ * 
+ * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_write_snippet
+ *
+ * 
+ * \subsection stop_recording 7. 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.
+ * 
+ * \snippet tests/examples/testWorkflowExamples.cpp example_workflow_stop_snippet
+ *
+ *
+ */

src/Utils.hpp

@@ -58,11 +58,11 @@ inline std::string getCurrentTime()
  * @brief Factory method to create an IO object.
  * @return A pointer to a BaseIO object
  */
-inline std::unique_ptr<BaseIO> createIO(const std::string& type,
+inline std::shared_ptr<BaseIO> createIO(const std::string& type,
                                         const std::string& filename)
 {
   if (type == "HDF5") {
-    return std::make_unique<HDF5::HDF5IO>(filename);
+    return std::make_shared<HDF5::HDF5IO>(filename);
   } else {
     throw std::invalid_argument("Invalid IO type");
   }

src/nwb/NWBFile.cpp

@@ -45,7 +45,6 @@ Status NWBFile::initialize()
 
 Status NWBFile::finalize()
 {
-  recordingContainers.reset();
   return io->close();
 }
 
@@ -93,7 +92,8 @@ Status NWBFile::createFileStructure()
 
 Status NWBFile::createElectricalSeries(
     std::vector<Types::ChannelVector> recordingArrays,
-    const BaseDataType& dataType)
+    const BaseDataType& dataType,
+    RecordingContainers* recordingContainers)
 {
   if (!io->canModifyObjects()) {
     return Status::Failure;
@@ -145,16 +145,6 @@ Status NWBFile::createElectricalSeries(
   return Status::Success;
 }
 
-Status NWBFile::startRecording()
-{
-  return io->startRecording();
-}
-
-void NWBFile::stopRecording()
-{
-  io->stopRecording();
-}
-
 template<SizeType N>
 void NWBFile::cacheSpecifications(
     const std::string& specPath,
@@ -182,26 +172,3 @@ std::unique_ptr<AQNWB::BaseRecordingData> NWBFile::createRecordingData(
   return std::unique_ptr<BaseRecordingData>(
       io->createArrayDataSet(type, size, chunking, path));
 }
-
-TimeSeries* NWBFile::getTimeSeries(const SizeType& timeseriesInd)
-{
-  if (timeseriesInd >= this->recordingContainers->containers.size()) {
-    return nullptr;
-  } else {
-    return this->recordingContainers->containers[timeseriesInd].get();
-  }
-}
-
-// Recording Container
-
-RecordingContainers::RecordingContainers(const std::string& name)
-    : name(name)
-{
-}
-
-RecordingContainers::~RecordingContainers() {}
-
-void RecordingContainers::addData(std::unique_ptr<TimeSeries> data)
-{
-  this->containers.push_back(std::move(data));
-}

src/nwb/NWBFile.hpp

@@ -9,6 +9,7 @@
 
 #include "BaseIO.hpp"
 #include "Types.hpp"
+#include "nwb/RecordingContainers.hpp"
 #include "nwb/base/TimeSeries.hpp"
 
 /*!
@@ -18,8 +19,6 @@
 namespace AQNWB::NWB
 {
 
-class RecordingContainers;  // declare here because gets used in NWBFile class
-
 /**
  * @brief The NWBFile class provides an interface for setting up and managing
  * the NWB file.
@@ -69,28 +68,14 @@ class NWBFile
    * @param recordingArrays vector of ChannelVector indicating the electrodes to
    *                        record from. A separate ElectricalSeries will be
    *                        created for each ChannelVector.
+   * @param recordingContainers The container to store the created TimeSeries.
    * @param dataType The data type of the elements in the data block.
    * @return Status The status of the object creation operation.
    */
   Status createElectricalSeries(
       std::vector<Types::ChannelVector> recordingArrays,
-      const BaseDataType& dataType = BaseDataType::I16);
-
-  /**
-   * @brief Starts the recording.
-   */
-  Status startRecording();
-
-  /**
-   * @brief Stops the recording.
-   */
-  void stopRecording();
-
-  /**
-   * @brief Gets the TimeSeries object from the recordingContainers
-   * @param timeseriesInd The index of the timeseries dataset within the group.
-   */
-  TimeSeries* getTimeSeries(const SizeType& timeseriesInd);
+      const BaseDataType& dataType = BaseDataType::I16,
+      RecordingContainers* recordingContainers = nullptr);
 
 protected:
   /**
@@ -133,53 +118,8 @@ class NWBFile
       const std::array<std::pair<std::string_view, std::string_view>, N>&
           specVariables);
 
-  /**
-   * @brief Holds the Container (usually TimeSeries) objects that have been
-   * created in the nwb file for recording.
-   */
-  std::unique_ptr<RecordingContainers> recordingContainers =
-      std::make_unique<RecordingContainers>("RecordingContainers");
-
   const std::string identifierText;
   std::shared_ptr<BaseIO> io;
 };
 
-/**
- * @brief The RecordingContainers class provides an interface for managing
- * groups of TimeSeries acquired during a recording.
- */
-class RecordingContainers
-{
-public:
-  /**
-   * @brief Constructor for RecordingContainer class.
-   * @param name The name of the group of time series
-   */
-  RecordingContainers(const std::string& name);
-
-  /**
-   * @brief Deleted copy constructor to prevent construction-copying.
-   */
-  RecordingContainers(const RecordingContainers&) = delete;
-
-  /**
-   * @brief Deleted copy assignment operator to prevent copying.
-   */
-  RecordingContainers& operator=(const RecordingContainers&) = delete;
-
-  /**
-   * @brief Destructor for RecordingContainer class.
-   */
-  ~RecordingContainers();
-
-  /**
-   * @brief Adds a TimeSeries object to the container.
-   * @param data The TimeSeries object to add.
-   */
-  void addData(std::unique_ptr<TimeSeries> data);
-
-  std::vector<std::unique_ptr<TimeSeries>> containers;
-  std::string name;
-};
-
-}  // namespace AQNWB::NWB
+}  // namespace AQNWB::NWB