Add optional optical_path_scheme field to MicroscopyRig

Author: alessandratrapani

CHANGELOG.md

@@ -22,6 +22,7 @@
   - `ViralVectorInjection` objects (from ndx-ophys-devices)
   - `Indicator` objects (from ndx-ophys-devices)
 - Added support for `ViralVector` and `ViralVectorInjection` imports from ndx-ophys-devices
+- Added optional `optical_path_scheme` field to `MicroscopyRig` (an `Image` group) for storing an annotated diagram or picture of the microscope's optical path layout
 
 ## Notes
 - These changes improve metadata organization by centralizing all experiment-related objects in `MicroscopyExperimentMetadata`

README.md

@@ -99,6 +99,10 @@ classDiagram
         dichroic_mirror : DichroicMirror, optional
         photodetector : Photodetector, optional
         emission_filter : OpticalFilter, optional
+        --------------------------------------
+        groups
+        --------------------------------------
+        optical_path_scheme : Image, optional
     }
 
     class ExcitationSource {
@@ -297,6 +301,10 @@ classDiagram
         dichroic_mirror : DichroicMirror, optional
         photodetector : Photodetector, optional
         emission_filter : OpticalFilter, optional
+        --------------------------------------
+        groups
+        --------------------------------------
+        optical_path_scheme : Image, optional
     }
 
     class ViralVector {
@@ -478,6 +486,10 @@ classDiagram
         dichroic_mirror : DichroicMirror, optional
         photodetector : Photodetector, optional
         emission_filter : OpticalFilter, optional
+        --------------------------------------
+        groups
+        --------------------------------------
+        optical_path_scheme : Image, optional
     }
 
     MicroscopySeries <|-- PlanarMicroscopySeries : extends

docs/source/format.rst

@@ -73,6 +73,15 @@ A collection of devices and metadata that make up the microscopy rig.
             target_type: OpticalFilter
             doc: Link to OpticalFilter object which contains metadata about the emission filter. It can be either a BandOpticalFilter (e.g., 'Bandpass', 'Bandstop', 'Longpass', 'Shortpass') or a EdgeOpticalFilter (Longpass or Shortpass).
             quantity: "?"
+          - name: objective_lens
+            target_type: ObjectiveLens
+            doc: Link to ObjectiveLens object which contains metadata about the objective lens used in the microscopy rig.
+            quantity: "?"
+        groups:
+          - name: optical_path_scheme
+            neurodata_type_inc: Image
+            doc: optional link to Images object that provide an annotated scheme of the microscope and / or optical path.
+            quantity: "?"
 
 For other device components (ExcitationSource, OpticalFilter, Photodetector, etc.), please refer to the `ndx-ophys-devices documentation <https://ndx-ophys-devices.readthedocs.io/>`_.
 

docs/source/user_guide.rst

@@ -145,9 +145,18 @@ The device components include MicroscopeModel, Microscope, and MicroscopyRig:
            excitation_filter=ex_filter,
            dichroic_mirror=dichroic,
            photodetector=detector,
-           emission_filter=em_filter
+           emission_filter=em_filter,
+           # Optionally, attach a scheme image of the optical path
+           # optical_path_scheme=Image(
+           #     name="optical_path_scheme",
+           #     data=optical_path_image_data,  # numpy array, e.g. (H, W, 3) uint8
+           #     description="Annotated scheme of the two-photon optical path.",
+           # )
        )
 
+   The ``optical_path_scheme`` parameter is optional and accepts a ``pynwb.image.Image`` object. 
+   This can be used to store an annotated diagram or picture of the microscope's optical path layout.
+
 Other optical components (filters, sources, detectors) are provided by the ndx-ophys-devices extension.
 
 4. **MicroscopyExperimentMetadata**: Container for centralizing all experiment metadata

examples/two-photon_calcium_imaging_example.ipynb

@@ -270,6 +270,13 @@
    "outputs": [],
    "source": [
     "# Create microscopy rig\n",
+    "# Optionally, you can attach an annotated image/scheme of the optical path:\n",
+    "# from pynwb.image import Image\n",
+    "# optical_path_scheme = Image(\n",
+    "#     name='optical_path_scheme',\n",
+    "#     data=optical_path_image_array,  # numpy array, e.g. (H, W, 3) uint8\n",
+    "#     description='Annotated scheme of the two-photon optical path.',\n",
+    "# )\n",
     "microscopy_rig = MicroscopyRig(\n",
     "    name='2p_rig',\n",
     "    description='Two-photon microscopy rig for calcium imaging',\n",
@@ -278,7 +285,8 @@
     "    excitation_filter=excitation_filter,\n",
     "    dichroic_mirror=dichroic,\n",
     "    photodetector=detector,\n",
-    "    emission_filter=emission_filter\n",
+    "    emission_filter=emission_filter,\n",
+    "    # optical_path_scheme=optical_path_scheme,  # Optional: attach optical path diagram\n",
     ")\n",
     "\n",
     "# Create microscopy channel\n",

spec/ndx-microscopy.extensions.yaml

@@ -48,6 +48,11 @@ groups:
         target_type: ObjectiveLens
         doc: Link to ObjectiveLens object which contains metadata about the objective lens used in the microscopy rig.
         quantity: "?"
+    groups:
+      - name: optical_path_scheme
+        neurodata_type_inc: Image
+        doc: optional link to Images object that provide an annotated scheme of the microscope and / or optical path.
+        quantity: "?"
 
   - neurodata_type_def: MicroscopyChannel
     neurodata_type_inc: NWBContainer

src/pynwb/ndx_microscopy/testing/_mock.py

@@ -12,6 +12,7 @@
     mock_DichroicMirror,
 )
 
+from pynwb.image import Image
 from pynwb.testing.mock.utils import name_generator
 from pynwb.core import DynamicTableRegion
 import ndx_microscopy
@@ -79,6 +80,7 @@ def mock_MicroscopyRig(
     dichroic_mirror: DichroicMirror = None,
     photodetector: Photodetector = None,
     emission_filter: OpticalFilter = None,
+    optical_path_scheme: Optional[Image] = None,
 ) -> ndx_microscopy.MicroscopyRig:
     microscopy_rig = ndx_microscopy.MicroscopyRig(
         name=name or name_generator("MicroscopyRig"),
@@ -89,6 +91,7 @@ def mock_MicroscopyRig(
         dichroic_mirror=dichroic_mirror or mock_DichroicMirror(),
         photodetector=photodetector or mock_Photodetector(),
         emission_filter=emission_filter or mock_OpticalFilter(),
+        optical_path_scheme=optical_path_scheme,
     )
     return microscopy_rig