From 9589419ee5b1ae78b7f00100d82e9b3f5f82f2a3 Mon Sep 17 00:00:00 2001 From: esavary Date: Tue, 16 Apr 2024 16:11:43 +0200 Subject: [PATCH 1/8] doc: add usage inside a python module --- docs/index.rst | 1 + docs/usage.rst | 103 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 docs/usage.rst diff --git a/docs/index.rst b/docs/index.rst index 848e3cc2..e5fad0a2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,5 +14,6 @@ Contents :maxdepth: 3 installation + usage developers changes diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 00000000..241a9ec5 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,103 @@ +.. include:: links.rst + +How to Use +============ + +Incorporating Eddymotion into a Python Module +--------------------------------------------- + +To utilize Eddymotion functionalities within your Python module, follow these steps: + +1. **Import Eddymotion Components**: Start by importing necessary components from the Eddymotion package: + + .. code-block:: python + + # Import required components from the Eddymotion package + from eddymotion.data.dmri import DWI + from eddymotion.estimator import EddyMotionEstimator + +2. **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": + + .. code-block:: python + + # Load dMRI data into a DWI object + dwi_data = DWI.load('/path/to/your/dwi_data.nii.gz', gradients_file='/path/to/your/gradient_file') + +3. **Instantiate an Eddymotion Estimator Object**: Create an instance of the `EddyMotionEstimator` class, which encapsulates tools for estimating rigid-body head motion and distortions due to eddy currents. + + .. code-block:: python + + # Create an instance of the EddyMotionEstimator class + estimator = EddyMotionEstimator() + +4. **Fit the Models to Estimate the Affine Transformation**: + + Use the `fit` method of the `EddyMotionEstimator` object to estimate the affine transformation parameters: + + .. code-block:: python + + # Estimate affine transformation parameters + estimated_affine = estimator.fit( + dwi_data, + align_kwargs=align_kwargs, + models=models, + omp_nthreads=omp_nthreads, + n_jobs=n_jobs, + seed=seed, + ) + + The `fit` 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 :doc:`api/eddymotion.model`. + - `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 a list of affine matrices encoding the estimated parameters of the deformations due to head motion and eddy currents. + + Example: + + .. code-block:: python + + # Example of fitting the model + estimated_affine = estimator.fit( + dwi_data, + models=["b0"], + omp_nthreads=4, + n_jobs=4, + seed=42, + ) + +5. **Save Results**: Once transformations are estimated, save the realigned DWI data in your preferred output format, either HDF5 or NIfTI: + + .. code-block:: python + + # 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: + + .. code-block:: python + + # Save realigned DWI data in NIfTI format + output_filename = '/path/to/save/your/output.nii.gz' + dwi_data.to_nifti(output_filename) + +6. **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: + + .. code-block:: python + + # Visualize DWI data at a specific index + dwi_data.plot_mosaic(index=0) + # Visualize gradients + dwi_data.plot_gradients() + + From f9627693345aee2d77ffb5f9bff00f6130b10b12 Mon Sep 17 00:00:00 2001 From: esavary Date: Wed, 17 Apr 2024 10:43:21 +0200 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: Ariel Rokem --- docs/usage.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 241a9ec5..3c1028a1 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -3,10 +3,10 @@ How to Use ============ -Incorporating Eddymotion into a Python Module +Incorporating Eddymotion into a Python module or script --------------------------------------------- -To utilize Eddymotion functionalities within your Python module, follow these steps: +To utilize Eddymotion functionalities within your Python module or script, follow these steps: 1. **Import Eddymotion Components**: Start by importing necessary components from the Eddymotion package: From 18729e5907341fd1bd14a9c76f130000b55e8267 Mon Sep 17 00:00:00 2001 From: esavary Date: Mon, 22 Apr 2024 11:11:24 +0200 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Oscar Esteban --- docs/usage.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 3c1028a1..0a7ea863 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,8 +1,7 @@ .. include:: links.rst How to Use -============ - +========== Incorporating Eddymotion into a Python module or script --------------------------------------------- From b7115ff542edabe46ce24f5a922f6668313e4399 Mon Sep 17 00:00:00 2001 From: esavary Date: Mon, 22 Apr 2024 11:25:46 +0200 Subject: [PATCH 4/8] sty: fix title issue --- docs/usage.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 0a7ea863..e1adeb34 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -3,8 +3,7 @@ How to Use ========== Incorporating Eddymotion into a Python module or script ---------------------------------------------- - +------------------------------------------------------- To utilize Eddymotion functionalities within your Python module or script, follow these steps: 1. **Import Eddymotion Components**: Start by importing necessary components from the Eddymotion package: From 2ac7718da9401a6f79188771d2c185831b0781ee Mon Sep 17 00:00:00 2001 From: esavary Date: Mon, 22 Apr 2024 15:29:02 +0200 Subject: [PATCH 5/8] fix: update method name --- docs/usage.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index e1adeb34..f3caee0d 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -30,12 +30,12 @@ To utilize Eddymotion functionalities within your Python module or script, follo 4. **Fit the Models to Estimate the Affine Transformation**: - Use the `fit` method of the `EddyMotionEstimator` object to estimate the affine transformation parameters: + Use the `estimate` method of the `EddyMotionEstimator` object to estimate the affine transformation parameters: .. code-block:: python # Estimate affine transformation parameters - estimated_affine = estimator.fit( + estimated_affine = estimator.estimate( dwi_data, align_kwargs=align_kwargs, models=models, @@ -44,7 +44,7 @@ To utilize Eddymotion functionalities within your Python module or script, follo seed=seed, ) - The `fit` 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: + 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. @@ -60,7 +60,7 @@ To utilize Eddymotion functionalities within your Python module or script, follo .. code-block:: python # Example of fitting the model - estimated_affine = estimator.fit( + estimated_affine = estimator.estimate( dwi_data, models=["b0"], omp_nthreads=4, From b86b9cb14cc688ba68b75d0abe3c75117186bc1d Mon Sep 17 00:00:00 2001 From: esavary Date: Thu, 25 Apr 2024 11:19:18 +0200 Subject: [PATCH 6/8] enh: add link to test data --- docs/usage.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/usage.rst b/docs/usage.rst index f3caee0d..02f340de 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -21,6 +21,16 @@ To utilize Eddymotion functionalities within your Python module or script, follo # Load dMRI data into a DWI object dwi_data = DWI.load('/path/to/your/dwi_data.nii.gz', gradients_file='/path/to/your/gradient_file') + *Note*: To fetch an example of test data for running examples and tests from this page, you can use datalad, a data management tool. If you haven't already installed it, follow the instructions to install datalad given `here `_. Then, run the following commands to fetch our test data: + + .. code-block:: bash + + #install the test data datalad repository + datalad install -rg --source=https://gin.g-node.org/nipreps-data/tests-eddymotion.git + # Navigate to the test data folder + cd tests-eddymotion/ + + 3. **Instantiate an Eddymotion Estimator Object**: Create an instance of the `EddyMotionEstimator` class, which encapsulates tools for estimating rigid-body head motion and distortions due to eddy currents. .. code-block:: python From 4762fad519111306c63cf379a712823d091d6f2b Mon Sep 17 00:00:00 2001 From: esavary Date: Thu, 25 Apr 2024 14:33:19 +0200 Subject: [PATCH 7/8] fix: remove need of datalad --- docs/usage.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 02f340de..358453e7 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -21,14 +21,7 @@ To utilize Eddymotion functionalities within your Python module or script, follo # Load dMRI data into a DWI object dwi_data = DWI.load('/path/to/your/dwi_data.nii.gz', gradients_file='/path/to/your/gradient_file') - *Note*: To fetch an example of test data for running examples and tests from this page, you can use datalad, a data management tool. If you haven't already installed it, follow the instructions to install datalad given `here `_. Then, run the following commands to fetch our test data: - - .. code-block:: bash - - #install the test data datalad repository - datalad install -rg --source=https://gin.g-node.org/nipreps-data/tests-eddymotion.git - # Navigate to the test data folder - cd tests-eddymotion/ + *Note*: To run the examples and tests from this page, you can download an example of DWI data from `here `_. 3. **Instantiate an Eddymotion Estimator Object**: Create an instance of the `EddyMotionEstimator` class, which encapsulates tools for estimating rigid-body head motion and distortions due to eddy currents. From 3f5f837c8dcdc2afba28496a8b45637c20b06019 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Thu, 16 May 2024 07:48:50 -0400 Subject: [PATCH 8/8] DOC: Fix data load instructions, correct estimated_affines type description --- docs/usage.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 358453e7..a02fbe9f 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -11,7 +11,7 @@ To utilize Eddymotion functionalities within your Python module or script, follo .. code-block:: python # Import required components from the Eddymotion package - from eddymotion.data.dmri import DWI + from eddymotion.data import dmri from eddymotion.estimator import EddyMotionEstimator 2. **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": @@ -19,9 +19,17 @@ To utilize Eddymotion functionalities within your Python module or script, follo .. code-block:: python # Load dMRI data into a DWI object - dwi_data = DWI.load('/path/to/your/dwi_data.nii.gz', gradients_file='/path/to/your/gradient_file') + 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, you can download an example of DWI data from `here `_. + .. note:: + + To run the examples and tests from this page, + find `sample data `__ on OSF. + To load from an HDF5 file, use: + + .. code-block:: python + + dwi_data = dmri.DWI.from_filename('/path/to/downloaded/dwi_full.h5') 3. **Instantiate an Eddymotion Estimator Object**: Create an instance of the `EddyMotionEstimator` class, which encapsulates tools for estimating rigid-body head motion and distortions due to eddy currents. @@ -56,7 +64,8 @@ To utilize Eddymotion functionalities within your Python module or script, follo - `n_jobs`: Number of parallel jobs. - `seed`: Seed for the random number generator (necessary for deterministic estimation). - The method returns a list of affine matrices encoding the estimated parameters of the deformations due to head motion and eddy currents. + The method returns an Nx4x4 array of affine matrices encoding the estimated parameters of + the deformations due to head motion and eddy currents. Example: @@ -100,5 +109,3 @@ To utilize Eddymotion functionalities within your Python module or script, follo dwi_data.plot_mosaic(index=0) # Visualize gradients dwi_data.plot_gradients() - -