From 258cf87c52d3790d7c9f9c6cd8c87376947796f3 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Tue, 12 Aug 2025 17:30:56 -0600 Subject: [PATCH 1/5] first draft improve photon series --- core/nwb.ophys.yaml | 77 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 74 insertions(+), 3 deletions(-) diff --git a/core/nwb.ophys.yaml b/core/nwb.ophys.yaml index 65dc12c3..0fa264f5 100644 --- a/core/nwb.ophys.yaml +++ b/core/nwb.ophys.yaml @@ -29,6 +29,41 @@ groups: dtype: float32 doc: Intensity of the excitation in mW/mm^2, if known. required: false + datasets: + - name: data + dtype: numeric + dims: + - - time + - x + - y + - - time + - x + - y + - z + shape: + - - null + - null + - null + - - null + - null + - null + - null + doc: Time-series of microscopy data as multidimensional arrays indexed as data[time, x, y]. + The x dimension represents the first spatial axis and y represents the second spatial axis. + For raster-scanning systems (e.g., two-photon, confocal, or one-photon laser scanning + microscopy), the spatial dimensions have specific meanings related to the scanning pattern: + x typically corresponds to the fast scanning direction (horizontal, e.g., resonant mirror or + galvanometer X-axis within each scan line) and represents image width (number of columns), + while y corresponds to the slow scanning direction (vertical, advancing between scan + lines via galvanometer Y-axis) and represents image height (number of rows). + When a faster scanning axis is present, x usually refers to width (number of columns) + and y usually refers to height (number of rows), following standard imaging conventions. + For non-raster imaging modalities (e.g., wide-field, light-sheet, or random-access + scanning), x and y represent standard image plane coordinates without specific scanning + direction implications. Note that this indexing convention should not be confused with + mathematical matrix[row, column] notation where the first index represents rows; here, + data[time, x, y] follows image coordinate conventions where x represents the horizontal + axis (width/columns) and y represents the vertical axis (height/rows). links: - name: imaging_plane target_type: ImagingPlane @@ -49,15 +84,51 @@ groups: w/ the actual data. required: false datasets: + - name: data + dtype: numeric + dims: + - - time + - x + - y + - - time + - x + - y + - z + shape: + - - null + - null + - null + - - null + - null + - null + - null + doc: Time-series of microscopy data as multidimensional arrays indexed as data[time, x, y]. + The x dimension represents the first spatial axis and y represents the second spatial axis. + For raster-scanning systems (e.g., two-photon, confocal, or one-photon laser scanning + microscopy), the spatial dimensions have specific meanings related to the scanning pattern: + x typically corresponds to the fast scanning direction (horizontal, e.g., resonant mirror or + galvanometer X-axis within each scan line) and represents image width (number of columns), + while y corresponds to the slow scanning direction (vertical, advancing between scan + lines via galvanometer Y-axis) and represents image height (number of rows). + When a faster scanning axis is present, x usually refers to width (number of columns) + and y usually refers to height (number of rows), following standard imaging conventions. + For non-raster imaging modalities (e.g., wide-field, light-sheet, or random-access + scanning), x and y represent standard image plane coordinates without specific scanning + direction implications. Note that this indexing convention should not be confused with + mathematical matrix[row, column] notation where the first index represents rows; here, + data[time, x, y] follows image coordinate conventions where x represents the horizontal + axis (width/columns) and y represents the vertical axis (height/rows). - name: field_of_view dtype: float32 dims: - - - width|height - - - width|height|depth + - - x|y + - - x|y|z shape: - - 2 - - 3 - doc: Width, height and depth of image, or imaged area, in meters. + doc: Physical dimensions of the imaging field of view in x, y, and optionally z directions, + in meters. The x dimension corresponds to the faster scanning axis, and the y dimension + corresponds to the slower scanning axis. quantity: '?' links: - name: imaging_plane From 9bc5c2b4e1ed1396ea2eafd2b7607129d929cb8e Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Fri, 21 Nov 2025 08:54:07 -0600 Subject: [PATCH 2/5] add ascii diagram --- core/nwb.ophys.yaml | 126 ++++++++++++++++++++++++++++---------------- 1 file changed, 80 insertions(+), 46 deletions(-) diff --git a/core/nwb.ophys.yaml b/core/nwb.ophys.yaml index 0fa264f5..1d97f3ab 100644 --- a/core/nwb.ophys.yaml +++ b/core/nwb.ophys.yaml @@ -34,12 +34,12 @@ groups: dtype: numeric dims: - - time - - x - - y + - width + - height - - time - - x - - y - - z + - width + - height + - depth shape: - - null - null @@ -48,22 +48,40 @@ groups: - null - null - null - doc: Time-series of microscopy data as multidimensional arrays indexed as data[time, x, y]. - The x dimension represents the first spatial axis and y represents the second spatial axis. - For raster-scanning systems (e.g., two-photon, confocal, or one-photon laser scanning - microscopy), the spatial dimensions have specific meanings related to the scanning pattern: - x typically corresponds to the fast scanning direction (horizontal, e.g., resonant mirror or - galvanometer X-axis within each scan line) and represents image width (number of columns), - while y corresponds to the slow scanning direction (vertical, advancing between scan - lines via galvanometer Y-axis) and represents image height (number of rows). - When a faster scanning axis is present, x usually refers to width (number of columns) - and y usually refers to height (number of rows), following standard imaging conventions. - For non-raster imaging modalities (e.g., wide-field, light-sheet, or random-access - scanning), x and y represent standard image plane coordinates without specific scanning - direction implications. Note that this indexing convention should not be confused with - mathematical matrix[row, column] notation where the first index represents rows; here, - data[time, x, y] follows image coordinate conventions where x represents the horizontal - axis (width/columns) and y represents the vertical axis (height/rows). + + + doc: | + Time-series of microscopy data indexed as data[time, width, height]. + + Indexing convention: + - width: first spatial axis (horizontal direction, columns) + - height: second spatial axis (vertical direction, rows) + + For raster-scanning systems (two-photon, confocal, one-photon laser scanning): + - width: fast scan direction (horizontal) + - height: slow scan direction (vertical) + + Coordinate system diagram: + + height ^ + (slow) | + | +-----------------+ + | | | + | | Image plane | + | | | + | +-----------------+ + | + 0 ----------------------> width (fast) + + + For non-raster systems (wide-field, light-sheet, random-access), width and height + are arbitrary coordinates of the image plane. + + WARNING: This indexing convention conflicts with matrix[row, column] notation used + in common image analysis libraries (NumPy, scikit-image, OpenCV), where the first + index represents rows (vertical/height) and the second represents columns + (horizontal/width). Here, data[time, width, height] uses the first spatial index + for horizontal (width) and the second for vertical (height). links: - name: imaging_plane target_type: ImagingPlane @@ -88,12 +106,12 @@ groups: dtype: numeric dims: - - time - - x - - y + - width + - height - - time - - x - - y - - z + - width + - height + - depth shape: - - null - null @@ -102,32 +120,48 @@ groups: - null - null - null - doc: Time-series of microscopy data as multidimensional arrays indexed as data[time, x, y]. - The x dimension represents the first spatial axis and y represents the second spatial axis. - For raster-scanning systems (e.g., two-photon, confocal, or one-photon laser scanning - microscopy), the spatial dimensions have specific meanings related to the scanning pattern: - x typically corresponds to the fast scanning direction (horizontal, e.g., resonant mirror or - galvanometer X-axis within each scan line) and represents image width (number of columns), - while y corresponds to the slow scanning direction (vertical, advancing between scan - lines via galvanometer Y-axis) and represents image height (number of rows). - When a faster scanning axis is present, x usually refers to width (number of columns) - and y usually refers to height (number of rows), following standard imaging conventions. - For non-raster imaging modalities (e.g., wide-field, light-sheet, or random-access - scanning), x and y represent standard image plane coordinates without specific scanning - direction implications. Note that this indexing convention should not be confused with - mathematical matrix[row, column] notation where the first index represents rows; here, - data[time, x, y] follows image coordinate conventions where x represents the horizontal - axis (width/columns) and y represents the vertical axis (height/rows). + doc: | + Time-series of microscopy data indexed as data[time, width, height]. + + Indexing convention: + - width: first spatial axis (horizontal direction, columns) + - height: second spatial axis (vertical direction, rows) + + For raster-scanning systems (two-photon, confocal, one-photon laser scanning): + - width: fast scan direction (horizontal) + - height: slow scan direction (vertical) + + Coordinate system diagram: + + height ^ + (slow) | + | +-----------------+ + | | | + | | Image plane | + | | | + | +-----------------+ + | + 0 ----------------------> width (fast) + + + For non-raster systems (wide-field, light-sheet, random-access), width and height + are arbitrary coordinates of the image plane. + + WARNING: This indexing convention conflicts with matrix[row, column] notation used + in common image analysis libraries (NumPy, scikit-image, OpenCV), where the first + index represents rows (vertical/height) and the second represents columns + (horizontal/width). Here, data[time, width, height] uses the first spatial index + for horizontal (width) and the second for vertical (height). - name: field_of_view dtype: float32 dims: - - - x|y - - - x|y|z + - - width|height + - - width|height|depth shape: - - 2 - - 3 - doc: Physical dimensions of the imaging field of view in x, y, and optionally z directions, - in meters. The x dimension corresponds to the faster scanning axis, and the y dimension + doc: Physical dimensions of the imaging field of view in width, height, and optionally depth directions, + in meters. The width dimension corresponds to the faster scanning axis, and the height dimension corresponds to the slower scanning axis. quantity: '?' links: From f0c13b924f432839e4de41651ae1f42b2624c0cc Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Fri, 21 Nov 2025 09:28:33 -0600 Subject: [PATCH 3/5] fix notes --- core/nwb.ophys.yaml | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/core/nwb.ophys.yaml b/core/nwb.ophys.yaml index 1d97f3ab..9739c9a1 100644 --- a/core/nwb.ophys.yaml +++ b/core/nwb.ophys.yaml @@ -77,11 +77,16 @@ groups: For non-raster systems (wide-field, light-sheet, random-access), width and height are arbitrary coordinates of the image plane. - WARNING: This indexing convention conflicts with matrix[row, column] notation used - in common image analysis libraries (NumPy, scikit-image, OpenCV), where the first - index represents rows (vertical/height) and the second represents columns - (horizontal/width). Here, data[time, width, height] uses the first spatial index - for horizontal (width) and the second for vertical (height). + WARNING: This indexing convention conflicts with standard matrix[row, column] notation + where the first index moves vertically through rows and the second moves horizontally + through columns. In data[time, width, height], the first spatial index moves horizontally + (width) and the second moves vertically (height), which is transposed relative to matrix + convention. This means: + - data[t, w, h] follows image/Cartesian convention: data[time, x, y] where x is horizontal + - matrix[r, c] follows row-column convention: matrix[y, x] where row (y) is vertical + - To convert between them requires transposing the spatial dimensions + For array access, incrementing the first spatial index moves you horizontally across the + image, while in matrix notation it would move you vertically down rows. links: - name: imaging_plane target_type: ImagingPlane @@ -147,11 +152,16 @@ groups: For non-raster systems (wide-field, light-sheet, random-access), width and height are arbitrary coordinates of the image plane. - WARNING: This indexing convention conflicts with matrix[row, column] notation used - in common image analysis libraries (NumPy, scikit-image, OpenCV), where the first - index represents rows (vertical/height) and the second represents columns - (horizontal/width). Here, data[time, width, height] uses the first spatial index - for horizontal (width) and the second for vertical (height). + WARNING: This indexing convention conflicts with standard matrix[row, column] notation + where the first index moves vertically through rows and the second moves horizontally + through columns. In data[time, width, height], the first spatial index moves horizontally + (width) and the second moves vertically (height), which is transposed relative to matrix + convention. This means: + - data[t, w, h] follows image/Cartesian convention: data[time, x, y] where x is horizontal + - matrix[r, c] follows row-column convention: matrix[y, x] where row (y) is vertical + - To convert between them requires transposing the spatial dimensions + For array access, incrementing the first spatial index moves you horizontally across the + image, while in matrix notation it would move you vertically down rows. - name: field_of_view dtype: float32 dims: From 1673290ab41e544a5d67b10fcf5d39e2fb9cd300 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Fri, 21 Nov 2025 09:40:41 -0600 Subject: [PATCH 4/5] ophys --- core/nwb.ophys.yaml | 33 +++++++++++++-------------------- 1 file changed, 13 insertions(+), 20 deletions(-) diff --git a/core/nwb.ophys.yaml b/core/nwb.ophys.yaml index 9739c9a1..328fcd06 100644 --- a/core/nwb.ophys.yaml +++ b/core/nwb.ophys.yaml @@ -77,16 +77,14 @@ groups: For non-raster systems (wide-field, light-sheet, random-access), width and height are arbitrary coordinates of the image plane. - WARNING: This indexing convention conflicts with standard matrix[row, column] notation - where the first index moves vertically through rows and the second moves horizontally - through columns. In data[time, width, height], the first spatial index moves horizontally - (width) and the second moves vertically (height), which is transposed relative to matrix - convention. This means: - - data[t, w, h] follows image/Cartesian convention: data[time, x, y] where x is horizontal - - matrix[r, c] follows row-column convention: matrix[y, x] where row (y) is vertical - - To convert between them requires transposing the spatial dimensions - For array access, incrementing the first spatial index moves you horizontally across the - image, while in matrix notation it would move you vertically down rows. + Note: This indexing convention conflicts with standard matrix[row, column] notation + for array access where the first index moves vertically through rows and the second moves horizontally + through columns. In the schema, data[time, width, height] means that the first spatial + index moves horizontally (width) through columns and the second spatial index moves + vertically (height) through rows. In summary, incrementing the first spatial index + moves you horizontally across the image, while in matrix notation it would move you + vertically across the rows of the image. + links: - name: imaging_plane target_type: ImagingPlane @@ -152,16 +150,11 @@ groups: For non-raster systems (wide-field, light-sheet, random-access), width and height are arbitrary coordinates of the image plane. - WARNING: This indexing convention conflicts with standard matrix[row, column] notation - where the first index moves vertically through rows and the second moves horizontally - through columns. In data[time, width, height], the first spatial index moves horizontally - (width) and the second moves vertically (height), which is transposed relative to matrix - convention. This means: - - data[t, w, h] follows image/Cartesian convention: data[time, x, y] where x is horizontal - - matrix[r, c] follows row-column convention: matrix[y, x] where row (y) is vertical - - To convert between them requires transposing the spatial dimensions - For array access, incrementing the first spatial index moves you horizontally across the - image, while in matrix notation it would move you vertically down rows. + Note: This indexing convention conflicts with standard matrix[row, column] notation + for array access where the first index moves vertically through rows and the second moves horizontally + through columns. In the schema, data[time, width, height] means that the first spatial + index moves horizontally (width) through columns and the second spatial index moves + vertically (height) through rows. - name: field_of_view dtype: float32 dims: From 73e5792ed4d46caec88c125239e538750d33b954 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Fri, 21 Nov 2025 09:53:18 -0600 Subject: [PATCH 5/5] release notes --- docs/format/source/format_release_notes.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst index 237afe2c..23e52bf2 100644 --- a/docs/format/source/format_release_notes.rst +++ b/docs/format/source/format_release_notes.rst @@ -32,6 +32,10 @@ Minor changes - Made ``EventDetection.times`` optional and deprecated. Use `source_idx` instead. (#620) - Clarified documentation of ``PlaneSegmentation`` that at least one of ``image_mask``, ``pixel_mask``, and ``voxel_mask`` is required. (#636) +- Improved documentation for ``OnePhotonSeries`` and ``TwoPhotonSeries``: added ``data`` dataset specification + with an ASCII diagram clarifying the meaning of the ``height`` and ``width`` dimensions; clarified that for + raster-based microscopy, width (columns) is the fast scan direction; contrasted this convention with standard + matrix notation where the first array dimension slices through rows. (#649) 2.8.0 (November 24, 2024) -------------------------