Documentation development

docs/basic.md

@@ -1,43 +1,21 @@
+## Running *Nomadic*
+Whenever you want to run *Nomadic*, first do the following:
 
-## Quick summary
+- Make sure you have installed *Nomadic* from bioconda(see [Installation](installation.md)). 
 
-To run *Nomadic*, open a terminal window and type the following:
+- Open a terminal window and activate the *Nomadic* environment:
 
 ```
 conda activate nomadic
-cd <path/to/your/workspace>
-nomadic realtime <expt_name>
 ```
 
-- `<path/to/your/workspace>` should be replaced with the path to your *Nomadic* workspace.
-- `<expt_name>` should be replaced with the name of your experiment.
-    - You should have given your experiment the same name in *MinKNOW*.
-    - You should have given your metadata file this name, and put it in your workspace metadata folder (`<path/to/your/workspace>/metadata/<expt_name>.csv`).
-
-The dashboard will open in a browser window on your computer. 
-
-<!-- 1. Create a workspace if you have not already (`nomadic start pfalciparum`).
-2. Pick an experiment name (e.g. `2025-06-21_first-sequencing`)
-3. Start your sequencing run with *MinKNOW* using your experiment name.
-4. Put your metadata file in the `metadata` folder in your *Nomadic* workspace. Name the file with your experiment name (e.g. `2025-06-21_first-sequencing.csv`).
-5. Start *Nomadic*: `nomadic realtime 2025-06-21_first-sequencing` -->
-
-
-
----
-## Detailed instructions
-
-### Before starting
-Before starting make sure you have installed *Nomadic* (see [Installation](installation.md)). 
-
-Then, open a terminal window and activate the *Nomadic* environment:
+- Navigate to your workspace (or location you want to create one - see next section)
 
 ```
-conda activate nomadic
+cd path/to/your/workspace
 ```
 
-
-### Starting a workspace
+## Starting a workspace
 
 *Nomadic* creates workspaces to help organise your input data and analysis results. A workspace is just a folder on your computer where all of the input data needed to run *Nomadic*, as well as your analysis results, are stored. You can create a workspace with the following command:
 
@@ -51,7 +29,7 @@ By default the name of the new workspace is `nomadic`. You can enter the workspa
 cd nomadic
 ```
 
-Inside of the workspace, you should see the following folders:
+Inside the workspace, you should see the following folders:
 
 | Folder | Contents |
 | --- | --- |
@@ -60,76 +38,39 @@ Inside of the workspace, you should see the following folders:
 | `results` | Where the results from running *Nomadic* will go. Initially it will be empty. |
 
 
-### Using *Nomadic* for real-time analysis
-*Nomadic* can process nanopore squencing data being produced by *MinKNOW* in real-time. To do so, follow the steps below.
+## Analysing a sequencing run in realtime
+*Nomadic* can process nanopore squencing data being produced by *MinKNOW* in real-time. To do so, follow the steps below (steps 1 and 2 can be done in any order):
 
-**Step 1: Start nanopore sequencing with *MinKNOW***
-
-Use *MinKNOW* to start nanopore sequencing. Make sure to take note of the experiment name, you will need this in later steps.
-
-
-**Step 2: Create a metadata file**
-
-Create a metadata file containing information about what barcodes you have used and their associated sample IDs. Here is an example:
+**Step 1: Create a metadata file**
 
+Create a metadata file containing information about what barcodes you used in the sequencing library and their associated sample IDs. You can do this by manually entering values into a csv (comma separated value) file:
 
 ![metadata](img/basic/metadata.png){ .centered width="75%" }
 
 Only the `barcode` and `sample_id` columns are mandatory. The rest are optional, and you are also free to include any other columns you like.
 
-Move your metadata file into the metadata folder of your *Nomadic* workspace, and give it the same experiment name you used with *MinKNOW* (`<path/to/your/workspace>/metadata/<expt_name>.csv`).
-
+Alternatively you can complete the Excel template ("NOMADS_Library_Worksheet.xlsx", stored in the metadata folder). The sheet guides a user through data entry including data validation checks and generates a experiment name that the file should be saved as. Post-PCR gel images can also be saved in this template for future reference.
 
-**Step 3: Run**
+![metadata](img/basic/template.png){ .centered width="105%" }
 
-Open a terminal window and start the nomadic conda environment:
-
-```
-conda activate nomadic
-```
+The csv / excel file must be saved in the *metadata* folder of your workspace.
 
-Now navigate to your workspace folder:
+**Step 2: Start nanopore sequencing with *MinKNOW***
 
-```
-cd <path/to/your/workspace>
-```
+Use *MinKNOW* to start nanopore sequencing. Ensure you give *MinKNOW* the **exact** experiment name you gave your metadata file.
 
-And launch *Nomadic*:
+**Step 3: Start *Nomadic***
 
+Launch *Nomadic* to start analysis, the dashboard will open in a browser window on your computer:
 
 ```
 nomadic realtime <expt_name>
 ```
 
-The dashboard will open in a browser window on your computer. 
-
-### Using *Nomadic* to view a completed experiment
-
-Once an experiment is completed, you can still open the *Nomadic* dashboard to view your results.
-
-**Step 1. Activate the *Nomadic* environment.**
 
+## Viewing a completed experiment
 
-Open a terminal window and activate the *Nomadic* environment:
-
-```
-conda activate nomadic
-```
-
-**Step 2. Navigate in terminal to your workspace.**
-
-
-If you created your workspace in your home folder, this will simply be:
-```
-cd <path/to/your/workspace>
-```
-
-**Step 3. Open the dashboard.**
-
-
-To open the dashboard of a specific experiment, you only need to know the experiment name. You can then open the dashboard by running:
+Once an experiment is completed, you can still open the *Nomadic* dashboard to view your results by running:
 ```
 nomadic dashboard <expt_name>
