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)[source]¶ 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)[source]¶ 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 thepartial
parameter must be set to True. Ifpartial
is set to True, theid
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)[source]¶ Updates the record object from the cache or the server. Keyword arguments may be passed to
kwargs
, which will update the corresponding attributes of theCivicRecord
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 fromt he server, even if a full record ecists in the cache.
- Returns
True if record is complete after update, else False.
-
CIViC record types¶
The primary CIViC records are found on the CIViC advanced search page, and are fully-formed
-
class
civic.
Gene
(**kwargs)[source]¶ -
description
¶ A curated summary of the clinical significance of this gene.
-
name
¶ The HGNC Gene Symbol associated with this gene.
-
aliases
¶ A list of alternate gene symbols by which this gene is referenced.
-
-
class
civic.
Variant
(**kwargs)[source]¶ -
allele_registry_id
¶ The allele registry id associated with this variant.
-
civic_actionability_score
¶ The CIViC actionability score associated with this variant.
-
description
¶ A curated summary of the clinical significance of this variant.
-
entrez_name
¶ The HGNC Gene Symbol of the gene this variant belongs to.
-
gene_id
¶ The
CivicRecord.id
of the gene this variant belongs to.
-
name
¶ The curated name given to this variant.
-
clinvar_entries
¶ A list of clinvar ids associated with this variant.
-
coordinates
¶ A
CivicAttribute
object describing CIViC coordinates.
-
evidence_sources
¶ A list of sources associated with the evidence from this variant.
-
hgvs_expressions
¶ Curated HGVS expressions describing this variant.
-
sources
¶ A list of sources objects associated with the variant description.
-
variant_groups
¶ -
groups
¶ A list of variant groups to which this variant belongs.
-
variant_types
¶ -
types
¶ A list of
CivicAttribute
objects describing variant types from the Sequence Ontology.
-
CIViC attributes¶
The CivicAttribute
class is a special type of CivicRecord that is not indexed, and is used as a base container
class for additional complex records beyond those mentioned above (e.g. diseases, drugs). CivicAttributes are not cached
except as attached objects to non-CivicAttribute
CivicRecord
objects, and cannot be retrieved
independently.
-
class
CivicAttribute
¶
Getting records¶
Records can be obtained by ID through a collection of functions provided in the civic module. Gene
objects can be queried by the following methods:
-
civic.
get_gene_by_id
(gene_id)[source]¶ - Parameters
gene_id (int) – A single CIViC gene ID.
- Returns
A
Gene
object.
-
civic.
get_genes_by_ids
(gene_id_list)[source]¶ - Parameters
gene_id_list (list) – A list of CIViC gene IDs to query against to cache and (as needed) CIViC.
- Returns
A list of
Gene
objects.
-
civic.
get_all_genes
(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)[source]¶ Queries CIViC for all genes. The cache is not considered by this function.
- Parameters
include_status (list) – A list of statuses. Only genes and their associated entities matching the given statuses will be returned.
allow_cached (bool) – Indicates whether or not object retrieval from CACHE is allowed. If False it will query the CIViC database directly.
- Returns
A list of
Gene
objects.
-
civic.
get_all_gene_ids
()[source]¶ Queries CIViC for a list of all gene IDs. Useful for passing to
get_genes_by_ids()
to first check cache for any previously queried genes.- Returns
A list of all CIViC gene IDs.
Analogous methods exist for Variant
, Assertion
, and Evidence
:
-
civic.
get_variants_by_ids
(variant_id_list)[source]
-
civic.
get_variant_by_id
(variant_id)[source]
-
civic.
get_all_variants
(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)[source]
-
civic.
get_all_variant_ids
()[source]
-
civic.
get_assertions_by_ids
(assertion_id_list=[], get_all=False)[source]
-
civic.
get_assertion_by_id
(assertion_id)[source]
-
civic.
get_all_assertions
(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)[source]
-
civic.
get_all_assertion_ids
()[source]
-
civic.
get_all_evidence
(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)[source]
-
civic.
get_all_evidence_ids
()[source]