open-AIMS · ConnectedSystems · Jan 5, 2023 · Dec 22, 2022 · Dec 22, 2022 · Dec 20, 2022
diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
@@ -0,0 +1,5 @@
+Before submitting the Pull Request, check that:
+
+- [ ] Relevant files auto-formatted
+- [ ] All debug packages and references (`@infiltrate`, `using Revise`, etc) removed
+- [ ] If relevant, tests pass locally
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -5,8 +5,6 @@ on:
     branches:
       - main  # update to match your development branch (master, main, dev, trunk, ...)
     tags: '*'
-  pull_request:
-
 jobs:
   build:
     permissions:

diff --git a/Aviz/src/analysis.jl b/Aviz/src/analysis.jl
@@ -1,7 +1,8 @@
-import ADRIA.sensitivity: pawn, relative_importance
+import ADRIA.analysis: normalize
+import ADRIA.sensitivity: pawn
 
 
 function relative_sensitivities(X, y; S=10, stat=:median)::Vector{Float64}
-    return relative_importance(pawn(X, Array(y); S=S)[:, stat])
+    return normalize(pawn(X, Array(y); S=S)[:, stat])
 end
 
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "ADRIA"
 uuid = "7dc409a7-fbe5-4c9d-b3e2-b0c19a6ba600"
 authors = ["Takuya Iwanaga", "Rose Crocker", "Ken Anthony"]
-version = "0.4.3"
+version = "0.4.4"
 
 [deps]
 ArchGDAL = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"
@@ -85,6 +85,7 @@ OnlineStats = "1.5"
 PkgVersion = "0.2, 0.3"
 ProgressMeter = "1"
 RelocatableFolders = "1"
+Requires = "1"
 SciMLBase = "1"
 Setfield = "0.8, 1"
 SnoopPrecompile = "1"

