# -*- coding: utf-8 -*-
"""
===============================================================================
Suppress Gibbs oscillations
===============================================================================

Magnetic Resonance (MR) images are reconstructed from the Fourier coefficients
of acquired k-space images. Since only a finite number of Fourier coefficients
can be acquired in practice, reconstructed MR images can be corrupted by Gibbs
artefacts, which is manifested by intensity oscillations adjacent to edges of
different tissues types [1]_. Although this artefact affects MR images in
general, in the context of diffusion-weighted imaging, Gibbs oscillations
can be magnified in derived diffusion-based estimates [1]_, [2]_.

In the following example, we show how to suppress Gibbs artefacts of MR images.
This algorithm is based on an adapted version of a sub-voxel Gibbs suppression
procedure [3]_. Full details of the implemented algorithm can be found in
chapter 3 of [4]_  (please cite [3]_, [4]_ if you are using this code).

The algorithm to suppress Gibbs oscillations can be imported from the denoise
module of dipy:
"""

from dipy.denoise.gibbs import gibbs_removal

###############################################################################
# We first apply this algorithm to a T1-weighted dataset which can be fetched
# using the following code:


from dipy.data import get_fnames
from dipy.io.image import load_nifti_data


t1_fname, t1_denoised_fname, ap_fname = get_fnames('tissue_data')
t1 = load_nifti_data(t1_denoised_fname)

###############################################################################
# Let's plot a slice of this dataset.


import matplotlib.pyplot as plt
import numpy as np

axial_slice = 88
t1_slice = t1[..., axial_slice]

fig = plt.figure(figsize=(15, 4))
fig.subplots_adjust(wspace=0.2)

t1_slice = np.rot90(t1_slice)

plt.subplot(1, 2, 1)
plt.imshow(t1_slice, cmap='gray', vmin=100, vmax=400)
plt.colorbar()
fig.savefig('structural.png')

###############################################################################
# .. figure:: structural.png
#    :align: center
# 
#    Representative slice of a T1-weighted structural image.
# 
# Due to the high quality of the data, Gibbs artefacts are not visually
# evident in this dataset. Therefore, to analyse the benefits of the Gibbs
# suppression algorithm, Gibbs artefacts are artificially introduced by
# removing high frequencies of the image's Fourier transform.


c = np.fft.fft2(t1_slice)
c = np.fft.fftshift(c)
N = c.shape[0]
c_crop = c[64: 192, 64: 192]
N = c_crop.shape[0]
t1_gibbs = abs(np.fft.ifft2(c_crop)/4)

###############################################################################
# Gibbs oscillation suppression of this single data slice can be performed by
# running the following command:


t1_unring = gibbs_removal(t1_gibbs, inplace=False)

###############################################################################
# Let’s plot the results:


fig1, ax = plt.subplots(1, 3, figsize=(12, 6),
                        subplot_kw={'xticks': [], 'yticks': []})

ax.flat[0].imshow(t1_gibbs, cmap="gray", vmin=100, vmax=400)
ax.flat[0].annotate('Rings', fontsize=10, xy=(81, 70),
                    color='red',
                    xycoords='data', xytext=(30, 0),
                    textcoords='offset points',
                    arrowprops=dict(arrowstyle="->",
                                    color='red'))
ax.flat[0].annotate('Rings', fontsize=10, xy=(75, 50),
                    color='red',
                    xycoords='data', xytext=(30, 0),
                    textcoords='offset points',
                    arrowprops=dict(arrowstyle="->",
                                    color='red'))

ax.flat[1].imshow(t1_unring, cmap="gray", vmin=100, vmax=400)
ax.flat[1].annotate('WM/GM', fontsize=10, xy=(75, 50),
                    color='green',
                    xycoords='data', xytext=(30, 0),
                    textcoords='offset points',
                    arrowprops=dict(arrowstyle="->",
                                    color='green'))

