◆ FORGE Suite
GitHubMechanical Neuroimaging Lab · Univ. of Delaware
Skip to content

Run a low-rank reconstruction

oscillateRecon reconstructs all repetitions of a scan together, assuming the series of images can be described by a few temporal basis vectors. It is meant for OSCILLATE acquisitions, where the spiral is rotated between repetitions, and other multi-repetition data whose repetitions are strongly correlated. Low-rank reconstruction explains the model.

Prepare the input

The file needs everything forgePcSenseTimeSeg needs (SENSEMap, FieldMap, PhaseMaps), plus the temporal basis:

  • v: a complex NRep × NRep matrix whose columns are the temporal basis vectors, most important first. These are usually the right singular vectors of a low-resolution image series, computed during data preparation. Magneto's convertRecoInfoToIsmrmrd writes them from its v_svd argument, and the OSCILLATE workflow in FORGE Studio's multiband spiral MRE pack prepares them for you.

oscillateRecon stops with exit code 2 if v is missing or is not NRep × NRep.

Run it

mkdir -p recon
oscillateRecon -i data.h5 -o recon/ -L 12 -t 6 -I minmax -n 20 -B 0.01
  • -L is the rank: how many columns of v to use, from 1 to the number of repetitions. In this program -L does not mean time segments.
  • -t (time segments) and -I (interpolator) are required.
  • -n and -B are the iterations and regularization weight, as in the other programs.

Read the output

For each slice, average, echo and cardiac phase you get a magnitude and a phase file with one frame per repetition, for example recon/img_Slice0_Avg0_Echo0_Phase0_mag.nii. Load it as a 4-D image.

Pick the rank

A higher rank keeps more of the real changes between repetitions but also more noise, and each extra rank adds one image's worth of unknowns to the solve. Start from the rank your preparation suggests (the number of singular values that stand clearly above the noise), and compare the time course in a region you care about at a few nearby ranks.

The solver runs on the CPU for this program, because the low-rank operator has no GPU vector path. The per-repetition operators inside it still use the GPU in Metal and CUDA builds.