The civic module

CIViCpy is primarily designed to enable exploration of the content of CIViC through Python CivicRecord objects. While these record objects can be initialized independently, the civic module also provides several routines for Getting Records directly from CIViC. Use of these routines is recommended.

The civic module may be imported from civicpy at the top level:

>>>from civicpy import civic

CIViC Records

class civic.CivicRecord(partial=False, **kwargs)

As a base class, CivicRecord is used to define the characteristic of all records in CIViC. This class is not intended to be invoked directly by the end user, but provided for documentation of shared methods and variables in child classes.

__init__(partial=False, **kwargs)

The record object may be initialized by the user, though the practice is discouraged. To do so, values for each of the object attributes (except type) must be specified as keyword arguments, or the partial parameter must be set to True. If partial is set to True, the id keyword argument is still required.

Users are encouraged to use the functions for Getting Records in lieu of directly initializing record objects.

Parameters:

partial (bool) – Indicates whether the the set of object attributes passed is incomplete. If set to True the id keyword is required.

type

The type of record. This field is set automatically by child classes and should not be changed.

id

The record ID. This is set on initialization using the id keyword argument, and reflects the primary ID for the record as stored in CIViC.

property site_link

Returns a URL to the record on the CIViC web application.

update(allow_partial=True, force=False, **kwargs)

Updates the record object from the cache or the server. Keyword arguments may be passed to kwargs, which will update the corresponding attributes of the CivicRecord instance.

Parameters:

• allow_partial (bool) – Flag to indicate whether the record will be updated according to the contents of CACHE, without requiring all attributes to be assigned.

• force (bool) – Flag to indicate whether to force an update from the server, even if a full record exists in the cache.

Returns:

True if record is complete after update, else False.

The primary CIViC records are found on the sidebar menu on CIViC, and are fully-formed.

Gene

class civic.Gene(**kwargs)

Bases: CivicRecord

aliases

A list of alternate gene symbols by which this gene is referenced.

description

A curated summary of the clinical significance of this gene.

entrez_id

The Entrez ID associated with this gene.

name

The HGNC Gene Symbol associated with this gene.

property sources

A list of Source records associated with the gene description.

property variants

A list of Variant records associated with this gene.

Factor

class civic.Factor(**kwargs)

Bases: CivicRecord

aliases

A list of alternate names by which this factor is referenced.

description

A curated summary of the clinical significance of this factor.

full_name

Factor names are often an commonly-used abbreviation. The full name is the unabbreviated name.

name

The shortest, most concise reference to the factor. Often an abbreviation.

ncit_id

The NCIthesaurus ID referencing the factor.

property sources

A list of Source records associated with the factor description.

property variants

A list of Variant records associated with this factor.

Fusion

class civic.Fusion(**kwargs)

Bases: CivicRecord

subtype

aliases

A list of alternate names by which this fusion is referenced.

description

A curated summary of the clinical significance of this fusion.

five_prime_gene_id

The CivicRecord.id of the 5’ fusion partner Gene if that partner is KNOWN.

five_prime_partner_status

The status of the 5’ fusion partner. One of KNOWN, UNKNOWN, or MULTIPLE.

name

The name of the fusion. This will be the 5’ partner, followed by the 3’ partner, separated by ::. If a partner is KNOWN, the HGNC Gene Symbol of the partner gene is used. If the partner is UNKNOWN, a ? is used. If there are MULTIPLE possible gene partners, v is used.

three_prime_gene_id

The CivicRecord.id of the 3’ fusion partner Gene if that partner is KNOWN.

three_prime_partner_status

The status of the 3’ fusion partner. One of KNOWN, UNKNOWN, or MULTIPLE.

property five_prime_gene

The Gene record of the 5’ fusion partner if that partner is KNOWN.

property sources

A list of Source records associated with the fusion description.

property three_prime_gene

The Gene record of the 3’ fusion partner if that partner is KNOWN.

property variants

A list of Variant records associated with this fusion.

Region

class civic.Region(**kwargs)

Bases: CivicRecord

