pyjdata

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.

📁 15+ File Formats

NIfTI, HDF5, SNIRF, JSON, BJData, CSV/TSV and more

🔄 Unified Interface

One function to load any supported format

📊 JData Encoding

_ArrayType_, _ArraySize_, _ArrayData_ annotations

☁️ Cloud & REST API

Load data directly from URLs with caching

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)

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

📖 Documentation

github.com/NeuroJSON/pyjdata

🔗 Related Projects

neurojson.org • JSONLab (MATLAB)

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