Refactor ImagingSpace: Remove coordinate system metadata and update attributes

Author: alessandratrapani

CHANGELOG.md

@@ -4,6 +4,11 @@
 - **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
+- **Breaking Change**: Simplified `ImagingSpace` class by removing coordinate system metadata:
+  - Removed `origin_coordinates` dataset and its `unit` attribute
+  - Renamed `location` attribute to `anatomical_target` for clearer semantics
+  - Removed `reference_frame` attribute
+  - Removed `orientation` attribute
 - Updated `ndx-ophys-devices` dependency from v0.2.0 to v0.4.0
 
 ## Features

README.md

@@ -247,17 +247,10 @@ classDiagram
     class ImagingSpace {
         <<NWBContainer>>
         --------------------------------------
-        datasets
-        --------------------------------------
-        **description** : text
-        origin_coordinates : float64[3], optional
-        unit : text = "micrometers"
-        --------------------------------------
         attributes
         --------------------------------------
-        location : text, optional
-        reference_frame : text, optional
-        orientation : text, optional
+        **description** : text
+        **anatomical_target** : text
         --------------------------------------
         groups
         --------------------------------------
@@ -434,17 +427,10 @@ classDiagram
     class ImagingSpace {
         <<NWBContainer>>
         --------------------------------------
-        datasets
-        --------------------------------------
-        **description** : text
-        origin_coordinates : float64[3], optional
-        unit : text = "micrometers"
-        --------------------------------------
         attributes
         --------------------------------------
-        location : text, optional
-        reference_frame : text, optional
-        orientation : text, optional
+        **description** : text
+        **anatomical_target** : text
         --------------------------------------
         groups
         --------------------------------------

docs/source/examples.rst

@@ -214,10 +214,7 @@ Complete example of two-photon calcium imaging with full optical path configurat
         description='Layer 2/3 of visual cortex',
         pixel_size_in_um=[1.0, 1.0],
         dimensions_in_pixels=[height, width],
-        origin_coordinates=[-1.2, -0.6, -2.0],
-        location='Visual cortex, layer 2/3',
-        reference_frame='bregma',
-        orientation='RAS',  # Right-Anterior-Superior
+        anatomical_target='Visual cortex, layer 2/3',
         illumination_pattern=line_scan  # Include the illumination pattern
     )
 
@@ -541,10 +538,7 @@ Example of volumetric imaging with 3D ROI segmentation:
         description='Visual cortex volume',
         voxel_size_in_um=[1.0, 1.0, 2.0],  # Higher spacing in z
         dimensions_in_voxels=[height, width, depths],
-        origin_coordinates=[-1.2, -0.6, -2.0],
-        location='Visual cortex',
-        reference_frame='bregma',
-        orientation='RAS',  # Right-Anterior-Superior
+        anatomical_target='Visual cortex, layer 2/3',
         illumination_pattern=random_access_scan  # Include the illumination pattern
     )
 
@@ -882,10 +876,7 @@ Example of multi-plane imaging with an electrically tunable lens:
             description=f'Imaging plane at {depth} µm depth',
             pixel_size_in_um=[1.0, 1.0],
             dimensions_in_pixels=[height, width],
-            origin_coordinates=[-1.2, -0.6, depth/1000],  # Convert to mm
-            location='Visual cortex',
-            reference_frame='bregma',
-            orientation='RAS',
+            anatomical_target='Visual cortex',
             illumination_pattern=plane_acquisition  # Include the illumination pattern
         )
 

docs/source/format.rst

@@ -360,52 +360,22 @@ Base type for metadata about the region being imaged.
       - neurodata_type_def: ImagingSpace
         neurodata_type_inc: NWBContainer
         doc: Abstract class to contain metadata about the region of physical space that imaging data was recorded from. Extended by PlanarImagingSpace and VolumetricImagingSpace.
-        datasets:
-          - name: origin_coordinates
-            dtype: float64
-            dims:
-              - - x, y, z
-            shape:
-              - - 3
-            doc:
-              Physical location in stereotactic coordinates for the first element of the grid.
-              See reference_frame to determine what the coordinates are relative to (e.g., bregma).
-            quantity: "?"
-            attributes:
-              - name: unit
-                dtype: text
-                default_value: micrometers
-                doc: Measurement units for origin coordinates. The default value is 'micrometers'.
         attributes:
