Getting Records

CIViCpy offeres a wide range of convenience methods as part of the civic module to retrieve different CIViC entities.

Get All Records For A Specific Entity Type

Features

civic.get_all_features(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all features.

Parameters:

• include_status (list) – A list of statuses. Only features and their associated entities matching the given statuses will be returned. Use None to include features without any associated entities.

• 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, Fusion, and/or Factor objects.

civic.get_all_genes(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all gene features.

Parameters:

• include_status (list) – A list of statuses. Only genes and their associated entities matching the given statuses will be returned. Use None to include genes without any associated entities.

• 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_factors(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all factor features.

Parameters:

• include_status (list) – A list of statuses. Only factors and their associated entities matching the given statuses will be returned. Use None to include factors without any associated entities.

• 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 Factor objects.

civic.get_all_fusions(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all fusion features.

Parameters:

• include_status (list) – A list of statuses. Only fusions and their associated entities matching the given statuses will be returned. Use None to include fusions without any associated entities.

• 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 Fusion objects.

Variants

civic.get_all_variants(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all variants.

Parameters:

• include_status (list) – A list of statuses. Only variants and their associated entities matching the given statuses will be returned. Use None to include variants without any associated entities.

• 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 Variant objects.

civic.get_all_gene_variants(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all gene variants.

Parameters:

• include_status (list) – A list of statuses. Only variants and their associated entities matching the given statuses will be returned. Use None to include variants without any associated entities.

• 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 Variant objects of subtype gene_variant.

civic.get_all_factor_variants(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all factor variants.

Parameters:

• include_status (list) – A list of statuses. Only variants and their associated entities matching the given statuses will be returned. Use None to include variants without any associated entities.

• 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 Variant objects of subtype factor_variant.

civic.get_all_fusion_variants(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all fusion variants.

Parameters:

• include_status (list) – A list of statuses. Only variants and their associated entities matching the given statuses will be returned. Use None to include variants without any associated entities.

• 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 Variant objects of subtype fusion_variant.

Molecular Profiles

civic.get_all_molecular_profiles(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all molecular profiles.

Parameters:

• include_status (list) – A list of statuses. Only molecular profiles and their associated entities matching the given statuses will be returned. Use None to include molecular profiles without any associated entities.

• 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 MolecularProfile objects.

Assertions

civic.get_all_assertions(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all assertions.

Parameters:

• include_status (list) – A list of statuses. Only assertions 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 Assertion objects.

civic.get_all_assertions_ready_for_clinvar_submission_for_org(organization_id, allow_cached=True)

Queries CIViC for all assertions endorsed by a specific organization that are ready for submission to ClinVar.

Parameters:

• organization_id (int) – The CIViC organization ID that endorsed the assertion(s) for submission to ClinVar.

• 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 Assertion objects endorsed by a specific organization that are ready for submission to ClinVar.

Evidence Items

civic.get_all_evidence(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all evidence items.

Parameters:

• include_status (list) – A list of statuses. Only evidence items 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 EvidenceItem objects.

Variant Groups

civic.get_all_variant_groups(allow_cached=True)

Queries CIViC for all variant groups.

Parameters:

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 VariantGroup objects.

Sources

civic.get_all_sources(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all sources.

Parameters:

• include_status (list) – A list of statuses. Only sources 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 Source objects.

Diseases

civic.get_all_diseases(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all diseases.

Parameters:

• include_status (list) – A list of statuses. Only diseases 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 Disease objects.

Therapies

civic.get_all_therapies(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all therapies.

Parameters:

• include_status (list) – A list of statuses. Only therapies 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 Therapy objects.

Phenotypes

civic.get_all_phenotypes(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all phenotypes.

Parameters:

• include_status (list) – A list of statuses. Only phenotypes 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 Phenotype objects.

Organizations

civic.get_all_organizations(allow_cached=True)

Queries CIViC for all endorsements.

Parameters:

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 Organization objects.

Endorsements

civic.get_all_endorsements(include_status=['accepted', 'submitted', 'rejected'], allow_cached=True)

Queries CIViC for all endorsements.

Parameters:

• include_status (list) – A list of statuses. Only endorsements for assertions 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 Endorsement objects.

civic.get_all_endorsements_ready_for_clinvar_submission_for_org(organization_id: int) → list[civic.Endorsement]

Queries CIViC for all endorsements by a specific organization that are ready for submission to ClinVar.

Parameters:

organization_id (int) – A CIViC Organization ID.

Returns:

A list of Endorsement objects endorsed by a specific organization that are ready for submission to ClinVar.

By ID

Records can be obtained by CIViC ID through a collection of functions provided in the civic module.

Features

civic.get_feature_by_id(feature_id)

Parameters:

gene_id (int) – A single CIViC feature ID.

Returns:

A Gene, Fusion, or Factor object.

civic.get_features_by_ids(feature_id_list)

Parameters:

feature_id_list (list) – A list of CIViC feature IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Gene, Fusion, and/or Factor objects.

civic.get_gene_by_id(gene_id)

Parameters:

gene_id (int) – A single CIViC gene feature ID.

Returns:

A Gene object.

civic.get_genes_by_ids(gene_id_list)

Parameters:

gene_id_list (list) – A list of CIViC gene feature IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Gene objects.

civic.get_factor_by_id(factor_id)

Parameters:

factor_id (int) – A single CIViC factor feature ID.

Returns:

A Factor object.

civic.get_factors_by_ids(factor_id_list)

Parameters:

factor_id_list (list) – A list of CIViC factor feature IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Factor objects.

civic.get_fusion_by_id(fusion_id)

Parameters:

fusion_id (int) – A single CIViC fusion feature ID.

Returns:

A Fusion object.

civic.get_fusions_by_ids(fusion_id_list)

Parameters:

fusion_id_list (list) – A list of CIViC fusion feature IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Fusion objects.

Variants

civic.get_variant_by_id(variant_id)

Parameters:

variant_id (int) – A single CIViC variant ID.

Returns:

A Variant object.

civic.get_variants_by_ids(variant_id_list)

Parameters:

variant_id_list (list) – A list of CIViC variant IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Variant objects.

Molecular Profiles

civic.get_molecular_profile_by_id(mp_id)

Parameters:

mp_id (int) – A single CIViC molecular profile ID.

Returns:

A MolecularProfile object.

civic.get_molecular_profiles_by_ids(mp_id_list)

Parameters:

mp_id_list (list) – A list of CIViC molecular profile IDs to query against to cache and (as needed) CIViC.

Returns:

A list of MolecularProfile objects.

Assertions

civic.get_assertion_by_id(assertion_id)

Parameters:

assertion_id (int) – A single CIViC assertion ID.

Returns:

A Assertion object.

civic.get_assertions_by_ids(assertion_id_list)

Parameters:

assertion_id_list (list) – A list of CIViC assertion IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Assertion objects.

Evidence Items

civic.get_evidence_by_id(evidence_id)

Parameters:

phenotype_id (int) – A single CIViC evidence item ID.

Returns:

A EvidenceItem object.

civic.get_evidence_by_ids(evidence_id_list)

Parameters:

evidence_id_list (list) – A list of CIViC evidence item IDs to query against to cache and (as needed) CIViC.

Returns:

A list of EvidenceItem objects.

Variant Groups

civic.get_variant_group_by_id(variant_group_id)

Parameters:

variant_group_id (int) – A single CIViC variant group ID.

Returns:

A VariantGroup object.

civic.get_variant_groups_by_ids(variant_group_id_list)

Parameters:

variant_group_id_list (list) – A list of CIViC variant group IDs to query against to cache and (as needed) CIViC.

Returns:

A list of VariantGroup objects.

Sources

civic.get_source_by_id(source_id)

Parameters:

source_id (int) – A single CIViC source ID.

Returns:

A Source object.

civic.get_sources_by_ids(source_id_list)

Parameters:

source_id_list (list) – A list of CIViC source IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Source objects.

Diseases

civic.get_disease_by_id(disease_id)

Parameters:

disease_id (int) – A single CIViC disease ID.

Returns:

A Disease object.

civic.get_diseases_by_ids(disease_id_list)

Parameters:

disease_id_list (list) – A list of CIViC disease IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Disease objects.

Therapies

civic.get_therapy_by_id(therapy_id)

Parameters:

therapy_id (int) – A single CIViC therapy ID.

Returns:

A Therapy object.

civic.get_therapies_by_ids(therapy_id_list)

Parameters:

therapy_id_list (list) – A list of CIViC therapy IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Therapy objects.

Phenotypes

civic.get_phenotype_by_id(phenotype_id)

Parameters:

phenotype_id (int) – A single CIViC phenotype ID.

Returns:

A Phenotype object.

civic.get_phenotypes_by_ids(phenotype_id_list)

Parameters:

phenotype_id_list (list) – A list of CIViC phenotype IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Phenotype objects.

Organizations

civic.get_organization_by_id(organization_id)

Parameters:

organization_id (int) – A single CIViC organization ID.

Returns:

A Organization object.

civic.get_organizations_by_ids(organization_id_list)

Parameters:

organization_id_list (list) – A list of CIViC organization IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Organization objects.

Endorsements

civic.get_endorsement_by_id(endorsement_id)

Parameters:

endorsement_id (int) – A single CIViC endorsement ID.

Returns:

A Endorsement object.

civic.get_endorsements_by_ids(endorsement_id_list)

Parameters:

endorsement_id_list (list) – A list of CIViC endorsement IDs to query against to cache and (as needed) CIViC.

Returns:

A list of Endorsement objects.

By Coordinates

Variant records can be searched by GRCh37 coordinates. To query specific genomic coordinates, you will need to construct a CoordinateQuery object, and pass this query to the 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 CoordinateQuery objects (sorted by chr, start, stop, alt), and pass the list to the bulk_search_variants_by_coordinates() function.

class civic.CoordinateQuery(chr, start, stop, alt=None, ref=None, build='GRCh37', key=None)

A namedtuple with preset fields describing a genomic coordinate, for use with coordinate-based queries of CIViC Variants.

Parameters:

• chr (str) – A chromosome of value 1-23, X, Y

• start (int) – The chromosomal start position in base coordinates (1-based)

• stop (int) – The chromosomal stop position in base coordinates (1-based)

• alt (str optional) – The alternate nucleotide(s) at the designated coordinates

• ref (str optional) – The reference nucleotide(s) at the designated coordinates

• build (NCBI36,GRCh37,GRCh38) – The reference build version of the coordinates

• key (Any optional) – A user-defined object linked to the coordinate

civic.search_variants_by_coordinates(coordinate_query, search_mode='any')

Search the cache for variants matching provided coordinates using the corresponding search mode.

Parameters:

• coordinate_query (CoordinateQuery) – Coordinates to query

• search_mode (any,query_encompassing,variant_encompassing,exact) –

  any : any overlap between a query and a variant is a match

  query_encompassing : CIViC variant records must fit within the coordinates of the query

  record_encompassing : CIViC variant records must encompass the coordinates of the query

  exact : variants must match coordinates precisely, as well as reference allele(s) and alternate allele(s). Use '*' in the coordinate_query as a wildcard for reference and/or alternate alleles. Using None in the coordinate_query for reference or alternate alleles will only match variants that have no reference or alternate alleles, respectively (e.g. indels)

  search_mode is any by default

Returns:

Returns a list of variant hashes matching the coordinates and search_mode

civic.bulk_search_variants_by_coordinates(sorted_queries, search_mode='any')

An interator to search the cache for variants matching the set of sorted coordinates and yield matches corresponding to the search mode.

Parameters:

• sorted_queries (list[CoordinateQuery]) – Sorted list of coordinates to query

• search_mode (any,query_encompassing,variant_encompassing,exact) –

  any : any overlap between a query and a variant is a match

  query_encompassing : CIViC variant records must fit within the coordinates of the query

  record_encompassing : CIViC variant records must encompass the coordinates of the query

  exact : variants must match coordinates precisely, as well as reference allele(s) and alternate allele(s). Use '*' in the coordinate_query as a wildcard for reference and/or alternate alleles. Using None in the coordinate_query for reference or alternate alleles will only match variants that have no reference or alternate alleles, respectively (e.g. indels)

  search_mode is any by default

Returns:

returns a dictionary of Match lists, keyed by query

Coordinates can also be used to query Assertion and Evidence records:

civic.search_assertions_by_coordinates(coordinates, search_mode='any')

Search the cache for variants matching provided coordinates using the corresponding search mode and return all assertions linked to any molecular profile involving those variants.

Parameters:

• coordinate_query (CoordinateQuery) – Coordinates to query

• search_mode (any,query_encompassing,variant_encompassing,exact) –

  any : any overlap between a query and a variant is a match

  query_encompassing : CIViC variant records must fit within the coordinates of the query

  record_encompassing : CIViC variant records must encompass the coordinates of the query

  exact : variants must match coordinates precisely, as well as reference allele(s) and alternate allele(s). Use '*' in the coordinate_query as a wildcard for reference and/or alternate alleles. Using None in the coordinate_query for reference or alternate alleles will only match variants that have no reference or alternate alleles, respectively (e.g. indels)

  search_mode is any by default

Returns:

A list of Assertion objects linked to molecular profiles involving variants matching the coordinates and search_mode

civic.search_evidence_by_coordinates(coordinates, search_mode='any')

Search the cache for variants matching provided coordinates using the corresponding search mode and return all evidence items linked to any molecular profile involving those variants.

Parameters:

• coordinate_query (CoordinateQuery) – Coordinates to query

• search_mode (any,query_encompassing,variant_encompassing,exact) –

  any : any overlap between a query and a variant is a match

  query_encompassing : CIViC variant records must fit within the coordinates of the query

  record_encompassing : CIViC variant records must encompass the coordinates of the query

  exact : variants must match coordinates precisely, as well as reference allele(s) and alternate allele(s). Use '*' in the coordinate_query as a wildcard for reference and/or alternate alleles. Using None in the coordinate_query for reference or alternate alleles will only match variants that have no reference or alternate alleles, respectively (e.g. indels)

  search_mode is any by default

Returns:

A list of EvidenceItem objects linked to molecular profiles involving variants matching the coordinates and search_mode

By Other Attribute

Genes

civic.get_gene_by_entrez_id(entrez_id)

Parameters:

entrez_id (str) – A gene Entrez ID.

Returns:

A Gene object.

civic.get_gene_by_name(name)

Parameters:

name (str) – A HGNC Gene Symbol.

Returns:

A Gene object.

Factors

civic.get_factor_by_ncit_id(ncit_id)

Parameters:

ncit_id (str) – A factor NCIthesaurus ID.

Returns:

A Factor object.

civic.get_factor_by_name(name)

Parameters:

name (str) – A factor name or full name.

Returns:

A Factor object.

Fusions

civic.get_fusion_by_name(name)

Parameters:

name (str) – A fusion name.

Returns:

A Fusion object.

civic.search_fusions_by_partner_gene_id(partner_gene_id)

Parameters:

partner_gene_id (int) – A CIViC ID of one of the gene partners.

Returns:

A list of Fusion object.

Variants

civic.search_variants_by_allele_registry_id(caid)

Search the cache for variants matching the queried Allele Registry ID (CAID)

Parameters:

caid (str) – Allele Registry ID to query

Returns:

Returns a list of variant hashes matching the Allele Registry ID

civic.search_variants_by_hgvs(hgvs)

Search the cache for variants matching the queried HGVS expression

Parameters:

name (str) – HGVS expression to query

Returns:

Returns a list of variant hashes matching the HGVS expression

civic.search_variants_by_name(name)

Search the cache for variants matching the queried name

Parameters:

name (str) – Variant name to query

Returns:

Returns a list of variant hashes matching the name

Sources

civic.get_pubmed_source_by_id(pmid)

Parameters:

pmid (str) – A PubMed ID.

Returns:

A Source object.

civic.get_ash_source_by_doi(doi)

Parameters:

doi (str) – A ASH abstract DOI.

Returns:

A Source object.

civic.get_asco_source_by_id(asco_id)

Parameters:

asco_id (str) – A ASCO Web ID. This is the identification number found in the URL of the abstract.

Returns:

A Source object.

Diseases

civic.get_disease_by_doid(doid)

Parameters:

doid (str) – A single Disease Ontology ID.

Returns:

A Disease object.

civic.get_disease_by_name(name)

Parameters:

name (str) – A single Disease Ontology name.

Returns:

A Disease object.

Therapies

civic.get_therapy_by_ncit_id(ncit_id)

Parameters:

ncit_id (str) – A single NCIthesaurus ID.

Returns:

A Therapy object.

civic.get_therapy_by_name(name)

Parameters:

name (str) – A single NCIthesaurus name.

Returns:

A Therapy object.

Phenotypes

civic.get_phenotype_by_hpo_id(hpo_id)

Parameters:

hpo_id (str) – A single Human Phenotype Ontology ID.

Returns:

A Phenotype object.

civic.get_phenotype_by_name(name)

Parameters:

name (str) – A single Human Phenotype Ontology name (sometimes also referred to as HPO class).

Returns:

A Phenotype object.

Endorsements

civic.search_endorsements_by_organization_id(organization_id)

Parameters:

organization_id (int) – A CIViC Organization ID.

Returns:

A list of Endorsement objects.

civic.search_endorsements_by_assertion_id(assertion_id)

Parameters:

assertion_id (int) – A CIViC Assertion ID.

Returns:

A list of Endorsement objects.