Compatibility

Tested ParaVision releases

The committed and CI-managed corpora cover ParaVision 5.1, 6.0.1, 7.0.0, and PV360 3.x. PV360 1.1 recipes are supported but the repository currently has no PV360 1.1 binary corpus.

Dataset types

Supported primary binary names are:

  • fid

  • fid_proc.64

  • 2dseq

  • traj

  • rawdata.jobN

  • rawdata.Navigator

Unknown suffixes such as fid.npz and 2dseq.json are rejected instead of being interpreted as scanner data. fid.spiral, fid.navFid, and fid.orig are auxiliary companions and are available through dataset.fid_companions after loading the parent fid. TopSpin/NMR ser is intentionally not supported.

Acquisition schemes

Dedicated layouts exist for common Cartesian 2D/3D, field-map, RARE, EPI, diffusion EPI, radial/UTE, spiral, ZTE, spectroscopy, and CSI families. Known pulse-program names are matched first. Custom names then use metadata such as ACQ_dim, ACQ_dim_desc, ACQ_size, PVM_EncMatrix, NPro, and trajectory parameters. If a custom sequence remains ambiguous, pass a supported scheme_id explicitly:

dataset = Dataset("path/to/fid", scheme_id="RADIAL")

Data contract and limitations

  • FID data is returned as ordered raw k-space. AQ_mod=qf remains real; quadrature modes are assembled as complex data.

  • RARE/EPI phase-line ordering and EPI odd-line mirroring are applied. The reader uses ACQ_scan_size and the selected reconstruction’s RECO_inp_order when available; pulse-program scheme inference is the fallback for a FID without a reconstruction. The default reconstruction is the conventional first one, and reco_path= selects a different reco file. A disagreement between explicit metadata and the fallback inference emits RuntimeWarning. Ramp-sampling regridding and RECO_qopts corrections are not full reconstruction steps and remain the caller’s responsibility.

  • Rawdata jobs are returned as complex ordered samples in their stored job layout through data. Prefer raw for the normalized (sample, shot, receiver) acquisition stream and kspace for validated Cartesian PV360 layout conversion. STORE_discard jobs are omitted from folder discovery because no binary exists. When both records are present, ACQ_ScanPipeJobSettings.nStoredScans determines the stored shape and is checked against ACQ_jobs; the per-job receiver selection is also read.

  • 2dseq values are scaled as stored * slope + offset. Visu slopes/offsets take precedence, with RECO values as fallback.

  • PV7/PV360 2dseq geometry uses the version-independent Visu geometry fields. Reversed disk slice order is normalized on read.

  • COMPLEX_IMAGE/FG_COMPLEX reconstructions are returned as complex arrays by default. Use combine_complex=False to retain the real frame axis.

  • RECO_transposition records what the reconstruction already did and is not re-applied. Per-frame VisuCoreTransposition describes how a frame is stored, so a frame whose two exchanged dimensions differ in length is read in its stored shape and swapped back on read, and restored on write. FID ACQ_obj_order is normalized on read; the axis it orders is labelled object, because NI counts acquisition objects (slices x echoes x movie frames), not slices.

  • d3proc is an optional compatibility source for legacy/minimal 2dseq word type and image-size metadata after Visu and RECO metadata have been tried.

  • Dataset.metadata groups the Visu parameters the way the format defines them – administration, subject, study, series, equipment and acquisition – and the SUBJECT_* parameters of the study file, which subject in add_parameters= loads.

  • Version-dependent behaviour is selected on a parsed pv_version (5.1, 6.0.1, 7.0.0, 360.3.7, …) rather than on an exact version string, so an unlisted point release is not silently unsupported.

  • Dataset.affine is a voxel-index to patient-coordinate transform derived from VisuCorePosition/VisuCoreOrientation: index (0, 0, 0) maps onto the centre of the first voxel transferred, and the slice column carries the measured direction and spacing between slice centres. It is expressed in the Visu/DICOM patient frame (R->L, A->P, F->H); a NIfTI writer converts with np.diag([-1, -1, 1, 1]) @ affine, and the ParaVision user-interface frame needs both ends transformed. Frames that are not purely spatial (spectroscopy, CSI) have no image geometry and raise UnsupportedDatasetType rather than returning an identity matrix. A dataset with several slice packages cannot be described by one affine; it warns, and affine_of_package(i) or slice_packages gives the per-package transform. If optional slice-package metadata is absent (notably in PV5.1), contiguous frames with a common orientation are treated as one package. Consequently two adjacent inferred packages with the same orientation cannot be distinguished.