From 5b0c3cca2582ba2f21612c23f44c94f4f6ea22ed Mon Sep 17 00:00:00 2001 From: Neha Thomas Date: Tue, 3 Nov 2026 16:41:19 -0500 Subject: [PATCH 1/5] Adding in concrete examples of standardization approaches inspired by real BBQS teams --- docs/user-guide/data-standardization.md | 343 ++++++++++++++++++++++-- 1 file changed, 328 insertions(+), 15 deletions(-) diff --git a/docs/user-guide/data-standardization.md b/docs/user-guide/data-standardization.md index 54c6ce2..868ae92 100644 --- a/docs/user-guide/data-standardization.md +++ b/docs/user-guide/data-standardization.md @@ -48,55 +48,368 @@ You can see an example of reproducing analysis (figures) at [Example Standardiza ## Animal Data -COMING SOON ### Example 1 - Audio, Video, and pose estimation (SLEAP) in NWB - -### Example 2 - Audio and Video in BIDS, and pose estimation (SLEAP) in NWB +### Example 2 - Audio, video and pose-tracking in BIDS - + ### Example 3 - Multiple animals interacting +Expanding on Examples 1 and 2, now there are two animals in the cage. For this example, the NWB extension for handling data that represents multiple subjects at the same time should be used. Thus, the audio and video, which now capture two animals at once, will be placed into `ndx-multisubjects`, while the individual pose-tracking information will be placed into each animal's individual NWB file. + +The grouped NWB file will look like: + +``` +sub-multi_ses-01_behavior.nwb +│ +├── acquisition/ +│ ├── Audio (AcousticWaveformSeries, ndx-sound) +│ │ ├── data # Shape: (samples, 2 channels) +│ │ │ # Channel 0: Microphone 1 +│ │ │ # Channel 1: Microphone 2 +│ │ ├── starting_time +│ │ └── starting_time.rate +│ │ +│ └── Camera (ImageSeries) +│ ├── external_file # Shared video of both animals +│ ├── starting_frame +│ └── timestamps +│ +├── general/ + └── subjects (SubjectsTable, ndx-multisubjects) + ├── subject_id # sub-01, sub-02 + ├── species + ├── sex + └── individual_subj_link + ├── sub-01 -> sub-01_ses-01_behavior.nwb + └── sub-02 -> sub-02_ses-01_behavior.nwb + + +``` + +The individual NWB file will be structured like: + +``` +sub-01_ses-01_behavior.nwb +│ +├── processing/ +│ └── behavior/ +│ └── PoseEstimation (ndx-pose) +│ ├── Nose (PoseEstimationSeries) +│ │ ├── data # Shape: (frames, 2) +│ │ ├── timestamps +│ │ └── confidence +│ │ +│ ├── LeftEar (PoseEstimationSeries) +│ │ ├── data +│ │ ├── timestamps +│ │ └── confidence +│ │ +│ └── RightEar (PoseEstimationSeries) +│ ├── data +│ ├── timestamps +│ └── confidence +│ +└── general/ + └── subject/ + └── subject_id # sub-01 +``` + +The NWB files that represent the entire dataset are then organized according to: + +``` +myExperimentSession/ +│ +├── sub-multi_ses-01_behavior.nwb +│ # Shared audio and video; metadata for both animals +│ +├── sub-01_ses-01_behavior.nwb +│ # Pose estimation data for Animal 1 +│ +├── sub-02_ses-01_behavior.nwb +│ # Pose estimation data for Animal 2 +│ +└── camera_concatenated.mp4 + # Video containing both animals, referenced by + # the ImageSeries in sub-multi_ses-01_behavior.nwb +``` +If there are multiple sessions, then each session's NWB file should be within the correct individual subject folder or the grouped subject folder. + ## De-identified Human Data -COMING SOON + ### Example 1 - iEEG and motion in NWB +Here, iEEG and motion data are stored in a single .mat file per participant: + +``` +experiment.mat +└── data (MATLAB struct) + │ + ├── ieeg + │ ├── timestamps # Time vector + │ ├── channel_01 # Electrode 1 + │ ├── channel_02 # Electrode 2 + │ ├── channel_03 # Electrode 3 + │ ├── ... + │ └── channel_64 # Electrode 64 + │ + └── motion + ├── timestamps # Time vector + ├── Head_X + ├── Head_Y + ├── Head_Z + ├── Pelvis_X + ├── Pelvis_Y + ├── Pelvis_Z + ├── LeftShoulder_X + ├── LeftShoulder_Y + ├── LeftShoulder_Z + ├── RightShoulder_X + ├── RightShoulder_Y + ├── RightShoulder_Z + ├── ... + ├── RightAnkle_X + ├── RightAnkle_Y + └── RightAnkle_Z +``` + +This data is transformed into appropriate containers within a singe NWB file: + +``` +sub-01_ses-01.nwb +│ +├── acquisition/ +│ └── iEEG (ElectricalSeries) +│ ├── data # Shape: (samples, 64 channels) +│ ├── electrodes # Reference to ElectrodesTable +│ └── timestamps +│ +├── processing/ +│ └── behavior/ +│ └── Position (Position) +│ │ +│ ├── Head (SpatialSeries) +│ │ ├── data # Columns: Head_X, Head_Y, Head_Z +│ │ ├── timestamps +│ │ ├── reference_frame +│ │ └── unit +│ │ +│ ├── Pelvis (SpatialSeries) +│ │ ├── data # Columns: Pelvis_X, Pelvis_Y, Pelvis_Z +│ │ ├── timestamps +│ │ ├── reference_frame +│ │ └── unit +│ │ +│ ├── LeftShoulder (SpatialSeries) +│ │ ├── data # Columns: X, Y, Z +│ │ ├── timestamps +│ │ ├── reference_frame +│ │ └── unit +│ │ +│ ├── RightShoulder (SpatialSeries) +│ │ ├── data # Columns: X, Y, Z +│ │ ├── timestamps +│ │ ├── reference_frame +│ │ └── unit +│ │ +│ ├── LeftAnkle (SpatialSeries) +│ │ ├── data # Columns: X, Y, Z +│ │ ├── timestamps +│ │ ├── reference_frame +│ │ └── unit +│ │ +│ └── RightAnkle (SpatialSeries) +│ ├── data # Columns: X, Y, Z +│ ├── timestamps +│ ├── reference_frame +│ └── unit +│ +└── general/ + ├── subject/ + │ └── subject_id # sub-01 + │ + └── extracellular_ephys/ + ├── electrodes (ElectrodesTable) + │ ├── id + │ ├── location + │ ├── group + │ └── ... + │ + └── ElectrodeGroup(s) +``` + ### Example 2 - iEEG and motion in hybrid BIDS/NWB +Taking the same exmaple of human data as in Example 1, the .mat data is now transformed into both NWB and BIDS within an overarching BIDS folder structure as shown below: + +``` +myExperiment/ +│ +├── dataset_description.json +├── participants.tsv +├── README +│ +└── sub-01/ + └── ses-01/ + │ + ├── ieeg/ + │ ├── sub-01_ses-01_task-movement_ieeg.nwb + │ ├── sub-01_ses-01_task-movement_ieeg.json + │ ├── sub-01_ses-01_task-movement_channels.tsv + │ ├── sub-01_ses-01_electrodes.tsv + │ └── sub-01_ses-01_coordsystem.json + │ + └── motion/ + ├── sub-01_ses-01_task-movement_tracksys-vicon_motion.tsv + ├── sub-01_ses-01_task-movement_tracksys-vicon_motion.json + ├── sub-01_ses-01_task-movement_tracksys-vicon_channels.tsv + └── sub-01_ses-01_task-movement_tracksys-vicon_channels.json +``` From eb206a48b6ea3e145688c56779a5a736a13efe4a Mon Sep 17 00:00:00 2001 From: Neha Thomas Date: Tue, 3 Nov 2026 16:53:57 -0500 Subject: [PATCH 2/5] fix typos --- docs/user-guide/data-standardization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/data-standardization.md b/docs/user-guide/data-standardization.md index 868ae92..e990bc6 100644 --- a/docs/user-guide/data-standardization.md +++ b/docs/user-guide/data-standardization.md @@ -318,7 +318,7 @@ experiment.mat └── RightAnkle_Z ``` -This data is transformed into appropriate containers within a singe NWB file: +This data is transformed into appropriate containers within a single NWB file: ``` sub-01_ses-01.nwb @@ -385,7 +385,7 @@ sub-01_ses-01.nwb ### Example 2 - iEEG and motion in hybrid BIDS/NWB -Taking the same exmaple of human data as in Example 1, the .mat data is now transformed into both NWB and BIDS within an overarching BIDS folder structure as shown below: +Taking the same example of human data as in Example 1, the .mat data is now transformed into both NWB and BIDS within an overarching BIDS folder structure as shown below: ``` myExperiment/ From 4aa3615238beb00d7d1f2158ba86fcafb066149a Mon Sep 17 00:00:00 2001 From: Neha Thomas Date: Thu, 5 Nov 2026 16:30:53 -0500 Subject: [PATCH 3/5] adding clarification on the folder structure in example 1 for animal data --- docs/user-guide/data-standardization.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/user-guide/data-standardization.md b/docs/user-guide/data-standardization.md index e990bc6..f34fd91 100644 --- a/docs/user-guide/data-standardization.md +++ b/docs/user-guide/data-standardization.md @@ -50,31 +50,31 @@ You can see an example of reproducing analysis (figures) at [Example Standardiza ### Example 1 - Audio, Video, and pose estimation (SLEAP) in NWB -Let's suppose the original data is a single animal in cage with one camera and two microphones: +Let's suppose the original data is a single animal in cage with one camera and two microphones. The long recording session is split up into separate folders, containing five-minute splits: ``` myExperimentSession/ -├── folder1/ +├── split1/ │ ├── camera.mp4 │ ├── microphone1.wav │ ├── microphone2.wav │ └── pose.slp -├── folder2/ +├── split2/ │ ├── camera.mp4 │ ├── microphone1.wav │ ├── microphone2.wav │ └── pose.slp -├── folder3/ +├── split3/ │ ├── camera.mp4 │ ├── microphone1.wav │ ├── microphone2.wav │ └── pose.slp -├── folder4/ +├── split4/ │ ├── camera.mp4 │ ├── microphone1.wav │ ├── microphone2.wav │ └── pose.slp -└── folder5/ +└── split5/ ├── camera.mp4 ├── microphone1.wav ├── microphone2.wav @@ -84,9 +84,9 @@ myExperimentSession/ ``` -Each of the audio and video files in the folder1 in myExperiment hold data that is continuous in time with the files of folder2, which is continuous with folder3 and so and and so forth. Altogether, folders 1 - 5 constitute a single recording session. Best practices indicate that all the data should be contained inside a single NWB file. +Each of the audio and video files in the `split1` folder in myExperiment hold data that is continuous in time with the files of `split2`, which is continuous with `split3` and so and and so forth. Altogether, folders `split1` - `split5` constitute a single recording session. Best practices indicate that all the data should be contained inside a single NWB file. -To make it easier for a secondary user to parse the data, then, we will concatenate all video files together, all audio files together, and all pose data together within the single NWB file. The concatenated video file will be referenced externally, and audio files will be represented with `ndx-sound`. +To make it easier for a secondary user to parse the data, then, we will concatenate all video files together, all audio files together, and all pose data together within the single NWB file. The concatenated video file will be referenced externally, and audio files will be represented with `ndx-sound`, an NWB extension for audio data. The resulting NWB structure then looks like: From d3a069040dbf59b320713d2d6f28c9f34f2fdab6 Mon Sep 17 00:00:00 2001 From: nehatk17 Date: Thu, 5 Nov 2026 16:36:50 -0500 Subject: [PATCH 4/5] Apply Erik's batched suggestions from code review Co-authored-by: erikjohnson24 <32878471+erikjohnson24@users.noreply.github.com> --- docs/user-guide/data-standardization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/data-standardization.md b/docs/user-guide/data-standardization.md index f34fd91..dc1a48e 100644 --- a/docs/user-guide/data-standardization.md +++ b/docs/user-guide/data-standardization.md @@ -88,7 +88,7 @@ Each of the audio and video files in the `split1` folder in myExperiment hold da To make it easier for a secondary user to parse the data, then, we will concatenate all video files together, all audio files together, and all pose data together within the single NWB file. The concatenated video file will be referenced externally, and audio files will be represented with `ndx-sound`, an NWB extension for audio data. -The resulting NWB structure then looks like: +The resulting NWB structure for the single file then looks like: ``` myExperimentSession.nwb @@ -318,7 +318,7 @@ experiment.mat └── RightAnkle_Z ``` -This data is transformed into appropriate containers within a single NWB file: +This data is transformed into appropriate containers within a single NWB file, producing a standardized result that can be loaded with other tools and processing scripts: ``` sub-01_ses-01.nwb @@ -385,7 +385,7 @@ sub-01_ses-01.nwb ### Example 2 - iEEG and motion in hybrid BIDS/NWB -Taking the same example of human data as in Example 1, the .mat data is now transformed into both NWB and BIDS within an overarching BIDS folder structure as shown below: +Taking the same example of human data as in Example 1, the .mat data is now transformed into both NWB and BIDS within an overarching BIDS folder structure. This is a useful option as it allows easy access to individual modalities and organization of larger experiments. This is shown below: ``` myExperiment/ From 6a59a5377d2de61fc45005992bfa81d5bc717439 Mon Sep 17 00:00:00 2001 From: Neha Thomas Date: Mon, 9 Nov 2026 16:31:09 -0500 Subject: [PATCH 5/5] adding cue for BBQS teams to contact EMBER --- docs/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/index.md b/docs/index.md index d518afa..e49c80c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,6 +67,9 @@ If your data are: 4. You can embargo your dataset for a desired period of time, which means it is viewable only to you and selected individuals. 5. You can publish your dataset, making it publicly available and creating a DOI. +!!! tip + If you are on a BBQS team, please reach out to us to get this workflow started at [help@emberarchive.org](mailto:help@emberarchive.org). + ### How do I use EMBER-Vault? COMING SOON