Skip to content

Commit ee96ff4

Browse files
committed
docs: add documentation
1 parent e7680e7 commit ee96ff4

11 files changed

Lines changed: 728 additions & 0 deletions

File tree

‎docs/_static/.gitkeep‎

Whitespace-only changes.

‎docs/conf.py‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import re
2+
from pathlib import Path
3+
4+
5+
def _read_version() -> str:
6+
init = Path(__file__).resolve().parent.parent / "metapang" / "__init__.py"
7+
match = re.search(r'__version__\s*=\s*["\']([^"\']+)["\']', init.read_text())
8+
return match.group(1) if match else "0.0.0"
9+
10+
11+
project = "MetaPanG"
12+
author = "Téo Lemane"
13+
copyright = "2026, LABGeM"
14+
release = _read_version()
15+
version = release
16+
17+
extensions = [
18+
"myst_parser",
19+
"sphinx_copybutton",
20+
]
21+
22+
myst_enable_extensions = ["colon_fence", "deflist"]
23+
myst_heading_anchors = 3
24+
25+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
26+
27+
html_theme = "furo"
28+
html_title = f"MetaPanG {release}"
29+
html_static_path = ["_static"]
30+
html_theme_options = {
31+
"source_repository": "https://github.com/LABGeM/MetaPanG",
32+
"source_branch": "main",
33+
"source_directory": "docs/",
34+
}

‎docs/configuration.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Configuration
2+
3+
`MetaPanG` uses a cascading configuration system so that stable defaults can be kept
4+
in a file while individual runs, environments, or invocations override them without
5+
editing that file. A parameter may be set at several levels. Each level overrides the
6+
previous one. From lowest to highest precedence:
7+
8+
1. **system** (`~/.config/metapang-config.*`): user-wide defaults shared by every run,
9+
for example the cache directory or the `PanGBank` endpoint.
10+
2. **local** (`.metapang-config.*` in the current working directory): settings specific
11+
to an analysis directory, kept alongside its data.
12+
3. **cli** (a file passed with `metapang --config <path>`): a configuration selected
13+
explicitly for a given run.
14+
4. **environment** (variables of the form `METAPANG_<CMD>_<SUBCMD>_<PARAM>`): transient
15+
overrides, convenient in scripts, containers, or job schedulers.
16+
5. **option** (a command-line option, `--param <value>`): a one-off override for a
17+
single invocation.
18+
19+
Configuration files may be written in TOML, JSON, or YAML. A template, or the
20+
configuration schema, can be produced with:
21+
22+
```
23+
metapang configure template # commented template
24+
metapang configure template --schema # JSON schema
25+
```
26+
27+
The resolved configuration, and the origin of each value, can be inspected with:
28+
29+
```
30+
metapang configure show # the effective configuration
31+
metapang configure show -s # the same, annotated with the source of each value
32+
```
33+
34+
## File structure
35+
36+
A configuration file has two top-level sections:
37+
38+
`pangbank`
39+
: global settings such as the cache directory and the `PanGBank` endpoint.
40+
41+
`commands`
42+
: per-command defaults, keyed by command then option. A top-level command like
43+
`profile` is `commands.profile.<option>`. A nested one like `search bank` is
44+
`commands.search.bank.<option>`.
45+
46+
You only need to set the values you want to change. Everything else keeps its
47+
default. The following file sets the cache directory and a few `profile` defaults,
48+
shown in each supported format.
49+
50+
### YAML
51+
52+
```yaml
53+
pangbank:
54+
cache_directory: /shared/metapang-cache
55+
api_endpoint: https://pangbank-api.genoscope.cns.fr
56+
57+
commands:
58+
profile:
59+
threads: 8
60+
stop_rule: cv_paired
61+
k_max: 12
62+
search:
63+
bank:
64+
threshold_genome: 0.5
65+
```
66+
67+
### TOML
68+
69+
```toml
70+
[pangbank]
71+
cache_directory = "/shared/metapang-cache"
72+
api_endpoint = "https://pangbank-api.genoscope.cns.fr"
73+
74+
[commands.profile]
75+
threads = 8
76+
stop_rule = "cv_paired"
77+
k_max = 12
78+
79+
[commands.search.bank]
80+
threshold_genome = 0.5
81+
```
82+
83+
### JSON
84+
85+
```json
86+
{
87+
"pangbank": {
88+
"cache_directory": "/shared/metapang-cache",
89+
"api_endpoint": "https://pangbank-api.genoscope.cns.fr"
90+
},
91+
"commands": {
92+
"profile": {
93+
"threads": 8,
94+
"stop_rule": "cv_paired",
95+
"k_max": 12
96+
},
97+
"search": {
98+
"bank": {
99+
"threshold_genome": 0.5
100+
}
101+
}
102+
}
103+
}
104+
```
105+
106+
The format is chosen by the file extension (`.yaml`/`.yml`, `.toml`, or `.json`). A
107+
full commented template listing every option is produced with
108+
`metapang configure template`.
109+
110+
## Cache location
111+
112+
Downloaded pangenomes and indices are cached under `.metapang-cache` in the current
113+
directory by default. The location is set by the `pangbank.cache_directory` parameter,
114+
for example in a system configuration file:
115+
116+
```toml
117+
[pangbank]
118+
cache_directory = "/shared/metapang-cache"
119+
```
120+
121+
or through the corresponding environment variable:
122+
123+
```
124+
export METAPANG_PANGBANK_CACHE_DIRECTORY=/shared/metapang-cache
125+
```
126+
127+
On a shared system, pointing several users at the same directory lets them share a
128+
single cache. Downloads are file-locked, so concurrent runs may safely populate it.

