`ms_hrd_report()` scores each sample of an allele-specific segment table with the two Cortes-Castro genomic-scar scores – the fraction of partial loss of heterozygosity ([pLOH][hrd_ploh_score]) and the autosome-level [aneuploidy][hrd_aneuploidy] count – and combines them into the composite HRD call. The verbatim scoring expressions are anchored on the cran/SigMiner reference in [R/hrd-reference.R][hrd_ploh_score] and are replayed digit-for-digit against an independent oracle by the fidelity suite.
Usage
ms_hrd_report(
segments,
genome,
caller,
assay = c("wgs", "wes"),
experimental = FALSE,
...
)Arguments
- segments
A `data.frame` with columns `sample`, `chromosome`, `start`, `end`, `state` (integer major copy number), `minor_cn`, `caller` and `assay`. `start`/`end` are 1-based closed bp and together with `state`/`minor_cn` must be numeric.
- genome
Build label, one of `"GRCh37"` / `"GRCh38"`. Required and explicit – there is no silent default. Anything else raises `msuiter_error_genome`.
- caller
The allele-specific caller label to attribute and validate against the five-name whitelist (`battenberg`, `ascat`, `facets`, `purple`, `sequenza`); compared case-insensitively. `NULL` or `"auto"` derives it from the segment table's `caller` column.
- assay
Modality, `"wgs"` (default) or `"wes"`. A `"wes"` assay is refused unless `experimental = TRUE`.
- experimental
Single logical (default `FALSE`): the opt-in that lets a `"wes"` assay through the WGS-only gate; the tier column then reads `"experimental"`.
- ...
Reference-geometry injections: `chr_size` (positive pLOH denominator), `arms` (`data.frame(chrom, location, arm_start, arm_end)`), `ploidy` (numeric; `ploidy[1]` is subtracted by the aneuploidy flag) and `rm_black_arms` (single logical, default `FALSE`; drops the acrocentric p-arms `13,14,15,21,22` from the aneuploidy count). Any other name is ignored.
Value
An object of class `MsHrdReport`. Its [as.data.frame()][as.data.frame.MsHrdReport] face is an all-atomic table with one row per sample and the columns `sample`, `genome`, `caller`, `assay`, `ploh_fraction`, `aneuploidy_count`, `hrd_score`, `evidence_tier`, `n_windows_scored`, `coverage_note` and `ploidy_source`. A `chrom`-level aneuploidy table is carried on the object as `attr(rep, "aneuploidy_detail")`.
Details
Two hard gates protect the score's provenance (design memo section 2): a `wes` assay needs `experimental = TRUE` (`msuiter_error_hrd-wes-experimental`); a caller outside the five validated allele-specific callers is refused (`msuiter_error_hrd-caller-whitelist`). Reference geometry (the pLOH denominator, the arm table and ploidy) is injected through `...` – msuiter ships no genome-derived default and never fabricates one, so un-supplied geometry is surfaced through the uncertainty columns (`n_windows_scored`, `coverage_note`, `ploidy_source`) rather than invented.
Examples
seg <- data.frame(
sample = "S1", chromosome = "chr1",
start = 1L, end = 1000L, state = 2L, minor_cn = 0L,
caller = "ascat", assay = "wgs", stringsAsFactors = FALSE
)
arms <- data.frame(
chrom = "chr1", location = c("p", "q"),
arm_start = c(1L, 501L), arm_end = c(500L, 1000L),
stringsAsFactors = FALSE
)
rep1 <- ms_hrd_report(seg, genome = "GRCh37", caller = "ascat", assay = "wgs",
chr_size = 1000, ploidy = 2, arms = arms
)
as.data.frame(rep1)
#> sample genome caller assay ploh_fraction aneuploidy_count hrd_score
#> 1 S1 GRCh37 ascat wgs 1 0 0
#> evidence_tier n_windows_scored
#> 1 standard 2
#> coverage_note ploidy_source
#> 1 ploidy-source=caller; denominator=injected; aneuploidy=scored caller