JOSS review - Hessam comments (#57)

* typos addressed

* add installation section

* add installation section

* capitalize julia to Julia

* added plots documentation

* added joss status

* paper edits

* added expfit plot

* typo

* added references

* typo

* improved headings

* added goals and how to contribute in overview

* added why we need inversions

* added harminv clarification

* added target audience

Author: aris-mav

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/1D_gui.png

@@ -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/assets/2D_gui.png

@@ -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/assets/citations.css

@@ -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.