Copyedit the documentation, correct the pancreas data description, rbeam plot changes by imallona · Pull Request #4 · imallona/beam

imallona · 2026-10-07T13:19:31Z

This is a copyedit of the documentation, with one correction to the data description and a few changes to the rbeam plots.

The README, site index, contributing guide, DESCRIPTION, explanations, how-tos, tutorial and vignettes have shorter sentences.
The metric card how-to now matches the code on the optional card fields, on the check for an inverted range, and on the OWL classes of a card.
Tran's Dataset 4 has five pancreas studies and the scIB task has six, four of them in common. The text said both used the same five. No numbers change.
beam_rank_dots replaces beam_rank_bars. Calls to the old name will fail.
The attribution plot uses the colours of the rank sensitivity plot.
beam_funky_heatmap(size_legend = TRUE) adds a key for the circle size.
The reliability plot labels its two reference lines.
The labels of the forest and critical difference plots fit inside the panel.
Axis labels say "fraction" where they said "share".
.gitignore lists the R build leftovers and the generated man pages.

pytest gives 893 passed and 3 skipped, and ruff check is clean. I did not run R CMD check locally.

…rence lines Replace beam_rank_bars with beam_rank_dots, which draws one dot per series joined by a line so that reversed axes do not make the longest bar the worst method. Colour the attribution bars with the role palette shared by the sensitivity and variance plots. Add a size key option to the funky heatmap, label the group alpha and the bound in the reliability plot, and keep the P-score and method labels of the forest and critical difference plots inside the panel.

Plain sentences in the README, site index, contributing guide, package description, explanations, how-tos, tutorial and vignettes. Correct three statements that disagreed with the code: the optional card fields in the metric card how-to, the range check (card consistency audit, not the schema) and the OWL classes. Tran dataset 4 and the scIB pancreas task share four of their studies; the data README, the loader docstring and the cross-benchmark vignettes no longer call them the same data. Ignore R build leftovers and the generated man pages.

Axis labels say fraction instead of share, the specification curve names the method shown, the reliability plot has room above the group alpha line and puts the bound label in the facet with the lowest bars.

Copilot

Copilot review overview

🟡 Changes recommended

The inverted-range guidance contradicts runtime behavior, and the new size-legend branch lacks test coverage.

Review effort: Balanced
Findings: 1 · 1

Open (2)

Add coverage for the size_legend option · New
Clarify inverted-range behavior in beam.rank · New

What changed in this PR

This PR copyedits beam’s documentation, corrects the pancreas benchmark description, and updates rbeam visualizations.

Changes:

Clarifies documentation and the partial overlap between pancreas datasets.
Replaces beam_rank_bars with beam_rank_dots and improves plot labels, colors, legends, and spacing.
Updates tests, exports, changelog, and ignored R build artifacts.