-          - name: description
-            dtype: text
-            doc: Description of the imaging space.
-          - name: location
-            dtype: text
-            doc:
-              General estimate of location in the brain being subset by this space.
-              Specify the area, layer, etc.
-              Use standard atlas names for anatomical regions when possible.
-              Specify 'whole brain' if the entire brain is strictly contained within the space.
-            required: false
-          - name: reference_frame
-            dtype: text
-            doc:
-              The reference frame for the origin coordinates. For example, 'bregma' or 'lambda' for rodent brains.
-              If the origin coordinates are relative to a specific anatomical landmark, specify that here.
-            required: false
-          - name: orientation
-            doc:
-              "A 3-letter string. One of A,P,L,R,S,I for each of x, y, and z. For example, the most common
-              orientation is 'RAS', which means x is right, y is anterior, and z is superior (a.k.a. dorsal).
-              For dorsal/ventral use 'S/I' (superior/inferior). In the AnatomicalCoordinatesTable, an orientation of
-              'RAS' corresponds to coordinates in the order of (ML (x), AP (y), DV (z))."
-            dtype: text
-            required: false
-        groups:
-          - neurodata_type_inc: IlluminationPattern
-            doc: IlluminationPattern object containing metadata about the method used to acquire this imaging data.
-            quantity: 1
+      - name: description
+        dtype: text
+        doc: Description of the imaging space.
+        required: false
+      - name: anatomical_target
+        dtype: text
+        doc:
+          Name of the targeted anatomical location being subset by this space.
+          Specify the area, layer, etc. Use standard atlas names for anatomical regions when possible.
+          Specify 'whole brain' if the entire brain is strictly contained within the space.
+        required: true
+    groups:
+      - neurodata_type_inc: IlluminationPattern
+        doc: IlluminationPattern object containing metadata about the method used to acquire this imaging data.
+        quantity: 1
 
 PlanarImagingSpace
 ^^^^^^^^^^^^^^^

docs/source/getting_started.rst

@@ -246,11 +246,11 @@ Here's a minimal example showing how to create a basic microscopy dataset:
 
     # Define imaging space with illumination pattern
     planar_imaging_space = PlanarImagingSpace(
-        name='cortex_plane',
-        description='Layer 2/3 of visual cortex',
+        name='PlanarImagingSpace',
+        description='Imaging plane of layer 2/3 of visual cortex',
         pixel_size_in_um=[1.0, 1.0],
         dimensions_in_pixels=[512, 512],
-        origin_coordinates=[-1.2, -0.6, -2.0],
+        anatomical_target='Visual cortex, layer 2/3',
         illumination_pattern=line_scan  # Include the illumination pattern
     )
 

docs/source/user_guide.rst

@@ -283,17 +283,14 @@ Imaging spaces define the physical region being imaged:
        )
        
        # Then create the imaging space with the illumination pattern
-       space_2d = PlanarImagingSpace(
-           name='cortex_plane',
-           description='Layer 2/3 of visual cortex',
-           pixel_size_in_um=[1.0, 1.0],        # x, y spacing
-           dimensions_in_pixels=[512, 512],    # width, height in pixels
-           origin_coordinates=[-1.2, -0.6, -2.0], # relative to bregma
-           location='Visual cortex',
-           reference_frame='bregma',
-           orientation='RAS',                    # Right-Anterior-Superior
-           illumination_pattern=line_scan        # Include the illumination pattern
-       )
+        planar_imaging_space = PlanarImagingSpace(
+            name='PlanarImagingSpace',
+            description='Imaging plane of layer 2/3 of visual cortex',
+            pixel_size_in_um=[1.0, 1.0],
+            dimensions_in_pixels=[512, 512],
+            anatomical_target='Visual cortex, layer 2/3',
+            illumination_pattern=line_scan  # Include the illumination pattern
+        )
 
 2. **VolumetricImagingSpace**: For 3D imaging
 
@@ -314,10 +311,7 @@ Imaging spaces define the physical region being imaged:
            description='Visual cortex volume',
            voxel_size_in_um=[1.0, 1.0, 2.0],   # x, y, z spacing
            dimensions_in_voxels=[512, 512, 100], # width, height, depth in voxels
-           origin_coordinates=[-1.2, -0.6, -2.0],
-           location='Visual cortex',
-           reference_frame='bregma',
-           orientation='RAS',
+           anatomical_target='Visual cortex',
            illumination_pattern=plane_acquisition
        )
 
@@ -440,15 +434,12 @@ Basic workflow for 2D imaging:
 
     # 6. Set up imaging space with illumination pattern
     planar_imaging_space = PlanarImagingSpace(
-        name='cortex_plane',
-        description='Layer 2/3 of visual cortex',
-        pixel_size_in_um=[1.0, 1.0],        # x, y spacing
-        dimensions_in_pixels=[512, 512],    # width, height in pixels
-        origin_coordinates=[-1.2, -0.6, -2.0], # relative to bregma
-        location='Visual cortex',
-        reference_frame='bregma',
-        orientation='RAS',                    # Right-Anterior-Superior
-        illumination_pattern=line_scan        # Include the illumination pattern
+        name='PlanarImagingSpace',
+        description='Imaging plane of layer 2/3 of visual cortex',
+        pixel_size_in_um=[1.0, 1.0],
+        dimensions_in_pixels=[512, 512],
+        anatomical_target='Visual cortex, layer 2/3',
+        illumination_pattern=line_scan  # Include the illumination pattern
     )
 
     # 7. Create microscopy channel
