From 784165e7c19f6f60a47f0afa1a324aa9fbcd06f0 Mon Sep 17 00:00:00 2001 From: Tim Van Rillaer Date: Fri, 18 Oct 2024 14:25:44 +0200 Subject: [PATCH 1/6] Translate existing docs to sphinx (#2) --- docs/.gitignore | 1 + docs/Makefile | 20 ++++++ docs/_static/img/scarap_logo.png | Bin 0 -> 16241 bytes docs/_static/js/custom.js | 3 + docs/citation.rst | 5 ++ docs/conf.py | 38 +++++++++++ docs/feedback.rst | 6 ++ docs/getting-started.rst | 110 +++++++++++++++++++++++++++++++ docs/index.rst | 33 ++++++++++ docs/install.rst | 25 +++++++ docs/license.rst | 5 ++ docs/make.bat | 35 ++++++++++ docs/modules.rst | 22 +++++++ docs/requirements.txt | 3 + docs/scarap.rst | 78 ++++++++++++++++++++++ 15 files changed, 384 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/_static/img/scarap_logo.png create mode 100644 docs/_static/js/custom.js create mode 100644 docs/citation.rst create mode 100644 docs/conf.py create mode 100644 docs/feedback.rst create mode 100644 docs/getting-started.rst create mode 100644 docs/index.rst create mode 100644 docs/install.rst create mode 100644 docs/license.rst create mode 100644 docs/make.bat create mode 100644 docs/modules.rst create mode 100644 docs/requirements.txt create mode 100644 docs/scarap.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..e35d885 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/img/scarap_logo.png b/docs/_static/img/scarap_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..7f79d94585d67b3b2455dd25f1b5b80f94228cb1 GIT binary patch literal 16241 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. diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 0000000..1307620 --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,110 @@ +Getting started +=============== + +Obtaining data +-------------- + +SCARAP works mainly with faa files: amino acid sequences of all (predicted) genes in a genome assembly. You can obtain faa files in at least three ways: + +* You can run a gene prediction tool like `Prodigal `_ on genome assemblies of your favorite strains, or a complete annotation pipeline such as `Prokka `_ or `Bakta `_. +* You can search your favorite taxon on `NCBI genome `_ and manually download assemblies in the following way: click on an assembly, click "Download", select "Protein (FASTA)" as file type and click "Download" again. +* Given a list of assembly accession numbers (i.e. starting with GCA/GCF), you can use `ncbi-genome-download `_ to download the corresponding faa files. + +Given a list of accessions in a file called ``accessions.txt``, you can use ncbi-genome-download to download faa files as follows: :: + + ncbi-genome-download -P \ + --assembly-accessions accessions.txt \ + --section genbank \ + --formats protein-fasta \ + bacteria + +Inferring a pangenome +--------------------- + +If you want to infer the pangenome of a set of genomes, you only need their faa files (fasta files with protein sequences) as input. If the faa files are stored in a folder ``faas``, you can infer the pangenome using 16 threads by running: :: + + scarap pan ./faas ./pan -t 16 + +The pangenome will be stored in ``pan/pangenome.tsv`` +The pangenome is stored in a "long format": a table with the columns gene, genome and orthogroup. + +Inferring a core genome +----------------------- + +If you want to infer the core genome of a set of genomes directly, without inferring the full pangenome first, you can also do this with SCARAP. The reason you might want to do this, is because it is faster and because you sometimes don't need more than the core genome (e.g. when you are planning to infer a phylogeny). + +You can infer the core genome, given a set of faa files in a folder ``faas``, in the following way: :: + + scarap core ./faas ./core -t 16 + +The core genome will be stored in ``core/genes.tsv``. + +Subsampling a set of genomes +--------------------------- + +If you have a (large) dataset of genomes that you wish to subsample in a +representative way, you can do this using the ``sample`` module. You +will need to precompute the pangenome or core genome to do this; SCARAP +calculates average amino acid identity (AAI) or core amino acid identity +(cAAI) values in the subsampling process, and it uses the single-copy +orthogroups from a pan- or core genome to do this. + +For example, if you want to sample 100 genomes given a set of faa files +in a folder ``faas``: + +:: + + scarap core ./faas ./core -t 16 + scarap sample ./faas ./core/genes.tsv ./representatives -m 100 -t 16 + + +The representative genomes will be stored in +``representatives/seeds.txt``. + +Important remark: by default, the per-gene amino acid identity values +are estimated from alignment scores per column by MMseqs (`alignment +mode +1 `__). +For AAI values > 90%, these estimations are on average smaller than the +exact values. It is possible to calculate exact AAI values by adding the +``--exact`` option to the sample module, but this will be slower. + +You can also sample genomes based on average nucleotide identity (ANI) +or core nucleotide identity (cANI) values. In that case, you need to +supply nucleotide sequences of predicted genes, e.g. in a folder +``ffns``: + +:: + + scarap core ./faas ./core -t 16 + scarap sample ./ffns ./core/genes.tsv ./representatives -m 100 -t 16 + +Building a “supermatrix” for a set of genomes +---------------------------------------------- + +You can build a concatenated alignment of core genes (“supermatrix”) for +a set of genomes using the ``concat`` module. + +Let’s say you want to build a supermatrix of 100 core genes for a set of +genomes, with faa files given in a folder ``faas``: + +:: + + scarap core ./faas ./core -m 100 -t 16 + scarap concat ./faas ./core/genes.tsv ./supermatrix -t 16 + + +The amino acid supermatrix will be saved in +``supermatrix/supermatrix_aas.fasta``. + +If you want to produce a nucleotide-level supermatrix, this can be +achieved by giving a folder with ffn files (nucleotide sequences of +predicted genes) as an additional argument: + +:: + + scarap concat ./faas ./core/genes.tsv ./supermatrix -n ./ffns -t 16 + + +The nucleotide-level supermatrix will be saved in +``supermatrix/supermatrix_nucs.fasta``. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..9b12ba1 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,33 @@ +.. SCARAP documentation master file, created by + sphinx-quickstart on Fri Oct 18 12:50:18 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +SCARAP: pangenome inference and comparative genomics of prokaryotes +==================================================================== + +.. image:: _static/img/scarap_logo.png + :align: center + :width: 200 + :alt: SCARAP logo + +SCARAP is a toolkit with modules for various tasks related to comparative genomics of prokaryotes. SCARAP has been designed to be fast and scalable. Its main feature is pangenome inference, but it also has modules for direct core genome inference (without inferring the full pangenome), subsampling representatives from a (large) set of genomes and constructing a concatenated core gene alignment ("supermatrix") that can later be used for phylogeny inference. SCARAP has been designed for prokaryotes but should work for eukaryotic genomes as well. It can handle large genome datasets on a range of taxonomic levels; it has been tested on datasets with prokaryotic genomes from the species to the order level. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + install + getting-started + scarap + feedback + citation + license + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..264323a --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,25 @@ +Installing SCARAP +================= + +You can install SCARAP through `conda `_ :: + + git clone https://github.com/swittouck/scarap.git + cd scarap + conda env create -f environment.yml + +You can then run SCARAP as follows :: + + conda activate scarap + scarap -h + conda deactivate + +You can also install SCARAP manually by cloning it and installing the following dependencies: + +* `Python3 `_ version \>= 3.6.7 + * `numpy `_ version \>= 1.16.5 + * `scipy `_ version \>= 1.4.1 + * `pandas version `_ \>= 1.5.3 + * `biopython `_ version \>= 1.67 + * `ete3 `_ version \>= 3.1.1 +* `MAFFT `_ version \>= 7.407 +* `MMseqs2 `_ release 11, 12 or 13 \ No newline at end of file diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..7a8c811 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,5 @@ +License +------- + +SCARAP is free software, licensed under +`GPLv3 `__. \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..a4de367 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,22 @@ +Modules +------- + +SCARAP is able to perform a number of specific tasks related to +prokaryotic comparative genomics (see also ``scarap -h``). + +The most useful modules of SCARAP are probably the following: + +- ``pan``: infer a pangenome from a set of faa files +- ``core``: infer a core genome from a set of faa files +- ``sample``: sample a subset of representative genomes + +Modules for other useful tasks are also available: + +- ``build``: build a profile database for a core/pangenome +- ``search``: search query genes in a profile database +- ``checkgenomes``: assess the genomes in a core genome +- ``checkgroups``: assess the orthogroups in a core genome +- ``filter``: filter the genomes/orthogroups in a pangenome +- ``concat``: construct a concatenated core orthogroup alignment from a + core genome +- ``fetch``: fetch sequences and store in fasta per orthogroup diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..39beb36 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx +sphinx-rtd-theme +sphinxcontrib-jquery diff --git a/docs/scarap.rst b/docs/scarap.rst new file mode 100644 index 0000000..7f90e67 --- /dev/null +++ b/docs/scarap.rst @@ -0,0 +1,78 @@ +Package modules +=============== + +Submodules +---------- + +scarap.callers module +--------------------- + +.. automodule:: scarap.callers + :members: + :undoc-members: + :show-inheritance: + +scarap.checkers module +---------------------- + +.. automodule:: scarap.checkers + :members: + :undoc-members: + :show-inheritance: + +scarap.computers module +----------------------- + +.. automodule:: scarap.computers + :members: + :undoc-members: + :show-inheritance: + +scarap.helpers module +--------------------- + +.. automodule:: scarap.helpers + :members: + :undoc-members: + :show-inheritance: + +scarap.module\_wrappers module +------------------------------ + +.. automodule:: scarap.module_wrappers + :members: + :undoc-members: + :show-inheritance: + +scarap.modules module +--------------------- + +.. automodule:: scarap.modules + :members: + :undoc-members: + :show-inheritance: + +scarap.pan module +----------------- + +.. automodule:: scarap.pan + :members: + :undoc-members: + :show-inheritance: + +scarap.readerswriters module +---------------------------- + +.. automodule:: scarap.readerswriters + :members: + :undoc-members: + :show-inheritance: + +scarap.utils module +------------------- + +.. automodule:: scarap.utils + :members: + :undoc-members: + :show-inheritance: + From 3b9146785135a4a625492acec79293a139370d28 Mon Sep 17 00:00:00 2001 From: Tim Van Rillaer Date: Fri, 18 Oct 2024 14:30:43 +0200 Subject: [PATCH 2/6] Create documentation.yml --- .github/workflows/documentation.yml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 .github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..f95ae68 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,27 @@ +name: documentation + +on: [push, pull_request, workflow_dispatch] + +permissions: + contents: write + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + - name: Install dependencies + run: | + pip install sphinx sphinx_rtd_theme sphinxcontrib-jquery myst_parser + - name: Sphinx build + run: | + sphinx-build docs _build + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: _build/ + force_orphan: true From 655d2c228d8a70c394af7c0a8a4cbc113f70a65d Mon Sep 17 00:00:00 2001 From: Tim Van Rillaer Date: Fri, 18 Oct 2024 14:33:19 +0200 Subject: [PATCH 3/6] Update documentation.yml --- .github/workflows/documentation.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index f95ae68..a39b3f5 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -19,7 +19,6 @@ jobs: sphinx-build docs _build - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} From 758b79cd5d3ab28fe25b56a8b9f9ec52bcb5217c Mon Sep 17 00:00:00 2001 From: TheOaphidian Date: Fri, 3 Oct 2025 17:05:03 +0200 Subject: [PATCH 4/6] Add auto extensions --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 8226a89..67dd1c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,6 +18,8 @@ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', ] templates_path = ['_templates'] From 65824178f1a0c7872cf14903f17e778e94fba9ed Mon Sep 17 00:00:00 2001 From: TheOaphidian Date: Fri, 3 Oct 2025 17:23:16 +0200 Subject: [PATCH 5/6] Update docs --- docs/citation.rst | 5 +++-- docs/install.rst | 38 ++++++++++++++++++++++++++------------ 2 files changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/citation.rst b/docs/citation.rst index bd50819..e2baeaa 100644 --- a/docs/citation.rst +++ b/docs/citation.rst @@ -1,5 +1,6 @@ Citation -------- -A manuscript describing SCARAP and its validation has been prepared and -will (hopefully) be published shortly. \ No newline at end of file +If you've found SCARAP useful in your own work, please cite the following manuscript: :: + + Wittouck et al. (2025) "SCARAP: scalable cross-species comparative genomics of prokaryotes", Bioinformatics, Volume 41, Issue 1, January 2025, btae735, https://doi.org/10.1093/bioinformatics/btae735 diff --git a/docs/install.rst b/docs/install.rst index 264323a..0b6ac76 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,25 +1,39 @@ Installing SCARAP ================= -You can install SCARAP through `conda `_ :: - - git clone https://github.com/swittouck/scarap.git - cd scarap - conda env create -f environment.yml - -You can then run SCARAP as follows :: - +The easiest way to get started is to install SCARAP using conda. + +Conda +----- + +First, create and activate a new conda environment: :: + + conda create -n scarap python=3.11 conda activate scarap - scarap -h - conda deactivate + +Then install from the recipe on bioconda: :: + + conda install bioconda::scarap + + +Pip +--- + +First make sure that MAFFT and MMseqs2 are properly installed. Then install SCARAP with pip: :: + + pip install scarap + + +Manual install +-------------- You can also install SCARAP manually by cloning it and installing the following dependencies: -* `Python3 `_ version \>= 3.6.7 +* `Python3 `_ version \>= 3.6.7 and < 3.13 * `numpy `_ version \>= 1.16.5 * `scipy `_ version \>= 1.4.1 * `pandas version `_ \>= 1.5.3 * `biopython `_ version \>= 1.67 * `ete3 `_ version \>= 3.1.1 * `MAFFT `_ version \>= 7.407 -* `MMseqs2 `_ release 11, 12 or 13 \ No newline at end of file +* `MMseqs2 `_ release 11, 12 or 13 From 4f0706e479d6f6793e77abbee53df9de2d6b3261 Mon Sep 17 00:00:00 2001 From: TheOaphidian Date: Fri, 20 Feb 2026 12:30:56 +0100 Subject: [PATCH 6/6] Add explanation on output table --- docs/modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules.rst b/docs/modules.rst index a4de367..96b981b 100644 --- a/docs/modules.rst +++ b/docs/modules.rst @@ -14,7 +14,7 @@ Modules for other useful tasks are also available: - ``build``: build a profile database for a core/pangenome - ``search``: search query genes in a profile database -- ``checkgenomes``: assess the genomes in a core genome +- ``checkgenomes``: assess the genomes in a core genome. Returns a table with `genome`, `completeness` and `contamination`. - ``checkgroups``: assess the orthogroups in a core genome - ``filter``: filter the genomes/orthogroups in a pangenome - ``concat``: construct a concatenated core orthogroup alignment from a