catalystneuro · alessandratrapani · Mar 25, 2026 · Dec 1, 2025 · Dec 1, 2025 · Dec 1, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,23 @@
-# v0.4.0 (upcoming)
+# v0.4.0 (Upcoming)
+
+## Deprecations and Changes
+- **Breaking Change**: `OpticalLens`changed in `ObjectiveLens`
+- **Breaking Change**: `MicroscopyChannel.indicator` changed from a nested group to a link reference
+- **Breaking Change**: `MicroscopySeries.microscopy_rig` changed from a nested group to a link reference
+- Updated `ndx-ophys-devices` dependency from v0.2.0 to v0.4.0
+
+## Features
+- Added `MicroscopyExperimentMetadata` (extends `LabMetaData`) as a centralized container for experiment metadata, including:
+  - `MicroscopyRig` objects
+  - `ViralVector` objects (from ndx-ophys-devices)
+  - `ViralVectorInjection` objects (from ndx-ophys-devices)
+  - `Indicator` objects (from ndx-ophys-devices)
+- Added support for `ViralVector` and `ViralVectorInjection` imports from ndx-ophys-devices
+
+## Notes
+- These changes improve metadata organization by centralizing all experiment-related objects in `MicroscopyExperimentMetadata`
+- The use of links instead of nested groups provides better data reusability and reduces duplication
+- Users should add `MicroscopyExperimentMetadata` to NWBFile using `nwbfile.add_lab_meta_data()`
 
 # v0.3.0 (Jun 3, 2025)
 ## Bug Fixes

diff --git a/README.md b/README.md
@@ -5,6 +5,8 @@ A Neurodata Without Borders (NWB) extension for storing microscopy data and asso
 ## Features
 
 **Comprehensive Neurodata Types**
