jdata

Universal Scientific Data Parser for Python

A lightweight, fast parser for neuroimaging and scientific data formats. Load NIfTI, GIFTI, HDF5, SNIRF, JSON, binary JSON, CSV/TSV and more — from local files or REST APIs — into native Python structures.

pip install jdata

📁 15+ Formats

NIfTI, GIFTI, HDF5, SNIRF, JSON, BJData

📊 JData Encoding

_ArrayType_, _ArraySize_, _ArrayData_

🧠 NIfTI/JNIfTI

Load .nii/.nii.gz, save to .jnii/.bnii

🔬 SNIRF/JSNIRF

fNIRS HDF5 data, save to .jnirs/.bnirs

☁️ Cloud & REST API

Load from URLs with local caching

🌐 NeuroJSON Client

GUI, export, convert, 1500+ datasets

Scroll to explore

Supported Formats

One Library, Many Formats

Load and save scientific data in all major formats with automatic format detection.

NIfTI

.nii, .nii.gz, .img/.hdr

GIFTINEW

.gii, .jgii, .bgii

HDF5

.h5, .hdf5, .snirf, .nwb

JSON

.json, .jnii, .jnirs, .jgii

Binary JSON

.bjd, .bnii, .bgii, .ubj

Tabular

.csv, .tsv, .csv.gz

MATLAB

.mat, .pmat

MessagePack

.msgpack

import jdata as jd

# Auto-detect format from extension
nii = jd.loadjd('brain.nii.gz')      # NIfTI
gii = jd.loadjd('surface.gii')      # GIFTI (NEW!)
snirf = jd.loadjd('fnirs.snirf')     # SNIRF/HDF5
data = jd.loadjd('results.json')     # JSON
table = jd.loadjd('data.csv.gz')     # Compressed CSV
mat = jd.loadjd('matlabdata.mat')        # MATLAB .mat

Core Functions

Simple Load & Save

Use loadjd() and savejd() for any supported format. Compression is built-in!

import jdata as jd
import numpy as np

# Load from local file or URL
data = jd.loadjd('experiment.json')
data = jd.loadjd('https://example.com/data.json')

# Save with optional compression
results = {'volume': np.random.rand(64,64,64), 'name': 'test'}

jd.savejd(results, 'output.json')                    # Plain JSON
jd.savejd(results, 'output.jdb', compression='zlib') # Compressed binary
jd.savejd(results, 'output.bnii', compression='lzma') # LZMA compressed

JData Specification

Portable Data Encoding

Encode complex Python data (numpy arrays, complex numbers) into JSON-compatible structures that can be shared across languages like MATLAB, JavaScript, and more. 

import jdata as jd
import numpy as np

# Complex data with numpy arrays
data = {
    'matrix': np.arange(1, 13, dtype=np.float32).reshape(3, 4),
    'complex': 2 + 3j,
    'nan': float('nan')
}

# Encode to portable JData format
encoded = jd.encode(data)
# {'matrix': {'_ArrayType_': 'float32', '_ArraySize_': [3,4], '_ArrayData_': [...]}, ...}

# Decode back to native Python
restored = jd.decode(encoded)
# Original numpy arrays and complex numbers restored!

Neuroimaging

NIfTI & JNIfTI Support

Load NIfTI-1/2 files directly into Python dicts. Convert between NIfTI and JSON-based JNIfTI format.

import jdata as jd

# Load NIfTI file (returns JNIfTI structure)
nii = jd.loadnifti('brain_t1.nii.gz')

# Access header and data
header = nii['NIFTIHeader']
volume = nii['NIFTIData']        # numpy array
dims = header['Dim']             # [256, 256, 180]
voxel = header['VoxelSize']      # [1.0, 1.0, 1.0]

# Save as JSON-based JNIfTI (portable!)
jd.savejnifti(nii, 'brain.jnii')  # Text JSON
jd.savejnifti(nii, 'brain.bnii')  # Binary JSON

# Convert back to standard NIfTI
jd.savenifti(volume, 'output.nii.gz', header)

Surface Data NEW

GIFTI & JGIFTI Support

Load GIFTI surface files (.gii) for cortical meshes, labels, and functional data. Convert to portable JSON-based JGIFTI format (.jgii/.bgii) for web-friendly sharing. 

import jdata as jd

# Load GIFTI surface file
gii = jd.loadgifti('cortex.surf.gii')