ax.flat[2].imshow(t1_unring - t1_gibbs, cmap="gray", vmin=0, vmax=10)
ax.flat[2].annotate('Rings', fontsize=10, xy=(81, 70),
                    color='red',
                    xycoords='data', xytext=(30, 0),
                    textcoords='offset points',
                    arrowprops=dict(arrowstyle="->",
                                    color='red'))
ax.flat[2].annotate('Rings', fontsize=10, xy=(75, 50),
                    color='red',
                    xycoords='data', xytext=(30, 0),
                    textcoords='offset points',
                    arrowprops=dict(arrowstyle="->",
                                    color='red'))
plt.show()
fig1.savefig('Gibbs_suppression_structural.png')

###############################################################################
# .. figure:: Gibbs_suppression_structural.png
#    :align: center
# 
#    Uncorrected and corrected structural images are shown in the left
#    and middle panels, while the difference between these images is shown
#    in the right panel.
# 
# The image artificially corrupted with Gibb's artefacts is shown in the left
# panel. In this panel, the characteristic ringing profile of Gibbs artefacts
# can be visually appreciated (see intensity oscillations pointed by the red
# arrows). The corrected image is shown in the middle panel. One can appreciate
# that artefactual oscillations are visually suppressed without compromising
# the contrast between white and grey matter (e.g. details pointed by the green
# arrow). The difference between uncorrected and corrected data is plotted in
# the right panel which highlights the suppressed Gibbs ringing profile.
# 
# 
# Now let's show how to use the Gibbs suppression algorithm in diffusion-weighted
# images. We fetch the multi-shell diffusion-weighted dataset which was kindly
# supplied by Romain Valabrègue, CENIR, ICM, Paris [5]_.


from dipy.data import read_cenir_multib

bvals = [200, 400, 1000, 2000]

img, gtab = read_cenir_multib(bvals)

data = np.asarray(img.dataobj)

###############################################################################
# For illustration purposes, we select two slices of this dataset


data_slices = data[:, :, 40:42, :]

###############################################################################
# Gibbs oscillation suppression of all multi-shell data and all slices
# can be performed in the following way:


data_corrected = gibbs_removal(data_slices, slice_axis=2, num_processes=-1)

###############################################################################
# Due to the high dimensionality of diffusion-weighted data, we recommend
# that you specify which is the axis of data matrix that corresponds to different
# slices in the above step. This is done by using the optional parameter
# 'slice_axis'.
# 
# Below we plot the results for an image acquired with b-value=0:


fig2, ax = plt.subplots(1, 3, figsize=(12, 6),
                        subplot_kw={'xticks': [], 'yticks': []})

ax.flat[0].imshow(data_slices[:, :, 0, 0].T, cmap='gray', origin='lower',
                  vmin=0, vmax=10000)
ax.flat[0].set_title('Uncorrected b0')
ax.flat[1].imshow(data_corrected[:, :, 0, 0].T, cmap='gray',
                  origin='lower', vmin=0, vmax=10000)
ax.flat[1].set_title('Corrected b0')
ax.flat[2].imshow(data_corrected[:, :, 0, 0].T - data_slices[:, :, 0, 0].T,
                  cmap='gray', origin='lower', vmin=-500, vmax=500)
ax.flat[2].set_title('Gibbs residuals')

plt.show()
fig2.savefig('Gibbs_suppression_b0.png')

###############################################################################
# .. figure:: Gibbs_suppression_b0.png
#    :align: center
# 
#    Uncorrected (left panel) and corrected (middle panel) b-value=0 images. For
#    reference, the difference between uncorrected and corrected images is shown
#    in the right panel.
# 
# The above figure shows that the benefits of suppressing Gibbs artefacts is hard
# to observe on b-value=0 data. Therefore, diffusion derived metrics for both
# uncorrected and corrected data are computed using the mean signal diffusion
# kurtosis image technique (:ref:`example_reconst_msdki`).
# 
# To avoid unnecessary calculations on the background of the image, we also
# compute a brain mask.


# Create a brain mask
from dipy.segment.mask import median_otsu

