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:

# Import required components from the nifreeze package
from nifreeze.data import dmri
from nifreeze.estimator import Estimator

Load DWI Data: Load diffusion MRI (dMRI) data into a DWI object using the load function. Ensure the gradient table is provided. It should have one row per diffusion-weighted image. The first three columns represent the gradient directions, and the last column indicates the timing and strength of the gradients in units of s/mm² [ R A S+ b ]. If your data are in NIfTI file format, include a file containing the gradient information with the argument “gradients_file”:
```
# Load dMRI data into a DWI object
dwi_data = 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:
```
dwi_data = 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()
```
Fit the Models to Estimate the Affine Transformation:

Use the estimate method of the Estimator object to estimate the affine transformation parameters:
```
# Estimate affine transformation parameters
estimated_affine = estimator.estimate(
    dwi_data,
    align_kwargs=align_kwargs,
    models=models,
    omp_nthreads=omp_nthreads,
    n_jobs=n_jobs,
    seed=seed,
)
```
The estimate 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:
- dwi_data: The target DWI dataset, represented by this tool’s internal type.
- align_kwargs: Parameters to configure the image registration process.
- models: list of diffusion models used to generate the registration target for each gradient map. For a list of available models, see nifreeze.model package.
- 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 method returns an Nx4x4 array of affine matrices encoding the estimated parameters of the deformations due to head motion and eddy currents.

Example:
```
# Example of fitting the model
estimated_affine = estimator.estimate(
    dwi_data,
    models=["b0"],
    omp_nthreads=4,
    n_jobs=4,
    seed=42,
)
```

Save Results: Once transformations are estimated, save the realigned DWI 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'
dwi_data.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'
dwi_data.to_nifti(output_filename)

Plotting: Visualize data and results using built-in plotting functions of the DWI objects:
- Use plot_mosaic to visualize one direction of the dMRI dataset.
- Employ plot_gradients to visualize diffusion gradients.
Example Usage:
```
# Visualize DWI data at a specific index
dwi_data.plot_mosaic(index=0)
# Visualize gradients
dwi_data.plot_gradients()
```