Documentation

[imallona]

No description provided.

[Copilot]

Pull request overview

This PR restructures and refreshes the project documentation by consolidating many explanation pages into fewer, broader documents and updating links across the Python package docs, Quarto site, examples, and R vignettes so they point at the new locations.

Changes:

• Consolidates/renames several explanation pages (e.g., critical difference, pairwise comparison, metric-set diagnostics, heterogeneity, choice agreement) and removes superseded pages.
• Updates internal links throughout examples/vignettes/how-tos/tutorials to point at the new documentation structure (including new anchors).
• Minor wording/spelling polish and housekeeping (.gitignore for Quarto artifacts, Quarto nav updates).

Reviewed changes

Copilot reviewed 58 out of 59 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/beam/mcda/comet.py	Updates docstring reference to new docs location for COMET.
README.md	Renames “Licence” heading to “License”.
r/beam/vignettes/ranking.Rmd	Adds links to explanation pages; retitles sections for clarity.
r/beam/vignettes/metric-diagnostics.Rmd	Adds links to metric diagnostics explanations; simplifies headings.
r/beam/vignettes/heterogeneity.Rmd	Adds links to heterogeneity explanations; minor wording edits.
r/beam/vignettes/cross-benchmark.Rmd	Adds links to updated explanation pages; minor heading edits.
r/beam/vignettes/cell-type-annotation.Rmd	Updates links/headings to match new explanation structure.
index.qmd	Refreshes landing-page intro and “Where to start” links to new docs.
examples/transportation/transportation.qmd	Updates explanation links (critical difference, COMET anchor, pairwise comparison anchors, etc.).
examples/scenarios/scenarios.qmd	Updates explanation links (critical difference, pairwise comparison anchors, heterogeneity page).
examples/openproblems/openproblems.qmd	Updates explanation links (metric-set diagnostics, heterogeneity, pairwise comparison).
examples/m4/m4.qmd	Updates explanation links (critical difference, heterogeneity, pairwise comparison, spec curve anchor).
examples/duo2018/duo2018.qmd	Updates explanation links (critical difference, pairwise comparison, heterogeneity).
examples/cross_benchmark/cross_benchmark.qmd	Updates headings/links around cross-benchmark variance decomposition.
examples/cell_type_annotation/cell_type_annotation.qmd	Updates links (choice agreement, critical difference, pairwise comparison) and narrative wording.
docs/tutorials/quickstart.md	Updates wording and dataset concordance link to consolidated page.
docs/how-to/run-heterogeneity-from-the-cli.md	Updates explanation links to consolidated heterogeneity content.
docs/how-to/run-from-beam-yaml.md	Rewords reproducibility section and adds link to rerun-from-manifest.
docs/how-to/rerun-from-manifest.md	Small wording tweak clarifying manifest purpose.
docs/how-to/plot-a-beam-run.md	Updates critical-difference explanation link and wording.
docs/explanations/weighting-schemes.md	Updates spec-curve link to new anchor location.
docs/explanations/transitivity.md	Removed (content consolidated elsewhere).
docs/explanations/stato-term-proposals.md	Removed (content moved into ontology-mappings).
docs/explanations/specification-curve.md	Removed (content moved into rank-sensitivity).
docs/explanations/skillings-mack.md	Removed (content moved into critical-difference).
docs/explanations/reliability.md	Removed (content moved into metric-set-diagnostics).
docs/explanations/reference-levels.md	Updates links to consolidated pairwise comparison page/anchors.
docs/explanations/rank-sensitivity.md	Renamed/expanded to include specification-curve content and anchors.
docs/explanations/pairwise-superiority.md	Removed (content moved into pairwise-method-comparison).
docs/explanations/pairwise-method-comparison.md	New consolidated page covering superiority/transitivity/Bayesian comparison.
docs/explanations/openproblems-as-a-data-source.md	Updates heterogeneity link to consolidated page/anchors.
docs/explanations/ontology-mappings.md	Embeds former STATO proposal content; adds sectioned structure.
docs/explanations/normalization-and-scales.md	Updates link to choice-agreement normalization section.
docs/explanations/normalization-agreement.md	Removed (content moved into choice-agreement).
docs/explanations/network-meta-analysis.md	Updates heterogeneity linkage and keeps cross-reference to source variance decomposition.
docs/explanations/missing-data.md	Updates COMET and critical-difference/Skillings-Mack links/anchors; wording tweak.
docs/explanations/metric-set-diagnostics.md	New consolidated page for validity/reliability/dimensionality.
docs/explanations/method-by-dataset-heterogeneity.md	New consolidated page for heterogeneity models (mixed-effects, BT trees, PL, beta).
docs/explanations/heterogeneity-mixed-effects.md	Removed (content moved into method-by-dataset-heterogeneity).
docs/explanations/heterogeneity-bradley-terry.md	Removed (content moved into method-by-dataset-heterogeneity).
docs/explanations/funky-heatmaps-and-robustness.md	Updates links and tightens prose; points to consolidated pages.
docs/explanations/full-rankings-and-bounded-metrics.md	Removed (content moved into method-by-dataset-heterogeneity).
docs/explanations/dimensionality.md	Removed (content moved into metric-set-diagnostics).
docs/explanations/dataset-discrimination.md	Removed (content moved into dataset-concordance-and-discrimination).
docs/explanations/dataset-concordance-and-discrimination.md	Expanded to include dataset discrimination section; updates internal links.
docs/explanations/critical-difference.md	New consolidated page covering Friedman/Nemenyi and Skillings-Mack.
docs/explanations/convergent-discriminant-validity.md	Removed (content moved into metric-set-diagnostics).
docs/explanations/comparing-methods-across-datasets.md	Removed (superseded by critical-difference).
docs/explanations/comet.md	Removed (COMET documentation moved into aggregation-methods).
docs/explanations/choice-agreement.md	New consolidated page for aggregation & normalization agreement.
docs/explanations/cards-and-pipeline.qmd	Retitles page for clarity.
docs/explanations/card-data-consistency.md	Tightens wording and clarifies responsibility of the audit.
docs/explanations/bayesian-comparison.md	Removed (content moved into pairwise-method-comparison).
docs/explanations/attribution-synthesis.md	Updates links to consolidated heterogeneity/spec-curve anchors.
docs/explanations/analysis-blinding.md	Clarifies that unblinding renames only; updates spec-curve link.
docs/explanations/aggregation-methods.md	Updates COMET documentation inline; points aggregation agreement to choice-agreement.
docs/explanations/aggregation-agreement.md	Removed (content moved into choice-agreement).
.gitignore	Ignores Quarto build artifacts and quarto notebooks.
_quarto.yml	Updates site nav to point at consolidated explanation pages and removes retired pages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.