| Title: | Copy Number Variant Annotation and Transparent Scoring |
|---|---|
| Description: | Provides bedtools-free copy-number-variant annotation, a portable evaluator and bundled runtime-neutral form of the published X-CNV model of Zhang et al. (2021), and independently authored, provenance-first scoring under the ACMG and ClinGen 2019 constitutional copy-number-variant standard. Large scientific annotation resources remain outside the package payload. |
| Authors: | Sounkou Mahamane Toure [aut, cre], Lu Zhang [ctb], Jing Shi [ctb], Jing Ouyang [ctb], Rui Zhang [ctb], Yan Tao [ctb], Dong Yuan [ctb], Cong Lv [ctb], Rui Wang [ctb], Bing Ning [ctb], Richard Roberts [ctb], William Tong [ctb], Zhi Liu [ctb], Tao Shi [ctb] |
| Maintainer: | Sounkou Mahamane Toure <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.0.0.9000 |
| Built: | 2026-10-16 10:41:05 UTC |
| Source: | https://github.com/RGenomicsETL/XCNV |
Compute the coding, genome-wide, regulatory, haploinsufficiency, and
population-frequency features used by X-CNV. Overlap is computed in-process
using BED half-open interval arithmetic; the reciprocal 0.5 thresholds used
by the upstream frequency step are retained. CNV lengths use the upstream
inclusive end - start + 1 convention.
annotate_cnv(x, resources, overlap_backend = c("duckdb", "reference"))annotate_cnv(x, resources, overlap_backend = c("duckdb", "reference"))
x |
A path, data frame, or matrix containing CNV records. |
resources |
An |
overlap_backend |
|
A data frame in legacy feature order, with the input columns first,
the model and auxiliary annotation columns next, and Type.1 and
Length at the end.
Convert an ACMG/ClinGen 2019 CNV score to a five-tier classification
classify_cnv_score(score)classify_cnv_score(score)
score |
Numeric score vector. |
An ordered factor with the five constitutional CNV classes.
Return the machine-readable criterion identifiers and numeric ranges used by
the independently authored scoring lane. This is a scoring contract, not an
automatic clinical evidence adjudicator. Dynamic section 5 criteria have an
NA default and require an explicit score selected by the curator.
cnv_2019_criteria(cnv_type = c("loss", "gain"))cnv_2019_criteria(cnv_type = c("loss", "gain"))
cnv_type |
One or both of |
A data frame with allowed per-evidence ranges and aggregate caps.
Return landing pages and release policies for resources used to construct a provenance-labelled CNV annotation pack. This function does not download data. Staging records the selected release, assembly, and source URL.
cnv_resource_sources()cnv_resource_sources()
A data frame of source authorities and current pinned releases where the upstream publishes numbered releases.
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.
derive_cnv_2019_evidence( cnvs, genes, dosage, functional_biotypes = "protein_coding", established_score = 3 )derive_cnv_2019_evidence( cnvs, genes, dosage, functional_biotypes = "protein_coding", established_score = 3 )
cnvs |
Data frame with character/factor, non-missing, nonempty |
genes |
Gene relation with character/factor, non-missing, nonempty
|
dosage |
ClinGen dosage relation with character/factor, non-missing,
nonempty |
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
|
established_score |
Finite numeric ClinGen score treated as established; defaults to 3. Character and factor labels are parsed by label. |
A provenance-complete evidence data frame accepted by
score_cnv_2019().
Load a portable, tabular X-CNV tree model. The portable artifact is exported
from the pinned model during resource staging and is evaluated without an
XGBoost runtime. Serialized .Rdata, .rds, and native XGBoost files are
deliberately rejected; use tools/stage_xcnv_model.R to convert them in an
environment where XGBoost is installed.
load_xcnv_model(model = NULL)load_xcnv_model(model = NULL)
model |
A portable model object or path to an |
A model object suitable for predict_cnv().
Annotate CNVs and compute the X-CNV MVP score. With an upstream model this
evaluates a staged xcnv-tree-v1 artifact in ordinary R. Installing and
running the package does not require XGBoost.
predict_cnv( x, resources, model = NULL, overlap_backend = c("duckdb", "reference") )predict_cnv( x, resources, model = NULL, overlap_backend = c("duckdb", "reference") )
x |
A path, data frame, or matrix containing CNV records. |
resources |
An |
model |
A model object/path. If |
overlap_backend |
Passed to |
A data frame containing the legacy annotation columns, a final
MVP_score model column, and contract columns for provider, assembly,
resource release, model identity, policy identity, and status.
Read a tab-separated BED-like CNV table or normalize an in-memory table. The first four columns are used, matching the published command-line tool; additional columns are ignored.
read_cnv(x)read_cnv(x)
x |
A path, data frame, or matrix containing chromosome, start, end, and CNV type in its first four columns. |
A four-column data frame with columns chr, start, end, and
type, classed as xcnv_cnv.
Read CNVs, compute annotations and MVP scores, and optionally write the output table. Unlike the historical executable, this function never writes beside the input by default and never installs software or downloads data.
run_xcnv( input, resources, model = NULL, output = NULL, overlap_backend = c("duckdb", "reference") ) xcnv( input, resources, model = NULL, output = NULL, overlap_backend = c("duckdb", "reference") )run_xcnv( input, resources, model = NULL, output = NULL, overlap_backend = c("duckdb", "reference") ) xcnv( input, resources, model = NULL, output = NULL, overlap_backend = c("duckdb", "reference") )
input |
A CNV path, data frame, or matrix. |
resources |
An |
model |
A model object/path, or |
output |
|
overlap_backend |
Passed to |
A prediction data frame; the same object is returned invisibly when
output is non-NULL.
The input is an auditable evidence relation. Every row names its CNV,
deletion/gain context, criterion, numeric score, source, source release, and
evidence record. Repeated case evidence is capped by the published criterion
group maximum/minimum. Evidence selection remains explicit and is never
inferred from free text or phenotype similarity by this function. Contracts
are resolved independently for each (cnv_id, cnv_type). Evidence and
group rows retain contributing source identities and linked evidence counts;
the summary provider is the XCNV ACMG/ClinGen policy kernel. Only supported
status emits a clinical classification. Identifier, provenance, and contract
labels must be character or factor labels (never logical, numeric, list, or
matrix values) and required values must be non-missing and nonempty on every
row. If supplied, policy_id must be nonempty and equal the native
ACMG/ClinGen policy identity on every row; foreign or mixed policies are
rejected rather than reinterpreted. A scalar evidence model_id comes only
from selected evidence that contributes to the output grain: its group, or
the CNV/type summary score. It is emitted only when every such row has the
same nonmissing model; unselected rows never supply it. Distinct nonmissing
selected model identities for one CNV/type are rejected. Provider identity
remains evidence provenance and is neither a voting input nor rewritten.
score_cnv_2019(evidence, detail = c("summary", "groups"))score_cnv_2019(evidence, detail = c("summary", "groups"))
evidence |
Data frame with character/factor, non-missing, nonempty
|
detail |
|
A data frame. Summary rows include policy status and linked evidence counts/identities without treating provenance as scoring input.
Validate the first four columns of a CNV table using the input rules of the
pinned X-CNV executable. Chromosome names may use the executable's leading
chr convention, and coordinates are retained as integer values.
validate_cnv(x)validate_cnv(x)
x |
A path, data frame, or matrix containing chromosome, start, end, and CNV type in its first four columns. |
TRUE invisibly when validation succeeds; otherwise an ordinary R
error is raised.
Check that a local directory contains the named X-CNV annotation and/or model resources. Validation never downloads files and never changes the working directory.
validate_xcnv_resources( path = NULL, require = "annotations", assembly = "GRCh37" )validate_xcnv_resources( path = NULL, require = "annotations", assembly = "GRCh37" )
path |
Resource directory. If omitted, |
require |
Resource groups to require: |
assembly |
Assembly declared for the resource bundle. The X-CNV
compatibility lane currently supports only |
An object of class xcnv_resources, containing the normalized root
and resolved resource paths.
Write a prediction data frame as a comma-separated X-CNV output table. A file is written only when an explicit output path is supplied.
write_xcnv(x, output)write_xcnv(x, output)
x |
A data frame returned by |
output |
Explicit output path. |
The normalized output path, invisibly.
Return the bundled published X-CNV model
xcnv_bundled_model()xcnv_bundled_model()
A validated xcnv_portable_model object.
Resolve the small, non-scientific fixture shipped for tests and examples. It is not a substitute for the Zhang et al. annotations or model.
xcnv_fixture_resources()xcnv_fixture_resources()
An object of class xcnv_resources.
The fitted X-CNV classifier from Zhang et al. (2021), converted once from
its serialized XGBoost representation to the package's runtime-neutral
xcnv-tree-v1 relation.
An xcnv_portable_model list containing the logistic base score,
30 feature names, and a 41-row tree relation.
Zhang et al. (2021), doi:10.1186/s13073-021-00945-4.
Return ClinVar allele 72461, a pathogenic deletion containing SOX2, with
the case-limited GRCh37 annotation relations needed to run X-CNV and the
objective ACMG/ClinGen 2019 content-evidence lane. The annotation files are
subsets for this case and must not be used for unrelated CNVs.
xcnv_real_example()xcnv_real_example()
A list containing cnv, clinvar, resources, genes, and
dosage.
Return the file names and resource groups understood by the package. Large annotations are external resources; the model entry is an optional override for the bundled classifier.
xcnv_resource_manifest()xcnv_resource_manifest()
A data frame describing required resource keys, file names, groups, declared assembly, and source release.
Resolve and validate a resource directory. With no path, only the
explicit XCNV_RESOURCE_DIR environment variable is consulted; the current
working directory is never searched implicitly.
xcnv_resources(path = NULL, require = "annotations", assembly = "GRCh37")xcnv_resources(path = NULL, require = "annotations", assembly = "GRCh37")
path |
Resource directory, or |
require |
Resource groups to require. |
assembly |
Assembly declared for the resource bundle. |
An object of class xcnv_resources.