diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ae61765..1ac7992 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -245,8 +245,10 @@ writes. The documentation workflow runs `tools/check_site.py`, which fails on a documentation page that no longer matches its markdown, a dead link or anchor, an option `recore --help` does not have, an option missing from the reference, a default that differs from the binary's, a walkthrough that decides -differently from the code, or an example run whose counts differ from the -page's, instead of a stale page somebody finds six months later. The markdown +differently from the code, a README link or command that no longer works, or an +example run whose counts differ from the page's, instead of a stale page +somebody finds six months later. The README is held to the website too: its +Try-it block has to be the website's, so change them together. The markdown also reads on GitHub as it is. `docs/assets/example-report.html` is the tutorial run's own output, linked from diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e67b9ae..d3d8f9e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,8 +11,8 @@ name: Documentation # on it: a documentation page that no longer matches its markdown, a dead link # or anchor, an option the pages show that `recore --help` does not have, an # option or a default the reference gets wrong, a walkthrough that decides -# differently from src/pipeline.rs, and an example run whose counts are not the -# ones the page promises. That last part runs the "Try it" commands for real, +# differently from src/pipeline.rs, a README link or command that no longer +# works, and an example run whose counts are not the ones the page promises. That last part runs the "Try it" commands for real, # which is why this needs minimap2 and a build. # # The workflow and job names are what the Dependabot auto-merge gate waits for @@ -25,6 +25,8 @@ on: - main paths: - "docs/**" + - "README.md" + - "assets/**" - "src/**" - "Cargo.toml" - "Cargo.lock" @@ -35,6 +37,8 @@ on: pull_request: paths: - "docs/**" + - "README.md" + - "assets/**" - "src/**" - "Cargo.toml" - "Cargo.lock" diff --git a/CHANGELOG.md b/CHANGELOG.md index e0a5f08..370bcf5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -112,7 +112,15 @@ and Recore uses semantic versioning. cell through seven animated drawings, from the search to what gets written down: pick what the search finds, whether the neighbours agree and the policy, and the drawings decide by the same rules as the code, which - `tools/check_site.py` holds them to. + `tools/check_site.py` holds them to. The README follows the website: the + same opening, the same numbered steps, an animated preview of How it works + and a link into each part of the site. `tools/check_site.py` checks its + links, the options of its commands, and that its Try-it block and counts + are the website's. The README names the authors, Paula Ruiz-Rodriguez and + Mireia Coscolla, and the contributors; the citation reads "Ruiz-Rodriguez P, + Coscolla M." in the README, on the website and in its BibTeX, and + `Cargo.toml` lists both authors. `tools/check_site.py` fails if a page of the + website cites differently from the README. - `publication_status` in `orthology_evidence.tsv` follows `matrix_action`. Evidence the matrix policy or a quality floor kept out reads `held_out_policy` or `held_out_quality` instead of a `corrected...` value, and a strict diff --git a/Cargo.toml b/Cargo.toml index 3377464..5f18f59 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "recore" version = "0.2.0" edition = "2021" rust-version = "1.85" -authors = ["Paula Ruiz-Rodriguez "] +authors = ["Paula Ruiz-Rodriguez ", "Mireia Coscolla"] description = "Post-hoc rescue of falsely absent genes in pangenome matrices" license = "GPL-3.0-only" repository = "https://github.com/PathoGenOmics-Lab/recore" diff --git a/README.md b/README.md index 5443557..b27caab 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,26 @@
- - - Recore - + + + + Recore + + -**Post-hoc rescue, audit, and quality control of pangenome presence/absence matrices.** -**Pure Rust · one external dependency · Linux and macOS** +### Missing from the matrix. Still in the genome. -[Documentation](#documentation) · [Install](#installation) · [Quick start](#quick-start) · [Tutorial](docs/getting-started/tutorial.md) · [Citation](#citation) +Recore searches every empty cell of a pangenome matrix in the assemblies,
+puts back the genes that are really there, and keeps the evidence for each one. + +Open the website + +[Install](https://pathogenomics-lab.github.io/recore/#start) · +[Your command](https://pathogenomics-lab.github.io/recore/#command) · +[Try it](https://pathogenomics-lab.github.io/recore/#try) · +[How it works](https://pathogenomics-lab.github.io/recore/how-it-works.html) · +[Docs](https://pathogenomics-lab.github.io/recore/documentation.html) · +[Reference](https://pathogenomics-lab.github.io/recore/reference.html) + +For Panaroo, Roary, PPanGGOLiN, PanTA and PIRATE · pure Rust · Linux and macOS CI License: GPLv3 @@ -15,151 +28,171 @@
-## What is Recore? - -Pangenome pipelines can mark a gene as absent even when the sequence is still -present in the assembly. These false absences inflate the accessory genome, -shrink the core genome, and create lineage-specific signals that are artefacts -of graph cleaning rather than biology. - -Recore searches every absent cell against the genome assemblies with minimap2, -classifies the evidence, validates orthology against annotation and synteny when -they are available, and writes both: - -- a **Panaroo-compatible corrected binary matrix** for downstream analyses, - as CSV and as the 1/0 `.Rtab` that pyseer and most R code read -- a **multistate evidence matrix** for audit, plotting, and manuscript review - -It reads the output of Panaroo, Roary, PPanGGOLiN, PanTA and PIRATE, can write -the rescued genes as nucleotide and protein FASTA for functional annotation, -and with `--search-cache` reruns with another policy or threshold without -aligning again. +__Paula Ruiz-Rodriguez1__ +__and Mireia Coscolla1__ +
+ 1. I2SysBio, University of Valencia-CSIC, FISABIO Joint Research Unit Infection and Public Health, Valencia, Spain -The central design choice is conservative. Recore separates *sequence evidence* -from *clean binary presence*: full-length evidence can be corrected in the binary -matrix, while partial homology, pseudogenes, paralog traps and -incompatible-context hits stay visible in audit outputs instead of silently -becoming presence calls. +

+ How Recore decides one empty cell, in seven steps: the matrix says absent, take the gene's sequence, search the assembly, look at what is there, check the neighbours, decide, write it down
+ One empty cell, seven steps. The interactive version lets you pick what the search finds. +

-## Installation +## 1 · Install -Needs [Rust 1.85+](https://www.rust-lang.org/tools/install) to build and -[minimap2](https://github.com/lh3/minimap2) on `PATH` to run. +Two commands. Recore uses [minimap2](https://github.com/lh3/minimap2) to search. ```bash conda install -c bioconda minimap2 # or: brew install minimap2 / sudo apt install minimap2 cargo install --git https://github.com/PathoGenOmics-Lab/recore --locked -recore --version ``` -Or build a clone with `cargo build --release` (the binary lands at -`target/release/recore`). `--nsc-engine mmseqs2` also needs -[MMseqs2](https://github.com/soedinglab/MMseqs2) on `PATH`; the default engine -is built in. +Needs Rust 1.85 or newer ([rustup.rs](https://rustup.rs)), about a minute to +build. Check with `recore --version`. From a clone, `cargo build --release` +puts the binary at `target/release/recore`. -## Quick start +## 2 · Your command + +Give it what your pangenome tool wrote and one assembly per genome, named like +the matrix columns. ```bash recore \ -p gene_presence_absence.csv \ -r pan_genome_reference.fa \ -g genomes/ \ - -a annotations/ \ - --synteny --multi-allele \ - --matrix-policy balanced \ - --reference-genome AS00146 \ - --tree species.tree \ + -a annotations/ --synteny \ --write-html-report \ -t 8 -o recore_output/ ``` -Four outputs answer most questions: +That is Panaroo with GFF files. +[The website writes it for your tool and the files you have](https://pathogenomics-lab.github.io/recore/#command), +and [Inputs](docs/getting-started/inputs.md) says how the names have to match. -| File | For | -|---|---| -| `gene_presence_absence_recore.csv` | the corrected binary matrix, for downstream tools | -| `gene_presence_absence_recore.Rtab` | the same matrix as 1/0, for pyseer and Rtab readers | -| `gene_presence_absence_recore_states.csv` | audit and figures, one biological state per cell | -| `orthology_evidence.tsv` | publication wording and manual review | -| `recore_report.html` | the whole run in one self-contained page | - -`--matrix-policy balanced` is the recommendation for anything that will be -published: it rescues full-length false absences while keeping partial or -disrupted homologues as audit-only evidence. The other two policies, and the -adaptive guard that sits on top of all three, are in -[Matrix policies](docs/guide/matrix-policies.md). - -To see it work on data with known answers before pointing it at your own, the -[tutorial](docs/getting-started/tutorial.md) generates a twelve-genome dataset -with eleven false absences planted in it and walks through the run. - -## Documentation - -The quickest way in is the website in [`docs/`](docs/index.html): an install -line, a command builder for your pangenome tool, a one-minute example, the -example report to click through, an illustrated walk through how one empty cell -is decided, a reference page with every option, output file and cell state, and -a Docs tab with every page below, searchable. It is plain HTML with no build -step, so open `docs/index.html` from a clone; once the repository is public, -GitHub Pages can serve it straight from `main` and `/docs`. The Docs pages are -built from the markdown by `tools/build_docs.py`, and `tools/check_site.py` -keeps the site honest in CI: the pages match their markdown, every option it -shows exists, the defaults match `recore --help`, the walkthrough decides by -the code's rules, and the example run gives the numbers the page promises. - -The same pages are markdown files in this repository and read here on GitHub. - -| Start here | | -|---|---| -| [Tutorial](docs/getting-started/tutorial.md) | a full run on a generated dataset with known answers | -| [Inputs](docs/getting-started/inputs.md) | what each input is, and how the names have to match | +## 3 · Or try it first + +Twelve genomes with eleven false absences planted in them. About a minute. + +```bash +curl -sO https://raw.githubusercontent.com/PathoGenOmics-Lab/recore/main/benchmarks/make_tutorial_dataset.py +python3 make_tutorial_dataset.py --out tutorial_data +recore -p tutorial_data/gene_presence_absence.csv \ + -r tutorial_data/pan_genome_reference.fa \ + -g tutorial_data/genomes -a tutorial_data/annotations --synteny \ + --tree tutorial_data/species.tree --write-html-report -o tutorial_out +``` -| Reference | | +`tutorial_out/summary.txt` should read: + +```text +Rescued: 11 every planted absence found +Matrix-corrected: 8 the other 3 are pseudogenes: kept out, with the reason +``` + +Then open `tutorial_out/recore_report.html`. The +[tutorial](docs/getting-started/tutorial.md) tells the story behind each number. + +## 4 · What you get + +Four files answer most questions. [All of them](docs/guide/outputs.md). + +| File | What it is | |---|---| -| [Parameters](docs/guide/parameters.md) | every option, with its default and what it changes | -| [Matrix policies](docs/guide/matrix-policies.md) | which evidence reaches the binary matrix | -| [Output files](docs/guide/outputs.md) | every table, column by column | -| [Run report](docs/guide/report.md) | the self-contained HTML viewer | +| `gene_presence_absence_recore.csv` | The corrected matrix, in the input's format (and as `.Rtab`). Feed it to your next tool. | +| `gene_presence_absence_recore_states.csv` | The same matrix with a state in every cell: input, put back, kept out and why. For figures. | +| `orthology_evidence.tsv` | One row per change: the evidence, the decision, and wording you can use in a paper. | +| `recore_report.html` | The whole run in one page that works offline. Open it in any browser. | + +[Explore a real report](https://pathogenomics-lab.github.io/recore/#report), +the one the example run writes. -| How it works | | +## 5 · One setting that matters + +`--matrix-policy` picks which evidence reaches the corrected matrix. All of it +stays in the audit files. + +| Policy | What reaches the corrected matrix | |---|---| -| [Algorithm](docs/how-it-works/algorithm.md) | each pipeline phase, its data structures and complexity | -| [Evidence states](docs/how-it-works/evidence-states.md) | the ten states of the multistate matrix | -| [Rescue types](docs/how-it-works/rescue-types.md) | rescue classes and biological interpretation | -| [Evolutionary events](docs/how-it-works/evolutionary-events.md) | how a mechanism is called, and how to word it in a paper | -| [Limits and comparisons](docs/how-it-works/limits.md) | what Recore does not claim, benchmark results, Panaroo refinding | +| `strict` | Only genes tied to the same locus by the annotation or by their neighbours. Fewest changes. | +| `balanced` (default) | Adds full-length genes found by sequence. Pseudogenes and partial copies stay out. **Use it for papers.** | +| `sensitive` | Also puts back partial and disrupted copies that pass the quality guard. For exploring. | -Version history is in [CHANGELOG.md](CHANGELOG.md). Benchmark design and -reproduction is in [benchmarks/README.md](benchmarks/README.md). +[Matrix policies](docs/guide/matrix-policies.md) has the rules and the quality +guard. -If the documentation does not answer it, ask in -[Discussions](https://github.com/PathoGenOmics-Lab/recore/discussions). Issues -are for something that crashed, refused to run, or is plainly wrong. +## If something looks off -## For developers +[The first questions people ask](https://pathogenomics-lab.github.io/recore/#faq) +are answered on the website. Still stuck? Ask in +[Discussions](https://github.com/PathoGenOmics-Lab/recore/discussions); +[Issues](https://github.com/PathoGenOmics-Lab/recore/issues) are for crashes and +plainly wrong results. -```bash -cargo fmt --all -- --check -cargo clippy --locked --all-targets -- -D warnings -RECORE_REQUIRE_MINIMAP2=1 cargo test --locked --all-targets -``` +## Learn more -The end-to-end test skips silently without minimap2 on `PATH`, which is why CI -sets that variable. [Contributing](docs/about/contributing.md) covers the report -assets, the two rules they have to keep, and how to regenerate the generated -files. +The website is plain HTML in [`docs/`](docs/), so it also opens from a clone, +offline: open `docs/index.html`. Every page of its Docs tab is a markdown file +here as well: -## Citation +- **Start:** [Tutorial](docs/getting-started/tutorial.md) · [Inputs](docs/getting-started/inputs.md) +- **Guide:** [Parameters](docs/guide/parameters.md) · [Matrix policies](docs/guide/matrix-policies.md) · [Output files](docs/guide/outputs.md) · [Run report](docs/guide/report.md) +- **How it works:** [Algorithm](docs/how-it-works/algorithm.md) · [Evidence states](docs/how-it-works/evidence-states.md) · [Rescue types](docs/how-it-works/rescue-types.md) · [Evolutionary events](docs/how-it-works/evolutionary-events.md) · [Limits and comparisons](docs/how-it-works/limits.md) +- **Project:** [Changelog](CHANGELOG.md) · [Benchmarks](benchmarks/README.md) · [Contributing](.github/CONTRIBUTING.md), with the tests and the checks CI runs -If you use Recore, please cite: +## Cite -> Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control -> of pangenome presence/absence matrices. *In preparation.* +> Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality +> control of pangenome presence/absence matrices. *In preparation.* -## Contact +GPL-3.0, see [LICENSE](LICENSE) · [PathoGenOmics Lab](https://github.com/PathoGenOmics-Lab) · Paula Ruiz-Rodriguez, paula.ruiz.rodriguez@csic.es -Paula Ruiz-Rodriguez - paula.ruiz.rodriguez@csic.es +--- -## License +

-GNU General Public License v3.0. See [LICENSE](LICENSE). +✨ [Contributors](https://github.com/PathoGenOmics-Lab/recore/graphs/contributors) +

+ + + + +
+Recore is developed with ❤️ by: + + + + + +
+ + +
+ Paula Ruiz-Rodriguez + +
+ 💻 + 🔬 + 🤔 + 🔣 + 🎨 + 🔧 + 		+ + +
+ Mireia Coscolla + +
+ 🔍 + 🤔 + 🧑‍🏫 + 🔬 + 📓 +
+ +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification ([emoji key](https://allcontributors.org/docs/en/emoji-key)). +
+ + + diff --git a/assets/how-it-works.gif b/assets/how-it-works.gif new file mode 100644 index 0000000..374a588 Binary files /dev/null and b/assets/how-it-works.gif differ diff --git a/docs/about/citation.html b/docs/about/citation.html index 7b20cdb..b4f2a7d 100644 --- a/docs/about/citation.html +++ b/docs/about/citation.html @@ -72,9 +72,9 @@

Docs / About

Citation

If you use Recore, please cite:

-

Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+

Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

@misc{recore,
-  author       = {Ruiz-Rodriguez, Paula and others},
+  author       = {Ruiz-Rodriguez, Paula and Coscolla, Mireia},
   title        = {Recore: post-hoc rescue and quality control of pangenome
                   presence/absence matrices},
   year         = {2026},
@@ -97,7 +97,7 @@ 
License
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/about/citation.md b/docs/about/citation.md
index 255be41..75482ed 100644
--- a/docs/about/citation.md
+++ b/docs/about/citation.md
@@ -2,12 +2,12 @@
 
 If you use Recore, please cite:
 
-> Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control
-> of pangenome presence/absence matrices. *In preparation.*
+> Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality
+> control of pangenome presence/absence matrices. *In preparation.*
 
 ```bibtex
 @misc{recore,
-  author       = {Ruiz-Rodriguez, Paula and others},
+  author       = {Ruiz-Rodriguez, Paula and Coscolla, Mireia},
   title        = {Recore: post-hoc rescue and quality control of pangenome
                   presence/absence matrices},
   year         = {2026},
diff --git a/docs/about/contributing.html b/docs/about/contributing.html
index 4d8d41a..7539680 100644
--- a/docs/about/contributing.html
+++ b/docs/about/contributing.html
@@ -91,6 +91,7 @@ 
Working on the HTML reportDocumentation#

 
The website is docs/index.html, docs/how-it-works.html and docs/reference.html, styled by docs/assets/site.css and driven by docs/assets/site.js: plain files, so opening docs/index.html in a browser shows a change. Keep the front page short. It is there to get someone running in two minutes; the details belong in the documentation.

 
The drawings of How it works are docs/assets/how.js. They decide with a copy of evidence_state and matrix_policy_corrects from src/pipeline.rs, so a change to those rules is a change there too; tools/check_site.py fails if the policy table, a state, a rescue type, a matrix action or a column no longer matches the code.

+
The README is the same front door on GitHub, in the website's words: keep the two in step. tools/check_site.py checks the README's links into the repository and into the website, the options of its recore commands, and that its Try-it block and counts are the website's.

 
The Docs tab is these markdown pages. tools/build_docs.py turns each one into an .html page next to it, with the site's header, sidebar, contents and search, and writes docs/documentation.html and the search index. The pages are committed, so after editing a .md file, rebuild them:

 
python3 tools/build_docs.py

 
A new page is a line in PAGES at the top of that script.

@@ -120,7 +121,7 @@ 
Reporting a problem
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/about/contributing.md b/docs/about/contributing.md
index f455f6e..cfffa99 100644
--- a/docs/about/contributing.md
+++ b/docs/about/contributing.md
@@ -69,6 +69,11 @@ change to those rules is a change there too; `tools/check_site.py` fails if the
 policy table, a state, a rescue type, a matrix action or a column no longer
 matches the code.
 
+The README is the same front door on GitHub, in the website's words: keep the
+two in step. `tools/check_site.py` checks the README's links into the
+repository and into the website, the options of its `recore` commands, and that
+its Try-it block and counts are the website's.
+
 The Docs tab is these markdown pages. `tools/build_docs.py` turns each one into
 an `.html` page next to it, with the site's header, sidebar, contents and
 search, and writes `docs/documentation.html` and the search index. The pages
diff --git a/docs/assets/search-index.js b/docs/assets/search-index.js
index 1e8ba3a..9ed1d8e 100644
--- a/docs/assets/search-index.js
+++ b/docs/assets/search-index.js
@@ -982,7 +982,7 @@ window.RECORE_DOCS_INDEX = [
 "page": "Citation",
 "section": "",
 "url": "about/citation.html",
-"text": "If you use Recore, please cite: Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation. Please also cite the tools Recore depends on for the run you report: minimap2, for every sequence search: Li H. (2018). Minimap2: pairwise alignment for nucleotide sequences. Bioinformatics 34(18):3094-3100. MMseqs2, if you used --nsc-engine mmseqs2: Steinegger M, Soeding J. (2017). MMseqs2 enables sensitive protein sequence searching for the analysis of massive data sets. Nature Biotechnology 35:1026-1028. the pangenome tool that "
+"text": "If you use Recore, please cite: Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation. Please also cite the tools Recore depends on for the run you report: minimap2, for every sequence search: Li H. (2018). Minimap2: pairwise alignment for nucleotide sequences. Bioinformatics 34(18):3094-3100. MMseqs2, if you used --nsc-engine mmseqs2: Steinegger M, Soeding J. (2017). MMseqs2 enables sensitive protein sequence searching for the analysis of massive data sets. Nature Biotechnology 35:1026-1028. the pangenome tool "
 },
 {
 "page": "Citation",
diff --git a/docs/documentation.html b/docs/documentation.html
index 6e75bbf..55e6ed5 100644
--- a/docs/documentation.html
+++ b/docs/documentation.html
@@ -103,7 +103,7 @@ 
About

   

     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/getting-started/inputs.html b/docs/getting-started/inputs.html
index 4fc4ea3..3a3f877 100644
--- a/docs/getting-started/inputs.html
+++ b/docs/getting-started/inputs.html
@@ -94,7 +94,7 @@ 
Choosing the optional inputs
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/getting-started/tutorial.html b/docs/getting-started/tutorial.html
index 927f343..0d5bd45 100644
--- a/docs/getting-started/tutorial.html
+++ b/docs/getting-started/tutorial.html
@@ -167,7 +167,7 @@ 
Next
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/guide/matrix-policies.html b/docs/guide/matrix-policies.html
index 8f98c6c..3384195 100644
--- a/docs/guide/matrix-policies.html
+++ b/docs/guide/matrix-policies.html
@@ -98,7 +98,7 @@ 
Reporting it
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/guide/outputs.html b/docs/guide/outputs.html
index 2bdff6a..7ff5d94 100644
--- a/docs/guide/outputs.html
+++ b/docs/guide/outputs.html
@@ -292,7 +292,7 @@ 
Common debug messages and their
   

     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/guide/parameters.html b/docs/guide/parameters.html
index 09cd825..4c92642 100644
--- a/docs/guide/parameters.html
+++ b/docs/guide/parameters.html
@@ -150,7 +150,7 @@ 
--nsc-threshold (NSC simila
   

     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/guide/report.html b/docs/guide/report.html
index df0bb32..e4ab246 100644
--- a/docs/guide/report.html
+++ b/docs/guide/report.html
@@ -141,7 +141,7 @@ 
If you did not use --write
   

     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/how-it-works.html b/docs/how-it-works.html
index 66dff32..d5b2ef8 100644
--- a/docs/how-it-works.html
+++ b/docs/how-it-works.html
@@ -96,7 +96,7 @@ 
Go deeper

   

     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/how-it-works/algorithm.html b/docs/how-it-works/algorithm.html
index 7b38616..9d1704b 100644
--- a/docs/how-it-works/algorithm.html
+++ b/docs/how-it-works/algorithm.html
@@ -234,7 +234,7 @@ 
Computational Complexity
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/how-it-works/evidence-states.html b/docs/how-it-works/evidence-states.html
index f90e4be..f8d1fa3 100644
--- a/docs/how-it-works/evidence-states.html
+++ b/docs/how-it-works/evidence-states.html
@@ -92,7 +92,7 @@ 
Which policy corrects which state
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/how-it-works/evolutionary-events.html b/docs/how-it-works/evolutionary-events.html
index 6a958c3..48574b6 100644
--- a/docs/how-it-works/evolutionary-events.html
+++ b/docs/how-it-works/evolutionary-events.html
@@ -105,7 +105,7 @@ 
Where the fields live
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/how-it-works/limits.html b/docs/how-it-works/limits.html
index e4480db..a623343 100644
--- a/docs/how-it-works/limits.html
+++ b/docs/how-it-works/limits.html
@@ -114,7 +114,7 @@ 
Reproducible review
     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/how-it-works/rescue-types.html b/docs/how-it-works/rescue-types.html
index 2a8f06b..33e82cf 100644
--- a/docs/how-it-works/rescue-types.html
+++ b/docs/how-it-works/rescue-types.html
@@ -173,7 +173,7 @@ 
Rescue Type Priority in Con
   

     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/index.html b/docs/index.html
index eeae1c8..8e1c257 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -314,7 +314,7 @@ 
Open source, on GitHub

   

     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/docs/reference.html b/docs/reference.html
index 151dc32..069ad78 100644
--- a/docs/reference.html
+++ b/docs/reference.html
@@ -229,7 +229,7 @@ 
Go deeper

   

     

       
Cite

-      
Ruiz-Rodriguez P, et al. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

+      
Ruiz-Rodriguez P, Coscolla M. (2026). Recore: post-hoc rescue and quality control of pangenome presence/absence matrices. In preparation.

     

     

       
Learn more

diff --git a/tools/build_docs.py b/tools/build_docs.py
index 38f275d..8cd4018 100644
--- a/tools/build_docs.py
+++ b/tools/build_docs.py
@@ -426,7 +426,7 @@ def nav(target: str, label: str, key: str, optional: bool = True, wide: bool = F
 def footer(root: str) -> str:
     return (
         '