JOSS review - Hessam comments

README.md

@@ -4,7 +4,7 @@
 </p>
 
 [![CI](https://github.com/aris-mav/NMRInversions.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/aris-mav/NMRInversions.jl/actions/workflows/CI.yml)
-
+[![status](https://joss.theoj.org/papers/ad59c8b34ac785bfdff155d4e579a086/status.svg)](https://joss.theoj.org/papers/ad59c8b34ac785bfdff155d4e579a086)
 
 This package can be used to easily perform numerical inversions for 1D and 2D NMR relaxation and diffusion measurements.
 

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"

docs/make.jl

@@ -1,5 +1,12 @@
 using Documenter, NMRInversions, GLMakie
 
+using DocumenterCitations
+
+bib = CitationBibliography(
+    joinpath(@__DIR__, "src", "refs.bib");
+    style=:numeric
+)
+
 makedocs(sitename="NMRInversions.jl",
          authors = "Aristarchos Mavridis",
 
@@ -18,7 +25,11 @@ makedocs(sitename="NMRInversions.jl",
                 "Saving data" => "savefiles.md",
                 "References" => "references.md"
                ],
-         checkdocs=:none
+         checkdocs=:none,
+         format = Documenter.HTML(
+         assets=String["assets/citations.css"],
+         ),
+         plugins=[bib]
         )
 
 deploydocs(

docs/src/assets/citations.css

@@ -0,0 +1,18 @@
+.citation dl {
+  display: grid;
+  grid-template-columns: max-content auto; }
+.citation dt {
+  grid-column-start: 1; }
+.citation dd {
+  grid-column-start: 2;
+  margin-bottom: 0.75em; }
+.citation ul {
+ padding: 0 0 2.25em 0;
+ margin: 0;
+ list-style: none !important;}
+.citation ul li {
+ text-indent: -2.25em;
+ margin: 0.33em 0.5em 0.5em 2.25em;}
+.citation ol li {
+ padding-left:0.75em;}
+

docs/src/functions.md

@@ -1,16 +1,15 @@
-# Functions
 This page contains the documentation for various useful 
 functions in the NMRInversions package.
 
 !!! tip
-    From the julia command line, you can enter '?', 
+    From the Julia command line, you can enter '?', 
     followed by the name of any function, struct, 
     or object you want to learn more about (try it!).
-    After typing `using NMRInversions` in the julia console, 
+    After typing `using NMRInversions` in the Julia console, 
     this feature will work for all the functions mentioned below.
 
 !!! info 
-    In julia, function definitions look like this:
+    In Julia, function definitions look like this:
     ```
     foo(x, y, z ; a, b)
     ``` 
@@ -41,7 +40,7 @@ functions in the NMRInversions package.
     but the name of each argument must be specified.
     For more information, please refer to [this link](https://docs.julialang.org/en/v1/manual/functions/).
 
-# Importing data functions
+## Importing data 
 This package offers some functions to import NMR experiment data of various formats.
 Alternatively, you can of course import your data however you see fit.
 If a format you're working with is not yet supported, 
@@ -76,7 +75,7 @@ import_geospec(::String)
 ```
 
 
-# Inversion functions
+## Inversion 
 The most important function is `invert()`, which is the main function of the package.
 It works as follows:
 
@@ -85,7 +84,7 @@ invert(::Type{<:pulse_sequence1D}, ::AbstractArray, ::Vector)
 invert(::input1D)
 ```
 
-Due to julia's multiple dispatch, 
+Due to Julia's multiple dispatch, 
 it is possible to define a function with the same name
 but different arguments, to achieve different results.
 
@@ -98,7 +97,7 @@ invert(::Type{<:pulse_sequence2D}, ::AbstractVector, ::AbstractVector, ::Abstrac
 invert(::input2D)
 ```
 
-# Finding alpha
+## Finding alpha
 Here we provide two options for finding the optimal value for alpha, 
 namely Generalized Cross Validation (GCV) or L-curve. 
 Generally gcv seems slightly more reliable in NMR, but it's far from 
@@ -115,13 +114,13 @@ lcurve(::Real; kwargs...)
 lcurve(::Real, ::Real ; kwargs...)
 ```
 
-The `gcv()` method (from Mithcell 2012) usually involves the least amount of 
+The `gcv()` method [Mitchell2012](@cite) usually involves the least amount of 
 function calls and it is thus much faster, thus used as the default option.
 If you want more precision, the univariate or box methods should be used instead.
 Note that `gcv()` will NOT work for `pdhgm()` solver, so you'll have to choose 
 an alternative explicitly when using that solver.
 
-# Exponential fit functions
+## Exponential fits 
 
 For 1D data, we can use the `expfit` function to perform multiexponential fits.
 We can use the function by specifying either the number of exponential components,
@@ -139,7 +138,7 @@ it's best to define some starting points close to these.
 
 
 
-# Plotting functions
+## Plotting 
 
 This package offers plotting capabilities, using its GLMakie extension.
 Simply use `using GLMakie` before or after `using NMRInversions`
@@ -175,7 +174,7 @@ plot(::NMRInversions.expfit_struct)
 plot!(::Union{Makie.Figure,Makie.GridPosition}, ::NMRInversions.expfit_struct )
 ```
 
-# Miscellaneous functions
+## Miscellaneous 
 
 Once you have selected some peaks in your inversion results through the GUI,
 you might want to extract the weighted averages of these selected peaks,

docs/src/index.md

@@ -1,52 +1,39 @@
-Welcome to the NMRInversions.jl package!
+Welcome to NMRInversions.jl!
+
+The goal is to provide an easy-to-use interface to process NMR 
+relaxation and diffusion data, completely free/open-source, and fully 
+written in Julia.
+
+Functionality includes :
+- Importing NMR data from various instrument manufacturers.
+- Performing numerical inversions and exponential fits with sensible default settings.
+- Interactive visualization of results, through the GLMakie extension.
+
+Who would want to use this package :
+- Researchers in chemistry, physics, and materials science who rely on NMR 
+  to study molecular dynamics, diffusion and interactions. 
+  NMRInversions.jl simplifies the process of data analysis, allowing researchers 
+  to focus on their scientific questions rather than the intricacies of data processing.
+- Professionals in various fields such as food science, subsurface applications, 
+  or materials engineering can utilize this package to analyze NMR data for quality 
+  control, product development, and research purposes. 
+- Students learning about NMR techniques can benefit from a straightforward tool 
+  that helps them understand data processing and analysis. 
+  Educators can use the package as a teaching aid in courses related to NMR or 
+  inverse problems.
 
 Hopefully this documentation will provide all the information you need to get started.
 
-!!! info "Installing julia"
-    You can download the julia programming language by following [this link](https://julialang.org/downloads/).
-    Afterwards, you can either use the julia console (aka REPL) 
-    by finding the julia .exe file in your computer, or you can use VScode,
-    which provides an environment similar to MATLAB with the use of the 
-    [julia extension](https://www.julia-vscode.org/)
-    (follow link for installation instructions). 
-    Of course, if you already have a preferred development workflow 
-    and you know what you're doing, by all means go for it.
-
-!!! info "Installing the package"
-    The package can be installed by running the following command on the julia console:
-    ```
-    using Pkg ; Pkg.add("NMRInversions")
-    ```
-    This usually takes a while, but it needs to be done only once 
-    (unless you swap environment, more on that 
-    [here](https://pkgdocs.julialang.org/v1/environments/)).
-
-    Afterwards, you can use the package by running 
-    ```
-    using NMRInversions
-    ```
-    in your julia console, every time you start a new session.
-
-
-    Whenever a new version comes up, you can run:
-    ```
-    using Pkg ; Pkg.update("NMRInversions")
-    ```
-    to update the package.
-
-!!! info "GLMakie extension"
-    The package provides an extension for interactive visualization,
-    using the GLMakie package. To gain access to these capabilities,
-    you also need to install GLMakie:
-    ```
-    using Pkg ; Pkg.add("GLMakie")
-    ```
-    And to use it, you need to run
-    ```
-    using GLMakie
-    ```
-    in order to access the plotting functions.
-
-
-For more details on how to use the package, you can start by refering to the [tutorial](tutorial.md) section.
-
+- The [Theory](theory.md) section should provide some info on what the package is really about.
+- For more details on how to use it, you can start by refering to the examples in the  
+  [tutorial](tutorial.md).
+- To understand how things really work, have a look at the 
+  [Functions](functions.md) and [Types and Structures](types_structs.md) sections.
+- If you have any problems or questions, please feel free to 
+  [submit an issue](https://github.com/aris-mav/NMRInversions.jl/issues).
+- If you would like to contribute to the package, you may start with one of 
+  the [existing issues](https://github.com/aris-mav/NMRInversions.jl/issues).
+  Please feel free to create a [pull request](https://docs.github.com/en/pull-requests)
+  if you'd like to implement a feature, or start a 
+  [discussion](https://github.com/aris-mav/NMRInversions.jl/discussions) 
+  if you're unsure about anything or need further guidance.

docs/src/installation.md

@@ -0,0 +1,44 @@
+!!! info "Installing Julia"
+    You can download the Julia programming language by following [this link](https://Julialang.org/downloads/).
+    Afterwards, you can either use the Julia console (aka REPL) 
+    by finding the Julia .exe file in your computer, or you can use VScode,
+    which provides an environment similar to MATLAB with the use of the 
+    [Julia extension](https://www.Julia-vscode.org/)
+    (follow link for installation instructions). 
+    Of course, if you already have a preferred development workflow 
+    and you know what you're doing, by all means go for it.
+
+!!! info "Installing the package"
+    The package can be installed by running the following command on the Julia console:
+    ```
+    using Pkg ; Pkg.add("NMRInversions")
+    ```
+    This usually takes a while, but it needs to be done only once 
+    (unless you swap environment, more on that 
+    [here](https://pkgdocs.Julialang.org/v1/environments/)).
+
+    Afterwards, you can use the package by running 
+    ```
+    using NMRInversions
+    ```
+    in your Julia console, every time you start a new session.
+
+
+    Whenever a new version comes up, you can run:
+    ```
+    using Pkg ; Pkg.update("NMRInversions")
+    ```
+    to update the package.
+
+!!! info "GLMakie extension"
+    The package provides an extension for interactive visualization,
+    using the GLMakie package. To gain access to these capabilities,
+    you also need to install GLMakie:
+    ```
+    using Pkg ; Pkg.add("GLMakie")
+    ```
+    And to use it, you need to run
+    ```
+    using GLMakie
+    ```
+    in order to access the plotting functions.

docs/src/references.md

@@ -0,0 +1,2 @@
+```@bibliography
+```

docs/src/refs.bib

@@ -0,0 +1,111 @@
+@article{bezanson2017julia,
+    title={Julia: A fresh approach to numerical computing},
+    author={Bezanson, Jeff and Edelman, Alan and Karpinski, Stefan and Shah, Viral B},
+    journal={SIAM review},
+    volume={59},
+    number={1},
+    pages={65--98},
+    year={2017},
+    publisher={SIAM},
+    doi={10.1137/141000671}
+}
+
+@article{Fordham2017,
+    author = {Fordham, Edmund and Venkataramanan, Lalitha and Mitchell, Jonathan and Valori, Andrea},
+    year = {2017},
+    month = {10},
+    pages = {},
+    title = {What are, and what are not, Inverse Laplace Transforms},
+    volume = {29},
+    journal = {Diffusion Fundamentals},
+    doi = {10.62721/diffusion-fundamentals.29.952}
+}
+
+
+@article{Mitchell2012,
+    author = {Mitchell, Jonathan and Chandrasekera, T.C. and Gladden, L.F.},
+    year = {2012},
+    month = {04},
+    pages = {34-50},
+    title = {Numerical estimation of relaxation and diffusion distributions in two dimensions},
+    volume = {62},
+    journal = {Progress in nuclear magnetic resonance spectroscopy},
+    doi = {10.1016/j.pnmrs.2011.07.002}
+} 
+
+
+@book{Hansen2010, 
+    title={Discrete inverse problems: Insight and algorithms}, 
+    publisher={Society for Industrial and Applied Mathematics}, 
+    author={Hansen, Per Christian}, 
+    year={2010}
+}
+
+@article{BPP,
+  title = {Relaxation Effects in Nuclear Magnetic Resonance Absorption},
+  author = {Bloembergen, N. and Purcell, E. M. and Pound, R. V.},
+  journal = {Phys. Rev.},
+  volume = {73},
+  issue = {7},
+  pages = {679--712},
+  year = {1948},
+  month = {Apr},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRev.73.679},
+}
+
+@article{Chand2018,
+  title = {Numerical inversion methods for recovering negative amplitudes in two-dimensional nuclear magnetic resonance relaxation-time correlations},
+  author = {Chandrasekera, Thusara C. and Mitchell, Jonathan},
+  journal = {Phys. Rev. E},
+  volume = {98},
+  issue = {4},
+  pages = {043308},
+  numpages = {19},
+  year = {2018},
+  month = {Oct},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevE.98.043308},
+  url = {https://link.aps.org/doi/10.1103/PhysRevE.98.043308}
+}
+
+@article{Song2002,
+    title = {T1–T2 Correlation Spectra Obtained Using a Fast Two-Dimensional Laplace Inversion},
+    journal = {Journal of Magnetic Resonance},
+    volume = {154},
+    number = {2},
+    pages = {261-268},
+    year = {2002},
+    issn = {1090-7807},
+    doi = {https://doi.org/10.1006/jmre.2001.2474},
+    url = {https://www.sciencedirect.com/science/article/pii/S1090780701924747},
+    author = {Y.-Q. Song and L. Venkataramanan and M.D. Hürlimann and M. Flaum and P. Frulla and C. Straley},
+    abstract = {Spin relaxation is a sensitive probe of molecular structure and dynamics. Correlation of relaxation time constants, such as T1 and T2, conceptually similar to the conventional multidimensional spectroscopy, have been difficult to determine primarily due to the absense of an efficient multidimensional Laplace inversion program. We demonstrate the use of a novel computer algorithm for fast two-dimensional inverse Laplace transformation to obtain T1–T2 correlation functions. The algorithm efficiently performs a least-squares fit on two-dimensional data with a nonnegativity constraint. We use a regularization method to find a balance between the residual fitting errors and the known noise amplitude, thus producing a result that is found to be stable in the presence of noise. This algorithm can be extended to include functional forms other than exponential kernels. We demonstrate the performance of the algorithm at different signal-to-noise ratios and with different T1–T2 spectral characteristics using several brine-saturated rock samples.}
+}
+
+@article{Reci2017,
+    title = {Obtaining sparse distributions in 2D inverse problems},
+    journal = {Journal of Magnetic Resonance},
+    volume = {281},
+    pages = {188-198},
+    year = {2017},
+    issn = {1090-7807},
+    doi = {https://doi.org/10.1016/j.jmr.2017.05.010},
+    url = {https://www.sciencedirect.com/science/article/pii/S1090780717301362},
+    author = {A. Reci and A.J. Sederman and L.F. Gladden},
+    keywords = { regularization, Inverse problems, 2D NMR correlation experiments, 2D inverse Laplace transformation},
+    abstract = {The mathematics of inverse problems has relevance across numerous estimation problems in science and engineering. L1 regularization has attracted recent attention in reconstructing the system properties in the case of sparse inverse problems; i.e., when the true property sought is not adequately described by a continuous distribution, in particular in Compressed Sensing image reconstruction. In this work, we focus on the application of L1 regularization to a class of inverse problems; relaxation-relaxation, T1–T2, and diffusion-relaxation, D–T2, correlation experiments in NMR, which have found widespread applications in a number of areas including probing surface interactions in catalysis and characterizing fluid composition and pore structures in rocks. We introduce a robust algorithm for solving the L1 regularization problem and provide a guide to implementing it, including the choice of the amount of regularization used and the assignment of error estimates. We then show experimentally that L1 regularization has significant advantages over both the Non-Negative Least Squares (NNLS) algorithm and Tikhonov regularization. It is shown that the L1 regularization algorithm stably recovers a distribution at a signal to noise ratio<20 and that it resolves relaxation time constants and diffusion coefficients differing by as little as 10%. The enhanced resolving capability is used to measure the inter and intra particle concentrations of a mixture of hexane and dodecane present within porous silica beads immersed within a bulk liquid phase; neither NNLS nor Tikhonov regularization are able to provide this resolution. This experimental study shows that the approach enables discrimination between different chemical species when direct spectroscopic discrimination is impossible, and hence measurement of chemical composition within porous media, such as catalysts or rocks, is possible while still being stable to high levels of noise.}
+}
+
+@ARTICLE{Venka2002,
+  author={Venkataramanan, L. and Yi-Qiao Song and Hurlimann, M.D.},
+  journal={IEEE Transactions on Signal Processing}, 
+  title={Solving Fredholm integrals of the first kind with tensor product structure in 2 and 2.5 dimensions}, 
+  year={2002},
+  volume={50},
+  number={5},
+  pages={1017-1026},
+  keywords={Tensile stress;Kernel;Density functional theory;Nuclear magnetic resonance;Constraint optimization;Random variables;Image restoration;Magnetic field measurement;Gaussian noise;Additive noise},
+  doi={10.1109/78.995059}
+}
+