‎docs/index.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# MetaPanG
2+
3+
:::{note}
4+
`MetaPanG` is under active development. A first release is coming soon.
5+
:::
6+
7+
`MetaPanG` is a tool for strain-level profiling of metagenomic samples against
8+
bacterial pangenome graphs. Given sequencing reads and a collection of species
9+
pangenomes, it detects the species present in a sample, maps the reads onto each
10+
species pangenome, and resolves the mixture of strains together with their
11+
relative abundances and per-strain gene content.
12+
13+
`MetaPanG` relies on `PanGBank`, a database of precomputed bacterial pangenomes
14+
accessed through a web API. For each species, `PanGBank` provides the pangenome
15+
together with the additional data structures that `MetaPanG` requires.
16+
17+
The files needed for a run are downloaded from `PanGBank` on demand and cached
18+
locally, so each resource is retrieved only once and reused by later runs.
19+
20+
## Quick start
21+
22+
```
23+
pixi install
24+
pixi run metapang profile -q reads.fastq.gz -b GTDB_refseq@2.0.0
25+
```
26+
27+
See [Installation](installation.md) for the other supported setups, and
28+
[Usage](usage.md) for a walkthrough.
29+
30+
:::{toctree}
31+
:maxdepth: 2
32+
:hidden:
33+
34+
installation
35+
configuration
36+
usage
37+
references
38+
:::

‎docs/installation.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Installation
2+
3+
`MetaPanG` is supported on Linux x86_64, macOS x86_64, and macOS arm64. Linux
4+
arm64 (aarch64) is not supported at the moment.
5+
6+
## With `conda`
7+
8+
`MetaPanG` depends on `graph-tool`, which is not available on PyPI. A conda
9+
environment file is provided at the repository root:
10+
11+
```
12+
conda env create -f environment.yaml
13+
conda activate metapang-env
14+
```
15+
16+
This installs `graph-tool` from conda and the remaining dependencies, declared in
17+
`pyproject.toml`, with pip.
18+
19+
:::{warning}
20+
`MetaPanG` also requires `metagraph >= 0.5.1`. Install it from its
21+
[documentation](https://github.com/ratschlab/metagraph). `metagraph` is not part
22+
of the conda environment above: it currently cannot share an environment with
23+
`graph-tool`, because the two link incompatible versions of the Boost libraries.
24+
This is a temporary limitation and will be fixed. For now, make `metagraph`
25+
available on the `PATH` (the default is the `metagraph` executable), or point
26+
`MetaPanG` at it with `metapang profile --metagraph-path /path/to/metagraph`.
27+
:::
28+
29+
The environment can be checked with:
30+
31+
```
32+
metapang checkhealth
33+
```
34+
35+
## With `pixi`
36+
37+
Alternatively, [pixi](https://pixi.sh) installs both `graph-tool` and `metagraph`
38+
for you, in two isolated environments wired together, so the manual `metagraph`
39+
step above is not needed:
40+
41+
```
42+
pixi install
43+
pixi run metapang profile -q reads.fastq.gz -b GTDB_refseq@2.0.0
44+
```
45+
46+
`pixi run` sets everything up on first use. Use `pixi shell` to enter the
47+
environment and call `metapang` directly.
48+
49+
## With `Docker`
50+
51+
The docker image bundles all dependencies.
52+
53+
```
54+
docker run --rm -t -v /path/to/data:/data -w /data \
55+
-v metapang-cache:/cache -e METAPANG_PANGBANK_CACHE_DIRECTORY=/cache \
56+
ghcr.io/labgem/metapang:latest profile -q reads.fastq.gz -b GTDB_refseq@2.0.0
57+
```
58+
59+
:::{important}
60+
`MetaPanG` caches the pangenomes and databases it downloads (see
61+
[Cache location](configuration.md#cache-location)). By default the cache is
62+
`.metapang-cache` relative to the working directory. Inside a container, anything
63+
written to the filesystem is lost when using `--rm`, so an unmounted cache is
64+
re-downloaded on every run. Set an explicit cache path with
65+
`METAPANG_PANGBANK_CACHE_DIRECTORY` and back it with a persistent volume (a named
66+
volume as above, or a host path with `-v /path/on/host:/cache`). This persists
67+
downloads across runs and lets several runs share a single cache.
68+
:::
69+
70+
An Apptainer/Singularity image can be built from the same image:
71+
72+
```
73+
apptainer build metapang.sif docker://ghcr.io/labgem/metapang:latest
74+
```

0 commit comments

Comments
 (0)