update documentation

Author: alessandratrapani

CHANGELOG.md

@@ -1,3 +1,24 @@
+# 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
 

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: 
@@ -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

docs/source/format.rst

@@ -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