1- JSNIRF: A lightweight and portable fNIRS data storage format
1+ JSNIRF: A JSON/binary JSON extension to the SNIRF format
22============================================================
33
4- - ** Status of this document** : This document is current under development.
54- ** Copyright** : (C) 2019-2025 Qianqian Fang <q.fang at neu.edu>
65- ** License** : Apache License, Version 2.0
7- - ** Version** : V1 (Draft-2)
6+ - ** Version** : V1 (Draft-2.preview)
7+ - ** URL** : https://neurojson.org/jsnirf/draft2
8+ - ** Status** : Draft-2 is a work-in-progress
9+ - ** Development** : https://github.com/NeuroJSON/jsnirf
810- ** Abstract** :
911
10- > JSNIRF is a portable format for storage, interchange and processing
11-
12- functional neuroimaging technique. Built upon the JData and SNIRF specifications,
13- a JSNIRF file has both a text-based interface using the JavaScript
14- Object Notation (JSON) [ RFC4627] format and a binary interface using
15- the Universal Binary JSON (UBJSON) serialization format. It contains
16- a compatibility layer to provide a 1-to-1 mapping to the existing HDF5
17- based SNIRF files. A JSNIRF file can be directly parsed by most existing
18- JSON and UBJSON parsers. Advanced features include optional hierarchical
19- data storage, grouping, compression, integration with heterogeneous
20- scientific data enabled by JData data serialization framework.
12+ > This specification defines the JSNIRF standard format. The JSNIRF format
13+
14+ JavaScript Object Notation (JSON) [ RFC4627] and binary JSON serialization
15+ methods. It loss-lessly maps all SNIRF/HDF5 headers and data structures to
16+ a human-readable JSON-based wrapper. Use of JSON and JSNIRF formats to store
17+ SNIRF data makes it possible to rapidly index, exchange, and query large amount
18+ of SNIRF datasets and metadata using modern database engines where JSON is used
19+ as the underlying data exchange format. With the extension of JData annotations,
20+ JSNIRF also permits optional hierarchical data storage, image data grouping,
21+ various data compression codecs, filters, streaming and encryption.
2122
2223
2324## Table of Content
@@ -97,7 +98,7 @@ JSON and UBJSON based files for easy sharing, parsing and integration.
9798
9899The purpose of this document is to
99100
100- - define a 1-to-1 mapping between the existing SNRIF data structures
101+ - define a 1-to-1 mapping between the existing SNIRF data structures
101102 to a JSON/UBJSON-based flexible data structure to allow lossless conversion
102103 from HDF5 data to JSON/UBJSON data
103104- demonstrate a set of flexible mechanisms to extend the capability of the
@@ -182,8 +183,8 @@ using the bellow mapping table
182183| ` "ManufacturerName" ` | ` "ManufacturerName": "s", ` | |
183184| ` "Model" ` | ` "Model": "s", ` | |
184185| ... | ... | |
185- | | ` }, ` | |
186- | ` data{} ` | ` "data": [ ` | * |
186+ | | ` }, ` | |
187+ | ` data{} ` | ` "data": [ ` | * |
187188| | ` { ` | |
188189| ` dataTimeSeries ` | ` "dataTimeSeries": [[<f>,...]], ` | * |
189190| ` time ` | ` "time": [<f>,...], ` | * |
@@ -203,16 +204,16 @@ using the bellow mapping table
203204| | ` } ` | |
204205| | ` }, ` | |
205206| | ` {...} ` | |
206- | | ` ], ` | |
207- | ` stim{} ` | ` "stim": [ ` | |
207+ | | ` ], ` | |
208+ | ` stim{} ` | ` "stim": [ ` | |
208209| | ` { ` | |
209210| ` name ` | ` "name": "s", ` | + |
210211| ` data ` | ` "data": [[<f>,...]], ` | + |
211212| ` dataLabels ` | ` "dataLabels": [["s",...]], ` | + |
212213| | ` }, ` | |
213214| | ` {...} ` | |
214- | | ` ], ` | |
215- | ` probe ` | ` "probe": { ` | * |
215+ | | ` ], ` | |
216+ | ` probe ` | ` "probe": { ` | * |
216217| ` wavelengths ` | ` "wavelengths": [<f>,...], ` | * |
217218| ` wavelengthsEmission ` | ` "wavelengthsEmission":[<f>,...], ` | |
218219| ` sourcePos2D ` | ` "sourcePos2D": [[<f>,...]], ` | * 1 |
@@ -232,8 +233,8 @@ using the bellow mapping table
232233| ` landmarkLabels ` | ` "landmarkLabels": ["s",...], ` | |
233234| ` coordinateSystem ` | ` "coordinateSystem": "s", ` | |
234235| ` coordinateSystemDescription ` | ` "coordinateSystemDescription":"s", ` | |
235- | | ` }, ` | |
236- | ` aux{} ` | ` "aux": [ ` | |
236+ | | ` }, ` | |
237+ | ` aux{} ` | ` "aux": [ ` | |
237238| | ` { ` | |
238239| ` name ` | ` "name": "s", ` | + |
239240| ` dataTimeSeries ` | ` "dataTimeSeries": [[<f>,...]], ` | + |
@@ -242,7 +243,7 @@ using the bellow mapping table
242243| ` timeOffset ` | ` "timeOffset": [<f>,...], ` | |
243244| | ` }, ` | |
244245| | ` {...} ` | |
245- | | ` ] ` | |
246+ | | ` ] ` | |
246247| | ` } ` | |
247248| | ` } ` , | |
248249| | ` {...} ` | |
@@ -271,9 +272,9 @@ length or longer to store the entire original string value.
271272The requirements for the dimensions of the 1-D and 2-D array subfields are specified
272273in the SNIRF specification.
273274
274- The order of the subfields in each element of the ` SNIRFData ` object is not required . However,
275+ The order of the subfields in each element of the ` SNIRFData ` object is storage dependent . However,
275276it is generally recommended that the ` formatVersion ` and ` metaDataTags ` appear before
276- other subfields.
277+ other subfields of the same level when the data are serialized .
277278
278279A reversed direction mapping, i.e. from JSNIRF to SNIRF, is not guaranteed to be lossless.
279280
@@ -306,7 +307,7 @@ Starting in SNIRF format v1.2, a new container, `measurementLists`, is introduce
306307the less disk-efficient ` measurementList ` container. Instead of storing array of structures (AoS),
307308` measurementLists ` stores structure of arrays (SoA), greatly reducing the storage overhead.
308309
309- Because JSNIRF's ` measurementList ` container is already required to use the array of structures (AoS)
310+ Because the ` measurementList ` container in JSNIRF is already required to use the array of structures (AoS)
310311by default, the ` measurementLists ` is simply an alias to ` measurementList ` in JSNIRF. One and
311312only one of the two containers should present in a single ` SNIRFData ` element.
312313
0 commit comments