Skip to content

JSNIRF Toolbox - A portable MATLAB toolbox for parsing SNIRF (HDF5) and JSNIRF (JSON) files

Latest
Latest
Compare
Choose a tag to compare
@fangq fangq released this 19 Sep 23:30
· 19 commits to master since this release
v0.4
808d45e

ChanageLog (v0.4)

2019-09-19 [61def95] adding issues link in README
2019-09-19 [b4d357c] polishing snirf toolbox, handling root object names
2019-09-19 [53966d4] pass variable name from savesnirf to saveh5
2019-09-19 [4744840] jsnirf toolbox v0.4
2019-09-19 [a9ffd3b] initial version of jsnirf toolbox
2019-09-17 [3559dcb] a compact SNIRF MATLAB parser and converter to JSNIRF JSON file

Overview

JSNIRF is a portable format for storage, interchange and processing data generated
from functional near-infrared spectroscopy, or fNIRS - an emerging functional neuroimaging
technique. Built upon the JData and SNIRF specifications, a JSNIRF file has both a
text-based interface using the JavaScript Object Notation (JSON) [RFC4627] format
and a binary interface using the Universal Binary JSON (UBJSON) serialization format.
It contains a compatibility layer to provide a 1-to-1 mapping to the existing
HDF5 based SNIRF files. A JSNIRF file can be directly parsed by most existing
JSON and UBJSON parsers. Advanced features include optional hierarchical data
storage, grouping, compression, integration with heterogeneous scientific data
enabled by JData data serialization framework.

This toolbox also provides a fast/complete reader/writer for the HDF5-based SNIRF
files (along with any HDF5 data) via the EazyH5 toolbox
(http://github.com/fangq/eazyh5). The toolbox can read/write SNIRF v1.0 data
files specified by the SNIRF specification http://github.com/fNIRS/snirf .

This toolbox is selectively dependent on the below toolboxes

SNIRF and JSNIRF format compatibility

The JSNIRF data structure is highly compatible with the SNIRF data structure.
This toolbox provides utilities convert from one form to the other losslessly.

There are only two minor differences:

  • A JSNIRF data container renames the SNIRF /nirs root object as SNITFData.
    If multiple measurement datasets are provided in the SNIRF data in the forms of
    /nirs1, /nirs2 ..., or /nirs/data1. /nirs/data2 ..., JSNIRF merges these
    data objects into struct/cell arrays, and removes the group indices from the
    group names. These grouped objects are stored as an JSON/UBJSON array object
    '[]' when saving to disk.
  • The /formatVersion object in the SNIRF data are moved from the root level
    to a subfield of SNIRFData, this allows the JSNIRF data files to be easily
    mixed/integrated with other JSON-based data containers, such as NIFTIData
    defined in other JData based data formats.

To further illustrate the above data reorganization steps, please find below
an example

An original SNIRF/HDF5 data outline

/formatVersion
/nirs1/
   /metaDataTags
   /data1
   /data2
   /aux1
   /aux2
   /probe
   ...
/nirs2/
   /metaDataTags
   /data
   /aux1
   /aux2
   /aux3
   /probe
   ...

is converted to the below JSON/JSNIRF data structure

{
  "SNIRFData": [
      {
          "formatVersion": '1.0',
          "metaDataTags":{
	      "SubjectID": ...
	  },
	  "data": [
	     {..for data1 ...},
	     {..for data2 ...}
	  ],
	  "aux": [
	     {..for aux1 ...},
	     {..for aux2 ...}
	  ],
	  "probe": ...
      },
      {
          "formatVersion": '1.0',
          "metaDataTags":{
	      "SubjectID": ...
	  },
	  "data": {...},
	  "aux": [
	     {..for aux1 ...},
	     {..for aux2 ...},
	     {..for aux3 ...}
	  ],
	  "probe": ...
      },
      ...
  ]
}

Installation

The JSNIRF toolbox can be installed using a single command

    addpath('/path/to/jsnirf');

where the /path/to/jsnirf should be replaced by the unzipped folder
of the toolbox (i.e. the folder containing savejnifti.m/loadjnifti.m).

In order for this toolbox to work, one must install the below dependencies

Usage

snirfcreate/jsnirfcreate - Create an empty SNIRF or JSNIRF data container (structure)

Example:

  data=snirfcreate;              % create an empty SNIRF data structure
  data=snirfcreate('data',realdata,'aux',realauxdata); % setting the default values to user data
  data=jsnirfcreate('format','snirf');                 % specify 'snirf' or 'jsnirf' using 'format' option
  jsn=snirfdecode(loadh5('mydata.snirf'));             % load raw HDF5 data and convert to a JSNIRF struct

loadsnirf/loadjsnirf - Loading SNIRF/JSNIRF files as in-memory MATLAB data structures

Example:

  data=loadsnirf('mydata.snirf');     % load an HDF5 SNIRF data file, same as loadh5+regrouph5
  jdata=loadjsnirf('mydata.bnirs');   % load a binary JSON/JSNIRF data file

savesnirf/savejsnirf - Saving in-memory MATLAB data structure into SNIRF/HDF5 or JSNIRF/JSON files

Example:

  data=snirfcreate;
  data.nirs.data.dataTimeSeries=rand(100,5);
  data.nirs.metaDataTags.SubjectID='subj1';
  data.nirs.metaDataTags.MeasurementDate=date;
  data.nirs.metaDataTags.MeasurementTime=datestr(now,'HH:MM:SS');
  savesnirf(data,'test.snirf');
  savejsnirf(data,'test.jnirs');

Contribute to JSNIRF

Please submit your bug reports, feature requests and questions to the Github Issues page at

https://github.com/fangq/jsnirf/issues

Please feel free to fork our software, making changes, and submit your revision back
to us via "Pull Requests". JSNIRF toolbox is open-source and we welcome your contributions!

Assets 3
Loading