DOC: PIESNO example, and linking from the examples index.

doc/examples/piesno.py

@@ -3,27 +3,35 @@
 Noise estimation using PIESNO
 =============================
 
-Using the Probabilistic Identification and Estimation of Noise (PIESNO) [Koay2009]_
-one can detect the standard deviation of the noise from
-diffusion-weighted imaging (DWI). PIESNO also works with multiple channel
-DWI datasets that are acquired from N array coils for both SENSE and
-GRAPPA reconstructions.
-
-The PIESNO paper [Koay2009]_ works in two steps. 1) First, it finds voxels that are most likely
-background voxels. Intuitively, these voxels have very similar
-diffusion-weighted intensities (up to some noise) in the fourth dimension
-of the DWI dataset. White matter, gray matter or CSF voxels have diffusion intensities
-that vary quite a lot across different directions.
-2) From these estimated background voxels and
-the input number of coils N, PIESNO finds what sigma each Gaussian
-from each of the N coils would have generated the observed Rician (N=1)
-or non-central Chi (N>1) distributed noise profile in the DWI datasets.
-[Koay2009]_ gives all the details.
-
-PIESNO makes an important assumption: the
-Gaussian noise standard deviation is assumed to be uniform. The noise
-is uniform across multiple slice locations or across multiple images of the same location.
+Often, one is interested in estimating the noise in the diffusion signal. One
+of the methods to do this is the Probabilistic Identification and Estimation of
+Noise (PIESNO) framework [Koay2009]_. Using this method, one can detect the
+standard deviation of the noise from diffusion-weighted imaging (DWI). PIESNO
+also works with multiple channel DWI datasets that are acquired from N array
+coils for both SENSE and GRAPPA reconstructions.
 
+The PIESNO method works in two steps:
+
+1) First, it finds voxels that are most likely background voxels. Intuitively,
+these voxels have very similar diffusion-weighted intensities (up to some noise)
+in the fourth dimension of the DWI dataset. White matter, gray matter or CSF
+voxels have diffusion intensities that vary quite a lot across different
+directions.
+
+2) From these estimated background voxels and the input number of coils N,
+PIESNO finds what sigma each Gaussian from each of the N coils would have
+generated the observed Rician (N=1) or non-central Chi (N>1) distributed noise
+profile in the DWI datasets.
+
+PIESNO makes an important assumption: the Gaussian noise standard deviation is
+assumed to be uniform. The noise is uniform across multiple slice locations or
+across multiple images of the same location.
+
+For the full details, please refer to the original paper.
+
+In this example, we will demonstrate the use of PIESNO with a 3-shell data-set.
+
+We start by importing necessary modules and functions and loading the data:
 """
 
 import nibabel as nib
@@ -37,21 +45,20 @@
 data = img.get_data()
 
 """
-
 Now that we have fetched a dataset, we must call PIESNO with the right number
 of coils used to acquire this dataset. It is also important to know what
-was the parallel reconstruction algorithm used.
-Here, the data comes from a GRAPPA reconstruction from
-a 12-elements head coil available on the Tim Trio Siemens, for which
-the 12 coil elements are combined into 4 groups of 3 coil elements
-each. The signal is received through 4 distinct groups of receiver channels,
-yielding N = 4. Had we used a GE acquisition, we would have used N=1 even
-if multiple channel coils are used because GE uses a SENSE reconstruction,
-which has a Rician noise nature and thus N is always 1.
+was the parallel reconstruction algorithm used. Here, the data comes from a
+GRAPPA reconstruction, was acquired with a 12-elements head coil available on
+the Tim Trio Siemens, for which the 12 coil elements are combined into 4 groups
+of 3 coil elements each. The signal is therefore received through 4 distinct
+groups of receiver channels, yielding N = 4. Had we used a GE acquisition, we
+would have used N=1 even if multiple channel coils are used because GE uses a
+SENSE acceleration, which has a Rician noise nature and thus N is always 1.
 
 As a convenience, we will estimate the noise for the whole volume in one go,
 but it is also possible to get a slice by slice estimation of the noise if
-it is more desirable through the :func:`dipy.denoise.noise_estimate.piesno_3D` function.
+it is more desirable through the :func:`dipy.denoise.noise_estimate.piesno_3D`
+function.
 """
 
 sigma, mask = piesno(data, N=4, return_mask=True)
@@ -74,7 +81,8 @@
 .. figure:: piesno.png
    :align: center
 
-   **Showing the mid axial slice of the b=0 image (left) and estimated background voxels (right) used to estimate the noise standard deviation**.
+   **Showing the mid axial slice of the b=0 image (left) and estimated
+   background voxels (right) used to estimate the noise standard deviation**.
 """
 
 nib.save(nib.Nifti1Image(mask, img.get_affine(), img.get_header()),
@@ -94,10 +102,10 @@
 """
 
 .. [Koay2009] Koay C.G., E. Ozarslan, C. Pierpaoli. Probabilistic
-   Identification and Estimation of Noise (PIESNO): A self-consistent approach
-   and its applications in MRI. JMR, 199(1):94-103, 2009.
+              Identification and Estimation of Noise (PIESNO): A
+              self-consistent approach and its applications in MRI.
+              JMR, 199(1):94-103, 2009.
 
 .. include:: ../links_names.inc
 
-
 """

doc/examples_index.rst

@@ -41,7 +41,7 @@ Basic SNR estimation
 
 PIESNO
 ~~~~~~
-- :ref:`example_piesno_sherbrooke`
+- :ref:`example_piesno`
 
 Denoising
 ~~~~~~~~~