Dataset

Construction and load stages

Dataset accepts a supported binary path or an experiment/processing directory containing fid or 2dseq. Loading is eager by default. Use LOAD_STAGES for parameters-only or properties-only work, and mmap=True for random access.

Important options include scheme_id for acquisition-family overrides, scale for 2dseq pixel scaling, and combine_complex for complex 2dseq frame assembly.

Reports exclude internal dataset typing fields and preserve property order. Malformed query expressions raise FilterEvalFalse instead of leaking raw eval exceptions.

Raw acquisition and k-space views

Use the explicit raw-data views for FIDs and supported PV360 jobs:

fid.raw                    # (sample, shot, receiver), acquisition order
fid.kspace                 # ordered FID k-space
rawdata.raw                # (sample, shot, receiver), acquisition order
rawdata.kspace             # validated Cartesian PV360 k-space
rawdata.to_kspace(bart=True)  # BART's 16-axis layout

Dataset.data is retained for compatibility. It is ordered k-space for FIDs, but the historical decoded job stream for PV360 rawdata.jobN files. Accessing the latter emits FutureWarning; use raw or kspace for new code. EPI and non-Cartesian PV360 jobs are intentionally not reconstructed by kspace.

Metadata views

Dataset.frame_group_values aligns values declared by VisuGroupDepVals to the corresponding 2dseq axes, with singleton axes for broadcasting. It supports, for example, per-echo echo times and per-diffusion B matrices:

echo_times = dataset.frame_group_values["VisuAcqEchoTime"]
b_matrices = dataset.frame_group_values["VisuAcqDiffusionBMatrix"]

Dataset.metadata provides normalized grouped access to parsed Visu and SUBJECT_* parameters, including visu_subject, visu_study, visu_series, visu_equipment, visu_acq, and subject.

dataset.metadata["visu_study"]["uid"]
dataset.metadata["visu_acq"]["sequence_name"]
dataset.metadata["subject"]["id"]
class brukerapi.dataset.Dataset(path, **state)

Data set is created using one binary file {fid, 2dseq, rawdata, …} and several JCAMP-DX files (method, acqp, visu_pars,…). The JCAMP-DX files necessary for a creation of a data set are denoted as essential. Each of the binary data files (fid, 2dseq,…) has slightly different data layout, i.e. the . The data in the binary files is stored Since the individual types of b some features We distinguish By he name of the binary file we determine the type of data set.

Main components of a data set:

  • parameters:

Meta data essential for construction of schema and manipulation with the binary data file.

  • properties

Derived from parameters.

An object encapsulating all functionality dependent on metadata. It provides method to reshape data.

  • data:

    • numpy.ndarray

Array containing the data read from any of the supported binary files.

Example:

from bruker.dataset import Dataset

dataset = Dataset("path/2dseq")
__init__(path, **state)

Constructor of Dataset

Dataset can be constructed either by passing a path to one of the SUPPORTED binary files, or to a directory containing it. It is possible, to create an empty object using the load switch.

Parameters:

path – str path to dataset

Raise:
UnsupportedDatasetType:

In case Dataset.type is not in SUPPORTED

Raise:
IncompleteDataset:

If any of the JCAMP-DX files, necessary to create a Dataset instance is missing

static is_supported_path(path, dataset_types=None)

Return whether a filename denotes a supported primary dataset binary.

__str__()

String representation is a path to the data set.

__call__(**kwargs)

Call self as a function.

load()

Load parameters, properties, schema and data. In case, there is a traj file related to a fid file, traj is loaded as well.

unload()

Unload parameters, properties, schema and data. In case, there is a traj file related to a fid file, traj is unloaded as well.

load_parameters()

Load all parameters essential for reading of given dataset type. For instance, type fid data set loads acqp and method file, from parent directory in which the fid file is contained.

add_parameter_file(file)

Load additional jcamp-dx file and add it to Dataset parameter space. It is later available via getters, or using the dot notation. :param file_type: JCAMP-DX file to add to the data set. Must be located in the same folder, or the first proc subfolder.

Example:

from bruker.dataset import Dataset

dataset = Dataset(".../2dseq")
dataset.add_parameter_file("method")
dataset["PVM_DwDir"].value
load_properties()

Load properties from two default configuration files. First configuration file contains core properties - properties essential for data loading, second contains custom properties - to provide more information about given data set, such as the date of measurement, the echo time, etc.

Some properties depend on values of parameters from JCAMP-DX files which are not essential for creating the dataset. For instance, the date property of the fid dataset type is dependent on the AdjStatePerScan. Such JCAMP-DX file can be added using the add_parameter_file function, then the load_properties function can be called to reevaluate values of properties, so that the properties dependent on parameters stored in non-essential JCAMP-DX files are loaded.

Example:

from bruker.dataset import Dataset

dataset = Dataset(".../fid")
dataset.add_parameter_file("AdjStatePerScan")
dataset.load_properties()
dataset.date
property rawdata_job_settings

The §13.1 settings record paired with this rawdata job, if present.

property rawdata_job_discarded

