@bgicli/bgicli 2.1.1 → 2.2.0

package/data/workflows/chip-atlas-target-genes/SKILL.md

@@ -0,0 +1,230 @@
+---
+id: chip-atlas-target-genes
+name: ChIP-Atlas Target Genes
+category: epigenomics
+short-description: "Retrieve pre-computed target genes for any transcription factor from ChIP-Atlas public ChIP-seq data."
+detailed-description: "Downloads binding score data across all public ChIP-seq experiments for a specified protein/TF, ranking genes by MACS2 scores with cell-type-specific filtering and STRING protein interaction integration. Supports 10 genomes - human (hg38, hg19), mouse (mm10, mm9), rat (rn6), fly (dm6, dm3), worm (ce11, ce10), yeast (sacCer3)."
+starting-prompt: Find target genes for a transcription factor using ChIP-Atlas public ChIP-seq data . .
+---
+
+# ChIP-Atlas Target Genes
+
+Find target genes for any transcription factor using pre-computed ChIP-Atlas public ChIP-seq data.
+
+## When to Use This Skill
+
+Use ChIP-Atlas target genes when you need to:
+- **Identify target genes of a specific TF** from all public ChIP-seq experiments
+- **Rank potential targets** by MACS2 binding score across hundreds of experiments
+- **Compare TF binding across cell types** using per-experiment binding scores
+- **Validate known TF-target relationships** with independent ChIP-seq evidence
+- **Cross-reference with STRING** protein interaction data for high-confidence targets
+
+**Don't use for:**
+- Finding which TFs bind near your genes (use **chip-atlas-peak-enrichment** instead)
+- Histone mark targets (only non-histone antigens/TFs available)
+- Offline analysis (requires internet for data download)
+- Raw ChIP-seq analysis from FASTQ/BAM files
+
+**Key Concept:** Downloads pre-computed TSV files containing MACS2 binding scores for every gene, across all public ChIP-seq experiments for the specified protein. Genes are ranked by average binding score. No API job submission needed — data is served as static files. STRING protein interaction scores are **pre-embedded columns** in the ChIP-Atlas TSV — no separate STRING API query is performed.
+
+## Installation
+
+| Software | Version | License | Commercial Use | Installation |
+|----------|---------|---------|----------------|--------------|
+| pandas | >=1.3 | BSD-3-Clause | Permitted | `pip install pandas` |
+| requests | >=2.25 | Apache-2.0 | Permitted | `pip install requests` |
+| numpy | >=1.20 | BSD-3-Clause | Permitted | `pip install numpy` |
+| plotnine | >=0.12 | MIT | Permitted | `pip install plotnine` |
+| plotnine_prism | >=0.1 | MIT | Permitted | `pip install plotnine_prism` |
+| matplotlib | >=3.4 | PSF-based | Permitted | `pip install matplotlib` |
+| seaborn | >=0.12 | BSD-3-Clause | Permitted | `pip install seaborn` |
+
+```bash
+pip install pandas requests numpy plotnine plotnine_prism matplotlib seaborn
+```
+
+**System requirements:** Internet connection (downloads from ChIP-Atlas data server)
+
+## Inputs
+
+**Query parameters:**
+- **Protein/TF name:** Case-sensitive gene symbol (e.g., "TP53", "CTCF", "MYC")
+- **Genome:** hg38 (default), hg19, mm10, mm9, rn6, dm6, dm3, ce11, ce10, sacCer3
+- **Distance from TSS:** 1kb, 5kb (default), or 10kb
+
+**Optional filters:**
+- **min_score:** Minimum average MACS2 binding score (default: 0)
+- **top_n:** Keep top N genes (default: 500)
+- **cell_types:** List of cell types to subset (recalculates averages)
+- **min_string_score:** Minimum STRING interaction score
+- **min_binding_rate:** Minimum fraction of experiments with binding
+
+## Outputs
+
+**Analysis objects (Pickle):**
+- `analysis_object.pkl` - Complete results for downstream use
+  - Load with: `import pickle; obj = pickle.load(open('analysis_object.pkl', 'rb'))`
+  - Contains: target_genes, experiment_data, cell_types, protein, parameters, metadata
+
+**Results (CSV):**
+- `target_genes_all.csv` - All target genes (gene, avg_score, string_score, binding_rate, num_bound, max_score, colocated_group)
+- `target_genes_top50.csv` - Top 50 by average binding score
+- `target_genes_with_string.csv` - Genes with STRING interaction evidence
+- `experiment_scores_top50.csv` - Wide-format per-experiment scores for top 50
+
+**Visualizations (PNG + SVG, plotnine with Prism theme):**
+- `target_genes_top_targets.png/.svg` - Top target genes barplot
+- `target_genes_score_distribution.png/.svg` - Binding score distribution histogram
+- `target_genes_heatmap.png/.svg` - Binding heatmap (top genes × experiments)
+- `target_genes_string_vs_binding.png/.svg` - STRING vs binding scatter
+
+**Reports:**
+- `summary_report.md` - Human-readable analysis summary
+
+## Clarification Questions
+
+🚨 **ALWAYS ask Question 1 FIRST. Do not ask about species, genome, or analysis parameters before the user has answered Question 1.**
+
+### 1. **Query** (ASK THIS FIRST):
+   - Which transcription factor / protein do you want to find target genes for?
+   - Protein name is **case-sensitive** (e.g., "TP53" not "tp53")
+   - **Or use example data?** `tp53` (large, ~16K genes), `e2f1` (cell cycle), `myc` (moderate)
+
+> 🚨 **IF EXAMPLE DATA SELECTED:** All parameters are pre-defined (human hg38, ±5kb TSS, all cell types, no score threshold). **DO NOT ask question 2.** Proceed directly to Step 1.
+
+**Question 2 is ONLY for users providing their own query:**
+
+### 2. **Analysis parameters:**
+   - **Species/genome?** Human hg38 (default), hg19, mouse mm10/mm9, rat rn6, fly, worm, yeast
+   - **Distance from TSS?** ±5kb (default), ±1kb (proximal only), ±10kb (distal included)
+   - **Cell type filter?** All cell types (default), or specific types to get cell-type-specific rankings
+   - **Score threshold?** No minimum (default), or set min_score to focus on strong targets
+
+## Standard Workflow
+
+🚨 **MANDATORY: USE SCRIPTS EXACTLY AS SHOWN - DO NOT WRITE INLINE CODE** 🚨
+
+**Step 1 - Load query:**
+```python
+# Option 1: Example query
+from scripts.load_example_query import load_example_query
+query = load_example_query("tp53")
+
+# Option 2: Your own protein
+# from scripts.load_user_query import load_user_query
+# query = load_user_query("TP53", genome="hg38", distance=5)
+```
+**VERIFICATION:** `"✓ Query loaded: TP53 target genes (hg38, ±5kb)"`
+
+**Step 2 - Run target genes analysis:**
+```python
+from scripts.run_target_genes_workflow import run_target_genes_workflow
+
+results = run_target_genes_workflow(
+    protein=query['protein'],
+    genome=query['genome'],
+    distance=query['distance'],
+    top_n=500,
+    output_dir="target_genes_results"
+)
+```
+**DO NOT write inline download/parsing code. Just use the script.**
+
+**VERIFICATION:** `"✓ Target genes analysis completed successfully!"`
+
+**Step 3 - Generate visualizations:**
+```python
+from scripts.generate_all_plots import generate_all_plots
+generate_all_plots(results, output_dir="target_genes_results", top_n=25)
+```
+**DO NOT write inline plotting code. The script handles PNG + SVG with graceful fallback.**
+
+**VERIFICATION:** `"✓ All visualizations generated successfully!"`
+
+**Step 4 - Export results:**
+```python
+from scripts.export_all import export_all
+export_all(results, output_dir="target_genes_results")
+```
+**DO NOT write custom export code. Use export_all().**
+
+**VERIFICATION:** `"=== Export Complete ==="`
+
+⚠️ **CRITICAL - DO NOT:**
+- ❌ **Write inline download/parsing code** → **STOP: Use `run_target_genes_workflow()`**
+- ❌ **Write inline plotting code** → **STOP: Use `generate_all_plots()`**
+- ❌ **Write custom export code** → **STOP: Use `export_all()`**
+
+**⚠️ IF SCRIPTS FAIL - Script Failure Hierarchy:**
+1. **Fix and Retry (90%)** - Install missing package, check internet, re-run
+2. **Modify Script (5%)** - Edit the script file itself, document changes
+3. **Use as Reference (4%)** - Read script, adapt approach, cite source
+4. **Write from Scratch (1%)** - Only if genuinely impossible, explain why
+
+**NEVER skip directly to writing inline code without trying the script first.**
+
+## Common Issues
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| **HTTP 404 for protein** | **Invalid or unavailable antigen** | **Check case sensitivity ("TP53" not "tp53"). Histone marks not available. See [references/target_genes_data_format.md](references/target_genes_data_format.md).** |
+| **Download timeout** | **Large file or slow connection** | **TP53 is ~13MB; allow up to 2 minutes. Try smaller TF first (e.g., MYC).** |
+| **Memory error on large file** | **Very wide TSV (100s of columns)** | **Use top_n parameter to limit genes. Cell-type filter reduces columns.** |
+| **No STRING data (all zeros)** | **Protein not in STRING database** | **Normal for less-studied TFs. Binding scores still valid without STRING.** |
+| **Empty results after filtering** | **Filters too strict** | **Lower min_score, remove cell_type filter, increase top_n.** |
+| **SVG export error** | **Missing optional dependency** | **Normal - `generate_all_plots()` handles fallback. PNG always created.** |
+
+## Interpretation Guidelines
+
+**Average Binding Score (MACS2):** −10 × log10(Q-value). Higher = stronger binding evidence.
+- **≥500:** Very strong binding (Q ≤ 1e-50) — high-confidence direct target
+- **100-500:** Strong binding — likely direct target
+- **50-100:** Moderate binding — possible target, may be cell-type-specific
+- **<50:** Weak binding — marginal evidence
+
+**Note:** The Q-value thresholds above apply to **individual experiment** scores. Average scores include zeros from non-binding experiments, so an average of 500 reflects a *consensus* level — not that every experiment shows Q ≤ 1e-50.
+
+**Binding Rate:** Fraction of experiments with any binding, shown as % with n/N count (e.g., "66.3% (260/392)"). >50% = consistent across cell types; <10% = cell-type-specific.
+
+**STRING Score:** Independent evidence of regulatory interaction. >400 = medium confidence; >700 = high confidence. Genes with BOTH high binding + high STRING = highest-confidence targets. **STRING score of 0 does NOT mean "not a target"** — even well-characterized targets (e.g., BBC3/PUMA for TP53) can have STRING score 0 due to gaps in STRING coverage.
+
+**Caveats:**
+- **Averaging includes zeros:** Average scores are computed across ALL experiments (including those with score 0). Use `max_score` and `binding_rate` for complementary views.
+- **Cell-type bias:** Experiments are unevenly distributed — a few well-studied cell lines dominate. See the "Experiment Composition" section in `summary_report.md` for exact distribution.
+- **Co-located genes:** Some genes share identical binding scores because they sit at the same genomic locus within the TSS window. The `colocated_group` column in the CSV flags these genes. For pathway enrichment, consider collapsing co-located groups to avoid double-counting loci. See `summary_report.md` Caveats for exact counts.
+- **External annotations:** ChIP-Atlas provides binding data only. Any biological role descriptions in the agent's summary are from general knowledge, not from this analysis output. Always cite the actual data columns (avg_score, binding_rate, string_score) when reporting results.
+
+## Reporting Results
+
+🚨 **CRITICAL: Follow these rules when presenting results to the user.**
+
+1. **Rankings MUST come from the data files.** Read `summary_report.md` or `target_genes_all.csv` for exact gene names, ranks, and scores. **NEVER construct ranking tables from general biological knowledge** — even if a gene is a well-known target, its rank must match the data.
+2. **Do NOT substitute biologically famous genes** into top-N lists where the data ranks them lower. If a well-known target is not in the top 10, say so explicitly (e.g., "BAX, a well-characterized target, ranks #17 with avg_score 368.8").
+3. **Use exact values from the CSV/report** (1 decimal place for scores, 1 decimal for percentages). Do not round to integers.
+4. **Cite the data source** as: ChIP-Atlas (Zou et al., 2024) with the DOI from the References section.
+5. **Mention co-located gene groups** if the summary report flags them — they affect the effective number of independent targets.
+6. **Label biological annotations:** When describing gene functions or pathway roles, explicitly note these come from general knowledge (e.g., "CDKN1A — known cell cycle arrest effector — ranks #1"), not from ChIP-Atlas output.
+
+## Suggested Next Steps
+
+1. **Run peak enrichment** with top target genes to find co-regulatory factors (chip-atlas-peak-enrichment)
+2. **Cell-type-specific analysis** — re-run with `cell_types` filter matching your experimental system
+3. **Gene regulatory network** construction using top targets as nodes
+4. **Functional enrichment** of top target genes (GO, pathway analysis)
+
+## Related Skills
+
+- **[chip-atlas-peak-enrichment](../chip-atlas-peak-enrichment/)** - Find enriched TFs near YOUR gene list (reverse query)
+- **[gene-correlation-archs4](../gene-correlation-archs4/)** - Co-expression across 600K RNA-seq samples
+- **[grn-pyscenic](../grn-pyscenic/)** - Gene regulatory networks from single-cell data
+
+## References
+
+- Zou et al. (2024). ChIP-Atlas 3.0: a data-mining suite to explore chromosome architecture. *Nucleic Acids Research*. [doi:10.1093/nar/gkad884](https://doi.org/10.1093/nar/gkad884)
+- Zou et al. (2022). ChIP-Atlas 2021 update. *Nucleic Acids Research*. [doi:10.1093/nar/gkab933](https://doi.org/10.1093/nar/gkab933)
+- Oki et al. (2018). ChIP-Atlas: a data-mining suite. *EMBO Reports* 19(12):e46255. [doi:10.15252/embr.201846255](https://doi.org/10.15252/embr.201846255)
+- ChIP-Atlas: https://chip-atlas.org
+- Target Genes documentation: See [references/target_genes_data_format.md](references/target_genes_data_format.md)
+- MACS2 binding scores: See [references/macs2_binding_scores.md](references/macs2_binding_scores.md)
+- STRING integration: See [references/string_scores.md](references/string_scores.md)

package/data/workflows/chip-atlas-target-genes/references/macs2_binding_scores.md

@@ -0,0 +1,89 @@
+# MACS2 Binding Scores
+
+## Score Formula
+
+Binding scores in ChIP-Atlas Target Genes data are computed as:
+
+```
+Score = −10 × log10(MACS2 Q-value)
+```
+
+This transforms MACS2 Q-values (Benjamini-Hochberg adjusted p-values) into
+positive scores where higher values indicate stronger binding evidence.
+
+## Score Interpretation
+
+| Score | MACS2 Q-value | Interpretation                                |
+| ----- | ------------- | --------------------------------------------- |
+| 0     | No peak       | No binding detected in this experiment        |
+| 50    | 1e-5          | Default MACS2 threshold (weak but detectable) |
+| 100   | 1e-10         | Moderate binding evidence                     |
+| 200   | 1e-20         | Strong binding evidence                       |
+| 500   | 1e-50         | Very strong binding evidence                  |
+| 1000  | 1e-100        | Extremely strong binding evidence             |
+
+## Color Mapping (ChIP-Atlas Web Interface)
+
+The web interface uses a three-color gradient:
+
+- **0** → Blue (no binding)
+- **500** → Green (strong binding)
+- **1000** → Red (very strong binding)
+
+## Multiple Peaks
+
+When multiple peaks from a single experiment overlap one gene's TSS window, only
+the **highest** score is retained. This ensures each experiment contributes a
+single score per gene.
+
+## Average Score
+
+The `{Protein}|Average` column contains the **arithmetic mean** of MACS2 scores
+across all experiments for that antigen. This provides a consensus binding
+strength:
+
+- **High average (>500):** Consistently strong binding across many experiments —
+  high-confidence direct target
+- **Moderate average (100-500):** Binding detected in multiple experiments —
+  likely target
+- **Low average (10-100):** Binding in few experiments or weak peaks — possible
+  target, may be cell-type-specific
+- **Very low average (<10):** Marginal evidence — binding in very few
+  experiments
+
+### Averaging Includes Zeros
+
+**Important:** The average is computed across ALL experiments, including those
+with no binding (score 0). This means genes bound in fewer experiments get
+diluted averages even if they have very strong binding in a few cell types. For
+example, a gene with score 1000 in 5 experiments but 0 in 395 experiments would
+have an average of ~12.5.
+
+### Q-value Interpretation of Averaged Scores
+
+**Important:** The score-to-Q-value mapping in the table above (e.g., 500 → Q =
+1e-50) applies to **individual experiment** scores. The averaged scores reported
+in gene rankings do NOT have a direct per-experiment Q-value interpretation
+because the average includes zeros from experiments with no binding. An average
+score of 500 means the _consensus across all experiments_ reaches that level —
+it does NOT mean every experiment shows Q ≤ 1e-50. Use `max_score` to see the
+strongest individual experiment evidence, and `binding_rate` to see how
+consistently the gene is bound.
+
+**Complementary metrics to consider:**
+
+- **`max_score`** — Highest score in any single experiment. Captures strong
+  cell-type-specific binding that the average may obscure.
+- **`binding_rate`** — Fraction of experiments with any binding. High binding
+  rate + moderate average suggests consistent but moderate binding; low binding
+  rate + moderate average suggests strong but cell-type-specific binding.
+- **Median non-zero score** — Not pre-computed, but can be derived from the
+  per-experiment data to avoid zero dilution.
+
+## Peak Calling Parameters
+
+ChIP-Atlas uses `MACS2 callpeak` with:
+
+- Q-value threshold: 1e-5 (default)
+- Genome size: `-g hs` (human), `-g mm` (mouse), etc.
+- Only peaks passing this threshold appear in target gene data

package/data/workflows/chip-atlas-target-genes/references/string_scores.md

@@ -0,0 +1,58 @@
+# STRING Interaction Scores
+
+## Overview
+
+The `STRING` column in ChIP-Atlas Target Genes data contains protein-gene
+interaction scores from the [STRING database](https://string-db.org/). These
+scores provide orthogonal evidence that a TF regulates a target gene,
+complementing the ChIP-seq binding evidence.
+
+## Score Extraction
+
+STRING scores are included when all of these conditions are met:
+
+- `item_id_a` matches the query antigen (the TF/protein)
+- `item_id_b` matches the target gene
+- Interaction mode = `"expression"` (regulatory relationship)
+- `a_is_acting` = `1` (the antigen is the regulator)
+
+## Score Interpretation
+
+| Score    | Interpretation                 |
+| -------- | ------------------------------ |
+| 0        | No STRING interaction evidence |
+| 1-399    | Low confidence interaction     |
+| 400-699  | Medium confidence interaction  |
+| 700-899  | High confidence interaction    |
+| 900-1000 | Highest confidence interaction |
+
+## Combining with Binding Scores
+
+The most confident target gene predictions have both:
+
+1. **High average binding score** — Direct ChIP-seq evidence of TF binding near
+   gene TSS
+2. **High STRING score** — Independent evidence of regulatory relationship
+
+| Binding Score | STRING Score | Confidence                                             |
+| ------------- | ------------ | ------------------------------------------------------ |
+| High (>200)   | High (>400)  | Very high — binding + regulatory evidence              |
+| High (>200)   | 0            | High — binding evidence only (novel target?)           |
+| Low (<50)     | High (>400)  | Moderate — known interaction but weak/indirect binding |
+| Low (<50)     | 0            | Low — minimal evidence                                 |
+
+## Limitations
+
+- STRING covers well-studied interactions; novel or tissue-specific regulatory
+  relationships may not be represented
+- STRING "expression" mode captures co-expression and regulatory evidence, not
+  exclusively direct regulation
+- **Score of 0 does NOT mean "not a target"** — it means STRING lacks evidence
+  for this specific pair. Even well-characterized, canonical targets can have
+  STRING score 0. For example, BBC3 (PUMA) is one of the best-characterized TP53
+  apoptosis targets, yet it has STRING score 0 in ChIP-Atlas data. This reflects
+  gaps in STRING's coverage, not biological reality.
+- When reporting results, always note that absence of STRING evidence is not
+  evidence of absence. Genes with high binding scores but STRING score 0 may
+  still be bona fide targets — they simply lack this particular line of
+  orthogonal evidence.

package/data/workflows/chip-atlas-target-genes/references/target_genes_data_format.md

@@ -0,0 +1,73 @@
+# ChIP-Atlas Target Genes Data Format
+
+## URL Pattern
+
+Pre-computed target gene data is available at:
+
+```
+https://chip-atlas.dbcls.jp/data/{genome}/target/{Protein}.{Distance}.tsv
+```
+
+| Parameter  | Values                                                    | Description                                          |
+| ---------- | --------------------------------------------------------- | ---------------------------------------------------- |
+| `genome`   | hg38, hg19, mm10, mm9, rn6, dm6, dm3, ce11, ce10, sacCer3 | Genome assembly                                      |
+| `Protein`  | e.g., TP53, CTCF, MYC                                     | Transcription factor / protein name (case-sensitive) |
+| `Distance` | 1, 5, 10                                                  | Distance from TSS in kilobases (±1kb, ±5kb, ±10kb)   |
+
+**Example:** `https://chip-atlas.dbcls.jp/data/hg38/target/TP53.5.tsv`
+
+## TSV File Structure (Wide Format)
+
+| Column Position | Header Format           | Description                                     |
+| --------------- | ----------------------- | ----------------------------------------------- |
+| 1               | `Target_genes`          | Gene symbol (one row per target gene)           |
+| 2               | `{Protein}\|Average`    | Mean MACS2 binding score across all experiments |
+| 3..N-1          | `{SRX_ID}\|{Cell_Type}` | Per-experiment MACS2 binding scores             |
+| N (last)        | `STRING`                | STRING database interaction score               |
+
+**Example header:**
+
+```
+Target_genes	TP53|Average	SRX21888064|22Rv1	SRX21888065|22Rv1	...	STRING
+```
+
+**Key properties:**
+
+- Rows are pre-sorted by Average column (descending) — top targets first
+- Values are MACS2 binding scores (0 = no binding, higher = stronger)
+- When multiple peaks overlap one gene, highest score is retained
+- Column count varies by antigen (TP53 has ~395 columns; others may have <10)
+- Row count varies (TP53: ~16K genes; smaller TFs may have <1K)
+
+## Validating Antigen Availability
+
+**HTTP HEAD check:**
+
+```
+HEAD https://chip-atlas.dbcls.jp/data/{genome}/target/{Protein}.{Distance}.tsv
+```
+
+- **200:** Data available
+- **404:** Antigen not found (check case, or protein may not have ChIP-seq data)
+
+**Notes:**
+
+- ~1,753 unique antigens available for hg38 (as of 2025)
+- Only non-histone antigens ("TFs and others") — histone marks (H3K4me3 etc.)
+  return 404
+- Protein names are case-sensitive (e.g., `TP53` not `tp53`)
+
+## Related Files on Server
+
+Each antigen has multiple files:
+
+- `{Protein}.{1,5,10}.tsv` — Target gene data at different distance windows
+- `STRING_{Protein}.{1,5,10}.tsv` — STRING-enhanced predictions (separate file)
+- `{SRX_ID}.{1,5,10}.tsv` — Individual experiment-level target genes
+
+## Computation Method
+
+Target genes are identified by overlapping transcription start sites (TSSs) with
+ChIP-seq peak-call intervals using `bedtools window`. Only protein-coding genes
+from UCSC refFlat files are included. Gene symbols follow official nomenclature
+(HGNC for human, MGI for mouse, etc.).

package/data/workflows/chip-atlas-target-genes/scripts/download_target_genes.py

@@ -0,0 +1,200 @@
+"""
+Download and parse ChIP-Atlas Target Genes pre-computed TSV data.
+
+Core script for the chip-atlas-target-genes skill.
+Downloads wide-format TSV from ChIP-Atlas and parses into summary + experiment DataFrames.
+"""
+
+import io
+import re
+
+import pandas as pd
+import requests
+
+# ChIP-Atlas data server base URL
+BASE_URL = "https://chip-atlas.dbcls.jp/data"
+
+# Valid genomes
+VALID_GENOMES = ["hg38", "hg19", "mm10", "mm9", "rn6", "dm6", "dm3", "ce11", "ce10", "sacCer3"]
+
+# Valid distance values (kb from TSS)
+VALID_DISTANCES = [1, 5, 10]
+
+
+def _build_url(protein, genome, distance):
+    """Build the download URL for target genes TSV."""
+    return f"{BASE_URL}/{genome}/target/{protein}.{distance}.tsv"
+
+
+def check_antigen_available(protein, genome="hg38", distance=5):
+    """
+    Check if target gene data exists for a given protein/antigen.
+
+    Args:
+        protein: Protein/TF name (case-sensitive, e.g., "TP53")
+        genome: Genome assembly (default: "hg38")
+        distance: Distance from TSS in kb (1, 5, or 10)
+
+    Returns:
+        bool: True if data is available, False otherwise
+    """
+    if genome not in VALID_GENOMES:
+        print(f"  ERROR: Invalid genome '{genome}'. Valid: {', '.join(VALID_GENOMES)}")
+        return False
+
+    if distance not in VALID_DISTANCES:
+        print(f"  ERROR: Invalid distance {distance}. Valid: {VALID_DISTANCES}")
+        return False
+
+    url = _build_url(protein, genome, distance)
+
+    try:
+        resp = requests.head(url, timeout=15, allow_redirects=True)
+        if resp.status_code == 200:
+            return True
+        elif resp.status_code == 404:
+            # Provide helpful suggestions
+            print(f"  WARNING: No target gene data for '{protein}' ({genome}, ±{distance}kb)")
+            print(f"  - Protein names are case-sensitive (e.g., 'TP53' not 'tp53')")
+            print(f"  - Histone marks (H3K4me3, etc.) are NOT available in Target Genes")
+            print(f"  - Check https://chip-atlas.org/target_genes for available antigens")
+            return False
+        else:
+            print(f"  WARNING: Unexpected HTTP {resp.status_code} for {url}")
+            return False
+    except requests.RequestException as e:
+        print(f"  ERROR: Network error checking antigen availability: {e}")
+        return False
+
+
+def download_target_genes(protein, genome="hg38", distance=5):
+    """
+    Download and parse ChIP-Atlas target genes TSV data.
+
+    Args:
+        protein: Protein/TF name (case-sensitive, e.g., "TP53")
+        genome: Genome assembly (default: "hg38")
+        distance: Distance from TSS in kb (1, 5, or 10)
+
+    Returns:
+        tuple: (summary_df, experiment_df)
+            - summary_df: Gene-level summary (gene, avg_score, string_score, etc.)
+            - experiment_df: Full wide-format per-experiment scores
+    """
+    url = _build_url(protein, genome, distance)
+    print(f"  Downloading target genes from: {url}")
+
+    # Stream download for large files
+    resp = requests.get(url, timeout=120, stream=True)
+    resp.raise_for_status()
+
+    # Read content (stream into memory, then parse)
+    content = resp.content.decode("utf-8")
+    print(f"  Downloaded {len(content) / 1024 / 1024:.1f} MB")
+
+    # Parse TSV
+    df = pd.read_csv(io.StringIO(content), sep="\t")
+
+    if df.empty:
+        raise ValueError(f"No target gene data returned for {protein} ({genome}, ±{distance}kb)")
+
+    # Parse into summary and experiment DataFrames
+    summary_df, experiment_df = parse_target_genes_tsv(df, protein)
+
+    print(f"  ✓ Downloaded target genes: {len(summary_df)} genes, {len(experiment_df.columns) - 1} experiments")
+    return summary_df, experiment_df
+
+
+def parse_target_genes_tsv(df, protein):
+    """
+    Parse raw wide-format TSV into summary and experiment DataFrames.
+
+    Args:
+        df: Raw DataFrame from TSV download
+        protein: Protein name (for identifying the Average column)
+
+    Returns:
+        tuple: (summary_df, experiment_df)
+    """
+    # Identify columns
+    gene_col = "Target_genes"
+    avg_col = f"{protein}|Average"
+    string_col = "STRING"
+
+    # Verify expected columns exist
+    if gene_col not in df.columns:
+        raise ValueError(f"Expected column '{gene_col}' not found. Columns: {list(df.columns[:5])}")
+
+    # Find the Average column (case-insensitive fallback)
+    if avg_col not in df.columns:
+        avg_candidates = [c for c in df.columns if c.lower().endswith("|average")]
+        if avg_candidates:
+            avg_col = avg_candidates[0]
+            print(f"  Using average column: {avg_col}")
+        else:
+            raise ValueError(f"No Average column found. Expected '{avg_col}'. Columns: {list(df.columns[:5])}")
+
+    # Identify experiment columns (SRX/ERX/DRX pattern)
+    experiment_cols = [
+        c for c in df.columns
+        if re.match(r"^[SED]RX\d+\|", c) and c != avg_col
+    ]
+
+    # Check for STRING column
+    has_string = string_col in df.columns
+
+    # Build experiment DataFrame (gene + per-experiment scores)
+    experiment_df = df[[gene_col] + experiment_cols].copy()
+    experiment_df = experiment_df.rename(columns={gene_col: "gene"})
+
+    # Build summary DataFrame
+    summary_data = {
+        "gene": df[gene_col],
+        "avg_score": pd.to_numeric(df[avg_col], errors="coerce").fillna(0),
+        "string_score": pd.to_numeric(df[string_col], errors="coerce").fillna(0) if has_string else 0,
+        "num_experiments": len(experiment_cols),
+    }
+
+    # Calculate per-gene binding statistics from experiment columns
+    experiment_values = df[experiment_cols].apply(pd.to_numeric, errors="coerce").fillna(0)
+    summary_data["num_bound"] = (experiment_values > 0).sum(axis=1).values
+    summary_data["binding_rate"] = (
+        summary_data["num_bound"] / max(len(experiment_cols), 1)
+    )
+    summary_data["max_score"] = experiment_values.max(axis=1).values
+
+    summary_df = pd.DataFrame(summary_data)
+
+    # Sort by average score descending (should already be sorted, but ensure)
+    summary_df = summary_df.sort_values("avg_score", ascending=False).reset_index(drop=True)
+
+    # Extract cell types from experiment column headers
+    cell_types = []
+    for col in experiment_cols:
+        parts = col.split("|", 1)
+        if len(parts) == 2:
+            cell_types.append(parts[1])
+    unique_cell_types = sorted(set(cell_types))
+
+    print(f"  Parsed: {len(summary_df)} genes, {len(experiment_cols)} experiments, {len(unique_cell_types)} cell types")
+    return summary_df, experiment_df
+
+
+def get_cell_types(experiment_df):
+    """
+    Extract unique cell types from experiment DataFrame column headers.
+
+    Args:
+        experiment_df: Wide-format DataFrame with {SRX_ID}|{CellType} columns
+
+    Returns:
+        list: Sorted unique cell type names
+    """
+    cell_types = set()
+    for col in experiment_df.columns:
+        if col == "gene":
+            continue
+        parts = col.split("|", 1)
+        if len(parts) == 2:
+            cell_types.add(parts[1])
+    return sorted(cell_types)