documentation

docs/src/GettingStarted.md

@@ -1,22 +1,50 @@
 # Get started
 
-There are available [user examples](https://github.com/NordicMRspine/UserExample_MRINavigator) to get started. The user needs to dispone of their own data to run the pipelines as currently there are not example data available.
+There are available [user examples](https://github.com/NordicMRspine/UserExample_MRINavigator) to get started. The user needs to provide their own data to run the pipelines, as there are currently no example data available.
 
 ## Data acquisition
-The user should have the raw data of a gradient echo acquisition. The pipelines can be run on both multi-echo and single-echo data. Other than the main acquisition, which is usually undersampled, also a lower resolution, fully sampled scan is necessary to compute the [coils sennsitivity maps](https://doi.org/10.1002/mrm.1241) and reconstruct the images. This low resolution scan is also called reference scan and should include only one echo. The main gradient echo acquisition must include a navigator readout trough the center of k-space at __the end__ of every TR. During the acqusition it is advisable to collect the signal from a respiratory belt. This can be used to unwrap the navigator phase estimates if phase wrapping is present.
+The user should have the raw data of a gradient echo acquisition. The pipelines can be run on both multi-echo and single-echo data. Other than the main acquisition, which is usually undersampled, a lower resolution, fully sampled scan is also necessary to compute the [coils sensitivity maps](https://doi.org/10.1002/mrm.1241) and reconstruct the images. This low-resolution scan is also called a reference scan and should include only one echo. The main gradient echo acquisition must include a navigator readout through the center of k-space at __the end__ of every TR. During the acquisition, it is advisable to collect the signal from a respiratory belt. This can be used to unwrap the navigator's phase estimates if phase wrapping is present.
 
 ## Data reshaping
-All the data should be exported from the scanner in raw format. Then they should be converted to [ISMRMRD](https://ismrmrd.readthedocs.io/en/latest/index.html) format. Siemens TWIX data can be converted to ISMRMRD using [siemens_to_ismrmrd](https://github.com/ismrmrd/siemens_to_ismrmrd). After the conversion the data can be loaded in the julia framework. The repiratory belt recording must be synchronised with bla bla
-
+All the data should be exported from the scanner in raw format. Then they should be converted to [ISMRMRD](https://ismrmrd.readthedocs.io/en/latest/index.html) format. Siemens TWIX data can be converted to ISMRMRD using [siemens_to_ismrmrd](https://github.com/ismrmrd/siemens_to_ismrmrd). After the conversion, the data can be loaded into the Julia framework.
+The repiratory belt recording must be synchronised with the time stamps in the image acquisition. Then they must be saved in a two-column vector (1:time [ms], 2:trace) in .mat format. Each repetition should be in a different file. The time should be expressed in seconds from the beginning of the day and contain time points before and after the image acquisition (at least 4 s).
 
 ## The parameters dictionary
-Before calling the package function the correction pipeline should be chosen and the parameters should be set. For more informations regarding the correction pipelines and 
-
+Before calling the package function the correction pipeline should be chosen and the parameters should be set. Also the data paths and results paths need to be defined. For more details regarding the correction pipelines and parameters read the [Navigator-based correction pipelines](@ref) page.
+All the information necessary to apply the corrections is defined in a [dictionary](https://docs.julialang.org/en/v1/base/collections/#Dictionaries). This includes all the file paths and analysis parameters. The user can also add items to the dictionary if needed.
+Here is an example of a `params` dictionary:
+
+```julia
+params = Dict{Symbol,Any}()
+params[:subject] = "sub_01"
+params[:slices] = [1,2] # type nothing for all slices
+params[:echoes] = [3,4] # type nothing for all echoes
+params[:rep] = 0
+params[:comp_sensit] = true
+params[:comp_centerline] = true
+params[:trust_SCT] = false
+params[:use_centerline] = true
+params[:corr_type] = "FFT_unwrap"
+params[:FFT_interval] = 35 # millimeters
+params[:root_path] = "/Users/me/my_data/"
+
+params[:lable] = params[:corr_type] * "_rep_" * string(params[:rep])
+params[:path_imgData] = params[:root_path] * params[:subject] * "/h5/gre2D.h5"
+params[:path_refData] = params[:root_path] * params[:subject] * "/h5/gre2D_Ref.h5"
+params[:path_niftiMap] = params[:root_path] * params[:subject] * "/Nifti/gre2D_Ref.nii"
+params[:path_centerline] = params[:root_path] * params[:subject] * "/Nifti/"
+params[:path_physio] = params[:root_path] * params[:subject] * "/Physiological_trace/belt_reco_rep"
+params[:path_sensit] = params[:root_path] * params[:subject] * "/Results/senseMap_GRE.jld2"
+params[:path_noise] = params[:root_path] * params[:subject] * "/Results/noisemat.jld2"
+params[:path_results] = params[:root_path] * params[:subject] * "/Results/"
+params[:file_name] = "gre2D"
+```
 
 ## User examples
-* Compact
-* Semi-Compact
-* Complete
+Three user examples are available in the folder [user examples](https://github.com/NordicMRspine/UserExample_MRINavigator):
+* __Compact__: runs all the selected pipeline automatically but it is not customizable and harder to debug.
+* __Semi-Compact__: allows for some level of customization and it is easier to debug.
+* __Complete__: requires more knowledge of the data structures but it is flexible and adaptable.
 
 ## Disclaimer
-MRINavigator and the functions to ajdust the data after loading the were developed using Siemens data [bla bla]
+Siemens data only were used to develop MRINavigator. All the functions to adjust the data before running the pipeline (e.g., the function to extract the navigator profiles or to remove the reference profiles) have been tested on Siemens data only. There is no guarantee that all of these functions are needed and will work on other vendors data. Other vendors users should convert the raw data in [ISMRMRD](https://ismrmrd.readthedocs.io/en/latest/index.html) format and when loading these into the Julia framework they should make sure that all the needed information is present. Please start from the [complete user example](https://github.com/NordicMRspine/UserExample_MRINavigator) if doing this. The functions to compute and apply the corrections should then work correctly.

docs/src/Pipelines.md

@@ -1,14 +1,14 @@
 # Navigator-based correction pipelines
 
-Standard navigator processing that have been developed for brain imaging are not sufficiently robust in the spinal cord because:
+Standard navigator processing that has been developed for brain imaging is not sufficiently robust in the spinal cord because:
 * There is higher in-plane variability in the field distribution
-* The signal to noise ratio (SNR) is lower
-* There is larger variation in signal contribution from different receiver coils
+* The signal-to-noise ratio (SNR) is lower
+* There are larger variations in signal contribution from different receiver coils
 
 To face these challenges we introduced:
 * __SNR weighted averaging__ of the navigator profile
 * __mean phase removal__ to recenter the phase distribution and reduce wrapping
-* __A fast Fourier transform (FFT) and spatial region selection step__. This consists of applying a one dimensional Fourier transform to each navigator profile and considering for the phase estimate only the data points in certain spatial interval centered on the spinal cord.
+* __A fast Fourier transform (FFT) and spatial region selection step__. This consists of applying a one-dimensional Fourier transform to each navigator profile and considering for the phase estimate only the data points in a certain spatial interval centered on the spinal cord.
 * __Phase unwrapping__ function for the navigator estimates using the respiratory trace recording.
 These features are combined in multiple pipelines as shown in the figure.
 
@@ -19,14 +19,14 @@ The available pipelines are:
 * __FFT_nav__ that compared to k-nav includes an additional FFT snd spatial region selection step.
 * __unwrap__ includes the phase unwrapping algorithm and makes use of the respiratory belt recordings.
 
-MRINavigator is designed to be flexible and multiple analysis parameters are tunable. It is possible to select the correction pipeline and paramenter using the params dictionary.
-For more informations check the [Get started](@ref) or [API](@ref) pages. Alternatively start `julia` from the command line, type `?` to enter the help REPL mode. Then enter
+MRINavigator is designed to be flexible and multiple analysis parameters are tunable. It is possible to select the correction pipeline and parameters using the params dictionary.
+For more information check the [Get started](@ref) or [API](@ref) pages. Alternatively start `julia` from the command line, and type `?` to enter the help REPL mode. Then enter
 
 ```julia
 help?> defaultNavParams
 ```
 
-Here are listed the main features and parametes the user can slect and modify:
-* The Spinal cord toolbpx ([SCT](https://spinalcordtoolbox.com)) can be used to locate the spinal cord centerline position (`params[:comp_centerline] = true`). To do this the reference data, which are fully sampled, are reconstructed combining the coils, and saved in [NIfTI](https://brainder.org/2012/09/23/the-nifti-file-format/) format (`params[:reconstruct_map] = true`).  The user can also manually locate the centerline if the automatic algorithm fails, selecting `params[:trust_SCT] = false`. Alternatively the center of the image will be used (`params[:use_centerline] = false`).
+Here are listed the main features and parameters the user can select and modify:
+* The Spinal cord toolbox ([SCT](https://spinalcordtoolbox.com)) can be used to locate the spinal cord centerline position (`params[:comp_centerline] = true`). To do this the reference data, which are fully sampled, are reconstructed combining the coils, and saved in [NIfTI](https://brainder.org/2012/09/23/the-nifti-file-format/) format (`params[:reconstruct_map] = true`).  The user can also manually locate the centerline if the automatic algorithm fails, selecting `params[:trust_SCT] = false`. Alternatively, the center of the image will be used (`params[:use_centerline] = false`).
 * The interval width for the region selection after the FFT step can be selected (`params[:FFT_interval] = type number in millimeters`).
 * The unwrap function can be applied added both to the __FFT__ and the __k nav__ pipelines. To do this type `params[:corr_type] = "FFT_unwrap"` or `params[:corr_type] = "knav_unwrap"`.

docs/src/index.md

@@ -14,10 +14,10 @@ Depth = 2
 ```
 
 ## Introduction
-MRINavigator provides multiple navigator-based correction pipelines for Magnetic Resonance (MR) images. These aim at demodulating time-dependent field variations present in multi echo-gradient echo acquisitions. The package was developed with a focus on spinal cord imaging, however it can be used for multiple imaging applications. The corrections are to be applied on the raw data before the image reconstruction. [MRIReco.jl](https://github.com/MagneticResonanceImaging/MRIReco.jl) can be used to reconstruct the images.
+MRINavigator provides multiple navigator-based correction pipelines for Magnetic Resonance (MR) images. These aim at demodulating time-dependent field variations present in multi echo-gradient echo acquisitions. The package was developed with a focus on spinal cord imaging, but it can be used for multiple imaging applications. The corrections are to be applied to the raw data before the image reconstruction. [MRIReco.jl](https://github.com/MagneticResonanceImaging/MRIReco.jl) can be used to reconstruct the images.
 
 !!! note
-    MRINavigator.jl is newly published and any feedback is welcome. Please report any bugs or features under issues in the GitHub folder.
+    MRINavigator.jl is newly published, and any feedback is welcome. Please report any bugs or features under issues in the GitHub folder.
 
 ## Installation
 Start `julia` and open the package manager REPL mode by entering `]`. Then enter
@@ -35,8 +35,8 @@ More information on how to develop a package can be found in the Julia documenta
 To use some package functionalities external softwares are necessary. These include
 * [Spinal Cord Toolbox (SCT)](https://spinalcordtoolbox.com)
 * [FSLeyes](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSLeyes)
-Using these should improve the correction outcome of the pipelines including a fourier transform (FFT) step. This is only relevant for spinal cord acquisitions.
-For additinal information read the [Get started](@ref) and [Navigator-based correction pipelines](@ref) sections.
+Using these should improve the correction outcome of the pipelines including a Fourier transform (FFT) step. This is only relevant for spinal cord acquisitions.
+For additional information read the [Get started](@ref) and [Navigator-based correction pipelines](@ref) sections.
 
 ## Testing MRINavigator
 To make sure that the package is correctly installed and works, start `julia` from the command line, type `]` to enter the package manager REPL mode. Then enter
@@ -50,11 +50,10 @@ To update MRINavigator to the latest version, start `julia` from the command lin
 pkg> update MRINavigator
 ```
 ## Navigator-based correction
-Multi-echo gradient-echo (GRE) sequence are commonly acquired both in research labs and clinical practice. However, one of their main limitations is the sensitivity to field instabilities both in space and time. Indeed, for the signal spatial encoding to be effective a background homogeneous field in time and space is required. Time-varying background fields can lead to phase modulation between k-space lines, and therefore TE-dependent ghosting artefacts. [Navigator](https://www.sciencedirect.com/science/article/pii/S1053811910003356?via%3Dihub) readouts in the k-space center can be used to measure the intensity of the filed fluctuations allowing to demodulate the acquired signal before the image reconstruction. The standard navigaotr-based correction was developed for brain imaging and it is not robus when applied in other areas e.g. the spinal cord. When failing the correction can even exhacerbate the artifacts. This package provides optimised post-processing pipelines to correct for dynamic field instabilities in GRE sequences. For additinal information read the [Navigator-based correction pipelines](@ref) section.
+Multi-echo gradient-echo (GRE) sequences are commonly acquired both in research labs and clinical practice. However, one of their main limitations is the sensitivity to field instabilities both in space and time. Indeed, for the signal spatial encoding to be effective a background homogeneous field in time and space is required. Time-varying background fields can lead to phase modulation between k-space lines, and therefore TE-dependent ghosting artefacts. [Navigator](https://www.sciencedirect.com/science/article/pii/S1053811910003356?via%3Dihub) readouts in the k-space center can be used to measure the intensity of the filed fluctuations allowing to demodulate the acquired signal before the image reconstruction. The standard navigator-based correction was developed for brain imaging and it is not robust when applied in other areas e.g. the spinal cord. When failing the correction can even exhacerbate the artifacts. This package provides optimised post-processing pipelines to correct for dynamic field instabilities in GRE sequences. For additional information read the [Navigator-based correction pipelines](@ref) section.
 
 ## Plotting
-`MRINavigator` is not depending on a particular plotting package since there
-are various plotting packages available in Julia.
+`MRINavigator` is not depending on a particular plotting package since there are various plotting packages available in Julia.
 
 ## Acknowledgements
 This package uses the reconstruction functions and data structures available in [MRIReco.jl](https://github.com/MagneticResonanceImaging/MRIReco.jl).

src/NavParameters.jl

@@ -27,7 +27,7 @@ Define default parameters for data loading, navigator correction and image recon
 * `path_niftiMap::String`             - path to the file where the reconstructed reference data will be saved in nifti format. The file extension must be .nii
 * `path_centerline::String`           - path to the folder where the Spinal Cord Toolbox (SCT) centerline results will be saved
 * `path_physio::String`              - path to the physiological trace recording in .mat format. The variable should be a two columns vector (1:time [ms], 2:trace).
-                                        The time should be expressed in seconds from the beginning of the day and contains time points befroe and after the image acquisiton (at least 2 s).
+                                        The time should be expressed in seconds from the beginning of the day and contain time points before and after the image acquisiton (at least 4 s).
 
 ISMRMRD reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.26089
 SCT reference: https://spinalcordtoolbox.com