From 107b5f8245d2284540c5d4b2464d65e4359f9fa2 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Thu, 6 Aug 2020 17:44:49 -0700 Subject: [PATCH 1/6] Make data required for ImageSeries, update docs --- core/nwb.image.yaml | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/core/nwb.image.yaml b/core/nwb.image.yaml index 3d7eb838..5d51200a 100644 --- a/core/nwb.image.yaml +++ b/core/nwb.image.yaml @@ -39,11 +39,8 @@ datasets: groups: - neurodata_type_def: ImageSeries neurodata_type_inc: TimeSeries - doc: General image data that is common between acquisition and stimulus time series. - Sometimes the image data is stored in the file in a raw format while other - times it will be stored as a series of external image files in the host file system. - The data field will either be binary data, if the data is stored in the NWB file, or - empty, if the data is stored in an external image stack. [frame][x][y] or [frame][x][y][z]. + doc: General image data. The image data may be stored in the file in a raw format or in a single external image file + or series of external image files in the host filesystem. datasets: - name: data dtype: numeric @@ -63,8 +60,8 @@ groups: - null - null - null - doc: Binary data representing images across frames. - quantity: '?' + doc: Data representing images across frames. The dimensions are [frame][x][y] or [frame][x][y][z]. If data is + stored in an external_file, set this dataset to an empty 3-dimensional array. - name: dimension dtype: int32 dims: From fa3c48f929c212b14d558a3fa07b5b60c32a0c2f Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Mon, 2 Aug 2021 15:41:54 -0700 Subject: [PATCH 2/6] Add ExternalImageSeries, update ImageSeries --- core/nwb.image.yaml | 103 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 94 insertions(+), 9 deletions(-) diff --git a/core/nwb.image.yaml b/core/nwb.image.yaml index 5d51200a..3e91f80d 100644 --- a/core/nwb.image.yaml +++ b/core/nwb.image.yaml @@ -39,8 +39,7 @@ datasets: groups: - neurodata_type_def: ImageSeries neurodata_type_inc: TimeSeries - doc: General image data. The image data may be stored in the file in a raw format or in a single external image file - or series of external image files in the host filesystem. + doc: Image data stored in a raw format. datasets: - name: data dtype: numeric @@ -60,8 +59,7 @@ groups: - null - null - null - doc: Data representing images across frames. The dimensions are [frame][x][y] or [frame][x][y][z]. If data is - stored in an external_file, set this dataset to an empty 3-dimensional array. + doc: Data representing images across frames. The dimensions are [frame][x][y] or [frame][x][y][z]. - name: dimension dtype: int32 dims: @@ -76,10 +74,12 @@ groups: - num_files shape: - null - doc: Paths to one or more external file(s). The field is only present if format='external'. + doc: Use of this dataset is discouraged and will be deprecated. Please use + ExternalImageSeries instead. Paths to one or more external file(s). + The field is only present if format='external'. This is only relevant if the image series is stored in the file system as one or more image file(s). This field should NOT be used if the image is stored - in another NWB file and that file is linked to this file. + in another NWB file and that file is linked to this file. quantity: '?' attributes: - name: starting_frame @@ -102,9 +102,10 @@ groups: - name: format dtype: text default_value: raw - doc: Format of image. If this is 'external', then the attribute 'external_file' - contains the path information to the image files. If this is 'raw', then the raw - (single-channel) binary data is stored in the 'data' dataset. If this attribute + doc: Format of image. If this is 'raw', then the raw (single-channel) binary data is + stored in the 'data' dataset. If this is 'external', then the attribute 'external_file' + contains the path information to the image files. Use of external files is discouraged + and will be deprecated. Please use ExternalImageSeries instead. If this attribute is not present, then the default format='raw' case is assumed. quantity: '?' links: @@ -112,6 +113,90 @@ groups: target_type: Device doc: Link to the Device object that was used to capture these images. quantity: '?' + +- neurodata_type_def: ExternalImageSeries + neurodata_type_inc: NWBDataInterface + doc: General image data stored in external files on the filesystem. Note that this type + does not extend TimeSeries because there is no 'data' dataset. However, there is still + a time dimension which can be stored as timestamps or a starting time and sampling rate. + datasets: + - name: dimension + dtype: int32 + dims: + - rank + shape: + - null + doc: Number of pixels on x, y, (and z) axes. + quantity: '?' + - name: external_file + dtype: text + dims: + - num_files + shape: + - null + doc: Paths to one or more external image file(s). + quantity: '?' + attributes: + - name: starting_frame + dtype: int32 + dims: + - num_files + shape: + - null + doc: "Each external image may contain one or more consecutive frames of the full + ExternalImageSeries (e.g., if an external image is a tiff stack). This attribute + serves as an index to indicate which frames each file + contains, to faciliate random access. The 'starting_frame' attribute, hence, + contains a list of numbers corresponding to the index of the image series at which + each external file begins. Zero-based indexing is used; hence, the first element will + always be zero. For example, if the 'external_file' dataset has three paths to files + and the first file has 5 frames, the second file has 10 frames, and the third file has + 20 frames, then this attribute will have values [0, 5, 15]. In other words, + starting_frame[0] = 0; + for i in range(1, length(external_file)), + starting_frame[i] = starting_frame[i-1] + num_frames(external_file[i]) + If there is a single external file that holds all of the frames of the + ExternalImageSeries (and so there is a single element in the 'external_file' + dataset), then this attribute should have value [0]. If there are N + external files with a single frame each, then this attribute should have values + [0, 1, ..., N-1]." + - name: starting_time + dtype: float64 + doc: Timestamp of the first sample in seconds. When timestamps are uniformly + spaced, the timestamp of the first sample can be specified and all subsequent + ones calculated from the sampling rate attribute. + quantity: '?' + attributes: + - name: rate + dtype: float32 + doc: Sampling rate, in Hz. + - name: unit + dtype: text + value: seconds + doc: Unit of measurement for time, which is fixed to 'seconds'. + - name: timestamps + dtype: float64 + dims: + - num_times + shape: + - null + doc: Timestamps for samples stored in data, in seconds, relative to the + common experiment master-clock stored in NWBFile.timestamps_reference_time. + quantity: '?' + attributes: + - name: interval + dtype: int32 + value: 1 + doc: Value is '1' + - name: unit + dtype: text + value: seconds + doc: Unit of measurement for timestamps, which is fixed to 'seconds'. + links: + - name: device + target_type: Device + doc: Link to the Device object that was used to capture these images. + quantity: '?' - neurodata_type_def: ImageMaskSeries neurodata_type_inc: ImageSeries From bdda1bcd59834def0589e9625c99b26c1c7a21f6 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Mon, 2 Aug 2021 19:18:16 -0700 Subject: [PATCH 3/6] Change dims of ImageSeries and reset dims of OpticalSeries --- core/nwb.image.yaml | 33 +++++++-------------------------- 1 file changed, 7 insertions(+), 26 deletions(-) diff --git a/core/nwb.image.yaml b/core/nwb.image.yaml index 3e91f80d..d0f55342 100644 --- a/core/nwb.image.yaml +++ b/core/nwb.image.yaml @@ -50,7 +50,7 @@ groups: - - frame - x - y - - z + - r, g, b shape: - - null - null @@ -58,15 +58,15 @@ groups: - - null - null - null - - null - doc: Data representing images across frames. The dimensions are [frame][x][y] or [frame][x][y][z]. + - 3 + doc: Data representing images across frames. The dimensions are [frame][x][y] or [frame][x][y][rgb]. - name: dimension dtype: int32 dims: - - rank + - x, y shape: - - null - doc: Number of pixels on x, y, (and z) axes. + - 2 + doc: Number of pixels on x and y axes. quantity: '?' - name: external_file dtype: text @@ -230,27 +230,8 @@ groups: shape: - - 2 - - 3 - doc: Width, height and depth of image, or imaged area, in meters. + doc: Width, height, and depth of image, or imaged area, in meters. quantity: '?' - - name: data - dtype: numeric - dims: - - - frame - - x - - y - - - frame - - x - - y - - r, g, b - shape: - - - null - - null - - null - - - null - - null - - null - - 3 - doc: Images presented to subject, either grayscale or RGB - name: orientation dtype: text doc: Description of image relative to some reference frame (e.g., which way is From d8999486cda08ca534042ec4a0cb059341cb3592 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Mon, 2 Aug 2021 19:21:20 -0700 Subject: [PATCH 4/6] Add VolumeSeries --- core/nwb.image.yaml | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/core/nwb.image.yaml b/core/nwb.image.yaml index d0f55342..b9f39043 100644 --- a/core/nwb.image.yaml +++ b/core/nwb.image.yaml @@ -114,6 +114,47 @@ groups: doc: Link to the Device object that was used to capture these images. quantity: '?' +- neurodata_type_def: VolumeSeries + neurodata_type_inc: TimeSeries + doc: Volume data stored in a raw format. + datasets: + - name: data + dtype: numeric + dims: + - - frame + - x + - y + - z + - - frame + - x + - y + - z + - r, g, b + shape: + - - null + - null + - null + - null + - - null + - null + - null + - null + - 3 + doc: Data representing images across frames. The dimensions are [frame][x][y][z] or [frame][x][y][z][rgb]. + - name: dimension + dtype: int32 + dims: + - x, y, z + shape: + - 3 + doc: Number of pixels on x, y, and z axes. + quantity: '?' + links: + - name: device + target_type: Device + doc: Link to the Device object that was used to capture these images. + quantity: '?' + - neurodata_type_def: ExternalImageSeries neurodata_type_inc: NWBDataInterface doc: General image data stored in external files on the filesystem. Note that this type From 6e9846a1329e3e14d18b090f99f8dacd9ded8456 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Mon, 2 Aug 2021 19:22:22 -0700 Subject: [PATCH 5/6] Allow 5D data in TimeSeries --- core/nwb.base.yaml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/core/nwb.base.yaml b/core/nwb.base.yaml index 82f59c81..ebc22f20 100644 --- a/core/nwb.base.yaml +++ b/core/nwb.base.yaml @@ -97,6 +97,11 @@ groups: - num_DIM2 - num_DIM3 - num_DIM4 + - - num_times + - num_DIM2 + - num_DIM3 + - num_DIM4 + - num_DIM5 shape: - - null - - null @@ -108,7 +113,12 @@ groups: - null - null - null - doc: Data values. Data can be in 1-D, 2-D, 3-D, or 4-D. The first dimension + - - null + - null + - null + - null + - null + doc: Data values. Data can be in 1-D, 2-D, 3-D, 4-D, or 5-D. The first dimension should always represent time. This can also be used to store binary data (e.g., image frames). This can also be a link to data stored in an external file. attributes: From d633e726af24b78d3dd7625ae604ab78087495b3 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Tue, 3 Aug 2021 00:25:34 -0700 Subject: [PATCH 6/6] Update nwb.image.yaml --- core/nwb.image.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/core/nwb.image.yaml b/core/nwb.image.yaml index b9f39043..cf866607 100644 --- a/core/nwb.image.yaml +++ b/core/nwb.image.yaml @@ -58,8 +58,10 @@ groups: - - null - null - null - - 3 - doc: Data representing images across frames. The dimensions are [frame][x][y] or [frame][x][y][rgb]. + - null + doc: 'Data representing images across frames. The dimensions are [frame][x][y] or [frame][x][y][rgb]. + Use of ImageSeries to store volumetric data (shape: (frame, x, y, z)) is discouraged and will be + deprecated in a future major release. Please use VolumeSeries instead.' - name: dimension dtype: int32 dims: