Rename grid_spacing_in_um to pixel_size_in_um and voxel_size_in_um for clarity in imaging space definitions

alessandratrapani · alessandratrapani · commit bbb457d089bc · 2025-03-19T10:19:48.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,7 @@
 - Modified the YAML specification to include new neurodata type definitions and relationships
 - Updated Python implementation files to expose the new classes in the API
 - Enhanced test files to verify the new classes work correctly
+- Change `grid_spacing_in_um` in `pixel_size_in_um` and `voxel_size_in_um` (and relative doc string) to better represent the physical dimension of the fundamental unit of the image (pixel or voxel).
 
 ### Notes
 
diff --git a/README.md b/README.md
@@ -344,15 +344,15 @@ classDiagram
         --------------------------------------
         datasets
         --------------------------------------
-        grid_spacing_in_um : float64[2], optional
+        pixel_size_in_um : float64[2], optional
     }
 
     class VolumetricImagingSpace {
         <<ImagingSpace>>
         --------------------------------------
         datasets
         --------------------------------------
-        grid_spacing_in_um : float64[3], optional
+        voxel_size_in_um : float64[3], optional
     }
 
     class Microscope {
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -160,7 +160,7 @@ Complete example of two-photon calcium imaging with full optical path configurat
     imaging_space = PlanarImagingSpace(
         name='cortex_plane1',
         description='Layer 2/3 of visual cortex',
-        grid_spacing_in_um=[1.0, 1.0],
+        pixel_size_in_um=[1.0, 1.0],
         origin_coordinates=[-1.2, -0.6, -2.0],
         location='Visual cortex, layer 2/3',
         reference_frame='bregma',
@@ -432,7 +432,7 @@ Example of volumetric imaging with 3D ROI segmentation:
     volume_space = VolumetricImagingSpace(
         name='cortex_volume',
         description='Visual cortex volume',
-        grid_spacing_in_um=[1.0, 1.0, 2.0],  # Higher spacing in z
+        voxel_size_in_um=[1.0, 1.0, 2.0],  # Higher spacing in z
         origin_coordinates=[-1.2, -0.6, -2.0],
         location='Visual cortex',
         reference_frame='bregma',
@@ -717,7 +717,7 @@ Example of multi-plane imaging with an electrically tunable lens:
         plane_space = PlanarImagingSpace(
             name=f'plane_depth_{depth}',
             description=f'Imaging plane at {depth} µm depth',
-            grid_spacing_in_um=[1.0, 1.0],
+            pixel_size_in_um=[1.0, 1.0],
             origin_coordinates=[-1.2, -0.6, depth/1000],  # Convert to mm
             location='Visual cortex',
             reference_frame='bregma',
diff --git a/docs/source/format.rst b/docs/source/format.rst
@@ -356,13 +356,13 @@ For 2D imaging planes.
         neurodata_type_inc: ImagingSpace
         doc: Metadata about the 2-dimensional slice of physical space that imaging data was recorded from.
         datasets:
-          - name: grid_spacing_in_um
+          - name: pixel_size_in_um
             dtype: float64
             dims:
               - - x, y
             shape:
               - - 2
-            doc: Amount of space between pixels in micrometers.
+            doc: The physical dimensions of the pixel in micrometers.
             quantity: "?"
 
 VolumetricImagingSpace
@@ -376,13 +376,13 @@ For 3D imaging volumes.
         neurodata_type_inc: ImagingSpace
         doc: Metadata about the 3-dimensional region of physical space that imaging data was recorded from.
         datasets:
-          - name: grid_spacing_in_um
+          - name: voxel_size_in_um
             dtype: float64
             dims:
               - - x, y, z
             shape:
               - - 3
-            doc: Amount of space between voxels in micrometers.
+            doc: The physical dimensions of the voxel in micrometers.
             quantity: "?"
 
 Segmentation Components
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -173,7 +173,7 @@ Here's a minimal example showing how to create a basic microscopy dataset:
     planar_imaging_space = PlanarImagingSpace(
         name='cortex_plane',
         description='Layer 2/3 of visual cortex',
-        grid_spacing_in_um=[1.0, 1.0],
+        pixel_size_in_um=[1.0, 1.0],
         origin_coordinates=[-1.2, -0.6, -2.0],
         illumination_pattern=line_scan  # Include the illumination pattern
     )
diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst
@@ -128,7 +128,7 @@ Imaging spaces define the physical region being imaged:
        space_2d = PlanarImagingSpace(
            name='cortex_plane',
            description='Layer 2/3 of visual cortex',
-           grid_spacing_in_um=[1.0, 1.0],        # x, y spacing
+           pixel_size_in_um=[1.0, 1.0],        # x, y spacing
            origin_coordinates=[-1.2, -0.6, -2.0], # relative to bregma
            location='Visual cortex',
            reference_frame='bregma',
@@ -153,7 +153,7 @@ Imaging spaces define the physical region being imaged:
        space_3d = VolumetricImagingSpace(
            name='cortex_volume',
            description='Visual cortex volume',
-           grid_spacing_in_um=[1.0, 1.0, 2.0],   # x, y, z spacing
+           voxel_size_in_um=[1.0, 1.0, 2.0],   # x, y, z spacing
            origin_coordinates=[-1.2, -0.6, -2.0],
            location='Visual cortex',
            reference_frame='bregma',
@@ -194,7 +194,7 @@ Basic workflow for 2D imaging:
     planar_imaging_space = PlanarImagingSpace(
         name='cortex_plane',
         description='Layer 2/3 of visual cortex',
-        grid_spacing_in_um=[1.0, 1.0],        # x, y spacing
+        pixel_size_in_um=[1.0, 1.0],        # x, y spacing
         origin_coordinates=[-1.2, -0.6, -2.0], # relative to bregma
         location='Visual cortex',
         reference_frame='bregma',
@@ -246,7 +246,7 @@ Workflow for one-photon widefield imaging:
     planar_imaging_space = PlanarImagingSpace(
         name='hippo_plane',
         description='CA1 region of hippocampus',
-        grid_spacing_in_um=[1.0, 1.0],
+        pixel_size_in_um=[1.0, 1.0],
         origin_coordinates=[-1.8, 2.0, 1.2],
         location='Hippocampus, CA1 region',
         reference_frame='bregma',
@@ -299,7 +299,7 @@ Workflow for volumetric imaging with targeted scanning:
     volumetric_imaging_space = VolumetricImagingSpace(
         name='cortex_volume',
         description='Visual cortex volume',
-        grid_spacing_in_um=[1.0, 1.0, 2.0],   # x, y, z spacing
+        voxel_size_in_um=[1.0, 1.0, 2.0],   # x, y, z spacing
         origin_coordinates=[-1.2, -0.6, -2.0],
         location='Visual cortex',
         reference_frame='bregma',
diff --git a/examples/multi_plane_imaging_example.ipynb b/examples/multi_plane_imaging_example.ipynb
@@ -276,7 +276,7 @@
     "    plane_space = PlanarImagingSpace(\n",
     "        name=f'plane_depth_{depth}',\n",
     "        description=f'Imaging plane at {depth} µm depth',\n",
-    "        grid_spacing_in_um=[1.0, 1.0],\n",
+    "        pixel_size_in_um=[1.0, 1.0],\n",
     "        origin_coordinates=[-1.2, -0.6, depth/1000],  # Convert to mm\n",
     "        location='Visual cortex',\n",
     "        reference_frame='bregma',\n",
diff --git a/examples/one-photon_calcium_imaging_example.ipynb b/examples/one-photon_calcium_imaging_example.ipynb
@@ -245,7 +245,7 @@
     "imaging_space = PlanarImagingSpace(\n",
     "    name=\"hippo_plane1\",\n",
     "    description=\"CA1 region of hippocampus\",\n",
-    "    grid_spacing_in_um=[1.0, 1.0],\n",
+    "    pixel_size_in_um=[1.0, 1.0],\n",
     "    origin_coordinates=[-1.8, 2.0, 1.2],  # Matches the indicator injection coordinates\n",
     "    location=\"Hippocampus, CA1 region\",\n",
     "    reference_frame=\"bregma\",\n",
diff --git a/examples/two-photon_calcium_imaging_example.ipynb b/examples/two-photon_calcium_imaging_example.ipynb
@@ -256,7 +256,7 @@
     "imaging_space = PlanarImagingSpace(\n",
     "    name=\"cortex_plane1\",\n",
     "    description=\"Layer 2/3 of visual cortex\",\n",
-    "    grid_spacing_in_um=[1.0, 1.0],\n",
+    "    pixel_size_in_um=[1.0, 1.0],\n",
     "    origin_coordinates=[-1.2, -0.6, -2.0],\n",
     "    location=\"Visual cortex, layer 2/3\",\n",
     "    reference_frame=\"bregma\",\n",
diff --git a/examples/volumetric_imaging_example.ipynb b/examples/volumetric_imaging_example.ipynb
@@ -258,7 +258,7 @@
     "volume_space = VolumetricImagingSpace(\n",
     "    name='cortex_volume',\n",
     "    description='Visual cortex volume',\n",
-    "    grid_spacing_in_um=[1.0, 1.0, 2.0],  # Higher spacing in z\n",
+    "    voxel_size_in_um=[1.0, 1.0, 2.0],  # Higher spacing in z\n",
     "    origin_coordinates=[-1.2, -0.6, -2.0],\n",
     "    location='Visual cortex',\n",
     "    reference_frame='bregma',\n",
diff --git a/spec/ndx-microscopy.extensions.yaml b/spec/ndx-microscopy.extensions.yaml
@@ -172,21 +172,21 @@ groups:
     neurodata_type_inc: ImagingSpace
     doc: Metadata about the 2-dimensional slice of physical space that imaging data was recorded from.
     datasets:
-      - name: grid_spacing_in_um
+      - name: pixel_size_in_um
+        doc: The physical dimensions of the pixel in micrometers.
         dtype: float64
         dims:
           - - x, y
         shape:
           - - 2
-        doc: Amount of space between pixels in micrometers.
         quantity: "?"
 
   - neurodata_type_def: VolumetricImagingSpace
     neurodata_type_inc: ImagingSpace
     doc: Metadata about the 3-dimensional region of physical space that imaging data was recorded from.
     datasets:
-      - name: grid_spacing_in_um
-        doc: Amount of space between voxels in micrometers.
+      - name: voxel_size_in_um
+        doc: The physical dimensions of the voxel in micrometers.
         dtype: float64
         dims:
           - - x, y, z
diff --git a/src/pynwb/ndx_microscopy/testing/_mock.py b/src/pynwb/ndx_microscopy/testing/_mock.py
@@ -147,7 +147,7 @@ def mock_PlanarImagingSpace(
     name: Optional[str] = None,
     description: str = "A mock instance of a PlanarImagingSpace type to be used for rapid testing.",
     origin_coordinates: Tuple[float, float, float] = (-1.2, -0.6, -2),
-    grid_spacing_in_um: Tuple[float, float, float] = (20, 20),
+    pixel_size_in_um: Tuple[float, float, float] = (20, 20),
     location: str = "The location targeted by the mock imaging space.",
     reference_frame: str = "The reference frame of the mock planar imaging space.",
     orientation: str = "The orientation of the mock planar imaging space.",
@@ -157,7 +157,7 @@ def mock_PlanarImagingSpace(
         name=name or name_generator("PlanarImagingSpace"),
         description=description,
         origin_coordinates=origin_coordinates,
-        grid_spacing_in_um=grid_spacing_in_um,
+        pixel_size_in_um=pixel_size_in_um,
         location=location,
         reference_frame=reference_frame,
         orientation=orientation,
@@ -171,7 +171,7 @@ def mock_VolumetricImagingSpace(
     name: Optional[str] = None,
     description: str = "A mock instance of a VolumetricImagingSpace type to be used for rapid testing.",
     origin_coordinates: Tuple[float, float, float] = (-1.2, -0.6, -2),
-    grid_spacing_in_um: Tuple[float, float, float] = (20, 20, 50),
+    voxel_size_in_um: Tuple[float, float, float] = (20, 20, 50),
     location: str = "The location targeted by the mock imaging space.",
     reference_frame: str = "The reference frame of the mock volumetric imaging space.",
     orientation: str = "The orientation of the mock planar imaging space.",
@@ -181,7 +181,7 @@ def mock_VolumetricImagingSpace(
         name=name or name_generator("VolumetricImagingSpace"),
         description=description,
         origin_coordinates=origin_coordinates,
-        grid_spacing_in_um=grid_spacing_in_um,
+        voxel_size_in_um=voxel_size_in_um,
         location=location,
         reference_frame=reference_frame,
         orientation=orientation,

Original file line number	Diff line number	Diff line change
`@@ -173,7 +173,7 @@ Here's a minimal example showing how to create a basic microscopy dataset:`
`173`	`173`	`planar_imaging_space = PlanarImagingSpace(`
`174`	`174`	`name='cortex_plane',`
`175`	`175`	`description='Layer 2/3 of visual cortex',`
`176`		`- grid_spacing_in_um=[1.0, 1.0],`
	`176`	`+ pixel_size_in_um=[1.0, 1.0],`
`177`	`177`	`origin_coordinates=[-1.2, -0.6, -2.0],`
`178`	`178`	`illumination_pattern=line_scan # Include the illumination pattern`
`179`	`179`	`)`