-```
-Where you should replace `<expt_name>` with the name of the experiment.
-
+```

docs/css/custom.css

@@ -14,3 +14,27 @@
   margin: 2em auto;
   text-align: center;
 }
+
+/* Section headers (non-clickable parents) */
+.md-nav__title {
+  font-weight: 400;
+}
+
+/* Top-level links (clickable sections WITHOUT children) */
+.md-nav__list > .md-nav__item > .md-nav__link {
+  font-weight: 400;
+}
+
+/* Sub-section links */
+.md-nav__item .md-nav__list .md-nav__link {
+  font-weight: 200;
+  /* text-transform: none; */
+  opacity: 0.85;
+}
+
+/* Visual grouping for nested items */
+.md-nav__item .md-nav__list {
+  margin-left: 0.8rem;
+  padding-left: 0.6rem;
+  border-left: 1px solid rgba(0, 0, 0, 0.08);
+}

docs/faq.md

@@ -1,3 +1,8 @@
 **Can I stop and restart `nomadic realtime`?**
 
 Yes, you can safely stop and restart `nomadic realtime`. The program keeps track of what FASTQ files have been processed, and will continue processing from where it left off.
+
+**Can I run more than one instance of `nomadic` at once?**
+
+Yes, but if the process generates a webpage e.g. `nomadic dashboard` or `nomadic realtime`, only one will be live. You can run multiple instances of anything else e.g. `nomadic process` that doesn't have a dashboard.
+

docs/index.md

