NWBFile.hpp

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
#include "Types.hpp"
#include "Utils.hpp"
#include "io/BaseIO.hpp"
#include "io/ReadIO.hpp"
#include "nwb/base/NWBContainer.hpp"
#include "nwb/base/ProcessingModule.hpp"
#include "nwb/base/TimeSeries.hpp"
#include "nwb/epoch/TimeIntervals.hpp"
#include "nwb/event/EventsTable.hpp"
#include "nwb/file/ElectrodesTable.hpp"
#include "nwb/file/Subject.hpp"
#include "spec/core.hpp"

namespace AQNWB::NWB
{

class NWBFile : public NWBContainer
{
public:
  // Register the NWBFile as a subclass of NWBContainer
  REGISTER_SUBCLASS(NWBFile, NWBContainer, AQNWB::SPEC::CORE::namespaceName)
 
  // Static paths for NWB file structure
  inline const static std::string ACQUISITION_PATH = "/acquisition";
  inline const static std::string SPECIFICATIONS_PATH = "/specifications";
  inline const static std::string PROCESSING_PATH = "/processing";
  inline const static std::string STIMULUS_PATH = "/stimulus";
  inline const static std::string GENERAL_PATH = "/general";
  inline const static std::string ANALYSIS_PATH = "/analysis";
  inline const static std::string EVENTS_PATH = "/events";
  inline const static std::string INTERVALS_PATH = "/intervals";

  static std::shared_ptr<NWBFile> create(std::shared_ptr<IO::BaseIO> io)
  {
    return RegisteredType::create<NWBFile>("/", io);
  }
 
protected:
  explicit NWBFile(std::shared_ptr<IO::BaseIO> io);

  NWBFile(const std::string& path, std::shared_ptr<IO::BaseIO> io);
 
public:
  NWBFile(const NWBFile&) = delete;

  NWBFile& operator=(const NWBFile&) = delete;

  ~NWBFile() override;

  Status initialize(const std::string& identifierText,
                    const std::string& description = "a recording session",
                    const std::string& dataCollection = "",
                    const std::string& sessionStartTime = "",
                    const std::string& timestampsReferenceTime = "",
                    const std::optional<AQNWB::NWB::Subject::SubjectSpec>&
                        subjectSpec = std::nullopt);

  bool isInitialized() const;

  std::shared_ptr<ElectrodesTable> createElectrodesTable(
      std::vector<Types::ChannelVector> recordingArrays,
      bool finalizeTable = true,
      const SizeType rowChunkSize = 100);

  static Status requireEventsGroup(std::shared_ptr<IO::BaseIO> io);

  static Status requireIntervalsGroup(std::shared_ptr<IO::BaseIO> io);

  std::shared_ptr<EventsTable> createEventsTable(
      const std::string& name,
      const std::string& description,
      const std::optional<std::string>& sourceDescription = std::nullopt,
      std::optional<float> timestampResolution = std::nullopt,
      bool createDurationColumn = false,
      std::optional<float> durationResolution = std::nullopt,
      const bool createAnnotationColumn = false,
      const SizeType rowChunkSize = 100);

  std::shared_ptr<EventsTable> createEventsTable(
      const std::string& name,
      const std::string& description,
      const std::string& sourceDescription,
      const std::vector<NWB::DynamicTable::DataSpecPtr>& columnSpecs);

  std::shared_ptr<TimeIntervals> createEpochs(
      const bool createTagsColumn = false, const SizeType rowChunkSize = 100);

  std::shared_ptr<TimeIntervals> createTrials(
      const bool createTagsColumn = false, const SizeType rowChunkSize = 100);

  std::shared_ptr<TimeIntervals> createInvalidTimes(
      const bool createTagsColumn = false, const SizeType rowChunkSize = 100);

  std::shared_ptr<TimeIntervals> createTimeIntervals(
      const std::string& name,
      const std::string& description,
      const bool createTagsColumn = false,
      const SizeType rowChunkSize = 100);

