.. _programmer-interface:

Programmer Interface
====================

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

.. contents:: Tools
   :local:
   :depth: 1


Database Schema
---------------

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

**Example:**

.. code-block:: bash

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

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

.. argparse::
   :module: clinvar_build.schema_generator
   :func: _parse_arguments
   :prog: clinvar-schema


Database Parser
---------------

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

**Example:**

.. code-block:: bash

   # 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

.. argparse::
   :module: clinvar_build.parser
   :func: _parse_arguments
   :prog: clinvar-parse


Database Queries
----------------

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:**

.. code-block:: bash

   # 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

.. argparse::
   :module: clinvar_build.queries
   :func: _filter_parser
   :prog: clinvar-filter


clinvar-fetch-variant
~~~~~~~~~~~~~~~~~~~~~

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

**Example:**

.. code-block:: bash

   # 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

.. argparse::
   :module: clinvar_build.queries
   :func: _fetch_variant_parser
   :prog: clinvar-fetch-variant


clinvar-fetch-range
~~~~~~~~~~~~~~~~~~~

Fetch variants within genomic region(s).

**Example:**

.. code-block:: bash

   # 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

.. argparse::
   :module: clinvar_build.queries
   :func: _fetch_range_parser
   :prog: clinvar-fetch-range


clinvar-list-conditions
~~~~~~~~~~~~~~~~~~~~~~~

List condition identifiers from the RCV database.

**Example:**

.. code-block:: bash

   # 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

.. argparse::
   :module: clinvar_build.queries
   :func: _list_conditions_parser
   :prog: clinvar-list-conditions