.. py:module:: civic The **civic** module ====================== CIViCpy is primarily designed to enable exploration of the content of CIViC through Python :class:`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 ------------- .. autoclass:: CivicRecord :members: .. automethod:: __init__ .. attribute:: type The type of record. This field is set automatically by child classes and should not be changed. .. attribute:: 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. .. attribute:: site_link A URL string to the appropriate landing page for the CivicRecord on the CIViC web application. CIViC record types ~~~~~~~~~~~~~~~~~~ The primary CIViC records are found on the CIViC advanced search page, and are fully-formed .. autoclass:: Gene :show-inheritance: .. attribute:: description A curated summary of the clinical significance of this gene. .. attribute:: entrez_id The `Entrez ID`_ associated with this gene. .. attribute:: name The `HGNC Gene Symbol`_ associated with this gene. .. attribute:: aliases A list of alternate gene symbols by which this gene is referenced. .. attribute:: variants A list of :class:`Variant` records associated with this gene. .. attribute:: lifecycle_actions A :class:`LifecycleAction` container. .. _Entrez ID: https://www.ncbi.nlm.nih.gov/gene/ .. _HGNC Gene Symbol: https://www.genenames.org/ .. autoclass:: Variant :show-inheritance: .. attribute:: allele_registry_id The `ClinGen Allele Registry ID`_ associated with this variant. .. attribute:: civic_actionability_score The CIViC `actionability score`_ associated with this variant. .. attribute:: description summary A curated summary of the clinical significance of this variant. .. attribute:: entrez_id The `Entrez ID`_ of the gene this variant belongs to. .. attribute:: entrez_name The `HGNC Gene Symbol`_ of the gene this variant belongs to. .. attribute:: gene The :class:`Gene` this variant belongs to. .. attribute:: gene_id The :attr:`CivicRecord.id` of the gene this variant belongs to. .. attribute:: name The curated name given to this variant. .. attribute:: assertions A list of :class:`Assertion` records associated with this variant. .. attribute:: clinvar_entries A list of `clinvar ids`_ associated with this variant. .. attribute:: coordinates A :class:`CivicAttribute` object describing `CIViC coordinates`_. .. attribute:: evidence_items evidence A list of :class:`Evidence` associated with this variant. .. attribute:: evidence_sources A list of :class:`CivicAttribute` source objects associated with the evidence from this variant. .. attribute:: hgvs_expressions Curated `HGVS expressions`_ describing this variant. .. attribute:: sources A list of :class:`CivicAttribute` source objects associated with the variant description. .. attribute:: variant_aliases aliases A curated list of aliases by which this variant is referenced. .. attribute:: variant_groups groups A list of `variant groups`_ to which this variant belongs. .. attribute:: variant_types types A list of :class:`CivicAttribute` objects describing `variant types`_ from the `Sequence Ontology`_. .. attribute:: lifecycle_actions A :class:`LifecycleAction` container. .. _ClinGen Allele Registry ID: http://reg.clinicalgenome.org .. _actionability score: https://docs.civicdb.org/en/latest/model/variants/evidence_score.html .. _clinvar ids: https://www.ncbi.nlm.nih.gov/clinvar .. _CIViC coordinates: https://docs.civicdb.org/en/latest/model/variants/coordinates.html .. _HGVS expressions: https://varnomen.hgvs.org .. _variant groups: https://docs.civicdb.org/en/latest/model/variant_groups.html .. _variant types: https://docs.civicdb.org/en/latest/model/variants/types.html .. _Sequence Ontology: http://www.sequenceontology.org/ .. autoclass:: Evidence :show-inheritance: .. attribute:: assertions CIViC :class:`Assertion` records containing this evidence. .. attribute:: clinical_significance A string indicating the type of clinical significance statement being made, values are defined based on the corresponding :attr:`evidence_type`. Please see `Understanding Clinical Significance`_ for more details on the expected values for this field. .. attribute:: description statement The Evidence Statement (returned as `description` by the CIViC API) is a brief summary of the clinical implications of the :attr:`variant` in the context of the specific :attr:`disease`, :attr:`evidence_type`, and :attr:`clinical_significance` as curated from the cited literature source. .. attribute:: disease The cancer or cancer subtype context for the evidence record. .. attribute:: drugs Zero or more drug :class:`CivicAttribute`, linked to corresponding `NCIT`_ terms when applicable. Only used with therapeutic response predictive :attr:`evidence_type`. .. attribute:: drug_interaction_type One of 'Combination', 'Sequential', or 'Substitutes', this field describes how multiple indicated drugs within a therapeutic response predictive :attr:`evidence_type` are related. .. attribute:: evidence_direction One of 'Supports', 'Does Not Support' or 'N/A', indicating whether the evidence statement supports or refutes the clinical significance of an event. The evidence_direction is 'N/A' for Predisposing evidence items. .. attribute:: 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`_. .. attribute:: 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 four types: Predictive, Prognostic, Predisposing and Diagnostic. .. attribute:: gene_id An integer designating the :attr:`CivicRecord.id` for the gene associated with this evidence record. .. attribute:: lifecycle_actions A :class:`LifecycleAction` container. .. attribute:: name A system-generated unique identifier for the evidence record, e.g. `EID7`. .. attribute:: phenotypes Zero or more phenotype :class:`CivicAttribute`, linked to corresponding Human Phenotype Ontology (`HPO`_) terms when applicable. .. attribute:: 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`_. .. attribute:: source A :class:`CivicAttribute` source object from which this evidence was derived. .. attribute:: 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 .. _Understanding Levels: https://civic.readthedocs.io/en/latest/model/evidence/level.html#understanding-levels .. _Understanding Evidence Ratings: https://civic.readthedocs.io/en/latest/model/evidence/evidence_rating.html#understanding-evidence-ratings .. autoclass:: Assertion :show-inheritance: .. attribute:: acmg_codes Evidence codes used in the assessment of variants under the `ACMG/AMP`_ classification guidelines. .. attribute:: allele_registry_id The `ClinGen Allele Registry ID`_ associated with the assertion's variant. .. attribute:: amp_level The clinical interpretation classification by `AMP/ASCO/CAP`_ or `ACMG/AMP`_ guidelines. .. attribute:: clinical_significance A string indicating the type of clinical significance statement being made, values are defined based on the corresponding :attr:`evidence_type`. Please see `Understanding Clinical Significance`_ for more details on the expected values for this field. .. attribute:: description The Assertion Description gives detail including practice guidelines and approved tests for the variant. See `curating assertions`_ for more details. .. attribute:: disease A disease :class:`CivicAttribute`, linked to a corresponding `Disease Ontology`_ term when applicable. .. attribute:: drugs Zero or more drug :class:`CivicAttribute`, linked to corresponding `NCIT`_ terms when applicable. Only used with therapeutic response predictive :attr:`evidence_type`. .. attribute:: drug_interaction_type One of 'Combination', 'Sequential', or 'Substitutes', this field describes how multiple indicated drugs within a therapeutic response predictive :attr:`evidence_type` assertion are related. .. attribute:: evidence_direction One of 'Supports' or 'Does Not Support', indicating whether the evidence statement supports or refutes the clinical significance of an event. .. attribute:: 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 four types: Predictive, Prognostic, Predisposing and Diagnostic. .. attribute:: fda_companion_test A boolean indicating whether or not the assertion has an associated FDA companion test. .. attribute:: fda_regulatory_approval A boolean indicating whether or not the drugs indicated in the assertion have regulatory approval for use in the treatment of the assertion disease. .. attribute:: lifecycle_actions A :class:`LifecycleAction` container. .. attribute:: name A system-generated unique identifier for the assertion, e.g. `AID7`. .. attribute:: nccn_guideline A string linking the assertion to the corresponding `NCCN Guidelines for treatment of cancer by disease site`_, if applicable. .. attribute:: nccn_guideline_version The version associated with the indicated :attr:`nccn_guideline` document. .. attribute:: phenotypes Zero or more phenotype :class:`CivicAttribute`, linked to corresponding Human Phenotype Ontology (`HPO`_) terms when applicable. .. attribute:: 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 .. attribute:: summary The Assertion Summary restates the Clinical 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 Clinical Significance, especially when displayed in a longer list with other variants. .. attribute:: variant The :class:`Variant` associated with this assertion. .. attribute:: variant_origin The origin of this variant, one of 'Somatic', 'Rare Germline', 'Common Germline', 'Unknown', 'N/A', 'Germline or Somatic' .. _AMP/ASCO/CAP: https://www.ncbi.nlm.nih.gov/pubmed/27993330 .. _ACMG/AMP: https://www.ncbi.nlm.nih.gov/pubmed/25741868 .. _curating assertions: https://docs.civicdb.org/en/latest/curating/assertions.html .. _Disease Ontology: http://disease-ontology.org/ .. _documentation on evidence types: https://docs.civicdb.org/en/latest/model/evidence/type.html .. _NCIT: https://ncit.nci.nih.gov/ncitbrowser/ .. _NCCN Guidelines for treatment of cancer by disease site: https://www.nccn.org/professionals/physician_gls/default.aspx#site .. _HPO: https://hpo.jax.org/ .. _Understanding Clinical Significance: https://docs.civicdb.org/en/latest/model/evidence/clinical_significance.html#understanding-clinical-significance CIViC attributes ~~~~~~~~~~~~~~~~ The :class:`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, drugs). CivicAttributes are not cached except as attached objects to non-:class:`CivicAttribute` :class:`CivicRecord` objects, and cannot be retrieved independently. .. autoclass:: CivicAttribute Record provenance ~~~~~~~~~~~~~~~~~ The :class:`LifecycleAction` class is used to track the provenance of many types of :class:`CivicRecord`, by serving as a container class for :class:`BaseLifecycleAction` objects which in turn specify the timestamp and :class:`User` associated with a given action on a record. .. autoclass:: LifecycleAction :show-inheritance: .. autoclass:: BaseLifecycleAction :show-inheritance: .. attribute:: timestamp A CIViC timestamp string indicating the time the BaseLifecycleAction took place. .. attribute:: user A CIViC :class:`User` object. .. autoclass:: Submitted :show-inheritance: .. autoclass:: LastModified :show-inheritance: .. autoclass:: LastReviewed :show-inheritance: .. autoclass:: Accepted :show-inheritance: .. autoclass:: User :show-inheritance: .. attribute:: name The user-defined full name for the :class:`User`. .. attribute:: username The user-defined system name for the :class:`User`. .. attribute:: role The CIViC role held by a :class:`User`: Administrator, Editor, or Curator. .. attribute:: area_of_expertise An optional attribute for a :class:`User` indicating their perspective as a CIViC participant: Research Scientist, Clinical Scientist, or Patient Advocate. .. attribute:: orcid An optional attribute for a :class:`User` indicating their `ORCiD `_. .. attribute:: display_name This attribute is populated with the first non-blank value from :attribute:`username`, :attribute:`name`, :attribute:`email`, or :attribute:`id`. .. attribute:: created_at A `datetime` describing when the :class:`User` object was created. .. attribute:: url A string describing a personal website or blog for the :class:`User`. .. attribute:: twitter_handle A string describing the Twitter handle for a :class:`User`. .. attribute:: facebook_profile A string describing the Facebook profile ID for a :class:`User`. .. attribute:: linkedin_profile A string describing the Linked profile ID for a :class:`User`. .. attribute:: bio A short biography for a :class:`User`. .. attribute:: featured_expert A flag indicating if a user is a featured expert, and thus displayed on the CIViC `domain experts `_ section .. autoclass:: Organization :show-inheritance: .. attribute:: name The :class:`Organization` name. .. attribute:: url A URL for more information about the :class:`Organization`. .. attribute:: description A short text description about the :class:`Organization`. .. attribute:: profile_image A set of resource paths for the :class:`Organization` image at varying resolution. .. attribute:: parent A parent :class:`Organization`, if applicable. .. autoclass:: Country :show-inheritance: .. attribute:: iso The `ISO 3166 Country Code `_ for the :class:`Country`. .. attribute:: name The full-text name for the :class:`Country`. Getting records --------------- By ID ~~~~~ Records can be obtained by ID through a collection of functions provided in the `civic` module. :class:`Gene` objects can be queried by the following methods: .. autofunction:: get_gene_by_id .. autofunction:: get_genes_by_ids .. autofunction:: get_all_genes .. autofunction:: get_all_gene_ids Analogous methods exist for :class:`Variant`, :class:`Assertion`, and :class:`Evidence`: .. autofunction:: get_variants_by_ids .. autofunction:: get_variant_by_id .. autofunction:: get_all_variants .. autofunction:: get_all_variant_ids .. autofunction:: get_assertions_by_ids .. autofunction:: get_assertion_by_id .. autofunction:: get_all_assertions .. autofunction:: get_all_assertion_ids .. autofunction:: get_all_evidence .. autofunction:: get_all_evidence_ids By Coordinate ~~~~~~~~~~~~~ Variant records can be searched by GRCh37 coordinates. To query specific genomic coordinates, you will need to construct a :class:`CoordinateQuery` object, and pass this query to the :func:`search_variants_by_coordinates` function. If you wish to query multiple genomic coordinates (e.g. a set of variants observed in a patient tumor), construct a sorted list of :class:`CoordinateQuery` objects (sorted by `chr`, `start`, `stop`, `alt`), and pass the list to the :func:`bulk_search_variants_by_coordinates` function. .. autoclass:: CoordinateQuery .. autofunction:: search_variants_by_coordinates .. autofunction:: bulk_search_variants_by_coordinates