@@ -30,7 +30,7 @@ It was designed to work with amplicon sequencing data from the NOMADS-MVP protoc
 ## Features
 - [x] Real-time read mapping with [*Minimap2*](https://github.com/lh3/minimap2).
 - [x] Real-time sample quality control and amplicon coverage evaluation.
-- [x] Real-time variant calling with [*bcftools*](https://github.com/samtools/bcftools). These calls are preleiminary; treat with caution.
+- [x] Real-time variant calling with [*delve*](https://github.com/berndbohmeier/delve).
 - [x] Support for different reference genomes or amplicons panels.
 
 

docs/installation.md

@@ -35,7 +35,7 @@ conda create -c bioconda -n nomadic nomadic
 Or, if you are using _Mamba_:
 
 ```
-mambda create -c bioconda -n nomadic nomadic
+mamba create -c bioconda -n nomadic nomadic
 ```
 
 _Nomadic_ should now be installed in it's own conda environment.
@@ -74,20 +74,13 @@ Commands:
 
 ### Update nomadic
 
-To update _Nomadic_ to the newest version, activate your conda environment:
+To update _Nomadic_ to the newest version, activate your conda environment, and then update nomadic as follows:
 
 ```
 conda activate nomadic
-```
-
-Then type:
-
-```
 conda update nomadic
 ```
 
-to update _Nomadic_.
-
 You can check your installed version with
 
 ```

docs/output_files.md

@@ -71,9 +71,4 @@ Each row contains information about the genotype, depth, quality, and within-sam
 | `wsaf` | Within-sample alternative allele frequency (`ad_alt / (ad_alt + ad_ref)`), where `ad_ref` and `ad_alt` are the depths of the reference and alternative allele. |
 
 
-For more information about variant calling, please see [Understanding the Dashboard](understand.md#preliminary-variant-calling).
-
-## Sharing data
-The results folder for an experiment (`results/<expt_name>`) contains all the outputs from *Nomadic*. 
-
-Only the CSV files starting `summary` and the `metadata` folder are required to relaunch the dashboard with the `nomadic dashboard` command (see [Basic Usage](basic.md)).
+For more information about variant calling, please see [Understanding the Dashboard](understand.md#preliminary-variant-calling).

docs/quick_start.md

@@ -0,0 +1,21 @@
+
+To run *Nomadic* for a sequencing run, open a terminal window and type the following:
+
+```
+conda activate nomadic
+cd <path/to/your/workspace>
+nomadic realtime <expt_name>
+```
+
+- `<path/to/your/workspace>` should be replaced with the path to your *Nomadic* workspace.
+- `<expt_name>` should be replaced with the name of your experiment.
+    - You should have given your experiment the same name in *MinKNOW*.
+    - You should have given your metadata file this name, and put it in your workspace metadata folder (`<path/to/your/workspace>/metadata/<expt_name>.csv|xlsx`).
+
+The dashboard will open in a browser window on your computer. 
+
+<!-- 1. Create a workspace if you have not already (`nomadic start pfalciparum`).
+2. Pick an experiment name (e.g. `2025-06-21_first-sequencing`)
+3. Start your sequencing run with *MinKNOW* using your experiment name.
+4. Put your metadata file in the `metadata` folder in your *Nomadic* workspace. Name the file with your experiment name (e.g. `2025-06-21_first-sequencing.csv`).
+5. Start *Nomadic*: `nomadic realtime 2025-06-21_first-sequencing` -->

docs/share_backup.md

@@ -0,0 +1,38 @@
+## Backing up
+
+To create a complete backup of your workspace e.g. to an external hard disk drive or other location accessible on or from your computer (including an ssh location): 
+
+```
+nomadic backup -t <path/to/your/backup/location>
+```
+
+The backup process will also backup all minknow data so be prepared for it to take a while the first time you run it. At the end you will see a short summary:
+
+
+![metadata](img/backup_share/backup_summary.png){ .centered width="75%" }
+
+
+## Sharing data
+
+The results folder for an experiment (`results/<expt_name>`) contains all the outputs from *Nomadic*. Only the CSV files starting `summary` and the `metadata` folder are required to relaunch the dashboard with the `nomadic dashboard` command (see [Basic Usage](basic.md)). `Nomadic` allows easy sharing of your workspace by copying key summary `Nomadic` and `MinKNOW` files to a new location, e.g. a cloud synchronised folder. 
+
+```
+nomadic share -t <path/to/your/shared/location>
+```
+
+Once shared, `Nomadic` can be run by collaborators and other members of the group as needed.
+
+## Configuring default values
+
+The above settings can be saved per workspace so that you don't need to enter the details each time. To save the configuration do the following:
+
+```
+nomadic configure share -t <path/to/your/backup/location>
+nomadic configure backup -t <path/to/your/shared/location>
+```
+
+Once configured you can omit the `-t` option e.g.
+```
+nomadic share
+nomadic backup
+```

mkdocs.yml

@@ -24,10 +24,13 @@ extra_css:
 nav:
   - Overview: index.md
   - Installation: installation.md
-  - Basic Usage: basic.md
+  - Usage:
+    - Quick Start: quick_start.md
+    - Basic Usage: basic.md
+    - Sharing and Backing up: share_backup.md
+    - Advanced Usage: advanced.md
   - Understanding the Dashboard: understand.md
   - Output Files & Sharing Data: output_files.md
-  - Advanced Usage: advanced.md
   - FAQ: faq.md