@@ -566,15 +557,12 @@ Workflow for one-photon widefield imaging:
 
     # 6. Set up imaging space with illumination pattern
     planar_imaging_space = PlanarImagingSpace(
-        name='hippo_plane',
-        description='CA1 region of hippocampus',
+        name='PlanarImagingSpace',
+        description='Imaging plane of layer 2/3 of visual cortex',
         pixel_size_in_um=[1.0, 1.0],
-        dimensions_in_pixels=[512, 512],  # width, height in pixels
-        origin_coordinates=[-1.8, 2.0, 1.2],
-        location='Hippocampus, CA1 region',
-        reference_frame='bregma',
-        orientation='RAS',
-        illumination_pattern=plane_acquisition
+        dimensions_in_pixels=[512, 512],
+        anatomical_target='Visual cortex, layer 2/3',
+        illumination_pattern=plane_acquisition  # Include the illumination pattern
     )
 
     # 7. Create microscopy channel
@@ -697,10 +685,7 @@ Workflow for volumetric imaging with targeted scanning:
         description='Visual cortex volume',
         voxel_size_in_um=[1.0, 1.0, 2.0],   # x, y, z spacing
         dimensions_in_voxels=[512, 512, 100], # width, height, depth in voxels
-        origin_coordinates=[-1.2, -0.6, -2.0],
-        location='Visual cortex',
-        reference_frame='bregma',
-        orientation='RAS',
+        anatomical_target='Visual cortex',
         illumination_pattern=random_access_scan
     )
 

examples/multi_plane_imaging_example.ipynb

@@ -348,10 +348,7 @@
     "        description=f\"Imaging plane at {depth} µm depth\",\n",
     "        pixel_size_in_um=[1.0, 1.0],\n",
     "        dimensions_in_pixels=[height, width],\n",
-    "        origin_coordinates=[-1.2, -0.6, depth / 1000],  # Convert to mm\n",
-    "        location=\"Visual cortex\",\n",
-    "        reference_frame=\"bregma\",\n",
-    "        orientation=\"RAS\",\n",
+    "        anatomical_target=\"Visual cortex\",\n",
     "        illumination_pattern=illumination_pattern,\n",
     "    )\n",
     "\n",

examples/one-photon_calcium_imaging_example.ipynb

@@ -323,10 +323,7 @@
     "    description=\"CA1 region of hippocampus\",\n",
     "    pixel_size_in_um=[1.0, 1.0],\n",
     "    dimensions_in_pixels=[width, height],\n",
-    "    origin_coordinates=[-1.8, 2.0, 1.2],  # Matches the indicator injection coordinates\n",
-    "    location=\"Hippocampus, CA1 region\",\n",
-    "    reference_frame=\"bregma\",\n",
-    "    orientation=\"RAS\",  # Right-Anterior-Superior\n",
+    "    anatomical_target=\"Hippocampus, CA1 region\",\n",
     "    illumination_pattern=illumination_pattern,\n",
     ")\n",
     "\n",

examples/two-photon_calcium_imaging_example.ipynb

@@ -326,10 +326,7 @@
     "    description=\"Layer 2/3 of visual cortex\",\n",
     "    pixel_size_in_um=[1.0, 1.0],\n",
     "    dimensions_in_pixels=[height, width],\n",
-    "    origin_coordinates=[-1.2, -0.6, -2.0],\n",
-    "    location=\"Visual cortex, layer 2/3\",\n",
-    "    reference_frame=\"bregma\",\n",
-    "    orientation=\"RAS\",  # Right-Anterior-Superior\n",
+    "    anatomical_target=\"Visual cortex, layer 2/3\",\n",
     "    illumination_pattern=illumination_pattern,\n",
     ")\n",
     "\n",

examples/volumetric_imaging_example.ipynb

@@ -332,10 +332,7 @@
     "    description=\"Visual cortex volume\",\n",
     "    voxel_size_in_um=[1.0, 1.0, 2.0],  # Higher spacing in z\n",
     "    dimensions_in_voxels=[height, width, depths],\n",
-    "    origin_coordinates=[-1.2, -0.6, -2.0],\n",
-    "    location=\"Visual cortex\",\n",
-    "    reference_frame=\"bregma\",\n",
-    "    orientation=\"RAS\",  # Right-Anterior-Superior\n",
+    "    anatomical_target=\"Visual cortex\",\n",
     "    illumination_pattern=illumination_pattern,\n",
     ")\n",
     "\n",