Add Microscopy Rig (#61)

* add MicroscopyRig and MicroscopeModel

* add mock functions

* update tests

* update README

* update docs

* update notebooks

* update changelog

* ruff fixes

* update requirements

* update ndx-ophys-devices dependency to use GitHub repository

* update ndx-ophys-devices dependency to version 0.2.0 and add OpticalLens to the namespace and extensions

* update ndx-ophys-devices dependency to version 0.2.0 and add OpticalLens to the namespace and extensions

Author: alessandratrapani

CHANGELOG.md

@@ -1,9 +1,16 @@
 # v0.3.0 (upcoming)
 ## Bug Fixes
 
+## Deprecations and Changes
+- Removed `ExcitationLightPath` and `EmissionLightPath` classes in favor of a more integrated approach with `MicroscopyRig`
+
 ## Features
 ### NWB TAB reviews Issue[#48](https://github.com/catalystneuro/ndx-microscopy/issues/48)
 - Added MicroscopyChannel object Sub-Issue[#49](https://github.com/catalystneuro/ndx-microscopy/issues/49)
+- Added `MicroscopyRig` object Sub-Issue[#51](https://github.com/catalystneuro/ndx-microscopy/issues/51)
+- Changed `Microscope` to inherit from `DeviceInstance` instead of `Device` Sub-Issue[#51](https://github.com/catalystneuro/ndx-microscopy/issues/51)
+- Added `MicroscopeModel` that inherit from `DeviceModel` Sub-Issue[#51](https://github.com/catalystneuro/ndx-microscopy/issues/51)
+- Updated `MicroscopySeries` to use `MicroscopyRig` instead of individual `microscope`, `excitation_light_path`, and `emission_light_path` references Sub-Issue[#51](https://github.com/catalystneuro/ndx-microscopy/issues/51)
 
 # v0.2.1 (March 28, 2025)
 

README.md

@@ -6,16 +6,16 @@ A Neurodata Without Borders (NWB) extension for storing microscopy data and asso
 
 **Comprehensive Neurodata Types**
 - Microscope and optical component metadata (integration with [ndx-ophys-devices](https://github.com/catalystneuro/ndx-ophys-devices)):
+    - `MicroscopeModel`
     - `Microscope`
+    - `MicroscopyRig`
     - `ExcitationSource` / `PulsedExcitationSource`
     - `BandOpticalFilter` / `EdgeOpticalFilter` / 
     - `DichroicMirror` 
     - `Photodetector` 
     - `Indicator`
 - Microscopy channel configurations: 
     - `MicroscopyChannel`
-    - `ExcitationLightPath`
-    - `EmissionLightPath` 
 - Imaging space definitions: 
     - `PlanarImagingSpace`
     - `VolumetricImagingSpace`
@@ -38,65 +38,66 @@ A Neurodata Without Borders (NWB) extension for storing microscopy data and asso
 
 ## Entity Relationship Diagrams
 
-#### Device and Light Path Components
+#### Device Components
 
 ```mermaid
 %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffffff', 'primaryBorderColor': '#144E73', 'lineColor': '#D96F32'}}}%%
 
 classDiagram
     direction TB
-
-    class DeviceModel {
+    
+    class DeviceModel{
         <<Device>>
         --------------------------------------
         attributes
         --------------------------------------
-        model : text, optional
-    }    
-
-    class ExcitationLightPath {
-        <<LabMetaData>>
+        manufacturer : text
+        model_number : text, optional
+    }
+    
+    class DeviceInstance{
+        <<Device>>
         --------------------------------------
         attributes
         --------------------------------------
-        **description** : text
+        serial_number : text, optional
         --------------------------------------
         links
         --------------------------------------
-        **excitation_source** : ExcitationSource
-        excitation_filter : OpticalFilter, optional
-        dichroic_mirror : DichroicMirror, optional
-        --------------------------------------
-        methods
-        --------------------------------------
-        get_excitation_wavelength()
+        model : DeviceModel, optional
     }
 
-    class EmissionLightPath {
-        <<LabMetaData>>
+    class MicroscopeModel {
+        <<DeviceModel>>
+    }
+
+    class Microscope {
+        <<DeviceInstance>>
         --------------------------------------
         attributes
         --------------------------------------
-        **description** : text
+        technique : text, optional
+    }
+
+    class MicroscopyRig {
+        <<NWBContainer>>
         --------------------------------------
-        groups
+        attributes
         --------------------------------------
-        **indicator** : Indicator
+        description : text
         --------------------------------------
         links
         --------------------------------------
-        **photodetector** : Photodetector
-        emission_filter : OpticalFilter, optional
+        microscope : Microscope
+        excitation_source : ExcitationSource, optional
+        excitation_filter : OpticalFilter, optional
         dichroic_mirror : DichroicMirror, optional
-        --------------------------------------
-        methods
-        --------------------------------------
-        get_emission_wavelength()
-        get_indicator_label()
+        photodetector : Photodetector, optional
+        emission_filter : OpticalFilter, optional
     }
 
     class ExcitationSource {
-        <<DeviceModel>>
+        <<DeviceInstance>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -119,7 +120,7 @@ classDiagram
     }
 
     class OpticalFilter {
-        <<DeviceModel>>
+        <<DeviceInstance>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -147,7 +148,7 @@ classDiagram
     }
 
     class DichroicMirror {
-        <<DeviceModel>>
+        <<DeviceInstance>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -159,7 +160,7 @@ classDiagram
     }
     
     class Photodetector {
-        <<DeviceModel>>
+        <<DeviceInstance>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -181,21 +182,15 @@ classDiagram
         injection_coordinates_in_mm : float[3], optional
     }
 
-    DeviceModel <|-- ExcitationSource : extends
-    DeviceModel <|-- OpticalFilter : extends
-    DeviceModel <|-- Photodetector : extends
-    DeviceModel <|-- DichroicMirror : extends
-    ExcitationSource <|-- PulsedExcitationSource : extends
-    OpticalFilter <|-- BandOpticalFilter : extends
-    OpticalFilter <|-- EdgeOpticalFilter : extends
-
-    ExcitationLightPath o--> ExcitationSource : links
-    ExcitationLightPath o--> OpticalFilter : links
-    ExcitationLightPath o--> DichroicMirror : links
-    EmissionLightPath o--> Photodetector : links
-    EmissionLightPath o--> OpticalFilter : links
-    EmissionLightPath o--> DichroicMirror : links
-    EmissionLightPath *-- Indicator : contains
+    DeviceModel <|-- MicroscopeModel : extends
+    DeviceInstance <|-- Microscope : extends
+
+    Microscope o--> MicroscopeModel : links
+    MicroscopyRig o--> Microscope : links
+    MicroscopyRig o--> ExcitationSource : links
+    MicroscopyRig o--> OpticalFilter : links
+    MicroscopyRig o--> DichroicMirror : links
+    MicroscopyRig o--> Photodetector : links
 ```
 
 #### Illumination Pattern Components
@@ -296,14 +291,9 @@ classDiagram
     class MicroscopySeries {
         <<TimeSeries>>
         --------------------------------------
-        links
-        --------------------------------------
-        **microscope** : Microscope
-        **excitation_light_path** : ExcitationLightPath
-        **emission_light_path** : EmissionLightPath
-        --------------------------------------
         groups
         --------------------------------------
+        **microscopy_rig** : MicroscopyRig
         **microscopy_channel** : MicroscopyChannel
 
     }
@@ -376,13 +366,21 @@ classDiagram
         voxel_size_in_um : float64[3], optional
     }
 
-    class Microscope {
-        <<Device>>
+    class MicroscopyRig {
+        <<NWBContainer>>
         --------------------------------------
         attributes
         --------------------------------------
-        model : text, optional
-        technique : text, optional
+        description : text
+        --------------------------------------
+        links
+        --------------------------------------
+        microscope : Microscope
+        excitation_source : ExcitationSource, optional
+        excitation_filter : OpticalFilter, optional
+        dichroic_mirror : DichroicMirror, optional
+        photodetector : Photodetector, optional
+        emission_filter : OpticalFilter, optional
     }
 
     MicroscopySeries <|-- PlanarMicroscopySeries : extends
@@ -393,9 +391,7 @@ classDiagram
     PlanarMicroscopySeries *-- PlanarImagingSpace : contains
     VolumetricMicroscopySeries *-- VolumetricImagingSpace : contains
     MultiPlaneMicroscopyContainer *-- PlanarMicroscopySeries : contains
-    MicroscopySeries o--> Microscope : links
-    MicroscopySeries o--> ExcitationLightPath : links
-    MicroscopySeries o--> EmissionLightPath : links
+    MicroscopySeries *-- MicroscopyRig : contains
     MicroscopyChannel *-- MicroscopySeries : contains    
     MicroscopyChannel --* Indicator : contains
 ```
@@ -530,7 +526,7 @@ For detailed documentation, including API reference and additional examples, ple
 
 To help ensure a smooth Pull Request (PR) process, please always begin by raising an issue on the main repository so we can openly discuss any problems/additions before taking action.
 
-The main branch of ndx-microscopy is protected; you cannot push to it directly. You must upload your changes by pushing a new branch, then submit your changes to the main branch via a Pull Request. This allows us to conduct automated testing of your contribution, and gives us a space for developers to discuss the contribution and request changes. If you decide to tackle an issue, please make yourself an assignee on the issue to communicate this to the team. Don’t worry - this does not commit you to solving this issue. It just lets others know who they should talk to about it.
+The main branch of ndx-microscopy is protected; you cannot push to it directly. You must upload your changes by pushing a new branch, then submit your changes to the main branch via a Pull Request. This allows us to conduct automated testing of your contribution, and gives us a space for developers to discuss the contribution and request changes. If you decide to tackle an issue, please make yourself an assignee on the issue to communicate this to the team. Don't worry - this does not commit you to solving this issue. It just lets others know who they should talk to about it.
 
 From your local copy directory, use the following commands.
 
@@ -546,7 +542,7 @@ $ git checkout -b <new_branch>
 
 Make your changes. Add new objects related to optical experiment or add more attributes on the existing ones. To speed up the process, you can write mock function (see _mock.py) that would be used to test the new neurodata type
 
-We will automatically run tests to ensure that your contributions didn’t break anything and that they follow our style guide. You can speed up the testing cycle by running these tests locally on your own computer by calling pytest from the top-level directory.
+We will automatically run tests to ensure that your contributions didn't break anything and that they follow our style guide. You can speed up the testing cycle by running these tests locally on your own computer by calling pytest from the top-level directory.
 Push your feature branch to origin (i.e. GitHub)
 
 ```bash
@@ -555,9 +551,9 @@ $ git push origin <new_branch>
 
 Once you have tested and finalized your changes, create a pull request (PR) targeting dev as the base branch:
 Ensure the PR description clearly describes the problem and solution.
-Include the relevant issue number if applicable. TIP: Writing e.g. “fix #613” will automatically close issue #613 when this PR is merged.
+Include the relevant issue number if applicable. TIP: Writing e.g. "fix #613" will automatically close issue #613 when this PR is merged.
 Before submitting, please ensure that the code follows the standard coding style of the respective repository.
-If you would like help with your contribution, or would like to communicate contributions that are not ready to merge, submit a PR where the title begins with “[WIP].”
+If you would like help with your contribution, or would like to communicate contributions that are not ready to merge, submit a PR where the title begins with "[WIP]."
 
 Update the CHANGELOG.md regularly to document changes to the extension.
 

docs/source/api.rst

@@ -9,39 +9,27 @@ This section provides detailed documentation for all classes and methods in the
 Device Components
 ===========
 
-Microscope
----------
-.. autoclass:: ndx_microscopy.Microscope
+MicroscopeModel
+---------------
+.. autoclass:: ndx_microscopy.MicroscopeModel
    :members:
    :undoc-members:
    :show-inheritance:
 
-Light Path Components
-===================
-
-ExcitationLightPath
-------------------
-.. autoclass:: ndx_microscopy.ExcitationLightPath
+Microscope
+---------
+.. autoclass:: ndx_microscopy.Microscope
    :members:
    :undoc-members:
    :show-inheritance:
 
-Methods
-^^^^^^^
-.. automethod:: ndx_microscopy.ExcitationLightPath.get_excitation_wavelength
-
-EmissionLightPath
-----------------
-.. autoclass:: ndx_microscopy.EmissionLightPath
+MicroscopyRig
+-------------
+.. autoclass:: ndx_microscopy.MicroscopyRig
    :members:
    :undoc-members:
    :show-inheritance:
 
-Methods
-^^^^^^^
-.. automethod:: ndx_microscopy.EmissionLightPath.get_emission_wavelength
-.. automethod:: ndx_microscopy.EmissionLightPath.get_indicator_label
-
 MicroscopyChannel
 ---------------
 .. autoclass:: ndx_microscopy.MicroscopyChannel

docs/source/description.rst

@@ -10,21 +10,16 @@ Key Features
 
 Device and Optical Components
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-- Microscope metadata
+- MicroscopeModel for defining microscope models
+- Microscope instances with technique specifications
+- MicroscopyRig for organizing optical components
 - Integration with ndx-ophys-devices for:
     - Excitation sources (continuous and pulsed)
     - Optical filters (band and edge types)
     - Dichroic mirrors
     - Photodetectors
     - Fluorescent indicators
 
-Light Path Configuration
-^^^^^^^^^^^^^^^^^^^^^
-- Excitation light path tracking
-- Emission light path tracking
-- Comprehensive optical component specifications
-- Wavelength and power specifications
-
 Illumination Pattern Support
 ^^^^^^^^^^^^^^^^^^^^^
 - Base illumination pattern class for general use cases
@@ -58,12 +53,11 @@ The extension organizes microscopy data hierarchically::
 
     nwbfile
     ├── devices
+    │   ├── microscope_model: MicroscopeModel
     │   └── microscope: Microscope
-    ├── lab_meta_data
-    │   ├── excitation_path: ExcitationLightPath
-    │   └── emission_path: EmissionLightPath
     ├── acquisition
     │   └── MicroscopySeries
+    │       └── microscopy_rig: MicroscopyRig
     └── processing
         └── ophys
             ├── MicroscopyResponseSeriesContainer