aliases

A list of alternate names by which this region is referenced.

description

A curated summary of the clinical significance of this region.

name

The name of the region. Either a chromosome, a chromosome arm, or a cytoband.

property sources

A list of Source records associated with the region description.

property variants

A list of Variant records associated with this region.

Variant

class civic.Variant(**kwargs)

Bases: CivicRecord

feature_id

The CivicRecord.id of the Gene, Factor, Fusion, or Region the variant belongs to.

name

The curated name given to this variant.

single_variant_molecular_profile_id

The CivicRecord.id of the MolecularProfile representing the single variant on its own.

subtype

The specific type of variant. One of gene_variant, factor_variant, or fusion_variant.

variant_aliases

A curated list of aliases by which this variant is referenced.

variant_types

A list of VariantType objects describing variant types from the Sequence Ontology.

property aliases

A curated list of aliases by which this variant is references. Shorthand for the variant_aliases attribute.

property groups

A list of VariantGroup records to which this variant belongs. Shorthand for the variant_groups attribute.

property molecular_profiles

A list of MolecularProfile records involving this variant.

property single_variant_molecular_profile

The MolecularProfile record representing the single variant on its own.

property types

A list of CivicAttribute objects describing variant types from the Sequence Ontology.

property variant_groups

A list of VariantGroup records to which this variant belongs.

GeneVariant

class civic.GeneVariant(**kwargs)

Bases: Variant

allele_registry_id

The ClinGen Allele Registry ID associated with this variant.

clinvar_entries

A list of clinvar ids associated with this variant.

coordinates

A Coordinate object describing CIViC coordinates.

entrez_id

The Entrez ID of the gene this variant belongs to.

entrez_name

The HGNC Gene Symbol of the gene this variant belongs to.

hgvs_expressions

Curated HGVS expressions describing this variant.

property feature

The Gene feature this variant belongs to.

property gene

The Gene record this variant belongs to.

property is_deletion

Based on the coordiantes, True if the variant is a deletion, else False.

property is_insertion

Based on the coordiantes, True if the variant is an insertion, else False.

FactorVariant

class civic.FactorVariant(**kwargs)

Bases: Variant

ncit_id

The NCIthesaurus ID referencing the factor variant.

property factor

The Factor record this variant belongs to.

property feature

The Factor feature this variant belongs to.

FusionVariant

class civic.FusionVariant(**kwargs)

Bases: Variant

five_prime_coordinates

A ExonCoordinate object describing CIViC coordinates of the 5’ fusion partner, if that partner is KNOWN.

three_prime_coordinates

A ExonCoordinate object describing CIViC coordinates of the 3’ fusion partner, if that partner is KNOWN.

vicc_compliant_name

A name representing the fusion variant compliant with the VICC fusion specification.

property feature

The Fusion feature this variant belongs to.

property fusion

The Fusion record this variant belongs to.

RegionVariant

class civic.RegionVariant(**kwargs)

Bases: Variant

iscn_name

The International System for Human Cytogenomic Nomenclature Name representing the region variant.

property feature

The Region feature this variant belongs to.

property region

The Region record this variant belongs to.

MolecularProfile

class civic.MolecularProfile(**kwargs)

Bases: CivicRecord

aliases

A curated list of aliases by which this molecular profile is referenced.

description

A curated summary of the clinical significance of this molecular profile.

molecular_profile_score

The CIViC molecular profile score associated with this molecular profile.

name

The human readable name of this molecular profile, including gene and variant names.

source_ids

A list of integers designating the CivicRecord.id for the class:Source records associated with the molecular profile description.

variant_ids

An list of integers designating the CivicRecord.id for the class:Variant records involved in this molecular profile.

property assertions

A list of Assertion records associated with this molecular profile.

property evidence

A shorthand for evidence_items.

property evidence_items

A list of Evidence records associated with this molecular profile.

property evidence_sources

A list of Source records associated with all the Evidence records under this molecular profile.

property sources

A list Source objects involved in this molecular profile.

property summary

A shorthand for the description.