maskdata, mask = median_otsu(data_slices, vol_idx=range(10, 50),
                             median_radius=3, numpass=1, autocrop=False,
                             dilate=1)

# Define mean signal diffusion kurtosis model
import dipy.reconst.msdki as msdki

dki_model = msdki.MeanDiffusionKurtosisModel(gtab)

# Fit the uncorrected data
dki_fit = dki_model.fit(data_slices, mask=mask)
MSKini = dki_fit.msk

# Fit the corrected data
dki_fit = dki_model.fit(data_corrected, mask=mask)
MSKgib = dki_fit.msk

###############################################################################
# Let's plot the results


fig3, ax = plt.subplots(1, 3, figsize=(12, 12),
                        subplot_kw={'xticks': [], 'yticks': []})

ax.flat[0].imshow(MSKini[:, :, 0].T, cmap='gray', origin='lower',
                  vmin=0, vmax=1.5)
ax.flat[0].set_title('MSK (uncorrected)')
ax.flat[0].annotate('Rings', fontsize=12, xy=(59, 63),
                    color='red',
                    xycoords='data', xytext=(45, 0),
                    textcoords='offset points',
                    arrowprops=dict(arrowstyle="->",
                                    color='red'))

ax.flat[1].imshow(MSKgib[:, :, 0].T, cmap='gray', origin='lower',
                  vmin=0, vmax=1.5)
ax.flat[1].set_title('MSK (corrected)')

ax.flat[2].imshow(MSKgib[:, :, 0].T - MSKini[:, :, 0].T, cmap='gray',
                  origin='lower', vmin=-0.2, vmax=0.2)
ax.flat[2].set_title('MSK (uncorrected - corrected')
ax.flat[2].annotate('Rings', fontsize=12, xy=(59, 63),
                    color='red',
                    xycoords='data', xytext=(45, 0),
                    textcoords='offset points',
                    arrowprops=dict(arrowstyle="->",
                                    color='red'))

plt.show()
fig3.savefig('Gibbs_suppression_msdki.png')

###############################################################################
# .. figure:: Gibbs_suppression_msdki.png
#    :align: center
# 
#    Uncorrected and corrected mean signal kurtosis images are shown in the left
#    and middle panels. The difference between uncorrected and corrected images
#    are show in the right panel.
# 
# In the left panel of the figure above, Gibbs artefacts can be appreciated by
# the negative values of mean signal kurtosis (black voxels) adjacent to the
# brain ventricle (red arrows). These negative values seem to be suppressed
# after the `gibbs_removal` function is applied. For a better visualization of
# Gibbs oscillations, the difference between corrected and uncorrected images are
# shown in the right panel.
# 
# 
# References
# ----------
# .. [1] Veraart, J., Fieremans, E., Jelescu, I.O., Knoll, F., Novikov, D.S.,
#        2015. Gibbs Ringing in Diffusion MRI. Magn Reson Med 76(1): 301-314.
#        https://doi.org/10.1002/mrm.25866
# .. [2] Perrone, D., Aelterman, J., Pižurica, A., Jeurissen, B., Philips, W.,
#        Leemans A., 2015. The effect of Gibbs ringing artifacts on measures
#        derived from diffusion MRI. Neuroimage 120, 441-455.
#        https://doi.org/10.1016/j.neuroimage.2015.06.068.
# .. [3] Kellner, E., Dhital, B., Kiselev, V.G, Reisert, M., 2016. Gibbs‐ringing
#        artifact removal based on local subvoxel‐shifts. Magn Reson Med
#        76:1574–1581.
#        https://doi.org/10.1002/mrm.26054.
# .. [4] Neto Henriques, R., 2018. Advanced Methods for Diffusion MRI Data
#        Analysis and their Application to the Healthy Ageing Brain
#        (Doctoral thesis). https://doi.org/10.17863/CAM.29356
# .. [5] Valabrègue, R. (2015). Diffusion MRI measured at multiple b-values.
#        Retrieved from:
#        https://digital.lib.washington.edu/researchworks/handle/1773/33311
# 
# .. include:: ../links_names.inc