Merge branch 'v0.3.x' into add-multichannelcontainer

Author: alessandratrapani

CHANGELOG.md

@@ -1,10 +1,17 @@
-# v0.3.0 (upcoming)
+# v0.3.0 (Jun 3, 2025)
 ## 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)
+- Added `dimensions_in_pixels` to `PlanarImagingSpace` and `dimensions_in_voxels` to `VolumetricImagingSpace` object Sub-Issue[#52](https://github.com/catalystneuro/ndx-microscopy/issues/52)
 - Added `MultiChannelMicroscopyContainer` object Sub-Issue[#53](https://github.com/catalystneuro/ndx-microscopy/issues/53)
 
 # v0.2.1 (March 28, 2025)

README.md

@@ -6,15 +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`
-- Advanced light path configurations: 
-    - `ExcitationLightPath`
-    - `EmissionLightPath` 
+- Microscopy channel configurations: 
+    - `MicroscopyChannel`
 - Imaging space definitions: 
     - `PlanarImagingSpace`
     - `VolumetricImagingSpace`
@@ -38,65 +39,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
+        manufacturer : text
+        model_number : text, optional
     }
-
-    class ExcitationLightPath {
-        <<LabMetaData>>
+    
+    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 +121,7 @@ classDiagram
     }
 
     class OpticalFilter {
-        <<DeviceModel>>
+        <<DeviceInstance>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -147,7 +149,7 @@ classDiagram
     }
 
     class DichroicMirror {
-        <<DeviceModel>>
+        <<DeviceInstance>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -159,7 +161,7 @@ classDiagram
     }
     
     class Photodetector {
-        <<DeviceModel>>
+        <<DeviceInstance>>
         --------------------------------------
         attributes
         --------------------------------------
@@ -181,21 +183,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
@@ -229,7 +225,7 @@ classDiagram
         --------------------------------------
         attributes
         --------------------------------------
-        plane_thickness_in_um : float64, optional
+        point_spread_function_in_um : text, optional
         illumination_angle_in_degrees : float64, optional
         plane_rate_in_Hz : float64, optional
     }
@@ -278,14 +274,29 @@ classDiagram
 classDiagram
     direction TB
 
+    class MicroscopyChannel {
+        <<NWBContainer>>
+        --------------------------------------
+        attributes
+        --------------------------------------
+        **name** : text
+        description : text, optional
+        **excitation_wavelength_in_nm** : float
+        **emission_wavelength_in_nm** : float
+        --------------------------------------
+        groups
+        --------------------------------------
+        indicator
+    }
+
     class MicroscopySeries {
         <<TimeSeries>>
         --------------------------------------
-        links
+        groups
         --------------------------------------
-        **microscope** : Microscope
-        **excitation_light_path** : ExcitationLightPath
-        **emission_light_path** : EmissionLightPath
+        **microscopy_rig** : MicroscopyRig
+        **microscopy_channel** : MicroscopyChannel
+
     }
 
     class PlanarMicroscopySeries {
@@ -355,6 +366,7 @@ classDiagram
         datasets
         --------------------------------------
         pixel_size_in_um : float64[2], optional
+        dimensions_in_pixels : float64[2], optional 
     }
 
     class VolumetricImagingSpace {
@@ -363,15 +375,24 @@ classDiagram
         datasets
         --------------------------------------
         voxel_size_in_um : float64[3], optional
+        dimensions_in_voxels : 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
@@ -383,9 +404,9 @@ classDiagram
     VolumetricMicroscopySeries *-- VolumetricImagingSpace : contains
     MultiPlaneMicroscopyContainer *-- PlanarMicroscopySeries : contains
     MultiChannelMicroscopyContainer *-- MicroscopySeries : contains
-    MicroscopySeries o--> Microscope : links
-    MicroscopySeries o--> ExcitationLightPath : links
-    MicroscopySeries o--> EmissionLightPath : links
+    MicroscopySeries *-- MicroscopyRig : contains
+    MicroscopyChannel *-- MicroscopySeries : contains    
+    MicroscopyChannel --* Indicator : contains
 ```
 
 #### Segmentation Components
@@ -518,7 +539,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.
 
@@ -534,7 +555,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
@@ -543,9 +564,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,38 +9,64 @@ This section provides detailed documentation for all classes and methods in the
 Device Components
 ===========
 
+MicroscopeModel
+---------------
+.. autoclass:: ndx_microscopy.MicroscopeModel
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Microscope
 ---------
 .. autoclass:: ndx_microscopy.Microscope
    :members:
    :undoc-members:
    :show-inheritance:
 
-Light Path Components
-===================
+MicroscopyRig
+-------------
+.. autoclass:: ndx_microscopy.MicroscopyRig
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
-ExcitationLightPath
-------------------
-.. autoclass:: ndx_microscopy.ExcitationLightPath
+MicroscopyChannel
+---------------
+.. autoclass:: ndx_microscopy.MicroscopyChannel
    :members:
    :undoc-members:
    :show-inheritance:
 
-Methods
-^^^^^^^
-.. automethod:: ndx_microscopy.ExcitationLightPath.get_excitation_wavelength
+Illumination Pattern Components
+==========================
 
-EmissionLightPath
+IlluminationPattern
 ----------------
-.. autoclass:: ndx_microscopy.EmissionLightPath
+.. autoclass:: ndx_microscopy.IlluminationPattern
    :members:
    :undoc-members:
    :show-inheritance:
 
-Methods
-^^^^^^^
-.. automethod:: ndx_microscopy.EmissionLightPath.get_emission_wavelength
-.. automethod:: ndx_microscopy.EmissionLightPath.get_indicator_label
+LineScan
+-------
+.. autoclass:: ndx_microscopy.LineScan
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PlaneAcquisition
+--------------
+.. autoclass:: ndx_microscopy.PlaneAcquisition
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+RandomAccessScan
+--------------
+.. autoclass:: ndx_microscopy.RandomAccessScan
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Imaging Space Components
 =====================