property variants

A list Variant objects involved in this molecular profile.

Evidence

class civic.Evidence(**kwargs)

Bases: CivicRecord

assertion_ids

The list of CivicRecord.id of Assertion records this evidence is a part of.

description

The Evidence Statement (returned as description by the CIViC API) is a brief summary of the clinical implications of the variant in the context of the specific disease, evidence_type, and significance as curated from the cited literature source.

disease_id

The CivicRecord.id of the Disease record of the cancer of cancer subtype context for the evidence record. None for functional evidence_type.

evidence_direction

One of ‘Supports’, ‘Does Not Support’, indicating whether the evidence statement supports or refutes the significance of an event.

evidence_level

The evidence level describes the robustness of the study supporting the evidence item. Five different evidence levels are supported: “A - Validated association”, “B - Clinical evidence”, “C - Case study”, “D - Preclinical evidence”, and “E - Inferential association”. For more information, please see Understanding Levels.

evidence_type

Category of clinical action/relevance implicated by event. Refer to the additional documentation on evidence types for details on how to enter evidence of each of the six types: Predictive, Prognostic, Predisposing, Diagnostic, Functional, and Oncogenic.

molecular_profile_id

The CivicRecord.id of the MolecularProfile this evidence item belongs to.

name

A system-generated unique identifier for the evidence record, e.g. EID7.

phenotype_ids

The list of CivicRecord.id of Phenotype records linked to corresponding Human Phenotype Ontology (HPO) terms when applicable.

rating

The Evidence Rating is an integer from 1 to 5, indicating the curator’s confidence in the quality of the summarized evidence as a number of stars. For more information about this metric, please see Understanding Evidence Ratings.

significance

A string indicating the type of significance statement being made, values are defined based on the corresponding evidence_type. Please see Understanding Significance for more details on the expected values for this field.

source_id

The CivicRecord.id of the Source object this evidence was derived from.

status

One of ‘accepted’, ‘rejected’, or ‘submitted’, describing the state of this evidence in the CIViC curation cycle. An evidence item needs to be reviewed by a CIViC editor before being accepted or rejected. Therefore “submitted” evidence might not be accurate or complete.

• submitted: This evidence has been submitted by a CIViC curator or editor

• accepted: This evidence has been reviewed and approved by a CIViC editor

• rejected: This evidence has been reviewed and rejected by a CIViC editor

therapy_ids

The list of CivicRecord.id of the Therapy objects this evidence item is linked to. Only used with therapeutic response predictive evidence_type.

therapy_interaction_type

One of ‘Combination’, ‘Sequential’, or ‘Substitutes’, this field describes how multiple indicated therapies within a therapeutic response predictive evidence_type are related.

property assertions

CIViC Assertion records containing this evidence.

property disease

The Disease record of the cancer or cancer subtype context for the evidence record. None for functional evidence_type.

is_valid_for_gks_json(emit_warnings: bool = False) → bool

Determine whether Evidence is able to be represented as GKS model

Parameters:

emit_warnings – Whether to log warnings, defaults to False

Returns:

True if Evidence is able to be represented as GKS model. False otherwise

property molecular_profile

The MolecularProfile object this evidence item belongs to.

property phenotypes

Zero or more Phenotype records, linked to corresponding Human Phenotype Ontology (HPO) terms when applicable.

property source

A Source object from which this evidence was derived.

property statement

A shorthand for the evidence description.

property therapies

Zero or more Therapy records, linked to corresponding NCIt terms when applicable. Only used with therapeutic response predictive evidence_type.

property variants

One or more Variant objects associated with this evidence’s molecular profile.

Assertion

class civic.Assertion(**kwargs)

Bases: CivicRecord

acmg_codes

A list of AcmgCode objects describing the evidence codes used in the assessment of germline variant pathogenicity under the ACMG/AMP classification guidelines.

amp_level

The clinical tiering of somatic variants by AMP/ASCO/CAP guidelines.

assertion_direction

One of ‘Supports’ or ‘Does Not Support’, indicating whether the evidence statement supports or refutes the significance of an event.