File	Description
`src/beam/plot.py`	Renames variance proportions as fractions.
`src/beam/datasets.py`	Corrects pancreas benchmark overlap documentation.
`src/beam/data/README.md`	Documents the actual pancreas studies.
`README.md`	Reworks project and usage descriptions.
`r/beam/vignettes/ranking.Rmd`	Clarifies blinding terminology.
`r/beam/vignettes/metric-diagnostics.Rmd`	Clarifies blinding terminology.
`r/beam/vignettes/heterogeneity.Rmd`	Clarifies blinding terminology.
`r/beam/vignettes/cross-benchmark.Rmd`	Corrects pancreas overlap and related wording.
`r/beam/vignettes/cell-type-annotation.Rmd`	Clarifies blinding terminology.
`r/beam/tests/testthat/test-plots.R`	Updates the rank-plot smoke test.
`r/beam/R/plot_kinds.R`	Improves labels, colors, annotations, and clipping.
`r/beam/R/plot_grouped.R`	Replaces grouped rank bars with dots and ranges.
`r/beam/R/plot_builders.R`	Adds custom stacked-plot palettes.
`r/beam/R/funky_heatmap.R`	Adds an optional circle-size legend.
`r/beam/NAMESPACE`	Exports `beam_rank_dots`.
`r/beam/DESCRIPTION`	Rewrites the package description.
`index.qmd`	Reworks the documentation landing page.
`examples/transportation/transportation.qmd`	Clarifies MEREC’s zero handling.
`examples/m4/m4.qmd`	Updates variance terminology.
`examples/duo2018/duo2018.qmd`	Clarifies pooling and missing-data handling.
`examples/cross_benchmark/cross_benchmark.qmd`	Corrects pancreas overlap and terminology.
`examples/cell_type_annotation/cell_type_annotation.qmd`	Clarifies dataset coverage and comparisons.
`docs/tutorials/quickstart.md`	Copyedits introductory instructions.
`docs/README.md`	Clarifies the directory’s purpose.
`docs/metric-cards.qmd`	Documents optional card normalization.
`docs/how-to/run.md`	Expands manifest documentation.
`docs/how-to/run-heterogeneity-from-the-cli.md`	Clarifies required long-format input.
`docs/how-to/install.md`	Clarifies R installation constraints.
`docs/how-to/blind-an-analysis.md`	Clarifies method-label masking.
`docs/how-to/add-a-metric-card.md`	Updates optional fields and validation guidance.
`docs/explanations/weighting-schemes.md`	Copyedits CRITIC and MEREC descriptions.
`docs/explanations/reference-levels.md`	Clarifies reference-level checks.
`docs/explanations/rank-sensitivity.md`	Clarifies failure and missing-data behavior.
`docs/explanations/pairwise-method-comparison.md`	Copyedits implementation attribution.
`docs/explanations/ontology-mappings.md`	Clarifies URI requirements.
`docs/explanations/normalization-and-scales.md`	Clarifies normalization errors and audits.
`docs/explanations/missing-data.md`	Updates missing-cell terminology.
`docs/explanations/method-by-dataset-heterogeneity.md`	Clarifies tied ranks.
`docs/explanations/funky-heatmaps-and-robustness.md`	Clarifies caller-supplied panels.
`docs/explanations/dataset-concordance-and-discrimination.md`	Copyedits ranking behavior.
`docs/explanations/cards-and-pipeline.qmd`	Clarifies range-validation errors.
`docs/explanations/card-data-consistency.md`	Clarifies consistency-audit behavior.
`docs/explanations/attribution-synthesis.md`	Copyedits attribution descriptions.
`docs/explanations/analysis-blinding.md`	Clarifies seal handling.
`CONTRIBUTING.md`	Simplifies contribution guidance.
`CHANGELOG.md`	Records the rbeam plotting changes.
`.gitignore`	Ignores R build and generated documentation files.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+                               show_aggregation = TRUE, cliques = NULL,
+                               size_legend = FALSE, ...) {


 ```

-The schema check runs against every card in the registry. A missing required field, a polarity that does not match the polarity enum, or an inverted range (lower > upper) raises an error.
+The schema check runs against every card in the registry. A missing required field or a polarity outside the polarity enum raises an error. An inverted range (lower > upper) passes the schema check; `beam.rank` reports it as a violation in the [card-data consistency report](../explanations/card-data-consistency.md).


imallona added 3 commits October 7, 2026 09:41

rbeam: fraction labels and reliability label placement

cbfff53

Axis labels say fraction instead of share, the specification curve names the method shown, the reliability plot has room above the group alpha line and puts the bound label in the facet with the lowest bars.

imallona mentioned this pull request Oct 7, 2026

Pin beam, extend the numbers export, clearer figures, figures workflow imallona/beam_analysis#1

Merged

imallona requested a balanced review from Copilot October 7, 2026 13:22

Copilot started reviewing on behalf of imallona October 7, 2026 13:22 View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

address code review

aa06a3c

imallona merged commit cc5893e into main Oct 7, 2026
10 checks passed

imallona mentioned this pull request Oct 7, 2026

Pin beam to v0.3.1 imallona/beam_analysis#2

Merged

Navigation Menu

Repository navigation

Copyedit the documentation, correct the pancreas data description, rbeam plot changes - #4

Copyedit the documentation, correct the pancreas data description, rbeam plot changes#4
imallona merged 4 commits into
mainfrom
docs-copyedit-and-plots

imallona commented Oct 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		show_aggregation = TRUE, cliques = NULL,
		size_legend = FALSE, ...) {

Conversation

imallona commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

imallona commented Oct 7, 2026 •

edited

Loading