LDlinkPy

A Python interface to LDlink for reproducible linkage disequilibrium workflows

Project status: First public release series. Feedback and issue reports are welcome.

Introduction

LDlink is an interactive suite of web-based tools for investigating linkage disequilibrium (LD) across ancestral population groups. LDlink uses publicly available 1000 Genomes Project reference haplotypes to calculate human population-specific LD, accepts variants as RefSNP (RS) numbers or genomic positions, and references dbSNP for RS identifiers and bi-allelic variant information. Depending on the module, LDlink also incorporates data from resources such as UCSC RefSeq, RegulomeDB, genetic maps, the GTEx Portal, the GWAS Catalog, and FORGEdb.

LDlinkPy provides a Python interface to the LDlink REST API, making LDlink analyses scriptable, reproducible, and easier to integrate into pandas-based genomic workflows. It supports the major LDlink modules, including LDpair, LDproxy, LDmatrix, LDtrait, LDexpress, LDhap, LDpop, SNPclip, and SNPchip.

Internet access and a personal LDlink API token are required for API calls.

Install

LDlinkPy is available from PyPI. Using a virtual environment is recommended.

Requirements

• Python 3.10 or newer

macOS / Linux

python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install ldlinkpy

Windows PowerShell

py -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install ldlinkpy

Quick Start

1. Get And Set Your LDlink Token

Request a personal access token at https://ldlink.nih.gov/apiaccess. Once registered, your token will be emailed to you.

LDlinkPy reads your token from the LDLINK_TOKEN environment variable by default. You can also pass token="your_token_here" directly to endpoint functions.

macOS / Linux:

export LDLINK_TOKEN="your_token_here"

Windows PowerShell:

$env:LDLINK_TOKEN="your_token_here"

2. Start Python

macOS / Linux:

./.venv/bin/python

Windows PowerShell:

.\.venv\Scripts\python

3. Import LDlinkPy

from ldlinkpy import list_pop, list_chips, ldpair, ldproxy

4. Try A Simple Lookup

List available 1000 Genomes populations:

list_pop()

List available genotyping SNP chips:

list_chips()

5. Run A Simple Analysis

Check LD between two variants:

ldpair("rs3", "rs4", pop="YRI")

Find proxy variants for a SNP:

ldproxy("rs7412", pop="CEU")

Public Functions

Function	Purpose
ldpair	Query LD statistics for one or more variant pairs.
ldmatrix	Create an LD matrix for a set of variants.
ldproxy	Find proxy variants for a query variant.
ldproxy_batch	Run multiple LDproxy queries and write result files.
ldtrait	Query trait associations linked to variants in LD.
ldexpress	Query GTEx expression associations for variants in LD.
ldhap	Query haplotype and variant tables for a variant set.
ldpop	Query LD statistics across populations for two variants.
snpclip	Prune variants by LD and minor allele frequency thresholds.
snpchip	Identify genotyping arrays containing variants.
list_pop	Return available 1000 Genomes population codes.
list_chips / list_chip_platforms	Return available genotyping chip/platform codes.
list_gtex_tissues	Return GTEx tissue names and LDexpress tissue codes.

Most endpoint functions return pandas DataFrames by default. Some functions support raw responses, file output, or endpoint-specific return shapes. See the API reference for details.

More Documentation

• API reference: public functions, parameters, return types, and common exceptions.
• Longer usage examples: endpoint-by-endpoint command-line examples for local development and exploratory testing.
• End-to-end examples: includes an LDlinkPy-only workflow examining population-specific LD, haplotype structure, and optional SNPchip coverage for published SNP tags at the Ewing sarcoma 6p25.1/RREB1 susceptibility locus.

Authorship

LDlinkPy was conceived and overseen by Timothy Myers, Stephen Chanock, and Mitchel Machiela, with code and documentation assistance from ChatGPT 5.2 Thinking (OpenAI) and Codex 5.5 High (OpenAI). Additional authors and contributors may be added as the project develops.

AI Assistance Disclosure

LDlinkPy was developed with assistance from AI coding tools and agents, including ChatGPT 5.2 Thinking (OpenAI) and Codex 5.5 High (OpenAI). AI tools assisted with code generation, implementation, and documentation. Package behavior is validated by comparing outputs against the LDlink web app and the LDlinkR R package. Human contributors conceived the project, directed development, defined validation criteria, ran validation checks, and made release decisions.

Relationship To LDlinkR

LDlinkPy is intended to provide Python access to the major LDlink workflows familiar to LDlinkR users. Function names and behavior are generally aligned where practical, while using Python conventions such as pandas DataFrames and keyword arguments.

Development Status

This package is in its first public release series. Feedback from biomedical research users is welcome, especially on endpoint behavior, documentation clarity, and example workflows.