assertion_type

Category of clinical action/relevance implicated by event. Refer to the additional documentation on assertion types for details on how to enter assertions of each of the five types: Predictive, Prognostic, Predisposing, Diagnostic, and Oncogenic.

clingen_codes

A list of ClingenCode objects describing the classification of somatic variant oncogenicity under the ClinGen/CGC/VICC classification guidelines.

description

The Assertion Description gives detail including practice guidelines and approved tests for the molecular profile. See curating assertions for more details.

disease_id

The CivicRecord.id of the Disease record of the cancer of cancer subtype context for the assertion record.

evidence_ids

A list of CivicRecord.id of the Evidence records supporting this assertion record.

fda_companion_test

A boolean indicating whether or not the assertion has an associated FDA companion test.

fda_regulatory_approval

A boolean indicating whether or not the therapies indicated in the assertion have regulatory approval for use in the treatment of the assertion disease.

molecular_profile_id

The CivicRecord.id of the molecular profile this assertion belongs to.

name

A system-generated unique identifier for the assertion, e.g. AID7.

nccn_guideline

A string linking the assertion to the corresponding NCCN Guidelines for treatment of cancer by disease site, if applicable.

nccn_guideline_version

The version associated with the indicated nccn_guideline document.

phenotype_ids

Zero or more Phenotype CivicRecord.id, linked to corresponding Human Phenotype Ontology (HPO) terms when applicable.

significance

A string indicating the type of significance statement being made, values are defined based on the corresponding evidence_type. Please see Understanding Significance for more details on the expected values for this field.

status

One of ‘accepted’, ‘rejected’, or ‘submitted’, describing the state of this assertion in the CIViC curation cycle. An Assertion needs to be reviewed by a CIViC editor before being accepted or rejected. Therefore “submitted” Assertions might not be accurate or complete.

• submitted: This assertion has been submitted by a CIViC curator or editor

• accepted: This assertion has been reviewed and approved by a CIViC editor

• rejected: This assertion has been reviewed and rejected by a CIViC editor

summary

The Assertion Summary restates the Significance as a brief single sentence statement. It is intended for potential use in clinical reports. The Assertion Summary is designed for rapid communication of the Significance, especially when displayed in a longer list with other molecular profiles.

therapy_interaction_type

One of ‘Combination’, ‘Sequential’, or ‘Substitutes’, this field describes how multiple indicated therapies within a therapeutic response predictive evidence_type assertion are related.

variant_origin

The origin of the variants in this molecular profile, one of ‘Somatic’, ‘Rare Germline’, ‘Common Germline’, ‘Unknown’, ‘N/A’, ‘Germline or Somatic’, or ‘Mixed’

property approvals

Zero or more Approval records representing organizations approving this assertion.

property disease

The Disease record of the cancer or cancer subtype context for the assertion, linked to a corresponding Disease Ontology term when applicable.

property evidence

A shortcut for the evidence_items property.

property evidence_items

A list of Evidence records supporting this assertion.

property hpo_ids

A list of HPO IDs of the phenotypes associated with this assertion

is_valid_for_gks_json(emit_warnings: bool = False) → bool

Determine whether Assertion is able to be represented as GKS model

Parameters:

emit_warnings – Whether to log warnings, defaults to False

Returns:

True if Assertion is able to be represented as GKS model. False otherwise

property molecular_profile

The MolecularProfile object this assertion belongs to.

property phenotypes

Zero or more Phenotype records associated with the assertion, linked to corresponding Human Phenotype Ontology (HPO) terms.

property therapies

Zero or more Therapy records, linked to corresponding NCIt terms when applicable. Only used with therapeutic response predictive evidence_type.

property variants

One or more Variant objects associated with this assertion’s molecular profile.

Source

class civic.Source(**kwargs)

abstract

The abstract text of the source.

asco_abstract_id

For ASCO sources, the abstract ID.

author_string

A string of all of the authors of the source or, for ASCO sources, the abstract presenter.

citation

