Merge pull request #37 from arismavridis/dev

merge dev

.github/workflows/CI.yml

@@ -1,41 +1,41 @@
-# name: CI
-# on:
-#   push:
-#     branches:
-#       - master
-#     tags: ['*']
-#   pull_request:
-#   workflow_dispatch:
-# concurrency:
-#   # Skip intermediate builds: always.
-#   # Cancel intermediate builds: only if it is a pull request build.
-#   group: ${{ github.workflow }}-${{ github.ref }}
-#   cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
-# jobs:
-#   test:
-#     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
-#     runs-on: ${{ matrix.os }}
-#     timeout-minutes: 60
-#     permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
-#       actions: write
-#       contents: read
-#     strategy:
-#       fail-fast: false
-#       matrix:
-#         version:
-#           - '1.10'
-#           - '1.6'
-#           - 'pre'
-#         os:
-#           - ubuntu-latest
-#         arch:
-#           - x64
-#     steps:
-#       - uses: actions/checkout@v4
-#       - uses: julia-actions/setup-julia@v2
-#         with:
-#           version: ${{ matrix.version }}
-#           arch: ${{ matrix.arch }}
-#       - uses: julia-actions/cache@v2
-#       - uses: julia-actions/julia-buildpkg@v1
-#       - uses: julia-actions/julia-runtest@v1
+name: CI
+on:
+  push:
+    branches:
+      - master
+    tags: ['*']
+  pull_request:
+  workflow_dispatch:
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
+      actions: write
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.10'
+          - '1.6'
+          - 'pre'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1

.gitignore

@@ -1,3 +1,5 @@
 /Manifest.toml
 test.jl
 
+docs/Manifest.toml
+docs/build

README.md

@@ -1,14 +1,12 @@
 # NMRInversions.jl
 <p align="center">
-    <img width=450 src="./logo/logo.svg"/>
+    <img width=400 src="./logo/logo.svg"/>
 </p>
 
 This package can be used to easily perform numerical inversions for 1D and 2D NMR relaxation and diffusion measurements.
 
-The default method is Tikhonov regularization, where the optimal smoothing term is determinded through generalized cross-validation, as described in [Mitchell et al 2012](https://doi.org/10.1016/j.pnmrs.2011.07.002).
+A GUI is implemented as an extension through the use of the [GLMakie](https://github.com/MakieOrg/Makie.jl) package, which enables interactive visualisation for 2D NMR maps.
 
-A GUI is implemented as an extension through the use of the [GLMakie](https://github.com/MakieOrg/Makie.jl) package, which enables interactive visualisation for 2D NMR experiments.
-
-For more details, please refer to the documentation.
+For more details, please refer to the documentation (link coming soon!).
 
 If you have any problems or questions, please feel free to [submit an issue](https://github.com/arismavridis/NMRInversions.jl/issues).

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,11 @@
+using Documenter, NMRInversions
+
+makedocs(sitename="NMRInversions.jl",
+    pages=["Overview" => "index.md",
+        "Tutorial" => "tutorial.md",
+        "Theory" => "theory.md",
+        "Types and Functions" => "functions.md"
+    ]
+)
+
+

docs/src/functions.md

@@ -0,0 +1 @@
+This page contains the documentation for various useful functions that can be used.

docs/src/index.md

@@ -0,0 +1,16 @@
+Welcome to the NMRInversions.jl package!
+
+Hopefully this documentation will provide all the information you need to get started.
+
+You can download the Julia programming language by following [this link](https://julialang.org/downloads/).
+Afterwards, you can either use the 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.
+
+The package can be installed by running the following command on the julia console:
+```
+using Pkg ; Pkg.add("NMRInversions")
+```
+This needs to be done only once (unless you swap environment, more on that [here](https://pkgdocs.julialang.org/v1/environments/)).
+

docs/src/tutorial.md

@@ -0,0 +1,69 @@
+Here are some examples on how to use the package.
+
+# 1D inversion
+Suppose we would like to perform an inversion for a CPMG experiment.
+We need some data to work with, so let's create some.
+
+```julia
+using NMRInversions
+
+# Define the experiment's time acquisition range (in seconds)
+x = collect(range(0.0001,2,500)) 
+
+# Range of relaxation times
+X = exp10.(range(-5, 1, 128)) 
+
+# Create a kernel matrix
+K = create_kernel(CPMG, x, X) 
+
+# Create a distribution of relaxation times
+f_custom = [0.5exp.(-(x)^2 / 3) + exp.(-(x - 1.3)^2 / 0.5) for x in range(-5, 5, length(X))]
+
+# Use the "forward problem" to create the NMR signal from the T2 distribution
+g = K * f_custom
+
+# Add some noise to the data
+y = g + 0.005 * maximum(g) .* randn(length(x))
+```
+
+Now we have the data, the inversion can be performed using a single line of code!
+
+```julia
+results = invert(CPMG, x, y, alpha=gcv)
+```
+
+And the results can easily be visualised through the GLMakie extension of the package.
+
+```julia
+using GLMakie
+plot(results)
+```
+
+The `results` variable is an `inv_out_1D` structure, which contains all the relevant information produced by the `inversion` function.
+To access that information, we can look at the fields of the structure using the dot notation.
+The field names can be shown by using the REPL help mode (typing ? at the julia> prompt), 
+and typing the variable's name (in this case ?results). 
+Alternatively, running `@doc results` will also give you the same answers.
+For example, the vector of values for the relaxation time distribution can be accessed as `results.f`
+and the regularization parameter can be accessed as `results.alpha`.
+
+In the example above, the arguments we fed into the `invert()` function were the pulse sequence, 
+the time values, and the NMR signal corresponding to each time value. 
+Importing data using function such as `import_spinsolve` make things simpler, 
+since they return an `input1D` structure which can be used directly in the `invert` function as:
+```julia
+invert(import_spinsolve())
+```
+
+# 2D inversion
+Let's try with a T1-T2 experiment, using the IR-CPMG sequence.
+Again, we start by creating some data.
+
+
+# Importing data
+
+This package offfers functions to easily import data from various instruments into input1D / input2D structures to be used by the inversion functions.
+
+## Spinsolve format
+## Geospec format
+## Stelar format