Whether §13.1 says this job’s data is intentionally not written.

property rawdata_stored_scans

Number of scans physically written for this rawdata job (spec 3.3).

property rawdata_channels

Number of receivers recorded for this job (spec 3.3).

load_schema()

Load the schema for given data set.

load_data()

Load the data file. The data is first read from the binary file to a data vector. Then the data vector is deserialized into a data array. The process of deserialization is different for each data set type and is implemented in the individual subclasses of the brukerapi.schemas.Schema, i.e. brukerapi.schemas.SchemaFid, brukerapi.schemas.Schema2dseq, brukerapi.schemas.SchemaRawdata.

If the object was created with random_access=True, the data is not read, instead it can be accessed using sub-arrays.

called in the class constructor.

unload_data()

Remove the data array from the data set.

write(path, **kwargs)

Write the Dataset instance to the disk. This consists of writing the binary data file {fid, rawdata, 2dseq, …} and respective JCAMP-DX files {method, acqp, visu_pars, reco}.

Parameters:

  • path – str Path to one of the supported data set types.

  • kwargs

Returns:

report(path=None, props=None, verbose=None, format_=None)

Save properties to JSON, or YAML file.

if path is None then save report in-place as path / self.id + ‘.’ + format_ if path is a path to a folder then save report to path / self.id + ‘.’ + format_ if path is a json, or yml file save report to path

Parameters:

  • path – str path to a resulting report file

  • props – list names of properties to be exported

  • format – str json or yml, used when the file name is derived

to_json(path=None, props=None)

Save properties to JSON file.

Parameters:

  • path – str path to a resulting report file

  • names – list names of properties to be exported

to_yaml(path=None, props=None)

Save properties to YAML file.

Parameters:

  • path – str path to a resulting report file

  • names – list names of properties to be exported

to_dict(props=None)

Export properties as dict.

Parameters:

  • path – str path to a resulting report file

  • names – list names of properties to be exported

property data

Legacy primary data array.

FID datasets use this view for reordered k-space, while PV-360 rawdata.jobN datasets expose their decoded acquisition stream. Prefer raw or kspace when the representation matters.

Type:

numpy.ndarray

slice_packages_index()

[(first_frame, n_slices)] per slice package – spec 7.10.

Packages may have different slice counts, so each package carries its own count. PV5.1 writes no slice-package parameters at all; there, frames sharing one orientation are grouped instead.

affine_of_package(package=0)

4x4 voxel-index -> patient-coordinate transform of one slice package.

Built straight from the parameters that define the geometry (spec 7.2, 7.10, 12): VisuCoreOrientation maps patient to image coordinates (i = M.p), so its transpose maps image to patient, and VisuCorePosition is the centre of the first voxel transferred, which is the translation.

The result is in the Visu/DICOM patient frame (R->L, A->P, F->H). A NIfTI writer converts with np.diag([-1, -1, 1, 1]) @ affine; the ParaVision user-interface frame needs both ends transformed, per spec 12.

property affine

4x4 voxel-index -> patient-coordinate transform of the first slice package.

Raise:
UnsupportedDatasetType:

if the frames are not purely spatial, or

carry no geometry at all

get_slice_packages()

Return one in-memory 2dseq dataset per slice package.

Package datasets carry their package-specific visu_pars, geometry properties, and data array. Unequal package depths are therefore represented without padding. No files are written unless the caller explicitly writes the returned datasets.

to_kspace(*, bart=False)

Return a supported raw acquisition in k-space order.

FIDs are already decoded into k-space; validated Cartesian ParaVision 360 rawdata.jobN streams are reshaped on demand. Set bart=True for BART’s 16-axis array layout. It is intentionally not a reconstruction API: EPI and non-Cartesian raw data require acquisition-specific handling.

property raw

Decoded acquisition stream as (sample, shot, receiver).

The stream preserves on-disk acquisition order. Use kspace when phase lines, objects, and other supported acquisition dimensions must be put into k-space order.

property kspace

Derived k-space representation of a raw acquisition.

Unlike data, this may reshape PV-360 rawdata.jobN streams using validated acquisition metadata. Use to_kspace() for the optional BART layout.

property frame_group_values

Metadata values reshaped onto their declared frame-group axes.

Keys are Visu parameter names without angle brackets. The leading axes of each returned array align with data; trailing axes retain parameter payload, for example the nine B-matrix elements.

property metadata

Grouped Visu and SUBJECT metadata with snake-case field names.

The groups are the ones the specification defines (7.1, 7.5-7.9, 9). Several of them cannot be recognised from a name prefix – no parameter is called VisuEquipment*, and the 7.1 administration group is spelled VisuUid/VisuCreator/… – so those members are listed by name.

property slice_packages

In-memory package-specific 2dseq datasets.

property traj

Trajectory array loaded from a traj file

Type:

numpy.ndarray

__weakref__

list of weak references to the object

property fid_companions

Auxiliary fid.<subtype> datasets keyed by subtype.

property dim

number of dimensions of the data array

Type:

int

property shape

shape of data array

Type:

tuple