Eqtl Catalogue Region Fetch

Gotchas

1. Use FTP tabix, not the REST API, for regional fetches. The eQTL Catalogue v2 REST API at /api/v2/datasets/{id}/associations silently truncates regional fetches to one side of TSS and ignores pos_min / pos_max query parameters. This skill fetches via tabix on the canonical FTP .all.tsv.gz, which serves the full strand-aware cis-window correctly. Do NOT swap the fetcher to REST.

2. Cis-window is ±1 Mb of strand-aware TSS in genomic coordinates. The upstream pipeline computes cis-eQTLs only for variants within ±1 Mb of the gene's transcription start site. For + strand genes TSS = gene.start (lower coord). For − strand genes TSS = gene.end (higher coord). When querying a window in genomic coords that extends beyond ±1 Mb of TSS, expect zero rows on the far side. This is correct biology, not a bug.

3. molecular_trait_id filter is required for ge eQTL files. The harmonised ge .all.tsv.gz bundles every gene's variant rows together. Querying a chromosomal region without a gene filter returns variants for all genes in that region (potentially thousands of rows per variant). Always pass the target Ensembl gene ID. Other quant methods (tx, txrev, exon, leafcutter) have similar bundling behavior on molecular_trait_id (transcript / intron / exon ID).

4. β is reported on the ALT allele. Do NOT compare effect sizes across datasets without explicit allele harmonisation. The skill preserves ref / alt columns; downstream tools (e.g., TwoSampleMR harmonise_data) flip signs when alleles are swapped. Cross-dataset comparisons (eQTL β vs GWAS β at the same variant) without harmonisation can silently invert direction.

5. Quantification methods are not interchangeable.

   • ge (gene expression): gene-level, the most common eQTL definition
   • tx (transcript): per-isoform abundance
   • txrev (transcript usage): proportional, not abundance
   • exon (exon expression): per-exon read count
   • leafcutter (splice junction): splice-QTL on intron excision ratio

   These represent distinct biology. A txrev row is NOT a ge eQTL. The skill's manifest carries the raw quant_method code AND a human-readable label per the AGENTS.md expansion rule.

6. Dataset metadata comes from the bundled table, and the API is gone. The catalogue permanently disabled its metadata REST API in September 2026 (it answers HTTP 410; eQTL-Catalogue-resources#59), so study_id, the quantification method, the labels and the per-variant file class are read from data/dataset_index_r7.tsv, derived from the catalogue's own published dataset table, tabix/tabix_ftp_paths.tsv in the eQTL-Catalogue-resources repository (758 datasets; provenance, source checksum and licence in data/dataset_index_r7.provenance.json). A dataset_id the table does not carry (one added upstream after r7) raises EQTLCatalogueDatasetNotFound; it can still be fetched by passing study_id and file_class (all or cc) explicitly, which bypasses the table. Do not infer the file class from the quantification method: the table lists .all for QTD000584 (aptamer) where that rule says .cc, and since every .all dataset also serves a .cc file (33 of 758 probed 2026-09-13, 17 listed .all, all with a .cc twin), opening the wrong one substitutes the credible-set-filtered rows for the full ones without any error (QTD000584 over the 1 Mb SORT1 locus (chr1:108.77-109.77 Mb, GRCh38): .all holds 33,240 rows across 11 aptamers (10 genes), .cc holds 3,892 rows for 1 aptamer, 11.7% of the rows and 1 of the 11 traits). The result cache (~/.clawbio/eqtl_catalogue_region_fetch_cache) keys each window on the file class that is opened and on the table's release (r7), so a window cached before the table existed, under the retired inference rule, is never served again, and a table upgrade retires the cache the same way; --no-cache bypasses it entirely.

7. A row that does not match the expected columns fails the whole fetch. Every row in the window is checked against the 19 columns the script reads (FTP_COLUMNS), and its position must be an integer. If any row fails, the fetch raises EQTLCatalogueSchemaError naming the file, the first bad row and how many rows of the window were malformed; the CLI prints that message, exits 2 and writes no variants.tsv, manifest or report. It never returns the rows that did parse, because a window with some rows dropped reads as the full association set, and one with all rows dropped reads as a region with no associations. A cached window is reused only if it was written under this check.

Safety

Not for clinical decisions. This skill returns research-grade summary statistics from public databases. Do not use the output for direct clinical decision-making, diagnosis, or treatment selection without independent validation by a qualified clinician.

Effect estimates may not generalise across populations. The ancestry of the source study is recorded in the dataset metadata (sample_group, population fields where present). Effect sizes from a single-ancestry study should not be assumed to apply to other ancestries without appropriate harmonisation and trans-ancestry validation.

Agent Boundary

The skill returns harmonised summary statistics (β, SE, p-value) for variants in a chromosomal window from one (study × tissue × quant_method) dataset. The agent should:

• Use the output as input to colocalisation, fine-mapping, or Mendelian randomisation tooling. These are the appropriate downstream methods for inferring causal effects.
• NOT make causal-effect claims directly from a single eQTL p-value. A low p-value at a variant means statistical association, not causation. Causal interpretation requires colocalisation or MR analysis with proper instrumental-variable assumptions.
• NOT cherry-pick variants by p-value alone. Statistical inference requires the full credible set / window context.
• NOT compare effect sizes across datasets without harmonising effect alleles. The skill normalises within one dataset; cross-dataset comparison requires a harmonisation step (e.g., TwoSampleMR harmonise_data).
• Surface tissue, quant_method, and sample size in the user-facing reply alongside any β / p-value the agent quotes. The same variant in IAV-stimulated monocytes (Quach 2016, N=198) and in resting monocytes (BLUEPRINT, N=191) is a different biological measurement, even though the genomic position is identical. Per the user-friendly enum-expansion rule (AGENTS.md), expand all three fields when reporting: quantification = gene expression (ge); tissue = monocyte (UBERON:0000235); n_samples = 198.
• NOT silently swap tissues or quantification methods. If the user asked for monocyte / ge and the dataset is monocyte / txrev, the agent must say so explicitly and ask whether to proceed.

Citations

• Kerimov et al. (2021). A compendium of uniformly processed human gene expression and splicing quantitative trait loci. Nat Genet 53, 1290-1299. doi:10.1038/s41588-021-00924-w
• Per-dataset citation list at https://www.ebi.ac.uk/eqtl/Studies/.