switch to doctave for docs

add analyse/process to docs

Author: AroneyS

.github/workflows/deploy-docs.yml

@@ -0,0 +1,30 @@
+name: Build manual pages and deploy documentation
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/**'
+      - 'doctave.yml'
+      - '.github/workflows/deploy-docs.yml'
+
+jobs:
+  build:
+    name: Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: 'Checkout cargo and install doctave'
+        uses: actions-rs/toolchain@v1.0.6
+        with:
+          toolchain: stable
+      - run: cargo install --git https://github.com/Doctave/doctave --tag 0.4.2
+      - name: 'Build doctave site'
+        run: doctave build --release
+      - name: 'GitHub Pages'
+        uses: crazy-max/ghaction-github-pages@v3.0.0
+        with:
+          build_dir: site/
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,19 +1,18 @@
-<img src="images/galah_logo.png" alt="Galah logo" width="600"/>
-
-- [Galah](#galah)
-  - [Installation](#installation)
-    - [Install through the bioconda package](#install-through-the-bioconda-package)
-    - [Pre-compiled binary](#pre-compiled-binary)
-    - [Compiling from source](#compiling-from-source)
-    - [Development](#development)
-    - [Dependencies](#dependencies)
-  - [Usage](#usage)
-    - [Precluster ANI](#precluster-ani)
-  - [License](#license)
+<!-- NOTE: This intro should manually be kept in sync between the repo README and the docs README -->
+
+[![Current Build](https://github.com/wwood/galah/actions/workflows/test-galah.yml/badge.svg)](https://github.com/wwood/galah/actions)
+[![Conda version](https://img.shields.io/conda/v/bioconda/galah)](https://anaconda.org/bioconda/galah)
+[![Conda downloads](https://img.shields.io/conda/d/bioconda/galah)](https://anaconda.org/bioconda/galah)
+[![Crates.io version](https://img.shields.io/crates/v/galah)](https://crates.io/crates/galah)
+[![Crates.io downloads](https://img.shields.io/crates/d/galah)](https://crates.io/crates/galah)
 
 # Galah
 
-[![Anaconda-Server Badge](https://anaconda.org/bioconda/galah/badges/version.svg)](https://anaconda.org/bioconda/galah)
+[<img src="docs/_include/galah_logo.png" alt="Galah logo" width="600"/>](galah_logo.png)
+
+Galah - Scalable dereplication and MIMAG calculation for metagenome assembled genomes 
+
+Documentation can be found at [https://wwood.github.io/galah/](https://wwood.github.io/galah/).
 
 Galah aims to be a more scalable metagenome assembled genome (MAG) dereplication
 method. That is, it clusters microbial genomes together based on their average
@@ -23,111 +22,76 @@ representative.
 Galah uses a greedy clustering approach to speed up genome dereplication,
 relative to e.g. [dRep](https://drep.readthedocs.io/), particularly when there
 are many closely related genomes (i.e. >95% ANI). Generated cluster
-representatives have 2 properties. If the ANI threshold was set to 99%, then:
+representatives have 2 properties. If the ANI threshold was set to 95%, then:
 
-1. Each representative is <99% ANI to each other representative.
-2. All members are >=99% ANI to the representative.
+1. Each representative is <95% ANI to each other representative.
+2. All members are >=95% ANI to the representative.
 
-If [CheckM](https://ecogenomics.github.io/CheckM/) genome qualities were
-specified, then the clusters have an additional property:
+If `--run-checkm2` was specified, or [CheckM2](https://github.com/chklovski/CheckM2) /
+[CheckM](https://ecogenomics.github.io/CheckM/) genome qualities were provided,
+then the clusters have an additional property:
 
 3. Each representative genome has a better quality score than other members of
    the cluster. Each genome is assigned a quality score based on the formula
-   `completeness-5*contamination-5*num_contigs/100-5*num_ambiguous_bases/100000`, which is reduced from a quality formula described in
-  Parks et. al. 2020 https://doi.org/10.1038/s41587-020-0501-8.
+   `completeness-5*contamination-5*num_contigs/100-5*num_ambiguous_bases/100000`,
+   which is reduced from a quality formula described in
+   Parks et. al. 2020 https://doi.org/10.1038/s41587-020-0501-8.
+   Other quality score formula are available via `--quality-formula`.
 
-If instead CheckM qualities were not provided, then the following holds instead:
+If instead CheckM1/2 qualities are not available, then the following holds instead:
 
-3. Each representative genome was specified to galah before other members of the
+3. Each representative genome was specified to Galah before other members of the
    cluster.
 
 The overall greedy clustering approach was largely inspired by the work of
-Donovan Parks, as described in [Parks et. al. 2020](https://doi.org/10.1038/s41587-020-0501-8). It
-operates in 3 steps. In the first step, genomes are assigned as representative
-if no genomes of higher quality are >99% ANI. In the second step, each
-non-representative genome is assigned to the representative genome it has the
-highest ANI with.
+Donovan Parks, as described in [Parks et. al. 2020](https://doi.org/10.1038/s41587-020-0501-8).
+It operates in 3 steps. In the first step, genomes are assigned as representative
+if no genomes of higher quality are >95% ANI. In the second step, each
+non-representative genome is assigned to the representative genome with which it
+has the highest ANI.
 
-## Installation
+## Example usage
 
-### Install through the bioconda package
+For clustering a set of genomes at 95% ANI:
 
-Galah can be installed through the [bioconda](https://bioconda.github.io/) conda channel. After initial setup of conda and the bioconda channel, it can be installed with mamba (or conda) with:
-
-```
-mamba install galah
+```bash
+galah cluster --genome-fasta-files /path/to/genome1.fna /path/to/genome2.fna \
+  --output-cluster-definition clusters.tsv
 ```
 
-One can see [details of the galah recipe](https://bioconda.github.io/recipes/galah/README.html).
-
-Galah can also be used indirectly through
-[CoverM](https://github.com/wwood/CoverM) via its `cluster` subcommand, which is also available on bioconda.
-
-### Pre-compiled binary
-
-Galah can be installed by downloading statically compiled binaries, available on
-the [releases page](https://github.com/wwood/Galah/releases).
-
-Third party dependencies listed below are required for this method.
-
-### Compiling from source
+For clustering a set of contigs at 95% ANI:
 
-Galah can also be installed from source, using the cargo build system after
-installing [Rust](https://www.rust-lang.org/).
-
-```
-cargo install galah
+```bash
+galah cluster --cluster-contigs --small-genomes --genome-fasta-files /path/to/contigs.fna \
+  --output-cluster-definition clusters.tsv
 ```
-Third party dependencies listed below are required for this method.
-
-### Development
 
-To run an unreleased version of Galah, after installing
-[Rust](https://www.rust-lang.org/):
+For determining MIMAG quality scores for a set of genomes with CheckM2:
 
+```bash
+galah analyse --genome-fasta-files /path/to/genome1.fna /path/to/genome2.fna \
+  --output-mimag-summary mimag.tsv
 ```
-git clone https://github.com/wwood/galah
-cd galah
-pixi run cargo run -- cluster ...etc...
-```
-Third party dependencies listed below are required for this method.
-
-### Dependencies
 
-For some advanced usage of Galah, 3rd party tools are required, which must be installed separately:
+For clustering and determining MIMAG quality scores:
 
-* skani v0.2.2 https://github.com/bluenote-1577/skani
-* FastANI v1.34 https://github.com/ParBLiSS/FastANI
-
-## Usage
-For clustering a set of genomes at 99% ANI:
-```
-galah cluster --genome-fasta-files /path/to/genome1.fna /path/to/genome2.fna --output-cluster-definition clusters.tsv
-```
-There are several other options for specifying genomes, ANI cutoffs, etc.
-
-For clustering a set of contigs at 99% ANI:
-```
-galah cluster --cluster-contigs --small-genomes --genome-fasta-files /path/to/contigs.fna --output-cluster-definition clusters.tsv
+```bash
+galah process --genome-fasta-files /path/to/genome1.fna /path/to/genome2.fna \
+  --output-cluster-definition clusters.tsv --output-mimag-summary mimag.tsv
 ```
 
-The full usage is described on the [manual page](https://wwood.github.io/galah/galah-cluster.html), which can be accessed on the command line running `galah cluster --full-help`.
+## Help
 
-### Precluster ANI
-Similar to dRep, galah operates in two stages. In the first, a fast
-pre-clustering distance ([finch](https://github.com/onecodex/finch-rs)
-or [skani](https://github.com/bluenote-1577/skani)) is
-calculated between each pair of genomes. Genome pairs are only considered as
-potentially in the same cluster with [skani](https://github.com/bluenote-1577/skani) or
-[FastANI](https://github.com/ParBLiSS/FastANI) if the prethreshold ANI is
-greater than the specified value. By default, the precluster ANI is set at 95%
-and the final ANI is set at 99%.
+If you have any questions or need help, please [open an issue](https://github.com/wwood/galah/issues).
 
 ## License
+Galah is developed by the [Woodcroft lab](https://research.qut.edu.au/cmr/team/ben-woodcroft/) at the [Centre for Microbiome Research](https://research.qut.edu.au/cmr), School of Biomedical Sciences, QUT, with contributions from [Samuel Aroney](https://github.com/AroneyS), [Antônio Camargo](https://github.com/apcamargo), and [Rhys Newell](https://github.com/rhysnewell). It is licensed under [GPL3 or later](https://gnu.org/licenses/gpl.html).
 
-Galah is made available under GPL3+. See LICENSE.txt for details. Copyright Ben
-Woodcroft.
+The source code is available at [https://github.com/wwood/galah](https://github.com/wwood/galah).
 
-Developed by Ben Woodcroft at the [Centre for Microbiome Research, Queensland University of Technology](https://www.qut.edu.au/health/schools/school-of-biomedical-sciences/centre-for-microbiome-research).
+## Citation
+<!-- NOTE: Citations should manually be kept in sync between the repo README and the docs README -->
 
-[galah]: Eolophus_roseicapilla_-Wamboin,_NSW,_Australia_-juvenile-8.smaller.jpg
+Aroney, S.T.N., Camargo, A.P., Tyson, G.W. and Woodcroft B.J.
+Galah: More scalable dereplication for metagenome assembled genomes.
+Zenodo (2024). https://doi.org/10.5281/zenodo.13637856

docs/README.md

@@ -0,0 +1,97 @@
+<!-- NOTE: This intro should manually be kept in sync between the repo README and the docs README -->
+
+[![Current Build](https://github.com/wwood/galah/actions/workflows/test-galah.yml/badge.svg)](https://github.com/wwood/galah/actions)
+[![Conda version](https://img.shields.io/conda/v/bioconda/galah)](https://anaconda.org/bioconda/galah)
+[![Conda downloads](https://img.shields.io/conda/d/bioconda/galah)](https://anaconda.org/bioconda/galah)
+[![Crates.io version](https://img.shields.io/crates/v/galah)](https://crates.io/crates/galah)
+[![Crates.io downloads](https://img.shields.io/crates/d/galah)](https://crates.io/crates/galah)
+
+# Galah
+
+[<img src="docs/_include/galah_logo.png" alt="Galah logo" width="600"/>](galah_logo.png)
+
+Galah - Scalable dereplication and MIMAG calculation for metagenome assembled genomes 
+
+Documentation can be found at [https://wwood.github.io/galah/](https://wwood.github.io/galah/).
+
+Galah aims to be a more scalable metagenome assembled genome (MAG) dereplication
+method. That is, it clusters microbial genomes together based on their average
+nucleotide identity (ANI), and chooses a single member of each cluster as the
+representative.
+
+Galah uses a greedy clustering approach to speed up genome dereplication,
+relative to e.g. [dRep](https://drep.readthedocs.io/), particularly when there
+are many closely related genomes (i.e. >95% ANI). Generated cluster
+representatives have 2 properties. If the ANI threshold was set to 95%, then:
+
+1. Each representative is <95% ANI to each other representative.
+2. All members are >=95% ANI to the representative.
+
+If `--run-checkm2` was specified, or [CheckM2](https://github.com/chklovski/CheckM2) /
+[CheckM](https://ecogenomics.github.io/CheckM/) genome qualities were provided,
+then the clusters have an additional property:
+
+3. Each representative genome has a better quality score than other members of
+   the cluster. Each genome is assigned a quality score based on the formula
+   `completeness-5*contamination-5*num_contigs/100-5*num_ambiguous_bases/100000`,
+   which is reduced from a quality formula described in
+   Parks et. al. 2020 https://doi.org/10.1038/s41587-020-0501-8.
+   Other quality score formula are available via `--quality-formula`.
+
+If instead CheckM1/2 qualities are not available, then the following holds instead:
+
+3. Each representative genome was specified to Galah before other members of the
+   cluster.
+
+The overall greedy clustering approach was largely inspired by the work of
+Donovan Parks, as described in [Parks et. al. 2020](https://doi.org/10.1038/s41587-020-0501-8).
+It operates in 3 steps. In the first step, genomes are assigned as representative
+if no genomes of higher quality are >95% ANI. In the second step, each
+non-representative genome is assigned to the representative genome with which it
+has the highest ANI.
+
+## Example usage
+
+For clustering a set of genomes at 95% ANI:
+
+```bash
+galah cluster --genome-fasta-files /path/to/genome1.fna /path/to/genome2.fna \
+  --output-cluster-definition clusters.tsv
+```
+
+For clustering a set of contigs at 95% ANI:
+
+```bash
+galah cluster --cluster-contigs --small-genomes --genome-fasta-files /path/to/contigs.fna \
+  --output-cluster-definition clusters.tsv
+```
+
+For determining MIMAG quality scores for a set of genomes with CheckM2:
+
+```bash
+galah analyse --genome-fasta-files /path/to/genome1.fna /path/to/genome2.fna \
+  --output-mimag-summary mimag.tsv
+```
+
+For clustering and determining MIMAG quality scores:
+
+```bash
+galah process --genome-fasta-files /path/to/genome1.fna /path/to/genome2.fna \
+  --output-cluster-definition clusters.tsv --output-mimag-summary mimag.tsv
+```
+
+## Help
+
+If you have any questions or need help, please [open an issue](https://github.com/wwood/galah/issues).
+
+## License
+Galah is developed by the [Woodcroft lab](https://research.qut.edu.au/cmr/team/ben-woodcroft/) at the [Centre for Microbiome Research](https://research.qut.edu.au/cmr), School of Biomedical Sciences, QUT, with contributions from [Samuel Aroney](https://github.com/AroneyS), [Antônio Camargo](https://github.com/apcamargo), and [Rhys Newell](https://github.com/rhysnewell). It is licensed under [GPL3 or later](https://gnu.org/licenses/gpl.html).
+
+The source code is available at [https://github.com/wwood/galah](https://github.com/wwood/galah).
+
+## Citation
+<!-- NOTE: Citations should manually be kept in sync between the repo README and the docs README -->
+
+Aroney, S.T.N., Camargo, A.P., Tyson, G.W. and Woodcroft B.J.
+Galah: More scalable dereplication for metagenome assembled genomes.
+Zenodo (2024). https://doi.org/10.5281/zenodo.13637856