HRD
hrd_features
The HRD feature table, one row per sample: sig3_score, sig3_ml, sig3_exp, gis, hrd_loh, tai, lst, fga, lst_lr, mmej, nhej, tumor_type.
sg2.hrd_features(input=None, tumor_type=None, seq_type=None, *, indels=None, segments=None, gis=None,
ref_genome="hg19", model=None, beds=None, sig3=None, verbose=0) -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| inputpath, folder, DataFrame or Samples | The mutations: a MAF or VCF path, a folder of VCFs, or a matrix; the Signature 3 and indel features come from it. | None |
| tumor_typestr | One of the tumor types the HRD model covers. | Required |
| seq_typestr | The platform with an HRD model: msk, fo, op, seqcap or tcga_mc3. | Required |
| indelspath, VCF, MAF or DataFrame | Indels from a separate source: a path, a VCF or MAF object, or a DataFrame. | None |
| segmentspath or DataFrame | Copy-number segments, allele-specific (ASCAT, FACETS, PURPLE) or log-ratio (.seg), with a sample column. | None |
| gisSeries or dict | Precomputed genomic instability per sample when segments are not available. | None |
| ref_genomestr | The build of the coordinates or a FASTA path. | 'hg19' |
| modelstr or HRDModel | The HRD model whose Signature 3 settings are used, by name or as an HRDModel; the platform's when left out. | None |
| bedslist of BED | Repeat-locus BED files of another build for the indel features. | None |
| sig3DataFrame | A frame with SBS3_mva, SBS3_ml and exp_SBS3 from a Signature 3 run, instead of running one. | None |
| verboseint | 0 prints errors and some warnings; 1 also prints the run. | 0 |
Returns A DataFrame, one row per sample: the Signature 3 features, the copy-number features, mmej, nhej, tumor_type.
Signature 3 from a run on input or a sig3= frame; indels from input, indels= or precomputed columns; copy number from segments=, gis= or columns of input.
feats = sg2.hrd_features(
"test_mutations_50sample.maf",
tumor_type="breast",
seq_type="msk",
segments="msk_breast_50_segments.seg",
ref_genome="hg19",
)
scores = sg2.score_hrd(feats, seq_type="msk", tumor_type="breast")
Used in 3. Detect HRD, Worked example: HRD on exomes
score_hrd
Score a feature table: hrd_group, hrd_variant, hrd_score_pan, hrd_score_type, hrd_score, hrd_call.
sg2.score_hrd(features, seq_type=None, model=None, tumor_type=None, mmrd=None) -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| featuresDataFrame | The hrd_features() table to score. | Required |
| seq_typestr | The platform whose HRD model scores it. | None |
| modelstr or HRDModel | An HRD model by name or as an HRDModel; the platform's when left out. | None |
| tumor_type | The tumor type, when the features table has no tumor_type column. | None |
| mmrdpandas.Series | A per-sample MMRD/POLE category; those samples get it as hrd_call. | None |
Returns A DataFrame, one row per sample: hrd_group, hrd_variant, hrd_score_pan, hrd_score_type, hrd_score, hrd_call.
mmrd is an optional per-sample MMRD/POLE category; those samples get it as hrd_call.
feats = sg2.hrd_features(
"test_mutations_50sample.maf",
tumor_type="breast",
seq_type="msk",
segments="msk_breast_50_segments.seg",
ref_genome="hg19",
)
scores = sg2.score_hrd(feats, seq_type="msk", tumor_type="breast")
Used in 3. Detect HRD, Worked example: HRD on exomes
genomic_instability
HRD-LOH, TAI, LST and their sum gis from allele-specific segments.
sg2.genomic_instability(segments, genome="hg19", grid=None) -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| segmentspath or DataFrame | Allele-specific segments (ASCAT, FACETS, PURPLE, major/minor) as a path or DataFrame, with a sample column. | Required |
| genomestr | The build of the segments, hg19 or hg38. | 'hg19' |
| griddict | A panel gene grid to compute the scores on, as an HRD model records it. | None |
Returns A DataFrame, one row per sample: hrd_loh, tai, lst and their sum gis.
gis = sg2.genomic_instability("tcga_brca_ascat_segments.tsv", genome="hg19")
gis
Used in Worked example: HRD on exomes
copy_number_instability
Fraction of genome altered (fga) and log-ratio LST (lst_lr) from log-ratio segments.
sg2.copy_number_instability(segments, genome="hg19") -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| segmentspath or DataFrame | Log-ratio segments (.seg with seg.mean) as a path or DataFrame, with a sample column. | Required |
| genomestr | The build of the segments, hg19 or hg38. | 'hg19' |
Returns A DataFrame, one row per sample: fga and lst_lr.
indel_features
mmej, nhej, nins, ndel, nmsi_ins, nmsi_del per sample from indels, against the repeat loci.
sg2.indel_features(indels, ref_genome, samples=None, beds=None, repeats_build=None, min_del_size=None,
min_mh_size=None) -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| indelsDataFrame or VCF | The indels: a DataFrame with Chromosome, Position, REF, ALT and Sample columns (VCF or MAF style), or a VCF object. | Required |
| ref_genomestr or FastaFile | The build of the coordinates or an opened FASTA. | Required |
| sampleslist of str | The samples to report, in this order; a sample without indels gets a row of zeros. | None |
| bedslist of BED | Repeat-locus BED files; the installed hg19 files when left out. | None |
| repeats_buildstr | The build of the repeat loci given in beds. | None |
| min_del_sizeint | The smallest deletion counted for the HRD indel features. | None |
| min_mh_sizeint | The smallest microhomology counted as microhomology-mediated. | None |
Returns A DataFrame, one row per sample: mmej, nhej, nins, ndel, nmsi_ins, nmsi_del.
hrd_model
Load an HRD model.
sg2.hrd_model(name=None, seq_type=None) -> HRDModel
| Parameter | Description | Default |
|---|---|---|
| namestr | The model's name in the store. | None |
| seq_typestr | The platform whose model to load, when name is left out. | None |
Returns An HRDModel for the platform: its ensembles, variants and covered_tumor_types().
An HRDModel has covered_tumor_types(), unscorable_tumor_types() and meta (variants, pooled_types, groups, sig3, gis_grid, …).
import sigma2 as sg2
from sigma2 import classifiers
# Card(tumor_type, classifier, seq_type, kind, status, verified, trained, snv_cutoff)
cards = classifiers.cards(tumor_type="breast")
released = [c for c in cards if c.kind == "signature" and c.status != "experimental"]
names = sg2.models(tumor_type="breast", seq_type="msk")
covered = sg2.hrd_model("msk").covered_tumor_types()
platforms = classifiers.mmrd_platforms()
# ['fo', 'msk', 'op', 'seqcap', 'tcga_mc3']
tumor_types = sg2.get("indices/tumor_types")
seq_types = sg2.SeqType.options()
Used in 3. Detect HRD, For AI agents
hrd_models
The installed HRD models: fo, msk, op, seqcap, tcga_mc3, plus yours.
sg2.hrd_models() -> list[str]
hrd_models takes no parameters.
Returns The installed HRD models, one per platform, plus yours.
hrd.hrd_summary
Own or pooled per tumor type and platform, and the variants each model has.
sg2.hrd.hrd_summary() -> DataFrame
Returns DataFrame.
tune_hrd
Train an HRD model.
sg2.tune_hrd(features, labels="brca", seq_type=None, tumor_type="tumor_type", min_positives=10, neighbors=3,
cv=5, seed=0, sig3=None, name=None, save=True, description=None, gis_grid=None,
grid_genome=None, variants=None, complete=None) -> HRDModel
| Parameter | Description | Default |
|---|---|---|
| featuresDataFrame | An hrd_features() table of MMR-proficient tumors. | Required |
| labelsSeries or str | Biallelic BRCA1/2 status per sample as a bool Series, or the name of that column in features. | 'brca' |
| seq_typestr | The assay the features come from; also the model's name unless name is given. | None |
| tumor_typeSeries or str | The per-sample tumor type as a Series, or the name of that column. | 'tumor_type' |
| min_positivesint | Tumor types with more step-1 HRD tumors than this get their own model. | 10 |
| neighborsint | BRCA-wild-type nearest neighbors added per BRCA-deficient tumor in step 1. | 3 |
| cvint | The number of cross-validation folds. | 5 |
| seedint | The random seed of the folds. | 0 |
| sig3dict | The SigMA settings the Signature 3 features were computed with, recorded for scoring. | None |
| namestr | The model's name in the store; the assay's when left out. | None |
| savebool | Write the model to <data dir>/sysdata/hrd/<name>. | True |
| descriptionstr | A description recorded on the model. | None |
| gis_griddict | The panel gene grid the training GIS was computed on, recorded so scoring computes it the same way. | None |
| grid_genomestr | The build of gis_grid's coordinates. | None |
| variantsdict | Variant name to input columns, in order of preference for scoring. | None |
| completeSeries or str | Per sample, whether its truth is complete (germline included), or that column's name. | None |
Returns A trained HRD model, written to its directory, with its cross-validation summary.
Validation is cross-validation only.
Checks: at least 2 positives; a copy-number variant needs at least 50 rows with its inputs.