human-protein-atlas-database

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: human-protein-atlas-database
description: >
  Use when you want to retrieve semi-quantitative protein expression and
  spatial localisation data from the Human Protein Atlas (HPA).
---

# Human Protein Atlas (HPA) Database Integration

This skill provides semi-quantitative protein expression and spatial
localisation data from the Human Protein Atlas (HPA). While RNA-seq (e.g., GTEx)
tells us if a gene is being transcribed, HPA confirms if the protein product
actually exists, where it is located within the cell (e.g. nucleus vs
cytoplasm), and its concentration in systemic blood circulation. The data is
based on Immunohistochemistry (IHC) across normal human tissues and cancer
types.

## Prerequisites

1.  **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
    `uv` is installed and on PATH.
2.  **User Notification**: If .licenses/human_protein_atlas_database_LICENSE.txt
    does not already exist in the workspace root directory then (1) prominently
    notify the user to check the terms at
    https://www.proteinatlas.org/about/licence, then (2) create the file
    recording the notification text and timestamp.

## When to Use

**Use this skill when you need to:**

-   Map a gene symbol to its Ensembl ID for HPA queries.
-   Retrieve the semi-quantitative protein abundance in normal human tissues and
    cancer types based on IHC staining (High, Medium, Low, or Not Detected).
-   Find the specific organelles or subcellular structures where a protein has
    been localized (e.g., nucleoplasm, mitochondria).
-   Check the consistency/agreement between RNA-seq consensus and protein
    expression levels.
-   Search for genes based on specific protein expression criteria (e.g.,
    "elevated in amygdala" or "secreted proteins").

**Do NOT use when you need to:**

-   Query eQTLs, pQTLs, or any variant-level associations. HPA provides
    wild-type expression data and knows nothing about QTLs.
-   Query gene expression in non-human species. HPA is strictly for human
    proteins.
-   Retrieve purely quantitative RNA expression without interest in the protein
    product (consider using the GTEx skill instead).

## Command Selection Guide

**Pick the right command on the first try.** Match the user's input to the
correct subcommand below.

-   Map a gene symbol to Ensembl ID: `resolve-ensembl-id`
-   Get tissue protein expression levels: `get-tissue-expression`
-   Get subcellular location of a protein: `get-subcellular-location`
-   Get the full HPA metadata entry for a gene: `get-atlas-entry`
-   Search HPA for genes matching specific criteria: `search-hpa`

## Quick Start

```bash
# Map the ERBB2 gene symbol to its Ensembl ID
uv run scripts/hpa_cli.py resolve-ensembl-id ERBB2 --output /tmp/erbb2_id.json

# Get subcellular location by Ensembl ID
uv run scripts/hpa_cli.py get-subcellular-location ENSG00000141736 --output /tmp/erbb2_location.json
```

All subcommands write JSON to disk. Always save output in the `/tmp/` directory.
The default output file is `/tmp/hpa_output.json` if `--output` is not
specified.

## Commands

### 1. `resolve-ensembl-id` — Gene Symbol → Ensembl ID

Maps a common gene symbol (e.g., "TP53", "ERBB2") to its Ensembl gene ID. HPA
endpoints are strictly Ensembl-based.

```bash
uv run scripts/hpa_cli.py resolve-ensembl-id TP53 --output /tmp/tp53_id.json
```

*Arguments:*

-   `gene_symbol` (positional): The standard gene symbol (e.g., "TP53").
-   `--output`: Output file path (default: `/tmp/hpa_output.json`).

### 2. `get-tissue-expression` — Get Tissue Protein Levels

Returns a list of tissues and their corresponding protein expression levels
(High, Medium, Low, or Not Detected) based on IHC staining.

```bash
uv run scripts/hpa_cli.py get-tissue-expression ENSG00000130234 \
  --tissues "duodenum,thyroid gland" --output /tmp/tissue_expr.json
```

*Arguments:*

-   `ensembl_id` (positional): The Ensembl Gene ID.
-   `--tissues`: Comma-separated list of tissues to filter by (o