From fe3bd74d3eea79e35de22642c20974a92123fa48 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Thu, 6 Nov 2025 13:53:36 -0600 Subject: [PATCH 1/8] improve behavior types --- core/nwb.behavior.yaml | 130 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index 5e4e2bad..c97993b7 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -43,6 +43,111 @@ groups: doc: Description defining what exactly 'straight-ahead' means. quantity: '?' +- neurodata_type_def: PositionSeries + neurodata_type_inc: SpatialSeries + doc: Specialized SpatialSeries for tracking spatial position of a subject or object. + Stores coordinates in 1D, 2D, or 3D space (x, x/y, or x/y/z). The reference_frame + field should indicate the zero-position (e.g., 'top-left corner of enclosure'). + Units should be in spatial measurements (e.g., meters, centimeters, pixels). + datasets: + - name: data + dtype: numeric + dims: + - - num_times + - - num_times + - x + - - num_times + - x,y + - - num_times + - x,y,z + shape: + - - null + - - null + - 1 + - - null + - 2 + - - null + - 3 + doc: 1-D or 2-D array storing position data. First dimension is time, second dimension + represents spatial coordinates. + attributes: + - name: unit + dtype: text + default_value: meters + doc: Base unit of measurement for position data. Common values are 'meters', + 'centimeters', or 'pixels'. Actual stored values are not necessarily stored + in these units. To access the data in these units, multiply 'data' by 'conversion' + and add 'offset'. + required: false + +- neurodata_type_def: CompassDirectionSeries + neurodata_type_inc: SpatialSeries + doc: Specialized SpatialSeries for tracking directional heading or compass direction. + Stores a floating point value representing theta (heading angle). The reference_frame + field should indicate what direction corresponds to 0 degrees/radians and specify + the direction of rotation (clockwise is standard). Units should be 'radians' or + 'degrees'. + datasets: + - name: data + dtype: numeric + dims: + - - num_times + - - num_times + - theta + shape: + - - null + - - null + - 1 + doc: 1-D or 2-D array storing heading/compass direction. Typically stores a single + angular value (theta) per timepoint. + attributes: + - name: unit + dtype: text + default_value: radians + doc: Base unit of measurement for direction data. Should be 'radians' or 'degrees'. + Actual stored values are not necessarily stored in these units. To access + the data in these units, multiply 'data' by 'conversion' and add 'offset'. + required: false + +- neurodata_type_def: EyeTrackingSeries + neurodata_type_inc: SpatialSeries + doc: Specialized SpatialSeries for tracking direction of gaze. Stores 2D or 3D + coordinates representing gaze direction, which may be angular (gaze angles relative + to head) or spatial (screen/world coordinates). The reference_frame field should + indicate what 'straight-ahead' means (e.g., 'center of screen' or 'straight ahead + from head position'). Units may be degrees, radians, or pixels depending on the + eye tracking method. + datasets: + - name: data + dtype: numeric + dims: + - - num_times + - - num_times + - x + - - num_times + - x,y + - - num_times + - x,y,z + shape: + - - null + - - null + - 1 + - - null + - 2 + - - null + - 3 + doc: 1-D or 2-D array storing gaze direction. Typically 2D (x,y gaze angles or + screen coordinates), but can be 1D or 3D. + attributes: + - name: unit + dtype: text + default_value: degrees + doc: Base unit of measurement for gaze direction. Common values are 'degrees', + 'radians', or 'pixels'. Actual stored values are not necessarily stored in + these units. To access the data in these units, multiply 'data' by 'conversion' + and add 'offset'. + required: false + - neurodata_type_def: BehavioralEpochs neurodata_type_inc: NWBDataInterface default_name: BehavioralEpochs @@ -83,6 +188,31 @@ groups: doc: TimeSeries object containing continuous behavioral data. quantity: '+' +- neurodata_type_def: PupilTrackingSeries + neurodata_type_inc: TimeSeries + doc: Specialized TimeSeries for tracking pupil size/diameter over time. Stores + scalar measurements of pupil diameter or area for a single pupil. For tracking + both eyes, use two separate PupilTrackingSeries instances (e.g., one for left + eye, one for right eye). Units should be in length measurements (e.g., millimeters, + pixels) or arbitrary units with appropriate conversion factors. + datasets: + - name: data + dtype: numeric + dims: + - - num_times + shape: + - - null + doc: 1-D array storing pupil size data over time. + attributes: + - name: unit + dtype: text + default_value: millimeters + doc: Base unit of measurement for pupil size. Common values are 'millimeters', + 'pixels', or 'arbitrary units'. Actual stored values are not necessarily + stored in these units. To access the data in these units, multiply 'data' + by 'conversion' and add 'offset'. + required: false + - neurodata_type_def: PupilTracking neurodata_type_inc: NWBDataInterface default_name: PupilTracking From 1a9ebf7a870742efbfe3229f5d3a74b801db2c34 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Thu, 6 Nov 2025 14:01:25 -0600 Subject: [PATCH 2/8] some improvements --- core/nwb.behavior.yaml | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index c97993b7..a9f739d7 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -68,25 +68,27 @@ groups: - 2 - - null - 3 - doc: 1-D or 2-D array storing position data. First dimension is time, second dimension - represents spatial coordinates. + doc: 1-D or 2-D array storing position data. First dimension is time, and the remaining + dimension(s) represent spatial coordinates. attributes: - name: unit dtype: text default_value: meters doc: Base unit of measurement for position data. Common values are 'meters', - 'centimeters', or 'pixels'. Actual stored values are not necessarily stored - in these units. To access the data in these units, multiply 'data' by 'conversion' - and add 'offset'. + 'centimeters', or 'pixels'. required: false - neurodata_type_def: CompassDirectionSeries neurodata_type_inc: SpatialSeries - doc: Specialized SpatialSeries for tracking directional heading or compass direction. - Stores a floating point value representing theta (heading angle). The reference_frame - field should indicate what direction corresponds to 0 degrees/radians and specify - the direction of rotation (clockwise is standard). Units should be 'radians' or - 'degrees'. + doc: Specialized SpatialSeries for tracking directional heading or compass direction + of a subject (typically head direction in navigation studies). Stores a floating + point value representing theta (heading angle). The reference_frame field should + indicate what direction corresponds to 0 degrees/radians and specify the direction + of rotation (clockwise is standard). Units should be 'radians' or 'degrees'. Example + reference frames might be '0 radians is facing the reward port, rotation is clockwise + when viewed from above' or '0 degrees corresponds to magnetic North'. Commonly + used in spatial navigation research to track head direction cell activity or analyze + directional movement patterns. datasets: - name: data dtype: numeric @@ -105,8 +107,6 @@ groups: dtype: text default_value: radians doc: Base unit of measurement for direction data. Should be 'radians' or 'degrees'. - Actual stored values are not necessarily stored in these units. To access - the data in these units, multiply 'data' by 'conversion' and add 'offset'. required: false - neurodata_type_def: EyeTrackingSeries @@ -143,9 +143,7 @@ groups: dtype: text default_value: degrees doc: Base unit of measurement for gaze direction. Common values are 'degrees', - 'radians', or 'pixels'. Actual stored values are not necessarily stored in - these units. To access the data in these units, multiply 'data' by 'conversion' - and add 'offset'. + 'radians', or 'pixels'. required: false - neurodata_type_def: BehavioralEpochs @@ -208,8 +206,7 @@ groups: dtype: text default_value: millimeters doc: Base unit of measurement for pupil size. Common values are 'millimeters', - 'pixels', or 'arbitrary units'. Actual stored values are not necessarily - stored in these units. To access the data in these units, multiply 'data' + 'pixels', or 'arbitrary units'. by 'conversion' and add 'offset'. required: false From f9ec42a6a2657af3af823bdd845f402857ccc17b Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Thu, 6 Nov 2025 14:07:53 -0600 Subject: [PATCH 3/8] eye tracking improvements --- core/nwb.behavior.yaml | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index a9f739d7..4fbf12ba 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -111,12 +111,18 @@ groups: - neurodata_type_def: EyeTrackingSeries neurodata_type_inc: SpatialSeries - doc: Specialized SpatialSeries for tracking direction of gaze. Stores 2D or 3D - coordinates representing gaze direction, which may be angular (gaze angles relative - to head) or spatial (screen/world coordinates). The reference_frame field should - indicate what 'straight-ahead' means (e.g., 'center of screen' or 'straight ahead - from head position'). Units may be degrees, radians, or pixels depending on the - eye tracking method. + doc: Specialized SpatialSeries for tracking gaze location or eye position. Eye tracking + measures where the subject is looking, which can be represented in different coordinate + systems depending on the experimental setup. Common representations include (1) + gaze position on a screen/monitor in pixels or screen coordinates, (2) eye rotation + angles relative to the head (horizontal and vertical), or (3) gaze position in + world coordinates. The reference_frame field should specify the coordinate system. + Example reference frames might be 'gaze position in pixels, origin at top-left + corner of screen, x-axis pointing right, y-axis pointing down' for screen-based + tracking, or 'eye rotation angles in degrees, origin at straight ahead from head, + positive x is rightward, positive y is upward' for head-centered coordinates. Commonly + used in vision research, attention studies, and experiments correlating gaze with + neural activity. datasets: - name: data dtype: numeric From e8761ecdfa35d7f5a2af44d6628db55dd424f119 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Thu, 6 Nov 2025 14:10:06 -0600 Subject: [PATCH 4/8] improve position docs --- core/nwb.behavior.yaml | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index 4fbf12ba..cad0b52a 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -45,10 +45,17 @@ groups: - neurodata_type_def: PositionSeries neurodata_type_inc: SpatialSeries - doc: Specialized SpatialSeries for tracking spatial position of a subject or object. - Stores coordinates in 1D, 2D, or 3D space (x, x/y, or x/y/z). The reference_frame - field should indicate the zero-position (e.g., 'top-left corner of enclosure'). - Units should be in spatial measurements (e.g., meters, centimeters, pixels). + doc: Specialized SpatialSeries for tracking the spatial position/location of a subject + or object over time. Stores coordinates in 1D, 2D, or 3D space. Common use cases + include tracking animal position in an arena during behavioral experiments, monitoring + body part locations during movement, or recording object positions in the environment. + The reference_frame field should specify the coordinate system and origin. Example + reference frames might be 'origin at top-left corner of arena, x-axis pointing + right, y-axis pointing down, as viewed from above' for 2D arena tracking, or 'origin + at center of experimental chamber, x-axis pointing East, y-axis pointing North, + z-axis pointing up' for 3D tracking. Units should be in spatial measurements (e.g., + meters, centimeters, pixels). Commonly used in behavioral neuroscience, spatial + navigation studies, and motion tracking experiments. datasets: - name: data dtype: numeric From 4667b909a74f0cfcb3fb95c420884a83423baf82 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Thu, 6 Nov 2025 14:12:18 -0600 Subject: [PATCH 5/8] remove wrong doc reference --- core/nwb.behavior.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index cad0b52a..874739b9 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -220,7 +220,6 @@ groups: default_value: millimeters doc: Base unit of measurement for pupil size. Common values are 'millimeters', 'pixels', or 'arbitrary units'. - by 'conversion' and add 'offset'. required: false - neurodata_type_def: PupilTracking From 34ad8f3dfb56c8ebbc3c1e85420ef3f3b1520433 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Thu, 6 Nov 2025 14:14:31 -0600 Subject: [PATCH 6/8] add changelog --- core/nwb.behavior.yaml | 15 +++++---------- docs/format/source/format_release_notes.rst | 5 +++++ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index 874739b9..8a6853c2 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -47,15 +47,14 @@ groups: neurodata_type_inc: SpatialSeries doc: Specialized SpatialSeries for tracking the spatial position/location of a subject or object over time. Stores coordinates in 1D, 2D, or 3D space. Common use cases - include tracking animal position in an arena during behavioral experiments, monitoring - body part locations during movement, or recording object positions in the environment. + include tracking animal position in an arena during behavioral experiments + or recording object positions in the environment. The reference_frame field should specify the coordinate system and origin. Example reference frames might be 'origin at top-left corner of arena, x-axis pointing right, y-axis pointing down, as viewed from above' for 2D arena tracking, or 'origin at center of experimental chamber, x-axis pointing East, y-axis pointing North, z-axis pointing up' for 3D tracking. Units should be in spatial measurements (e.g., - meters, centimeters, pixels). Commonly used in behavioral neuroscience, spatial - navigation studies, and motion tracking experiments. + meters, centimeters, pixels). datasets: - name: data dtype: numeric @@ -93,9 +92,7 @@ groups: indicate what direction corresponds to 0 degrees/radians and specify the direction of rotation (clockwise is standard). Units should be 'radians' or 'degrees'. Example reference frames might be '0 radians is facing the reward port, rotation is clockwise - when viewed from above' or '0 degrees corresponds to magnetic North'. Commonly - used in spatial navigation research to track head direction cell activity or analyze - directional movement patterns. + when viewed from above' or '0 degrees corresponds to magnetic North'. datasets: - name: data dtype: numeric @@ -127,9 +124,7 @@ groups: Example reference frames might be 'gaze position in pixels, origin at top-left corner of screen, x-axis pointing right, y-axis pointing down' for screen-based tracking, or 'eye rotation angles in degrees, origin at straight ahead from head, - positive x is rightward, positive y is upward' for head-centered coordinates. Commonly - used in vision research, attention studies, and experiments correlating gaze with - neural activity. + positive x is rightward, positive y is upward' for head-centered coordinates. datasets: - name: data dtype: numeric diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst index 237afe2c..471155d9 100644 --- a/docs/format/source/format_release_notes.rst +++ b/docs/format/source/format_release_notes.rst @@ -26,6 +26,11 @@ Major changes Minor changes ^^^^^^^^^^^^^ +- Added specialized behavioral series types: ``PositionSeries``, ``CompassDirectionSeries``, ``EyeTrackingSeries``, + and ``PupilTrackingSeries``. These new types provide explicit semantics and appropriate default units for tracking + spatial position, head direction, gaze location, and pupil size, respectively. The legacy container types + (``Position``, ``CompassDirection``, ``EyeTracking``, ``PupilTracking``) remain for backward compatibility. + Users are encouraged to use the new specialized series types for new data. (@h-mayorquin, #655) - Made group quantities consistent ("1 or more") across data interfaces / wrapper types (#613) - Fixed typo and removed HTML tag from doc of behavioral neurodata types. (#600) - Improved the documentation of ``IndexSeries``. (#614) From f06ceee19ba43b91cd1a9bcb517d514e447134c9 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Thu, 6 Nov 2025 14:19:43 -0600 Subject: [PATCH 7/8] release notes --- docs/format/source/format_release_notes.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst index 471155d9..24890df2 100644 --- a/docs/format/source/format_release_notes.rst +++ b/docs/format/source/format_release_notes.rst @@ -23,14 +23,14 @@ Major changes neurodata type that extends ``DynamicTable`` with added columns. (#610) - Made ``SpikeEventSeries.timestamps`` explicitly required as described in the documentation. (#629) - Allowed ``EventDetection`` to have shape (num_events, 2) to store the channel index of the detected event. (#620) - -Minor changes -^^^^^^^^^^^^^ - Added specialized behavioral series types: ``PositionSeries``, ``CompassDirectionSeries``, ``EyeTrackingSeries``, and ``PupilTrackingSeries``. These new types provide explicit semantics and appropriate default units for tracking spatial position, head direction, gaze location, and pupil size, respectively. The legacy container types (``Position``, ``CompassDirection``, ``EyeTracking``, ``PupilTracking``) remain for backward compatibility. - Users are encouraged to use the new specialized series types for new data. (@h-mayorquin, #655) + Users are encouraged to use the new specialized series types for new data. (#655) + +Minor changes +^^^^^^^^^^^^^ - Made group quantities consistent ("1 or more") across data interfaces / wrapper types (#613) - Fixed typo and removed HTML tag from doc of behavioral neurodata types. (#600) - Improved the documentation of ``IndexSeries``. (#614) From d10819180151da885c05ea65daf87f2268655895 Mon Sep 17 00:00:00 2001 From: Heberto Mayorquin Date: Thu, 6 Nov 2025 14:50:01 -0600 Subject: [PATCH 8/8] add warnings --- core/nwb.behavior.yaml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index 8a6853c2..cebfeef4 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -220,7 +220,9 @@ groups: - neurodata_type_def: PupilTracking neurodata_type_inc: NWBDataInterface default_name: PupilTracking - doc: Eye-tracking data, representing pupil size. + doc: Eye-tracking data, representing pupil size. WARNING - Use the specialized + PupilTrackingSeries type for new data, which provides explicit semantics and + appropriate default units for pupil size measurements. groups: - neurodata_type_inc: TimeSeries doc: TimeSeries object containing time series data on pupil size. @@ -229,7 +231,9 @@ groups: - neurodata_type_def: EyeTracking neurodata_type_inc: NWBDataInterface default_name: EyeTracking - doc: Eye-tracking data, representing direction of gaze. + doc: Eye-tracking data, representing direction of gaze. WARNING - Use the specialized + EyeTrackingSeries type for new data, which provides explicit semantics and appropriate + default units for gaze tracking. groups: - neurodata_type_inc: SpatialSeries doc: SpatialSeries object containing data measuring direction of gaze. @@ -242,7 +246,9 @@ groups: representing a floating point value for theta. The SpatialSeries::reference_frame field should indicate what direction corresponds to 0 and which is the direction of rotation (this should be clockwise). The si_unit for the SpatialSeries should - be radians or degrees. + be radians or degrees. WARNING - Use the specialized CompassDirectionSeries type + for new data, which provides explicit semantics and appropriate default units for + directional heading measurements. groups: - neurodata_type_inc: SpatialSeries doc: SpatialSeries object containing direction of gaze travel. @@ -251,7 +257,9 @@ groups: - neurodata_type_def: Position neurodata_type_inc: NWBDataInterface default_name: Position - doc: Position data, whether along the x, x/y or x/y/z axis. + doc: Position data, whether along the x, x/y or x/y/z axis. WARNING - Use the + specialized PositionSeries type for new data, which provides explicit semantics + and appropriate default units for spatial position measurements. groups: - neurodata_type_inc: SpatialSeries doc: SpatialSeries object containing position data.