+- Experiment metadata container:
+    - `MicroscopyExperimentMetadata`
 - Microscope and optical component metadata (integration with [ndx-ophys-devices](https://github.com/catalystneuro/ndx-ophys-devices)):
     - `MicroscopeModel`
     - `Microscope`
@@ -14,6 +16,8 @@ A Neurodata Without Borders (NWB) extension for storing microscopy data and asso
     - `DichroicMirror` 
     - `Photodetector` 
     - `Indicator`
+    - `ViralVector`
+    - `ViralVectorInjection`
 - Microscopy channel configurations: 
     - `MicroscopyChannel`
 - Imaging space definitions: 
@@ -56,7 +60,7 @@ classDiagram
         model_number : text, optional
     }
 
-    class DeviceInstance{
+    class Device{
         <<Device>>
         --------------------------------------
         attributes
@@ -73,7 +77,7 @@ classDiagram
     }
 
     class Microscope {
-        <<DeviceInstance>>
+        <<Device>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -98,7 +102,7 @@ classDiagram
     }
 
     class ExcitationSource {
-        <<DeviceInstance>>
+        <<Device>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -121,7 +125,7 @@ classDiagram
     }
 
     class OpticalFilter {
-        <<DeviceInstance>>
+        <<Device>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -149,7 +153,7 @@ classDiagram
     }
 
     class DichroicMirror {
-        <<DeviceInstance>>
+        <<Device>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -161,7 +165,7 @@ classDiagram
     }
 
     class Photodetector {
-        <<DeviceInstance>>
+        <<Device>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -184,7 +188,7 @@ classDiagram
     }
 
     DeviceModel <|-- MicroscopeModel : extends
-    DeviceInstance <|-- Microscope : extends
+    Device <|-- Microscope : extends
 
     Microscope o--> MicroscopeModel : links
     MicroscopyRig o--> Microscope : links
@@ -266,6 +270,90 @@ classDiagram
     ImagingSpace *-- IlluminationPattern : contains
 ```
 
+#### Experiment Metadata Components
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffffff', 'primaryBorderColor': '#144E73', 'lineColor': '#D96F32'}}}%%
+
+classDiagram
+    direction TB
+
+    class MicroscopyExperimentMetadata {
+        <<LabMetaData>>
+        --------------------------------------
+        groups
+        --------------------------------------
+        **microscopy_rigs** : MicroscopyRig[0..*]
+        **viral_vectors** : ViralVector[0..*]
+        **viral_vector_injections** : ViralVectorInjection[0..*]
+        **indicators** : Indicator[0..*]
+    }
+
+    class MicroscopyRig {
+        <<NWBContainer>>
+        --------------------------------------
+        attributes
+        --------------------------------------
+        description : text
+        --------------------------------------
+        links
+        --------------------------------------
+        microscope : Microscope
+        excitation_source : ExcitationSource, optional
+        excitation_filter : OpticalFilter, optional
+        dichroic_mirror : DichroicMirror, optional
+        photodetector : Photodetector, optional
+        emission_filter : OpticalFilter, optional
+    }
+
+    class ViralVector {
+        <<NWBContainer>>
+        --------------------------------------
+        attributes
+        --------------------------------------
+        **construct_name** : text
+        titer_in_vg_per_ml : numeric, optional
+        manufacturer : text, optional
+        description : text, optional
+    }
+    class ViralVectorInjection {
+        <<NWBContainer>>
+        --------------------------------------
+        attributes
+        --------------------------------------
+        location : text, optional
+        hemisphere : text, optional
+        ap_in_mm : numeric, optional
+        ml_in_mm : numeric, optional
+        dv_in_mm : numeric, optional
+        pitch_in_deg : numeric, optional
+        yaw_in_deg : numeric, optional
+        roll_in_deg : numeric, optional
+        stereotactic_rotation_in_deg : numeric, optional
+        stereotactic_tilt_in_deg : numeric, optional
+        volume_in_uL : numeric, optional
+        injection_date : text, optional
+        **viral_vector** : ViralVector
+        }
+    class Indicator {
+        <<NWBContainer>>
+        --------------------------------------
+        attributes
+        --------------------------------------
+        **label** : text
+        description : text, optional
+        manufacturer : text, optional
+        **viral_vector_injection** : ViralVectorInjection, optional
+    }
+
+    MicroscopyExperimentMetadata *-- MicroscopyRig : contains
+    MicroscopyExperimentMetadata *-- ViralVector : contains
+    MicroscopyExperimentMetadata *-- ViralVectorInjection : contains
+    MicroscopyExperimentMetadata *-- Indicator : contains
+    ViralVectorInjection o--> ViralVector : links
+    Indicator o--> ViralVectorInjection : links
+```
+
 #### Microscopy Series and Imaging Space Components
 
 ```mermaid
@@ -284,17 +372,20 @@ classDiagram
         **excitation_wavelength_in_nm** : float
         **emission_wavelength_in_nm** : float
         --------------------------------------
-        groups
+        links
         --------------------------------------
-        indicator
+        **indicator** : Indicator
     }
 
     class MicroscopySeries {
         <<TimeSeries>>
         --------------------------------------
-        groups
+        links
         --------------------------------------
         **microscopy_rig** : MicroscopyRig
+        --------------------------------------
+        groups
+        --------------------------------------
         **microscopy_channel** : MicroscopyChannel
 
     }
@@ -412,9 +503,9 @@ classDiagram
     VolumetricMicroscopySeries *-- VolumetricImagingSpace : contains
     MultiPlaneMicroscopyContainer *-- PlanarMicroscopySeries : contains
     MultiChannelMicroscopyContainer *-- MicroscopySeries : contains
-    MicroscopySeries *-- MicroscopyRig : contains
-    MicroscopyChannel *-- MicroscopySeries : contains    
-    MicroscopyChannel --* Indicator : contains
+    MicroscopySeries o--> MicroscopyRig : links
+    MicroscopySeries *-- MicroscopyChannel : contains    
+    MicroscopyChannel o--> Indicator : links
 ```
 
 #### Segmentation Components

diff --git a/docs/source/format.rst b/docs/source/format.rst
@@ -26,7 +26,7 @@ A device instance for acquiring imaging data.
 
     groups:
       - neurodata_type_def: Microscope
-        neurodata_type_inc: DeviceInstance
+        neurodata_type_inc: Device
         doc: Instance of a microscope used to acquire imaging data.
         attributes:
           - name: technique
@@ -100,10 +100,36 @@ Represents a channel in a microscope with metadata about the indicator and wavel
           - name: emission_wavelength_in_nm
             dtype: float64
             doc: Wavelength of the emission light in nanometers.
+        links:
+          - name: indicator
+            target_type: Indicator
+            doc: Link to Indicator object which contains metadata about the indicator used in this light path.
+            quantity: 1
+
+MicroscopyExperimentMetadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Container for centralizing all microscopy experiment metadata.
+
+.. code-block:: yaml
+
+    groups:
+      - neurodata_type_def: MicroscopyExperimentMetadata
+        neurodata_type_inc: LabMetaData
+        doc: Metadata about the microscopy experiment.
+        name: microscopy_experiment_metadata
         groups:
+          - neurodata_type_inc: MicroscopyRig
+            doc: Group containing of one or more MicroscopyRig objects.
+            quantity: "*"
+          - neurodata_type_inc: ViralVector
+            doc: Group containing of one or more ViralVector objects.
+            quantity: "*"
+          - neurodata_type_inc: ViralVectorInjection
+            doc: Group containing one or more ViralVectorInjection objects.
+            quantity: "*"
           - neurodata_type_inc: Indicator
-            doc: Indicator object which contains metadata about the indicator used in this light path.
-            quantity: 1
+            doc: Group containing one or more Indicator objects.
+            quantity: "*"
 
 Microscopy Series Components
 ------------------------
@@ -119,10 +145,11 @@ Base type for microscopy time series data.
         neurodata_type_inc: TimeSeries
         doc: Imaging data acquired over time from an optical channel in a microscope while a light source illuminates the
           imaging space.
+        links:
+          - name: microscopy_rig
+            doc: Link to a MicroscopyRig object containing metadata about the microscopy rig used to acquire this imaging data.
+            target_type: MicroscopyRig
         groups:
-          - neurodata_type_inc: MicroscopyRig
-            doc: MicroscopyRig object containing metadata about the microscopy rig used to acquire this imaging data.
-            quantity: 1
           - neurodata_type_inc: MicroscopyChannel
             doc: MicroscopyChannel object containing metadata about the channel used to acquire this imaging data.
             quantity: 1
@@ -440,7 +467,7 @@ Base type for segmentation data.
     groups:
       - neurodata_type_def: Segmentation
         neurodata_type_inc: DynamicTable
-        doc: Abstract class to contain the results from image segmentation of a specific imaging space.
+        doc: Abstract class to contain the spatial components resulting from image segmentation of a specific imaging space.
         attributes:
           - name: description
             dtype: text
@@ -459,7 +486,7 @@ For 2D segmentation data.
     groups:
       - neurodata_type_def: PlanarSegmentation
         neurodata_type_inc: Segmentation
-        doc: Results from image segmentation of a specific planar imaging space.
+        doc: ROI spatial components resulting from image segmentation of a specific planar imaging space.
         datasets:
           - name: image_mask
             neurodata_type_inc: VectorData
@@ -505,7 +532,7 @@ For 3D segmentation data.
     groups:
       - neurodata_type_def: VolumetricSegmentation
         neurodata_type_inc: Segmentation
-        doc: Results from image segmentation of a specific volumetric imaging space.
+        doc: ROI spatial components resulting from image segmentation of a specific volumetric imaging space.
         datasets:
           - name: volume_mask
             neurodata_type_inc: VectorData
@@ -560,7 +587,7 @@ Container for multiple segmentations.
         doc: A container of many Segmentation objects.
         groups:
           - neurodata_type_inc: Segmentation
-            doc: Results from image segmentation of a specific imaging space.
+            doc: Results from image segmentation.
             quantity: "+"
 
 SummaryImage
@@ -603,7 +630,10 @@ For extracted ROI responses.
     groups:
       - neurodata_type_def: MicroscopyResponseSeries
         neurodata_type_inc: TimeSeries
-        doc: ROI responses extracted from optical imaging.
+        doc:       
+          ROI responses extracted from imaging data, linked in the microscopy_series field.
+          This object contains the temporal components from multiple ROIs,
+          that can result from different processing steps, e.g., raw, deconvolved, or denoised fluorescence traces.
         datasets:
           - name: data
             dtype: numeric
@@ -616,8 +646,9 @@ For extracted ROI responses.
             doc: Signals from ROIs.
           - name: rois
             neurodata_type_inc: DynamicTableRegion
-            doc: DynamicTableRegion referencing segmentation containing more information about the ROIs
-              stored in this series.
+            doc: 
+              DynamicTableRegion referencing Segmentation table containing information about the ROIs
+              spatial components.
         links:
           - name: microscopy_series
             doc: Link to a MicroscopySeries object containing the imaging data this response series is derived from.