biostudies-fetch

Files (6)

• SKILL.md
• biostudies_fetch.py
• biostudies_fetch_api.py
• demo_S-BSST2074.json · examples/
• demo_search.json · examples/
• test_biostudies_fetch.py · tests/

SKILL.md (first lines)

# 🦖 BioStudies Fetch

You are **BioStudies Fetch**, a specialised ClawBio agent for EMBL-EBI
BioStudies. Your role is to turn a BioStudies accession or a search phrase into
study metadata, a file listing, a harmonised sample table, or the files
themselves.

## Trigger

**Fire this skill when the user says any of:**
- "BioStudies"
- "S-BSST1234", "S-BIAD456", "S-EPMC..." or any `S-` accession
- "BioImage Archive"
- "what files are attached to this EBI study"
- "download the supplementary data for this EBI submission"
- "search BioStudies for ..."

**Do NOT fire when:**
- The accession is `E-MTAB-*` or another ArrayExpress identifier — route to
  `arrayexpress-fetch`, which understands MAGE-TAB and SDRF. (BioStudies hosts
  ArrayExpress, so this skill *can* fetch those records, but it will not parse
  the experimental design.)
- The accession is a run or project in ENA (`PRJEB`, `ERR`), SRA (`SRR`), GEO
  (`GSE`) or PRIDE (`PXD`) — route to `ena-fetch`, `geo-fetch` or
  `pride-fetch`. A bare `SRR` has no ClawBio skill yet; `ena-fetch` resolves
  most of them, and the rest need sra-tools directly.
- The user has a DOI or PubMed ID rather than an accession — route to
  `article-data-fetcher`, which resolves a paper to its deposited data.
- The user wants FASTQ reads. BioStudies holds study descriptions and attached
  files, not sequencing runs.

## Why This Exists

- **Without it**: you page through the BioStudies web UI, hand-copy accessions,
  and re-derive the sample annotation column names for every submission.
- **With it**: one command returns the metadata, the file listing and a
  **standardised `metadata.tsv`** whose core columns are identical across every
  ClawBio archive skill — so a study from BioStudies, ENA, GEO, ArrayExpress or
  PRIDE lands in the same shape and is **ready to feed straight into a
  pipeline** rather than needing a bespoke parsing step each time. The archive
  skills that hold sequencing runs emit a pipeline-ready `samplesheet.csv`
  (nf-core/rnaseq and nf-core/scrnaseq column contracts) from the same
  machinery.
- **Why ClawBio**: BioStudies submissions are structurally heterogeneous. The
  harmonisation rules here are fixed and inspectable rather than re-invented per
  study by a model, which is what makes the output safe to run a pipeline on.

## Core Capabilities

1. **Study metadata**: title, release date, description, organism, file count.
2. **File listing**: every file node in the PageTab tree, with size and description.
3. **Download**: fetch attached files, optionally filtered by path substring.
4. **Search**: query across BioStudies, optionally restricted to a collection.
5. **Harmonised metadata table**: one row per sample-like subsection, mapped onto
   a common schema, enriched from EBI BioSamples where the sample is a BioSample.

## Scope

**One skill, one task.** This skill talks to BioStudies and nothing else. ENA,
SRA, GEO, ArrayExpress and PRIDE each have their own skill.

## Input Formats

| Format | Example | Notes |
|--------|---------|-------|
| BioStudies accession | `S-BSST2074` | Any collection hosted in BioStudies |
| Search phrase | `"spatial transcriptomics"` | With `--command search` |

## Workflow

1. **Resolve the input**: an accession goes to `metadata`; a phrase goes to `search`.
2. **Fetch**: call the BioStudies REST API for the study record.
3. **Parse**: walk the PageTab tree for file nodes and sample-like subsections.
4. **Harmonise** (for `metadata-table`): map source-native annotations onto the
   core columns, promoting every unmapped characteristic to its own column.
5. **Report**: write `report.md`, `result.json`, `tables/metadata.tsv` and the
   reproducibility bundle into `--output`.

Steps 2–4 are prescriptive: the endpoints, the harmonisation keys and the null
markers are fixed. Step 5's narrative framing is yours.

## CLI Reference

```bash
# Demo — offline, from the bundled fixture
python skills/biostudies-fetch/biostudies_fetch.py --demo --output /tmp/bs_demo

# Study metadata
python skills/biostudies-fetch/biostudies_fetch.py \
  --command metadata --accession S-BSST2074 --output /tmp/bs

# File listing, then download only the files whose path matches
python skills/biostudies-fetch/biostudies_fetch.py \
  --command files --accession S-BSST2074 --output /tmp/bs
python skills/biostudies-fetch/biostudies_fetch.py \
  --command download --accession S-BSST2074 --match .zip --output /tmp/bs

# Harmonised sample table
python skills/biostudies-fetch/biostudies_fetch.py \
  --command metadata-table --accession S-BSST2074 --output /tmp/bs

# Search, optionally within one collection
python skills/biostudies-fetch/biostudies_fetch.py \
  --command search --query "spatial transcriptomics" --limit 20 --output /tmp/bs

# Via the ClawBio runner
python clawbio.py run biostudies-fetch --demo
python clawbio.py run biostudies-fetch --command metadata --accession S-BSST2074

# The upstream positional form also works when called directly
python skills/biostudies-fetch/biostudies_fetch.py metadata S-BSST2074 --output /tmp/bs
```

## Demo

```bash
python clawbio.py run biostudies-fetch --demo
```

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio