hca-scp

name

hca_scp

description

Reach for this whenever a request touches the Broad Institute Single Cell Portal — signaled by "Single Cell Portal", "Broad SCP", the host singlecell.broadinstitute.org, or an SCP accession like SCP257 or SCP2670. Use it to: search or browse SCP studies by keyword or facet (disease, organ, species, cell type); query the portal's API programmatically for structured results; peek inside a study — its genes, clusters, cell-type annotations, cell counts, file list — before deciding whether to download; pull visualization data (UMAP/tSNE coordinates, annotations, per-gene expression) as JSON instead of grabbing the whole matrix; or download study files. Trigger on casual phrasings too ("grab the UMAP for that SCP study", "is there an API for the single cell portal", "list their accessions and cell counts"). Specific to the Broad SCP — not GEO, cellxgene, or the HCA DCP.

Single Cell Portal (SCP) Skill

Programmatic access to the Broad Institute Single Cell Portal REST API v1. Search studies, read metadata, pull visualization data (cluster coords, annotations, gene expression) as JSON, and download files.

All discovery and visualization endpoints work anonymously. Only file downloads need a bearer token.

Tool

One stdlib-only CLI — no dependencies, Python 3.8+:

scripts/scp.py <command> [options]

Add --json (discovery commands) for raw API JSON, or --compact for one-line JSON.

Commands

Command	What it does	Auth
search [terms] [--facet id:val] [--genes G ...]	keyword/faceted study or gene search	no
facets [--name id [--query q]]	list facets, or filter values for one facet	no
studies [--limit N --offset N]	list all public studies	no
study <accession>	study details + file list (shows bucket_location)	no
explore <accession>	viz metadata: cluster names, annotations, available genes	no
cluster <accession> [--name N] [--gene G] [--annotation A]	cluster coordinates (UMAP/tSNE), colorable by gene/annotation	no
annotations <accession>	list a study's annotations	no
expression <accession> --genes G ... [--type violin|dotplot|heatmap]	expression plot data	no
download <accession> --file <bucket_location> [-o out]	download one file	yes
bulk-download <acc ...> [--file-types Expression Metadata ...]	write a curl config for many files	yes
selftest	live anonymous smoke test	no

Typical flow

# 1. Find studies
python3 scripts/scp.py search "tuberculosis granuloma"
python3 scripts/scp.py facets                       # see facet ids
python3 scripts/scp.py facets --name disease --query lung
python3 scripts/scp.py search --facet "disease:MONDO_0018076"

# 2. Inspect a study and its files
python3 scripts/scp.py study SCP257                 # note bucket_location values

# 3. Pull data WITHOUT downloading multi-GB matrices
python3 scripts/scp.py explore SCP257               # what genes/annotations exist
python3 scripts/scp.py cluster SCP257 --gene CD4    # UMAP coords colored by CD4
python3 scripts/scp.py expression SCP257 --genes CD4 CD8A --type violin

# 4. Download files (needs token — see below)
python3 scripts/scp.py download SCP257 --file all_cells_umap.txt
python3 scripts/scp.py bulk-download SCP257 --file-types Expression Metadata

Download authentication

Downloads hit user-scoped, non-public Google Cloud buckets, so they need a Google OAuth access token from an account that has accepted the Terra Terms of Service (same login as the SCP website).

The CLI resolves a token in this order:

1. --token <TOKEN>
2. $SCP_ACCESS_TOKEN
3. gcloud auth print-access-token (run gcloud auth login first)

download follows the signed-URL redirect and streams the file to disk. bulk-download writes a curl config (one-time auth code, expires in minutes) — run it with curl -K scp_bulk_download.cfg.

Discovery, metadata, and visualization commands need no token.

Notes

• Accessions look like SCP<number> (e.g. SCP257).
• Use study <acc> output's bucket_location as the --file value for download.
• Endpoint details, params, and response shapes: references/api.md.