Derive objective ACMG/ClinGen 2019 CNV content evidence

Derive only the criteria determined mechanically by gene content and established ClinGen dosage records: section 1 content, section 2A complete dosage-feature containment, and section 3 protein-coding gene count. Case, phenotype, segregation, population, partial-gene, and inheritance evidence are intentionally not inferred. Each input is a BED half-open relation with non-missing, nonempty character/factor contig labels without leading or trailing whitespace, and finite, nonnegative integer coordinates in the exactly representable range [0, 2^53) satisfying start < end. Character coordinates are range-checked before conversion, so values such as 9007199254740993 cannot be rounded into a different interval. Contig names are matched exactly: XCNV neither infers aliases nor rejects a valid no-overlap contig. CNV, gene, and dosage identifiers and source/release provenance must be non-missing, nonempty character/factor labels on every row; logical, numeric, list, and matrix values are rejected before label conversion. Each nonempty gene/dosage relation carries one source and release. Gene biotype must be explicit, nonempty character/factor labels, while functional_biotypes must additionally be unique before functional filtering; surrounding whitespace and case-insensitive placeholder tokens are rejected for both, while explicit nonfunctional Ensembl-style biotypes remain valid. Incomplete annotation cannot establish 1B or 3A absence evidence. An optional assembly column is accepted on all three relations; nonempty relations must declare one coherent value. GRCh37 and GRCh38 are recognized; other assemblies remain explicit as unsupported in the output contract. A zero-row CNV relation is neutral and returns typed empty evidence; nonempty CNVs require nonempty gene and dosage relations, so an empty resource is never interpreted as negative evidence.

Usage

derive_cnv_2019_evidence(
  cnvs,
  genes,
  dosage,
  functional_biotypes = "protein_coding",
  established_score = 3
)

Arguments

cnvs

Data frame with character/factor, non-missing, nonempty cnv_id and cnv_type ("loss" or "gain"), and a non-missing, nonempty character/factor chr without surrounding whitespace. It also has exactly representable nonnegative integer start and end in [0, 2^53) satisfying start < end. A zero-row relation is accepted as neutral.

genes

Gene relation with character/factor, non-missing, nonempty gene_id, source, and release values on every row, plus explicit nonempty biotype labels (surrounding whitespace and placeholder tokens are rejected); a nonempty relation has one source_id and source_release, a non-missing, nonempty character/factor chr without surrounding whitespace, and exactly representable nonnegative integer start and end in [0, 2^53) satisfying start < end.

dosage

ClinGen dosage relation with character/factor, non-missing, nonempty record_id, source, and release values on every row; a nonempty relation has one source_id and source_release, a non-missing, nonempty character/factor chr without surrounding whitespace, exactly representable nonnegative integer start and end in [0, 2^53) satisfying start < end, plus hi_score and ts_score.

functional_biotypes

Nonempty, unique character/factor biotype labels counted as functionally important for sections 1 and 3; surrounding whitespace and placeholder tokens are rejected. Defaults to "protein_coding".

established_score

Finite numeric ClinGen score treated as established; defaults to 3. Character and factor labels are parsed by label.

Value

A provenance-complete evidence data frame accepted by score_cnv_2019().