LOVD API Client

LOVD API Client#

The client module provides the main interface for interacting with LOVD databases.

Overview#

The LOVDClient class serves as the entry point to LOVDTools’ API client. It is almost certainly the class with which you will most frequently interact.

Basic Usage#

from lovd import LOVDClient

# Initialize client
client = LOVDClient()

# Fetch variants for a specific gene
variants = client.get_variants_for_gene("COL5A1")

# Search with filters
filtered_variants = client.get_variants_for_genes(
    target_gene_symbols=["COL5A1"],
    search_terms=["pathogenic"]
)

API Reference#

LOVD Client#

This module defines and implements an interface for querying the Global Variome shared Leiden Open Variants Database (LOVD) instance.

class lovd.client.LOVDClient(
config_path: PathLike | None = None,
email: str | None = None,
target_gene_symbols: list[str] | None = None,
user_agent: str | None = None,
logging_level: int | None = None,
is_progress_enabled: bool | None = None,
)[source]#

Bases: object

A client for interacting with the Global Variome shared LOVD instance’s API.

__init__(
config_path: PathLike | None = None,
email: str | None = None,
target_gene_symbols: list[str] | None = None,
user_agent: str | None = None,
logging_level: int | None = None,
is_progress_enabled: bool | None = None,
) → None[source]#

Initialize the LOVD API client.

Parameters can be provided directly or loaded from acquisition.yaml. Direct parameters override configuration file values.

Parameters:

  • config_path (PathLike, optional) – A path-like object representing the acquisition configuration filepath. If left unspecified, this constructor searches for acquisition.yaml first in the current working directory and then, ~/.lovdtools/. Defaults to None.

  • email (str, optional) – A string representing the email address to use for user agent identification. If specified, this parameter overrides the acquisition configuration file. Defaults to None.

  • target_gene_symbols (list[str], optional) – A list of strings representing the gene symbols for which to query LOVD. Defaults to None.

  • user_agent (str, optional) – A short description of your application. If specified, this parameter overrides the acquisition configuration file. Defaults to None.

  • logging_level (int, optional) – An integer value between 1 and 5 inclusive that controls the verbosity level to use in logging output. If specified, this parameter overrides the acquisition configuration file. Defaults to None.

  • is_progress_enabled (bool, optional) – A boolean value that controls whether the client displays a progress indicator during execution. Defaults to None.

__repr__() → str[source]#

Get a code literal representation of the object instance.

Returns:

Code literal that could be used to reconstruct this LOVDClient instance as it is currently configured.

Return type:

str

classmethod from_config(
config_path: PathLike | None = None,
) → LOVDClient[source]#

Create a client instance from acquisition.yaml configuration.

Parameters:

config_path (PathLike, optional) – A path-like object representing the acquisition configuration filepath. If left unspcecified, this method searches for the configuration file both in the current working directory and, if necessary, ~/.lovdtools/. Defaults to None.

Returns:

A configured instance of the LOVD API client.

Return type:

LOVDClient

get_variants_for_gene(
target_gene: str,
search_terms: list[str] | None = None,
include_effect: bool = True,
custom_filters: dict[str, str] | None = None,
) → dict[str, Any][source]#

Get variant data for a single gene from LOVD.

Parameters:

  • target_gene (str) – A string that represents the gene symbol for which to query the LOVD API.

  • search_terms (list[str] | None, optional) – A list of strings comprising additional terms to include in the LOVD query. Defaults to None.

  • include_effect (bool) – A boolean value that determines whether the API request sets the show_effect parameter to 1. Defaults to True.

  • custom_filters (dict[str, str], optional) – Additional parameters to include in the API request, provided as a dictionary that maps parameter names to their arguments. Defaults to None.

Returns:

A dictionary representing the JSON received in response to the LOVD API request.

Return type:

dict[str, Any]

Raises:

requests.RequestException – An exception raised whenever the LOVD API request fails.

get_variants_for_genes(
target_gene_symbols: list[str] | None = None,
save_to: PathLike | None = None,
search_terms: list[str] | None = None,
include_effect: bool = True,
custom_filters: dict[str, str] | None = None,
) → dict[str, dict[str, Any]][source]#

Get variant data for multiple genes from LOVD.

Parameters:

  • target_gene_symbols (list[str], optional) – A list of strings comprising the gene symbols for which to query the Global Variome shared LOVD instance. Defaults to None.

  • save_to (PathLike, optional) – A path-like object representing the path to which the client saves JSON outputs. Defaults to None.

  • search_terms (list[str], optional) – A list of strings representing search terms to include. Defaults to None.

  • include_effect (bool) – A boolean value that determines whether the API request sets the show_effect parameter to 1. Defaults to True.

  • custom_filters (dict[str, str], optional) – Additional parameters to include in the API request, provided as a dictionary that maps parameter names to their arguments. Defaults to None.

