jdata

Universal Scientific Data Parser for Python

A lightweight, fast parser for neuroimaging and scientific data formats. Load NIfTI, 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, HDF5, SNIRF, JSON, BJData, CSV/TSV

📊 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 GUI

Browse 1500+ datasets interactively

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

HDF5

.h5, .hdf5, .snirf, .nwb

JSON

.json, .jnii, .jnirs

Binary JSON

.bjd, .bnii, .ubj, .msgpack

Tabular

.csv, .tsv, .csv.gz

MATLAB

.mat, .pmat

import jdata as jd

# Auto-detect format from extension
nii = jd.load('brain.nii.gz')      # NIfTI
snirf = jd.load('fnirs.snirf')     # SNIRF/HDF5
data = jd.load('results.json')     # JSON
table = jd.load('data.csv.gz')     # Compressed CSV
mat = jd.load('legacy.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)

fNIRS Data

SNIRF & JSNIRF Support

Load HDF5-based SNIRF files for functional near-infrared spectroscopy. Convert to JSON-based JSNIRF format. Access metaDataTags, data, stim, probe, and aux fields. 

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, measurementList
probe = snirf['nirs']['probe']          # sourcePos, detectorPos, wavelengths
stim = snirf['nirs']['stim']            # stimulus data
aux = snirf['nirs']['aux']              # auxiliary channels

# Access time series and measurement list
timeseries = data['dataTimeSeries']     # numpy array [time x channels]
time = data['time']                     # time vector
ml = data['measurementList']           # source/detector/wavelength indices

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

# Convert back to HDF5 SNIRF
jd.savesnirf(snirf, 'output.snirf')

# Create new SNIRF structure from scratch
newsnirf = jd.snirfcreate(data=mydata, aux=myaux)

Data Queries

JSONPath Navigation

Query complex nested data structures using JSONPath expressions. Find data anywhere in your hierarchy!

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

NeuroJSON.io Client

Browse and download 1500+ neuroimaging datasets from NeuroJSON.io directly in Python!

import jdata as jd

# Launch interactive GUI browser
jd.neuroj('gui')

# Or use command-line interface
jd.neuroj('list')                         # List all databases
jd.neuroj('list', 'openneuro')            # List datasets
jd.neuroj('get', 'openneuro', 'ds000001') # Download dataset

# Search with regex patterns
jd.neuroj('find', '/abide/')              # Find ABIDE databases
jd.neuroj('find', 'openneuro', '/00[1-5]$/')  # Filter datasets

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