brukerapi-python

A Python package providing I/O interface for Bruker data sets.

tl;dr

Install using pip:

pip install brukerapi

Load any data set:

from brukerapi.dataset import Dataset
dataset = Dataset('{path}/2dseq')    # also supports fid, fid_proc.64, traj, and rawdata.jobN
dataset.data                         # access data array
dataset.get_value('VisuCoreSize')    # get a parameter value

Raw acquisitions and k-space

Raw Bruker acquisitions have format-dependent historical .data semantics. For explicit code, use the representation that matches the task:

fid = Dataset('{path}/fid')
fid.raw                 # decoded (sample, shot, receiver) acquisitions
fid.kspace              # ordered FID k-space

job = Dataset('{path}/rawdata.job0')
job.raw                 # decoded (sample, shot, receiver) acquisitions
job.kspace              # ordered Cartesian PV360 k-space, when metadata proves the layout
job.to_kspace(bart=True)  # optional 16-axis BART layout

Dataset.data remains backward compatible: FIDs expose their historical ordered k-space view, whereas PV360 rawdata.jobN exposes its historical decoded stream and emits a FutureWarning. .kspace is not a reconstruction API; EPI and non-Cartesian jobs require acquisition-specific handling.

Frame-group metadata

For 2dseq data, frame_group_values aligns values named by VisuGroupDepVals to the corresponding array axes. Returned arrays use singleton dimensions where needed and therefore broadcast directly against dataset.data:

echoes = dataset.frame_group_values['VisuAcqEchoTime']
b_matrices = dataset.frame_group_values['VisuAcqDiffusionBMatrix']

metadata provides normalized, grouped access to parsed subject, study, series, equipment, and acquisition fields:

dataset.metadata['visu_study']['uid']
dataset.metadata['visu_acq']['sequence_name']
dataset.metadata['subject']['id']

Load an entire study:

from brukerapi.folders import Study
study = Study('{path_to_study_folder}')
dataset = study.get_dataset(exp_id='1', proc_id='1')

dataset.data                         # Study loads datasets by default

Load a parametric file:

from brukerapi.jcampdx import JCAMPDX

parameters = JCAMPDX('path_to_scan/method')

TR = parameters.params["PVM_RepetitionTime"].value
TR = parameters.get_value("PVM_RepetitionTime")

Features

• I/O interface for fid data sets

• I/O interface for 2dseq data sets

• I/O interface for rawdata data sets

• Random access for fid and 2dseq data sets

• Split operation implemented over 2dseq data sets

• Filter operation implemented over Bruker folders (allowing you to work with a subset of your study only)

• ParaVision 5.1, 6.0.1, 7.0.0, and 360 metadata and binary-layout support

• Metadata-based fallback inference for custom Cartesian, EPI, radial/UTE, spiral, ZTE, CSI, and spectroscopy sequences

Examples

• How to read a Bruker fid, 2dseq, or rawdata file

• How to split slice packages of a 2dseq data set

• How to split FG_ECHO of a 2dseq data set

• How to split FG_ISA of a 2dseq data set

Documentation

Online documentation of the API is available at Read The Docs.

Install

Using pip:

pip install brukerapi

From source:

git clone https://github.com/isi-nmr/brukerapi-python.git
cd brukerapi-python
python -m pip install -e .[dev]

Testing

To ensure reliability, every commit to this repository is tested against the following, publicly available data sets:

• BrukerAPI test data set (Bruker ParaVision v5.1)

• BrukerAPI test data set (Bruker ParaVision v6.0.1)

• BrukerAPI test data set for ParaVision v7.0.0 (Zenodo DOI collection 10.5281/zenodo.4522220)

• PV360 standard data

The corpus download is opt-in for local runs:

python -m pytest test --download_test_data

Without that flag, pytest uses any corpus already present under test/test_data and skips unavailable collections.

File format reference

Bruker ParaVision Raw Data Format is the source of truth for file-format parsing, binary layouts, dataset typing, and metadata-driven acquisition scheme inference in this project.

Compatibility

Tested releases are ParaVision 5.1, 6.0.1, 7.0.0, and PV360 3.x. Supported primary binaries are fid, fid_proc.64, 2dseq, traj, rawdata.jobN, and named jobs declared by ACQ_jobs (for example, rawdata.Navigator or rawdata.echoNavigator). Known fid.spiral, fid.navFid, and fid.orig files are exposed as auxiliary subdatasets of their parent fid; they are not accepted as standalone primary datasets. TopSpin/NMR ser is intentionally unsupported.

Known pulse-program names use dedicated layouts. For custom sequences the reader also infers common acquisition families from metadata; callers can pass scheme_id= when inference is ambiguous. Rawdata is returned as complex ordered samples, not as reconstructed k-space. See the compatibility page in the documentation for behavior and current reconstruction limitations.