Programmer Interface

clinvar-build provides command line tools for building and querying ClinVar databases.

Database Schema 

The clinvar-schema command creates the SQLite database schema from configuration files.

Example:

# Create VCV schema
clinvar-schema /path/to/output --vcv -v

# Create RCV schema
clinvar-schema /path/to/output --rcv -v

Generate ClinVar SQLite database schemas

usage: clinvar-schema [-h] [--rcv] [--vcv] [-v] directory

Positional Arguments

directory: Directory path where database files will be created

Named Arguments

--rcv

Create RCV schema

Default: False

--vcv

Create VCV schema

Default: False

-v, --verbose

Increase verbosity (-v for INFO, -vv for DEBUG)

Default: 0

Database Parser 

The clinvar-parse command populates a database from ClinVar XML files.

Example:

# Parse VCV XML (full build — schema must be created first with clinvar-schema)
clinvar-parse \
    --db /path/to/clinvar_vcv.db \
    --xml /path/to/ClinVarVCVRelease_00-latest.xml.gz \
    --vcv \
    --batch-size 20 \
    -v

# Parse RCV XML with foreign key enforcement
clinvar-parse \
    --db /path/to/clinvar_rcv.db \
    --xml /path/to/ClinVarRCVRelease_00-latest.xml.gz \
    --rcv \
    --batch-size 50 \
    --enforce-fk \
    -v

Parse ClinVar XML files and populate SQLite database

usage: clinvar-parse [-h] [--db DB] [--xml XML] [--xsd XSD] [--xsd-strict]
                     [--rcv] [--vcv] [--batch-size BATCH_SIZE] [--enforce-fk]
                     [--no-validation] [--count-duplicates] [-v]

Named Arguments

--db

SQLite database path

--xml

The path to the ClinVar XML file

--xsd

The path to the ClinVar XSD file (Optional)

--xsd-strict

Treat XSD validation errors as fatal. By default, elements absent from the XSD are warned but not fatal.

Default: False

--rcv

Create RCV schema

Default: False

--vcv

Create VCV schema

Default: False

--batch-size

Number of top level records to commit at once (default: 10).

Default: 10

--enforce-fk

Enforce foreign keys during parsing (slower but safer)

Default: False

--no-validation

To skip post-build foreign key database validation

Default: True

--count-duplicates

Count duplicated rows per table

Default: False

-v, --verbose

Increase verbosity (-v for INFO, -vv for DEBUG, -vvv TRACE)

Default: 0

The build databases can be queried using standard SQL tools such as dbeaver or other (graphical) user interfaces. The clinvar-build package include a small number of Python wrapped queries provided through argparse based command line entry points.

clinvar-filter

Filter variants by gene, classification, or condition. Output is long format by default (one row per variant × assembly); use --wide for one row per variant with per-assembly column suffixes.

Example:

# Filter by gene
clinvar-filter /path/to/vcv.db \
    -g BRCA1 BRCA2 \
    -o brca_variants.tsv

# Filter by classification, GRCh38 only
clinvar-filter /path/to/vcv.db \
    -c Pathogenic "Likely pathogenic" \
    --grch38 \
    -o pathogenic_grch38.tsv

# Filter with condition pattern and RCV enrichment
clinvar-filter /path/to/vcv.db \
    --rcv-db /path/to/rcv.db \
    -n "%cardiomyopathy%" \
    -o cardiomyopathy_enriched.tsv

Filter variants by gene/condition/classification

usage: clinvar-filter [-h] [--rcv-db RCV_DB] [-g GENES [GENES ...]]
                      [-n CONDITION_NAMES [CONDITION_NAMES ...]]
                      [-i CONDITION_IDS [CONDITION_IDS ...]]
                      [-c CLASSIFICATIONS [CLASSIFICATIONS ...]] [--grch38]
                      [--grch37] -o OUTPUT [-v]
                      vcv_db

Positional Arguments

vcv_db: Path to VCV database

Named Arguments

--rcv-db

Path to RCV database (for enrichment)

-g, --genes

Gene symbols (e.g., LDLR APOB)

-n, --condition-names

Condition name patterns (e.g., ‘%cardiomyopathy%’)

-i, --condition-ids

Condition IDs as db:id (e.g., MedGen:C0007194)

-c, --classifications

Classifications (e.g., Pathogenic ‘Likely pathogenic’)

--grch38

Include GRCh38 assembly rows. Passing –grch38 alone returns only GRCh38; omit both flags to return both assemblies.

--grch37

Include GRCh37 assembly rows. Passing –grch37 alone returns only GRCh37; omit both flags to return both assemblies.

-o, --output

Output file (tsv)

-v, --verbose

Increase verbosity (-v, -vv, -vvv)

Default: 0

clinvar-fetch-variant

Fetch specific variants by accession, ID, name, location, or SPDI.

Example:

# Fetch by VCV accessions
clinvar-fetch-variant /path/to/vcv.db \
    --vcv VCV000000323 VCV000000826 \
    -o variants.tsv

