How to Use¶

Incorporating NiFreeze into a Python module or script¶

To utilize NiFreeze functionalities within your Python module or script, follow these steps:

Import NiFreeze Components: Start by importing necessary components from the NiFreeze package:

To use NiFreeze you will typically need to use three main components:
- Some data: allows to build a construct over your data that allows the model and the estimator objects to deal with the data in a standardized manner.
- A model: establishes the predictive model used to estimate the generate the registration target. It will typically implement the fit and predict methods. It is specified when instantiating the estimator.
- An estimator: orchestrates the registration target prediction.
The same approach applies to any 4D modality data. For illustrative purposes, we will use some dMRI data:
```
# Import required components from the nifreeze package
from nifreeze.data import dmri
from nifreeze.estimator import Estimator
```
Load 4D Data: Load your 4D data into a dataset object using the load() function.

Use the appropriate parameters for the particular imaging modality (e.g. dMRI, fMRI, or PET) that you are using.

For example, for dMRI data, ensure the gradient table is provided. It should have one column per diffusion-weighted image. The first three rows represent the gradient directions, and the last row indicates the timing and strength of the gradients in units of s/mm² [ R A S+ b ].
```
# Load dMRI data into a DWI object
dataset = dmri.load("/path/to/your/dwi_data.nii.gz", gradients_file="/path/to/your/gradient_file")
```
Note

To run the examples and tests from this page, find sample data on OSF. To load from an HDF5 file, use:
```
dataset = dmri.DWI.from_filename("/path/to/downloaded/dwi_full.h5")
```
Instantiate an NiFreeze Estimator Object: Create an instance of the Estimator class, which encapsulates tools for estimating rigid-body head motion and distortions due to eddy currents.
```
# Create an instance of the Estimator class
estimator = Estimator(
    model,
    strategy="random",
)
```
The estimator takes a model that determines how the target volume will be estimated.
- model: specifies the model used to generate the registration target for each gradient map (dMRI) or frame (dMRI, PET). For a list of available models, see nifreeze.model package.
- strategy: strategy used to traverse the 4D sequence. The list of supported strategies can be found at nifreeze.utils.iterators module.
- prev: estimators can be stacked and be run sequentially.
Fit the Models to Estimate the Affine Transformation:

Use the run() method of the Estimator object to estimate the affine transformation parameters:
```
# Estimate affine transformation parameters
_ = estimator.run(
    dataset,
    align_kwargs=align_kwargs,
    omp_nthreads=omp_nthreads,
    n_jobs=n_jobs,
    seed=seed,
)
```
The run method employs the Leave-One-Volume-Out (LOVO) splitting technique to iteratively process DWI data volumes for each specified model. Affine transformations align the volumes, updating the DWI object with the estimated parameters. This method accepts several parameters:
- dataset: The target dataset, represented by this tool’s internal type.
- align_kwargs: Parameters to configure the image registration process.
- omp_nthreads: Maximum number of threads an individual process may use.
- n_jobs: Number of parallel jobs.
- seed: Seed for the random number generator (necessary for deterministic estimation).
The estimated parameters encoding the deformations due to head motion and eddy currents are stored as an \(N \times 4 \times 4\) array of affine matrices in the dataset object after the model fitting and prediction (done under the hood by the estimator).

Example:
```
estimator = Estimator(
    model="b0",
    strategy="random",
)

# Example of estimating the motion parameters
_ = estimator.run(
    dataset,
    omp_nthreads=4,
    n_jobs=4,
    seed=42,
)
```

Save Results: Once transformations are estimated, save the realigned data in your preferred output format, either HDF5 or NIfTI:

# Save realigned DWI data in HDF5 format
output_filename = "/path/to/save/your/output.h5"
dataset.to_filename(output_filename)

or as a NIfTI file:

# Save realigned DWI data in NIfTI format
output_filename = "/path/to/save/your/output.nii.gz"
dataset.to_nifti(output_filename)

Plotting: Visualize data and results:

Estimated motion results can be visualized using nifreeze.viz.motion_viz module functions. This includes visualizing framewise displacement, motion overlay, and volume-wise motion.

Data results can be visualized using the NiReports functions, e.g.:
- Use nireports.reportlets.mosaic.plot_mosaic() to visualize one direction of the dMRI dataset or a frame of an fMRI or PET dataset.
- Employ nireports.reportlets.modality.dwi.plot_gradients() to visualize diffusion gradients.
Example Usage:
```
# Visualize 4D data at a specific index
dataset.plot_mosaic(index=0)
```
For dMRI gradients, we can visualize diffusion gradients using:
```
# Visualize gradients
dwi_data.plot_gradients()
```