Skip to content

v0.3.0

Choose a tag to compare

View all tags
@headmeister headmeister released this 23 Jul 17:40
· 141 commits to master since this release
v0.3.0
bbe7645
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's Changed

Full Changelog: v0.2.6...v0.3.0

brukerapi 0.3.0 — Breaking changes

Version 0.3.0 substantially improves support for ParaVision 5.1, 6.0.1, 7,
and PV360 data. It also corrects several long-standing parsing, layout, and
serialization defects. Some corrections change public names, accepted inputs,
array layouts, or numeric results.

Migration checklist

  • Replace UnsuportedDatasetType with UnsupportedDatasetType.
  • Replace DatasetTypeMissmatch with DatasetTypeMismatch.
  • Replace the FID property acq_lenght with acq_length.
  • Replace SchemaRawdata.seralize(...) with
    SchemaRawdata.serialize(...).
  • Stop constructing ser datasets; TopSpin/NMR ser is not supported.
  • If raw FG_COMPLEX frames are required, construct 2dseq datasets with
    combine_complex=False.
  • Remove any downstream slice reversal, phase-line reordering, or 2dseq
    scaling workarounds that compensated for the old behavior.
  • Review code that catches KeyError from missing Folder attributes; these
    misses now correctly raise AttributeError.
  • Review consumers of Dataset.to_dict(): internal type and subtype keys
    are no longer included.

Renamed and removed API

Corrected exception names

The misspelled exception classes were renamed without compatibility aliases:

Before 0.3.0
UnsuportedDatasetType UnsupportedDatasetType
DatasetTypeMissmatch DatasetTypeMismatch

Imports and exception handlers using the old names must be updated.

Corrected FID property name

The public/configured property acq_lenght is now acq_length. This affects
attribute access, custom property recipes, reports, and saved reference data.

Removed ser support

The incomplete ser implementation, including SchemaSer and the
DEFAULT_STATES["ser"] entry, was removed. Attempting to construct a ser
dataset now raises UnsupportedDatasetType instead of failing later with an
internal exception.

Removed misspelled serialization alias

The unused SchemaRawdata.seralize alias was removed. Use
SchemaRawdata.serialize.

JCAMP-DX helper signatures

The serialization helpers now require the JCAMP-DX version:

serialize_value(value, version)
serialize_list(value, version)
serialize_nested_list(values, version)
serialize_ndarray(value, version)

Direct positional construction of GenericParameter and DataParameter must
use the corrected order:

(key_str, size_str, val_str, version)

Dataset discovery and validation

Dataset suffixes are now checked against a supported-subtype allow-list.
Sidecars such as fid.npz, 2dseq.json, and arbitrary rawdata.* files are
rejected instead of being misidentified as scanner data.

The auxiliary files fid.spiral, fid.navFid, and fid.orig are loaded as
FID companion subdatasets and exposed through:

dataset.fid_companions

Folder discovery likewise ignores unsupported rawdata.<suffix> sidecars.
Code that relied on these files appearing in the dataset tree will observe a
different inventory.

Array dtype, shape, and ordering

Complex 2dseq images

COMPLEX_IMAGE/FG_COMPLEX reconstructions are now returned as complex arrays
by default. The former real-valued FG_COMPLEX frame axis is removed during
assembly.

To retain the raw frame representation:

dataset = Dataset(path, combine_complex=False)

Real-only FID acquisition

For AQ_mod=qf, FID data remains real. It is no longer incorrectly
deinterleaved as real/imaginary sample pairs.

Slice and phase ordering

  • VisuCoreDiskSliceOrder=disk_reverse_slice_order is normalized on read.
  • RARE/EPI phase-line reordering uses corrected indices and guards.
  • CSI reordering no longer assumes square encoding dimensions.
  • ZTE reaches its dedicated layout instead of being shadowed by RADIAL.
  • Ramp/navigator EPI layouts use the actual digitized sample count.
  • EPI acquisition trimming now accounts for the stored block layout.

Applications that manually corrected any of these layouts should remove those
workarounds to avoid applying the correction twice.

Numeric values and geometry

2dseq scaling now consistently implements:

real = stored * slope + offset
stored = (real - offset) / slope

RECO_map_slope and RECO_map_offset are used when the corresponding Visu
values are unavailable. Previously serialized data may therefore differ from
0.3.0 output, and values loaded from incomplete Visu metadata may now be
scaled.

PV7 and PV360 2dseq geometry now uses version-independent Visu geometry as a
fallback. Affines that previously degraded silently to identity matrices will
now contain the derived spacing and orientation.

Custom radial, UTE, CSI, and other non-Cartesian sequences can now infer a
scheme from acquisition metadata. Code that used load failure to identify an
unknown sequence should inspect dataset.scheme_id instead. An explicit
override remains available:

dataset = Dataset(path, scheme_id="RADIAL")

JCAMP-DX parsing and serialization

Correct parsing can change values returned for:

  • angle-bracket strings containing commas or parentheses;
  • @N*(value) compression occurring anywhere in an array;
  • exponential and non-numeric compressed values;
  • multiline values;
  • (XY..XY) data records; and
  • compact size declarations such as (2).

Serialized JCAMP-DX output now:

  • preserves $$ comments;
  • emits ##END= without trailing whitespace;
  • keeps lines within Bruker's 78-column convention; and
  • correctly serializes floats, lists, nested arrays, and data parameters.

Files written by 0.3.0 may therefore differ byte-for-byte from files written
by earlier releases.

Exceptions, queries, and reports

  • Missing Folder attributes now raise AttributeError, as required by
    Python's attribute protocol. Dictionary-style access continues to raise
    KeyError.
  • Malformed Dataset.query() expressions raise FilterEvalFalse rather than
    leaking NameError, SyntaxError, or TypeError.
  • Query evaluation uses a restricted namespace. Expressions relying on
    arbitrary builtins, imports, or module globals are no longer supported.
  • Dataset.to_dict() excludes internal type and subtype fields and
    preserves property order.
  • Empty reconstructions, Git LFS pointer files, unsupported suffixes, missing
    parameter files, and binary-size mismatches now produce more specific
    diagnostics. Code matching older exception strings may need adjustment.

Compatibility and test coverage

The test suite covers ParaVision 5.1, 6.0.1, 7.0.0, and PV360 3.x corpora,
including rawdata jobs, corrected 2dseq geometry/scaling, and random access.
PV360 external corpus coverage remains soft in environments where that corpus
is unavailable.

Contributors

headmeister
Assets 2
Loading