htan

Python CLI and library for accessing Human Tumor Atlas Network (HTAN) data — an NCI Cancer Moonshot initiative constructing 3D atlases of how human cancers evolve from precancerous lesions to advanced disease.

pip install htan

This package provides a single htan command that unifies access to four HTAN data platforms (portal ClickHouse, Synapse, Gen3/CRDC, ISB-CGC BigQuery), HTAN publication search via PubMed, and HTAN data model queries.

Looking for the Claude Code plugin? See ncihtan/htan-claude. It uses this package as its CLI backend.

Capabilities

All commands accept --help for full usage.

Quick start

pip install htan
htan init                      # interactive credential setup
htan query portal tables       # list available portal tables
htan query portal files --organ Breast --assay "scRNA-seq" --limit 20
htan pubs search --keyword "spatial transcriptomics"
htan model components
htan files lookup HTA9_1_19512

Authentication

Credentials are stored in standard config locations, never in environment variables echoed to your shell.

htan config check prints which services are currently configured.

Data access tiers

HTAN files fall into three access tiers; this package picks the right platform automatically.

The portal query result includes both synapseId and drs_uri columns when present, so a single query is enough to plan downloads across tiers.

Python API

from htan.query.portal import PortalClient
from htan.pubs import search_publications

client = PortalClient()
df = client.query("SELECT atlas_name, COUNT(*) FROM files GROUP BY atlas_name")

pubs = search_publications(keyword="spatial transcriptomics")

See src/htan/ for the full module layout. The CLI in htan.cli is the canonical entry point and demonstrates expected usage of each client.

Development

git clone https://github.com/ncihtan/htan-cli.git
cd htan-cli
uv venv && uv pip install -e ".[dev]"
uv run pytest tests/                  # 323 tests
uv run htan --help

Dependencies are managed with uv. Tests are pure Python (pytest); no integration credentials required.

License

MIT — see LICENSE.txt.