diff --git a/docs/basic.md b/docs/basic.md index fde19dd..aac28b1 100644 --- a/docs/basic.md +++ b/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* (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 -nomadic realtime ``` -- `` should be replaced with the path to your *Nomadic* workspace. -- `` 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 (`/metadata/.csv`). - -The dashboard will open in a browser window on your computer. - - - - - ---- -## 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 +## Analysing a sequencing run *Nomadic* can process nanopore squencing data being produced by *MinKNOW* in real-time. To do so, follow the steps below. -**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* (`/metadata/.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 -``` +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 ``` -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 -``` - -**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 -``` -Where you should replace `` with the name of the experiment. - +``` \ No newline at end of file diff --git a/docs/css/custom.css b/docs/css/custom.css index bf2020e..a410f4b 100644 --- a/docs/css/custom.css +++ b/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); +} diff --git a/docs/faq.md b/docs/faq.md index bee53f5..f1bede0 100644 --- a/docs/faq.md +++ b/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. + diff --git a/docs/img/backup_share/backup_summary.png b/docs/img/backup_share/backup_summary.png new file mode 100644 index 0000000..b0448b0 Binary files /dev/null and b/docs/img/backup_share/backup_summary.png differ diff --git a/docs/img/basic/template.png b/docs/img/basic/template.png new file mode 100644 index 0000000..661af56 Binary files /dev/null and b/docs/img/basic/template.png differ diff --git a/docs/installation.md b/docs/installation.md index 60c3ef2..bb52e16 100644 --- a/docs/installation.md +++ b/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 ``` diff --git a/docs/output_files.md b/docs/output_files.md index 61c7441..78f3cb4 100644 --- a/docs/output_files.md +++ b/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/`) 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)). \ No newline at end of file +For more information about variant calling, please see [Understanding the Dashboard](understand.md#preliminary-variant-calling). \ No newline at end of file diff --git a/docs/quick_start.md b/docs/quick_start.md new file mode 100644 index 0000000..51134c2 --- /dev/null +++ b/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 +nomadic realtime +``` + +- `` should be replaced with the path to your *Nomadic* workspace. +- `` 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 (`/metadata/.csv|xlsx`). + +The dashboard will open in a browser window on your computer. + + \ No newline at end of file diff --git a/docs/share_backup.md b/docs/share_backup.md new file mode 100644 index 0000000..387c4fd --- /dev/null +++ b/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 +``` + +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/`) 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 backup -t +``` + +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 +nomadic configure backup -t +``` + +Once configured you can omit the `-t` option e.g. +``` +nomadic share +nomadic backup +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 784f9ab..830177a 100644 --- a/mkdocs.yml +++ b/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