  std::shared_ptr<TimeIntervals> createTimeIntervals(
      const std::string& name,
      const std::string& description,
      const std::vector<NWB::DynamicTable::DataSpecPtr>& columnSpecs);

  Status createElectricalSeries(
      std::vector<Types::ChannelVector> recordingArrays,
      std::vector<std::string> recordingNames,
      const IO::BaseDataType& dataType,
      std::vector<SizeType>& containerIndexes);

  Status createSpikeEventSeries(
      std::vector<Types::ChannelVector> recordingArrays,
      std::vector<std::string> recordingNames,
      const IO::BaseDataType& dataType,
      std::vector<SizeType>& containerIndexes);

  Status createAnnotationSeries(const std::vector<std::string>& recordingNames,
                                std::vector<SizeType>& containerIndexes);
 
  DEFINE_REGISTERED_FIELD(readEpochs,
                          TimeIntervals,
                          "intervals/epochs",
                          "Table of experimental epochs.")
 
  DEFINE_REGISTERED_FIELD(readTrials,
                          TimeIntervals,
                          "intervals/trials",
                          "Table of experimental trials.")
 
  DEFINE_REGISTERED_FIELD(readInvalidTimes,
                          TimeIntervals,
                          "intervals/invalid_times",
                          "Table of invalid times.")
 
  DEFINE_REGISTERED_FIELD(readElectrodesTable,
                          ElectrodesTable,
                          ElectrodesTable::electrodesTablePath,
                          "table with the extracellular electrodes")
 
  DEFINE_ATTRIBUTE_FIELD(readNWBVersion,
                         std::string,
                         "nwb_version",
                         File version string)
 
  DEFINE_DATASET_FIELD(readFileCreateDate,
                       recordFileCreateDate,
                       std::string,
                       "file_create_date",
                       A record of the date the file was created and of
                           subsequent modifications)
 
  DEFINE_DATASET_FIELD(readIdentifier,
                      recordIdentifier,
                      std::string,
                      "identifier",
                      A unique text identifier for the file)
 
  DEFINE_DATASET_FIELD(readSessionDescription,
                       recordSessionDescription,
                       std::string,
                       "session_description",
                       A description of the experimental session and data in the
                           file)
 
  DEFINE_DATASET_FIELD(readSessionStartTime,
                       recordSessionStartTime,
                       std::string,
                       "session_start_time",
                       Date and time of the experiment or session start)
 
  DEFINE_DATASET_FIELD(readTimestampsReferenceTime,
                       recordTimestampsReferenceTime,
                       std::string,
                       "timestamps_reference_time",
                       Date and time corresponding to time zero of all
                           timestamps)
 
  DEFINE_UNNAMED_REGISTERED_FIELD(readAquisitionSeries,
                                  createAquisitionSeries,
                                  TimeSeries,
                                  "acquisition",
                                  Get a TimeSeries stored in the acquisition
                                      group)
 
  DEFINE_UNNAMED_REGISTERED_FIELD(readProcessingModule,
                                  createProcessingModule,
                                  ProcessingModule,
                                  "processing",
                                  Get a ProcessingModule stored in the
                                      processing group)
 
  DEFINE_UNNAMED_REGISTERED_FIELD(readTimeIntervals,
                                  createTimeIntervalsInstance,
                                  TimeIntervals,
                                  "intervals",
                                  Get a TimeIntervals object stored in the
                                      intervals group)
 
  DEFINE_UNNAMED_REGISTERED_FIELD(readEventsTable,
                                  createEventsTableInstance,
                                  EventsTable,
                                  "events",
                                  Get an EventsTable stored in the events group)
 
protected:
  Status createFileStructure(const std::string& identifierText,
                             const std::string& description,
                             const std::string& dataCollection,
                             const std::string& sessionStartTime,
                             const std::string& timestampsReferenceTime);
 
private:
  void cacheSpecifications(const Types::NamespaceInfo& namespaceInfo);

  std::unique_ptr<ElectrodesTable> m_electrodeTable;
};
 
}  // namespace AQNWB::NWB