diff --git a/docs/make.jl b/docs/make.jl
@@ -11,6 +11,7 @@ makedocs(sitename="ADRIA Documentation",
     pages=[
         "index.md",
         "synopsis.md",
+        "usage.md",
         "dMCDA.md",
         # "Examples" => [
         #     "Usage" => [
@@ -31,5 +32,5 @@ deploydocs(
     repo="github.com/open-AIMS/ADRIA.jl.git",
     devbranch="main",
     target="build",
-    push_preview=true
+    push_preview=false
 )
diff --git a/docs/src/API.md b/docs/src/API.md
@@ -5,6 +5,7 @@
 ```@autodocs
 Modules = [ADRIA.metrics]
 Order   = [:function, :type]
+Private = false
 ```
 
 ## Performance indicators
@@ -26,5 +27,6 @@ Order   = [:function, :type]
 ```@autodocs
 Modules = [ADRIA]
 Order   = [:function, :type]
+Private = false
 ```
 
diff --git a/docs/src/development/building_docs.md b/docs/src/development/building_docs.md
@@ -1,10 +1,29 @@
 # Building Documentation
 
+ADRIA documentation is built using [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).
+
+
 ## Building documentation locally
 
 From the ADRIA project directory:
 
 ```bash
 $ cd docs
 $ julia --project=. make.jl
-```
+```
+
+Locally generated documentation can be found under `docs/build`. Open the `index.html` file with any web browser.
+
+
+## Documentation deployment
+
+Documentation is hosted on [GitHub Pages](https://pages.github.com/) via [GitHub Actions](https://github.com/features/actions).
+
+Configuration is found [here](https://github.com/open-AIMS/ADRIA.jl/blob/main/.github/workflows/documentation.yml).
+
+Documentation is automatically built and deployed:
+
+- When a PR targeting `main` is submitted  
+  In this case, a preview URL is created: e.g., a URL with `previews/PR###` at the end, where `PR###` refers to the PR ID.
+- On commit/merge to `main`  
+  In this case the main documentation website is updated
diff --git a/docs/src/development/development_setup.md b/docs/src/development/development_setup.md
@@ -1,5 +1,9 @@
 # Development setup
 
+First, clone the repository.
+
+Then navigate to the project folder and start Julia.
+
 ```bash
 # Start julia specifying the current directory as the project
 $ julia --project=.
@@ -28,7 +32,10 @@ julia> ]activate .
 # Press ctrl+c to exit the package manager
 ```
 
-Development scripts/functions can then be worked on in the `sandbox` folder without these polluting the ADRIA project itself.
+Development scripts/functions can then be worked on in the `sandbox` folder, and its sub-folders, without these polluting the ADRIA project itself.
+
+We recommend [VS Code](https://code.visualstudio.com/) with its Julia extension when developing ADRIA.
+We also recommend the built-in Julia REPL within VS Code be used (see the notes below).
 
 
 ## Testing
@@ -53,10 +60,12 @@ See the documentation [here](https://github.com/open-AIMS/ADRIA.jl/tree/main/bui
 Note: compilation time to create a sysimage can be upwards of 30mins, and has to be repeated if the included packages are to be updated.
 
 !!! note "VS Code"
-    VS Code now has (experimental support) for generating a custom sysimage for its REPL.
-    The same caveats as above apply (it has to be recreated if the project specification has changed for any reason).
+    VS Code now has (experimental) support for generating a custom sysimage for its REPL.
+    The same caveats as above apply: the sysimage has to be recreated if the project specification has changed for any reason.
+
+    It is highly recommended that this sysimage be built and used.
 
-    See: https://www.julia-vscode.org/docs/dev/userguide/compilesysimage/
+    See: [This guide](https://www.julia-vscode.org/docs/dev/userguide/compilesysimage/)
 
 
 ```julia

diff --git a/docs/src/development/release_guide.md b/docs/src/development/release_guide.md
@@ -7,14 +7,32 @@
 3. Submit PR from development branch into `main` and request code review/approval
 4. Once PR is merged into main, go to the [releases page](https://github.com/open-AIMS/ADRIA.jl/releases) and draft a new release
 5. Under "choose a tag" create a new tag "on publish"  
-   Note version numbers should follow Semantic Versioning: https://semver.org/
+   Note version numbers should follow [Semantic Versioning](https://semver.org/)
 6. Click the "Generate release notes" button (top-right of textbox).  
    Under "Whats new" add a short description of the major changes.  
    Explicitly note any major breaking changes (i.e., anything that results obtained with previous versions of ADRIA incompatible)
 7. Release title should match the version number.
 
 Click "Publish release" (green button at the bottom)
 
+Finally, register the updated package with the Julia registry by:
+
+1. Opening a new issue. The title can be anything, but something along the lines of "Register [version number]"  
+   e.g., Register v1.0
+2. State in the comment: `@JuliaRegistrator register`  
+
+Release notes should also be included when appropriate, like so:
+
+```
+@JuliaRegistrator register
+
+Release notes:
+
+Some details of new features!
+```
+
+See Julia Registrator usage notes [here](https://github.com/JuliaComputing/Registrator.jl?installation_id=32448289&setup_action=install#details-for-triggering-juliaregistrator-for-step-2-above) for more details.
+
 
 ## Development Release
 
@@ -25,7 +43,7 @@ Deploying a Development Release follows the same steps as "Public" releases, exc
 
 1. Add "-dev.x" to the version number.  
    e.g., v1.2.3-dev.1; v1.2.3-dev.2 for the second development release, etc.
-2. Untick the "Set as the latest release" option and tick the "Set as a pre-release" option.
+2. Untick "Set as the latest release" and tick the "Set as a pre-release" option.
 
 
 ## Release Candidates
@@ -37,5 +55,5 @@ Deploying a Release Candidate follows the same steps as "Public" releases, excep
 
 1. Add "-rc.x" to the version number.  
    e.g., v1.2.3-rc.1; v1.2.3-rc.2 for the second release candidate, etc.
-2. Untick the "Set as the latest release" option and tick the "Set as a pre-release" option.
+2. Untick "Set as the latest release" and tick the "Set as a pre-release" option.
 
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -12,7 +12,7 @@ To specify user-specific options, a `config.toml` file should be created with th
 ```toml
 [operation]
 num_cores = 2     # No. of cores to use. Values <= 0 will use all available cores.
-threshold = 1e-6  # Result values below this will be set to 0.0
+threshold = 1e-8  # Result values below this will be set to 0.0 (to save disk space)
 debug = false     # Disable multi-processing to allow error messages to be shown
 
 [results]

diff --git a/docs/src/synopsis.md b/docs/src/synopsis.md
@@ -9,7 +9,7 @@ Deciding where, when, and how to intervene – if at all - using new reef restor
 
 To help reef modellers, decision-support teams and reef managers address these questions, AIMS has developed the Adaptive, Dynamic Reef Intervention Algorithm (ADRIA). In short, ADRIA simulates a reef decision maker operating inside the dynamic state space of a coral reef.
 
-For reef managers, ADRIA help provide line of sight to conservation solutions in complex settings where multiple objectives need to be considered. For investors, ADRIA helps analysts identify which options (R&D and/or deployment solutions) might have the highest likelihood of providing ecological and social returns on investment. While ADRIA’s key function is as a decision-support tool for intervention deployment, it uses a simple proxy model for reef coral dynamics, consisting of vital rates parameterised in a set of linked differential equations for four coral groups. The growth, mortality and recruitment of those four coral groups are further parameterised by environmental drivers and by different restoration and adaptation interventions.
+For reef managers, ADRIA help provide line of sight to conservation solutions in complex settings where multiple objectives need to be considered. For investors, ADRIA helps analysts identify which options (R&D and/or deployment solutions) might have the highest likelihood of providing ecological and social returns on investment across a range of considered environmental conditions. While ADRIA’s key function is as a decision-support tool for intervention deployment, it uses a simple proxy model for reef coral dynamics, consisting of vital rates parameterised in a set of linked differential equations for four coral groups. The growth, mortality and recruitment of those four coral groups are further parameterised by environmental drivers and by different restoration and adaptation interventions.
 
 The primary purpose of ADRIA is to help guide intervention deployment such that net benefits are maximised against primary objectives and minimised against costs. Solutions can be tuned (eventually optimised) via heuristics that control the selection of sites and/or reefs and the prioritisation of species, ecosystem services or benefits that favour what people (society) want. The key benefits considered in ADRIA are consistent with a triple-bottom-line approach, i.e.