{"id":28503014,"url":"https://github.com/neurojson/jsnirfy","last_synced_at":"2025-07-05T12:31:46.313Z","repository":{"id":78325028,"uuid":"219867618","full_name":"NeuroJSON/jsnirfy","owner":"NeuroJSON","description":"JSNIRF Toolbox","archived":false,"fork":false,"pushed_at":"2025-04-18T01:56:30.000Z","size":92,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-04T12:21:07.005Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NeuroJSON.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":"LICENSE_Apache-2.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-11-05T23:06:34.000Z","updated_at":"2025-04-18T01:56:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"1f1a1d6a-cd2c-4674-a509-93a22be9b981","html_url":"https://github.com/NeuroJSON/jsnirfy","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeuroJSON%2Fjsnirfy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeuroJSON%2Fjsnirfy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeuroJSON%2Fjsnirfy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeuroJSON%2Fjsnirfy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NeuroJSON","download_url":"https://codeload.github.com/NeuroJSON/jsnirfy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeuroJSON%2Fjsnirfy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258746984,"owners_count":22751111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-08T16:38:49.335Z","updated_at":"2025-07-05T12:31:46.307Z","avatar_url":"https://github.com/NeuroJSON.png","language":"MATLAB","readme":"# JSNIRFY - A MATLAB/Octave toolbox for parsing SNIRF (HDF5) and JSNIRF (JSON) files\n\n* Copyright (C) 2019-2025  Qianqian Fang \u003cq.fang at neu.edu\u003e\n* License: GNU General Public License version 3 (GPL v3) or Apache License 2.0, see License*.txt\n* Version: 0.9 (code name: Amygdala - final)\n* Compatibility: MATLAB R2010b or newer, R2016b or newer to save SNIRF-1.1 compliant files, or Octave 5.0 and newer\n* URL: https://github.com/NeuroJSON/jsnirfy\n\n## Overview\n\nJSNIRF is a portable format for storage, interchange and processing data generated \nfrom functional near-infrared spectroscopy, or fNIRS - an emerging functional neuroimaging \ntechnique. Built upon the JData and SNIRF specifications, a JSNIRF file has both a \ntext-based interface using the JavaScript Object Notation (JSON) [RFC4627] format \nand a binary interface using the University Binary JSON (UBJSON, https://ubjson.org) derived \nBinary JData ([BJData](https://github.com/NeuroJSON/bjdata)) serialization format.\nIt contains a compatibility layer to provide a 1-to-1 mapping to the existing \nHDF5 based SNIRF files. A JSNIRF file can be directly parsed by most existing \nJSON and BJData parsers. Advanced features include optional hierarchical data \nstorage, grouping, compression, integration with heterogeneous scientific data \nenabled by JData data serialization framework.\n\nThis toolbox also provides a fast/complete reader/writer for the HDF5-based SNIRF\nfiles (along with any HDF5 data) via the EasyH5 toolbox \n(https://github.com/NeuroJSON/easyh5). The toolbox can read/write SNIRF v1.0 data\nfiles specified by the SNIRF specification https://github.com/fNIRS/snirf .\n\nThis toolbox is selectively dependent on the below toolboxes\n- To read/write SNIRF/HDF5 files, one must install the EasyH5 toolbox at \n  https://github.com/NeuroJSON/easyh5\n- To read/write SNIRF/HDF5 files in GNU Octave, one must install the oct-hdf5 using\n  `pkg install https://github.com/fangq/oct-hdf5/archive/refs/heads/main.zip`\n- To create/read/write JSNIRF files, one must install the JSONLab toolbox\n  https://github.com/NeuroJSON/jsonlab; this is supported on both MATLAB and Octave.\n- To read/write JSNIRF files with internal data compression, one must install \n  the JSONLab toolbox https://github.com/NeuroJSON/jsonlab as well as ZMat toolbox\n  https://github.com/NeuroJSON/zmat ; this is supported on both MATLAB and Octave.\n\n## Why JSNIRF?\n\nA SNIRF data file is basically an HDF5 file. HDF5 (Hierarchical Data Format version 5)\nis a general purpose file format for storing flexible binary data. However, it has\nthe below limitations:\n\n- it is binary, not human readable, you must use a parser to load the file\n  and understand the content\n- it requires a spacial library, although widely and freely available, to load\n  or save such file; dependeny to such library requires extra work for deployment\n- HDF5 is a very sophisticated format; writing your own parser is quite difficult\n- when storing a small dataset, an HDF5 file has an overhead in file size\n\nIn comparison, the JSNIRF data format is defined based on the JData specification.\nand supports both a text-based interface and a binary interface. The text form\nJSNIRF file is a plain JSON file, and has various advantages\n\n- JSNIRF is human readable, you can read the data using an editor\n- JSNIRF is very simple (because JSON format is very simple)\n- JSNIRF is lightweight, little overhead for storing small datasets\n- JSNIRF can be readily parsed by numerous free JSON parsers available\n- Programming your own specialized JSNIRF parser is very easy to write\n\nThe binary JSNIRF format uses a binary JSON format (BJData) which is also\n- quasi-human readable despite it is binary\n- free parsers available for [MATLAB](https://github.com/NeuroJSON/jsonlab),\n  [Python](https://pypi.org/project/bjdata/), [C++](https://github.com/NeuroJSON/json),\n  and [C](https://github.com/NeuroJSON/ubj)\n- easy to write your own parser because of the simplicity\n\n\n\n## SNIRF and JSNIRF format compatibility\n\nThe JSNIRF data structure is highly compatible with the SNIRF data structure.\nThis toolbox provides utilities convert from one form to the other losslessly.\n\nThere are only two minor differences:\n* A JSNIRF data container renames the SNIRF `/nirs` root object as `SNIRFData`.\n  If multiple measurement datasets are provided in the SNIRF data in the forms of\n  `/nirs1`, `/nirs2` ..., or `/nirs/data1`. `/nirs/data2` ..., JSNIRF merges these\n  data objects into struct/cell arrays, and removes the group indices from the \n  group names. These grouped objects are stored as an JSON/BJData array object\n  '[]' when saving to disk.\n* The `/formatVersion` object in the SNIRF data are moved from the root level \n  to a subfield of `SNIRFData`, this allows the JSNIRF data files to be easily\n  mixed/integrated with other JSON-based data containers, such as `SNIRFData`\n  defined in other JData based data formats.\n\nTo further illustrate the above data reorganization steps, please find below\nan example\n\nAn original SNIRF/HDF5 data outline\n```\n/formatVersion\n/nirs1/\n   /metaDataTags\n   /data1\n   /data2\n   /aux1\n   /aux2\n   /probe\n   ...\n/nirs2/\n   /metaDataTags\n   /data\n   /aux1\n   /aux2\n   /aux3\n   /probe\n   ...\n```\nis converted to the below JSON/JSNIRF data structure\n```\n{\n  \"SNIRFData\": [\n      {\n          \"formatVersion\": '1.0',\n          \"metaDataTags\":{\n\t      \"SubjectID\": ...\n\t  },\n\t  \"data\": [\n\t     {..for data1 ...},\n\t     {..for data2 ...}\n\t  ],\n\t  \"aux\": [\n\t     {..for aux1 ...},\n\t     {..for aux2 ...}\n\t  ],\n\t  \"probe\": ...\n      },\n      {\n          \"formatVersion\": '1.0',\n          \"metaDataTags\":{\n\t      \"SubjectID\": ...\n\t  },\n\t  \"data\": {...},\n\t  \"aux\": [\n\t     {..for aux1 ...},\n\t     {..for aux2 ...},\n\t     {..for aux3 ...}\n\t  ],\n\t  \"probe\": ...\n      },\n      ...\n  ]\n}\n```\n\n## Installation\n\nThe JSNIRFY toolbox can be installed using a single command\n```\n  addpath('/path/to/jsnirf');\n```\nwhere the `/path/to/jsnirf` should be replaced by the unzipped folder\nof the toolbox (i.e. the folder containing `savejsnirf.m/loadjsnirf.m`).\n\nIn order for this toolbox to work, one must install the below dependencies\n- the `saveh5/loadh5` functions are provided by the EasyH5 toolbox at \n  https://github.com/NeuroJSON/easyh5\n- the `savejson` and `savebj` functions are provided by the JSONLab \n  toolbox at https://github.com/NeuroJSON/jsonlab \n- if data compression is specified by `'compression','zlib'` param/value \n  pairs, ZMat toolbox will be needed, https://github.com/NeuroJSON/zmat\n\n\n## Usage\n\n### `snirfcreate/jsnirfcreate` - Create an empty SNIRF or JSNIRF data container (structure)\nExample:\n```\n  data=snirfcreate;              % create an empty SNIRF data structure\n  data=snirfcreate('data',realdata,'aux',realauxdata); % setting the default values to user data\n  data=jsnirfcreate('format','snirf');                 % specify 'snirf' or 'jsnirf' using 'format' option\n  jsn=snirfdecode(loadh5('mydata.snirf', 'stringarray', 1)); % load raw HDF5 data and convert to a JSNIRF struct\n```\n### `loadsnirf/loadjsnirf` - Loading SNIRF/JSNIRF files as in-memory MATLAB data structures\nExample:\n```\n  data=loadsnirf('mydata.snirf');     % load an HDF5 SNIRF data file, same as loadh5+regrouph5\n  jdata=loadjsnirf('mydata.bnirs');   % load a binary JSON/JSNIRF data file\n```\n### `savesnirf/savejsnirf` - Saving in-memory MATLAB data structure into SNIRF/HDF5 or JSNIRF/JSON files\nExample:\n```\n  data=snirfcreate;\n  data.nirs.data.dataTimeSeries=rand(100,5);\n  data.nirs.metaDataTags.SubjectID='subj1';\n  data.nirs.metaDataTags.MeasurementDate=date;\n  data.nirs.metaDataTags.MeasurementTime=datestr(now,'HH:MM:SS');\n  savesnirf(data,'test.snirf');\n  savejsnirf(data,'test.jnirs');\n```\n\n## Contribute to JSNIRF\n\nPlease submit your bug reports, feature requests and questions to the Github Issues page at\n\nhttps://github.com/NeuroJSON/jsnirfy/issues\n\nPlease feel free to fork our software, making changes, and submit your revision back\nto us via \"Pull Requests\". JSNIRFY toolbox is open-source and we welcome your contributions!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneurojson%2Fjsnirfy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneurojson%2Fjsnirfy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneurojson%2Fjsnirfy/lists"}