Returns:

A nested dictionary mapping gene symbols to their variants.

Return type:

dict[str, dict[str, Any]]

get_variants_from_config() → dict[str, dict[str, Any]][source]#

Get variants using settings from the loaded configuration.

Returns:

Variant data for all genes specified in configuration

Return type:

dict[str, dict[str, Any]]

with_logging(level: int = 1) → LOVDClient[source]#

Enable the LOVD API client’s logger.

Parameters:

level (int) – An integer between 0 and 5 inclusive that determines the logger’s verbosity, with higher values corresponding to wordier logging output.

Return type:

Self.

with_progress() → LOVDClient[source]#

Enable the client’s tqdm progress indicator.

lovd.client.get_lovd_variants(
genes: str | list[str] | None = None,
save_to: PathLike | None = None,
include_effect: bool = True,
search_terms: list[str] | None = None,
custom_filters: dict[str, str] | None = None,
config_path: PathLike | None = None,
) → dict[str, dict[str, Any]][source]#

Get a JSON dictionary containing variants for the specified gene(s).

This is a convenience method. Internally, it creates a LOVDClient instance, loads its acquisition config file, and calls its .get_variants_for_genes() method.

Parameters:

  • genes (str | list[str], optional) – A string or list of strings representing the gene symbol(s) to query. Defaults to None.

  • save_to (PathLike, optional) – A path-like object representing the location at which downloaded data should be saved. If specified, this argument overrides the value set for the save_to key in the acquisition config file. Defaults to None.

  • include_effect (bool) – A boolean value that determines whether the client sets the API request’s show_variant_effect parameter to 1. Defaults to True.

  • search_terms (list[str], optional) – A list of strings comprising the search terms by which to filter variants (e.g., disease names, phenotypes). If specified, this argument overrides the value set for the search_terms key in the acquisition config file. Defaults to None.

  • custom_filters (dict[str, str] | None, optional) – Additional parameters to include in the API request, provided as a dictionary that maps parameter names to their arguments. Defaults to None.

  • config_path (PathLike, optional) – A path-like object that points to the location of the acquisition config file. Defaults to None.

Returns:

A dictionary object that contains the data downloaded from LOVD, keyed by gene symbol.

Return type:

dict[str, dict]

Examples

>>> # Use acquisition config file only.
>>> variants = get_lovd_variants()
>>>
>>> # Override genes from config.
>>> variants = get_lovd_variants(genes=["COL1A1", "COL3A1"])
>>>
>>> # Search for a specific disease.
>>> variants = get_lovd_variants(
...     ["COL1A1"],
...     search_terms=["Ehlers-Danlos", "connective tissue disorder"]
... )
>>>
>>> # Use an acquisition config file located at a nonstandard path.
>>> variants = get_lovd_variants(config_path="my_project.yaml")
lovd.client.get_variants_from_config(
config_path: PathLike | None = None,
) → dict[str, dict[str, Any]][source]#

Get variants using only settings from the acquisition config file.

Parameters:

config_path (PathLike, optional) – A path-like object that points to the location of an acquisition config file, first checking in the current working directory and then, if necessary, in ~/.lovdtools/.

Returns:

A dictionary object that contains the data downloaded from LOVD, keyed by gene symbol.

Return type:

dict[str, dict]

Examples

>>> # Use default config locations
>>> variants = get_variants_from_config()
>>>
>>> # Use specific config file
>>> variants = get_variants_from_config("eds_study.yaml")
lovd.client.load_acquisition_config(
config_path: PathLike | None = None,
) → dict[str, Any][source]#

Load the data acquisition configuration from acquisition.yaml.

Parameters:

config_path (PathLike, optional) – A path-like object representing the acquisition config filepath. If left unspecified, this function will search for acquisition.yaml first in the current working directory and then ~/.lovdtools, if necessary.

Returns:

A dictionary object that maps options to their configured values.

Return type:

dict[str, Any]

lovd.client.variants_to_dataframe(
variants_data: dict[str, dict[str, Any]],
is_progress_enabled: bool = False,
) → DataFrame[source]#

Convert LOVD variants data to a Polars data frame for analysis.

Parameters:

  • variants_data (dict[str, dict[str, Any]]) – Dictionary of variant data returned by the LOVD API client’s .get_variants_for_genes() instance method.

  • is_progress_enabled (bool) – A boolean value that determines the progress indicator’s visibility for this routine.

Returns:

A Polars data frame that tabulates the variants data acquired from LOVD.

Return type:

polars.DataFrame

Contents