# Access JGIFTI structure
header = gii['GIFTIHeader']           # Version, MetaData, LabelTable
data = gii['GIFTIData']               # MeshVertex3, MeshTri3

# Get vertices and faces
vertices = data['MeshVertex3']['Data']   # numpy array [N x 3]
faces = data['MeshTri3']['Data'] - 1    # [M x 3], convert to 0-based

# Access node properties (thickness, curvature, labels...)
props = data['MeshVertex3']['Properties']
thickness = props.get('Thickness')    # numpy array [N]

# Or use the JGifti class for easier access
from jdata.jgifti import JGifti
surf = JGifti('cortex.surf.gii')
nodes, faces = surf.node(), surf.face()
curv = surf['Curvature']              # Property access via []

# Save as JSON-based JGIFTI (portable, web-friendly!)
jd.savejgifti(gii, 'cortex.jgii')    # Text JSON
jd.savejgifti(gii, 'cortex.bgii')    # Binary JSON (smaller)

fNIRS Data

SNIRF & JSNIRF Support

Load HDF5-based SNIRF files for functional near-infrared spectroscopy. Convert to JSON-based JSNIRF format. 

import jdata as jd

# Load SNIRF file (HDF5-based fNIRS format)
snirf = jd.loadsnirf('experiment.snirf')

# Access SNIRF data structure
meta = snirf['nirs']['metaDataTags']   # SubjectID, MeasurementDate...
data = snirf['nirs']['data']            # dataTimeSeries, time
probe = snirf['nirs']['probe']          # sourcePos, detectorPos

# Access time series
timeseries = data['dataTimeSeries']     # numpy array [time x channels]
time = data['time']                     # time vector

# Save as JSON-based JSNIRF (portable, web-friendly)
jd.savejsnirf(snirf, 'output.jnirs')   # Text JSON
jd.savejsnirf(snirf, 'output.bnirs')   # Binary JSON

Data Queries

JSONPath Navigation

Query complex nested data structures using JSONPath expressions.

import jdata as jd

# Load complex nested data
data = jd.loadurl('https://neurojson.io:7777/openneuro/ds000001')

# Navigate with JSONPath
jd.jsonpath(data, '$.participant_id')      # Get field
jd.jsonpath(data, '$.sub-01.anat')          # Nested access
jd.jsonpath(data, '$..T1w')                  # Deep search
jd.jsonpath(data, '$.subjects[0:5]')         # Array slicing

# Find all data links in the dataset
links = jd.jsonpath(data, '$.._DataLink_')

# Download linked files with caching
jd.jdlink(links, regex='sub-01.*\\.nii')    # Filter & download

Cloud Data UPDATED

NeuroJSON.io Client

Browse, download, export, and convert 1500+ neuroimaging datasets from NeuroJSON.io. Features interactive GUI, dataset export to BIDS folders, and batch conversion tools. 

import jdata as jd

# Launch GUI with search, browse, export
jd.neuroj('gui')

# List & search datasets
jd.neuroj('list')                              # List all databases
jd.neuroj('list', 'openneuro')                 # List datasets in database
jd.neuroj('find', 'openneuro', '/ds00[1-5]/')  # Regex search

# Download & export to BIDS folder
ds = jd.neuroj('get', 'openneuro', 'ds000001')
jd.neuroj('export', 'openneuro', 'ds000001', exportpath='/data/bids')

# Convert local datasets to JSON (parallel processing)
jd.neuroj('convert', 'mydb', '*', input='/data/raw', output='/data/json', run=True, threads=8)

🖥️ GUI Features

Search panel with filters (age, gender, modality, task), database/dataset browser, JSON tree viewer, one-click export

⚡ Convert Features

Parallel processing, NIfTI/SNIRF/TSV support, SHA256 deduplication, dry-run mode, BIDS-compatible output

Get Started

Install pyjdata

Lightweight (~60KB) with minimal dependencies. Optional packages unlock additional formats.

Installation

# Install from PyPI
pip install jdata

# Optional dependencies for specific formats
pip install bjdata      # Binary JSON support
pip install h5py        # HDF5/SNIRF support
pip install scipy       # MATLAB .mat support
pip install lz4         # LZ4 compression

📖 Source Code

github.com/NeuroJSON/pyjdata

📦 PyPI Project

pypi.org/project/jdata

Created by Qianqian Fang • Part of the NeuroJSON Project • NIH U24-NS124027

Powered by Habitat