# Fetch by genomic location
clinvar-fetch-variant /path/to/vcv.db \
    -l 5:112819342:CAAG:C \
    -o apc_variant.tsv

# Fetch by name pattern with enrichment
clinvar-fetch-variant /path/to/vcv.db \
    --rcv-db /path/to/rcv.db \
    -N "%BRCA1%" \
    -o brca1_variants.tsv

Fetch variants by identifier or position

usage: clinvar-fetch-variant [-h] [--rcv-db RCV_DB] -o OUTPUT [-v]
                             (--vcv VCV [VCV ...] |
                             -I VARIATION_IDS [VARIATION_IDS ...] |
                             -n NAMES [NAMES ...] | -N NAME_PATTERN |
                             -l LOCATION | -s SPDI) [--grch38] [--grch37]
                             vcv_db

Positional Arguments

vcv_db: Path to VCV database

Named Arguments

--rcv-db

Path to RCV database (for enrichment)

-o, --output

Output file (TSV)

-v, --verbose

Increase verbosity (-v, -vv, -vvv)

Default: 0

--grch38

Include GRCh38 assembly rows. Passing –grch38 alone returns only GRCh38; omit both flags to return both assemblies.

--grch37

Include GRCh37 assembly rows. Passing –grch37 alone returns only GRCh37; omit both flags to return both assemblies.

lookup method (one required)

--vcv: VCV accessions (e.g., VCV000017639)
-I, --variation-ids: Variation IDs
-n, --names: Exact variant names
-N, --name-pattern: Variant name pattern using SQL LIKE patterns
-l, --location: Genomic location as chr:pos, chr:pos:assembly, chr:pos:ref:alt, or chr:pos:ref:alt:assembly
-s, --spdi: Canonical SPDI

clinvar-fetch-range

Fetch variants within genomic region(s).

Example:

# Fetch variants in a single region
clinvar-fetch-range /path/to/vcv.db \
    7:120810000-120811000 \
    -o tspan12_region.tsv

# Fetch variants in multiple regions
clinvar-fetch-range /path/to/vcv.db \
    7:120810000-120811000 \
    5:112800000-112850000 \
    -o multiple_regions.tsv

# Fetch with gene filter and enrichment
clinvar-fetch-range /path/to/vcv.db \
    17:43000000-43200000:GRCh38 \
    --rcv-db /path/to/rcv.db \
    -g BRCA1 \
    -o brca1_region.tsv

Fetch variants within genomic ranges

usage: clinvar-fetch-range [-h] [--rcv-db RCV_DB] [-g GENES [GENES ...]]
                           [-c CLASSIFICATIONS [CLASSIFICATIONS ...]]
                           -o OUTPUT [--grch38] [--grch37] [-v]
                           vcv_db range_specs [range_specs ...]

Positional Arguments

vcv_db: Path to VCV database
range_specs: Ranges as chr:start-end or chr:start-end:assembly (e.g., 19:11000000-12000000)

Named Arguments

--rcv-db

Path to RCV database (for enrichment)

-g, --genes

Filter by gene symbols

-c, --classifications

Filter by classifications

-o, --output

Output file (TSV)

--grch38

Include GRCh38 assembly rows. Passing –grch38 alone returns only GRCh38; omit both flags to return both assemblies.

--grch37

Include GRCh37 assembly rows. Passing –grch37 alone returns only GRCh37; omit both flags to return both assemblies.

-v, --verbose

Increase verbosity (-v, -vv, -vvv)

Default: 0

clinvar-list-conditions

List condition identifiers from the RCV database.

Example:

# List available sources
clinvar-list-conditions /path/to/rcv.db \
    --list-sources \
    -o sources.tsv

# List MedGen conditions with variant counts
clinvar-list-conditions /path/to/rcv.db \
    -s MedGen \
    -f \
    -o medgen_conditions.tsv

# List conditions with at least 10 variants
clinvar-list-conditions /path/to/rcv.db \
    -f \
    -m 10 \
    -o common_conditions.tsv

List condition identifiers from RCV database

usage: clinvar-list-conditions [-h] [-s SOURCE] [-f] [-m MIN_FREQUENCY]
                               [--list-sources] -o OUTPUT [-v]
                               rcv_db

Positional Arguments

rcv_db: Path to RCV database

Named Arguments

-s, --source

Filter by source (e.g., MedGen, OMIM)

-f, --include-frequency

Include variant counts

Default: False

-m, --min-frequency

Minimum variant count (default: 1)

Default: 1

--list-sources

List available sources and exit

Default: False

-o, --output

Output file (TSV)

-v, --verbose

Increase verbosity (-v, -vv, -vvv)

Default: 0

Programmer Interface

Database Schema

Positional Arguments

Named Arguments

Database Parser

Named Arguments

Database Queries

clinvar-filter

Positional Arguments

Named Arguments

clinvar-fetch-variant

Positional Arguments

Named Arguments

lookup method (one required)

clinvar-fetch-range

Positional Arguments

Named Arguments

clinvar-list-conditions

Positional Arguments

Named Arguments

Database Schema 

Database Parser 

Database Queries 