A short string containing key information about the source for human-readable identification.

citation_id

A unique identifier for the source. For PubMed sources, this is the PMID. For ASH sources this is the DOI. For ASCO sources this is the ASCO Web ID found in the URL of the abstract.

clinical_trials

A list of ClinicalTrial objects of Clinical Trials described in the source.

full_journal_title

The full title of the publishing journal.

journal

An abbreviated version of the title of the publishing journal.

pmc_id

When available, the PubMed Central ID of the source.

publication_date

The date the source was published.

source_type

The platform making the source available. One of PUBMED, ASCO, or ASH.

source_url

A link to the source on the platfrom that made the source available.

title

The title of the source.

property evidence

A shortcut for the evidence_items property.

property evidence_items

A list of Evidence records linked to this source.

property factors

A list of Factor records supported by this source.

property fusions

A list of Fusion records supported by this source.

property genes

A list of Gene records supported by this source.

property molecular_profiles

A list of MolecularProfile records supported by this source.

property regions

A list of Region records supported by this source.

Disease

class civic.Disease(**kwargs)

aliases

A list of alternate names for the disease.

disease_url

A link to the Disease Ontology entry for the disease concept.

doid

The Disease Ontology ID for the disease concept.

name

The name of the disease.

property assertions

A list of Assertion records linked to this disease.

property evidence

A shortcut for the evidence_items property.

property evidence_items

A list of Evidence records linked to this disease.

Therapy

class civic.Therapy(**kwargs)

aliases

A list of alternate names for the therapy.

name

The name of the therapy.

ncit_id

The NCIthesaurus ID for the therapy concept.

therapy_url

A link to the NCIthesaurus entry for the therapy concept.

property assertions

A list of Assertion records linked to this therapy.

property evidence

A shortcut for the evidence_items property.

property evidence_items

A list of Evidence records linked to this therapy.

Phenotype

class civic.Phenotype(**kwargs)

name

The name of the phenotype.

hpo_id

The Human Phenotype Ontology ID for the phenotype concept.

phenotype_url

A link to the Human Phenotype Ontology entry for the phenotype concept.

property assertions

A list of Assertion records linked to this phenotype.

property evidence

A shortcut for the evidence_items property.

property evidence_items

A list of Evidence records linked to this phenotype.

Organization

class civic.Organization(**kwargs)

name

The name of the organization.

url

The URL of the organization’s website.

description

A description of the organization.

property approvals

Zero or more Approval records representing assertions approved by this organization.

Approval

class civic.Approval(partial=False, **kwargs)

assertion_id

The CivicRecord.id of the Assertion record that this approval pertains to.

last_reviewed

Timestamp reflecting the last time the approval was reviewed and put into active status.

organization_id

The CivicRecord.id of the Organization record that approved the assertion.

ready_for_clinvar_submission

Boolean, reflecting whether the approval meets all criteria for submission of the assertion to ClinVar.

status

The status of the approval. One of ACTIVE, REQUIRES_REVIEW, or REVOKED.

property assertion

The Assertion object this approval applies to.

property organization

The Organization object this approval was made on behalf of.

CIViC Attributes

The CivicAttribute class is a special type of CivicRecord that is not indexed, and is used as a base class for additional complex records beyond those mentioned above (e.g. diseases, therapies). CivicAttributes are not cached except as attached objects to non-CivicAttribute CivicRecord objects, and cannot be retrieved independently.

Some complex records are:

class civic.Coordinate(**kwargs)

chromosome

start

stop

reference_bases

variant_bases

ensembl_version

representative_transcript

reference_build

class civic.ExonCoordinate(**kwargs)

chromosome

ensembl_id

ensembl_version

exon

exon_offset

exon_offset_direction

reference_build

representative_transcript

start

stop

strand

class civic.ClingenCode(**kwargs)

code

description

class civic.AcmgCode(**kwargs)

code

description

class civic.ClinicalTrial(**kwargs)

name

description

nct_id

url

class civic.VariantType(**kwargs)

name

so_id

description

url