/organ-aging-studio

name: organ-aging-studio
description: >-
  Interactive Goeminne proteomic aging clock with organ filters and per-protein
  contribution breakdown (protein NPX × coefficient). Agent- and demo-friendly.
license: MIT
metadata:
  version: 0.1.0
  author: ClawBio hackathon contributor
  domain: proteomics
  tags:
    - aging
    - longevity
    - proteomics
    - biological age
    - organ clock
    - Goeminne
    - interpretability
  inputs:
    - name: input_file
      type: file
      format:
        - csv
        - tsv
        - csv.gz
        - tsv.gz
      description: Olink NPX protein table (samples × proteins)
      required: true
  outputs:
    - name: report
      type: file
      format:
        - md
      description: Human-readable aging report with per-organ summary
    - name: result
      type: file
      format:
        - json
      description: Machine-readable predictions and protein contributions
  dependencies:
    python: ">=3.11"
    packages:
      - pandas>=2.0
      - numpy>=1.24
      - requests>=2.28
  demo_data:
    - path: ../proteomics-clock/data/demo_olink_npx.csv.gz
      description: Synthetic 20-sample Olink NPX demo (shared with proteomics-clock)
  endpoints:
    cli: python skills/organ-aging-studio/organ_aging_studio.py --input {input_file} --output {output_dir}
  openclaw:
    requires:
      bins:
        - python3
    always: false
    emoji: "🕰️"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install:
      - kind: pip
        package: pandas
      - kind: pip
        package: numpy
      - kind: pip
        package: requests
    trigger_keywords:
      - organ aging studio
      - proteomic clock breakdown
      - protein coefficient aging
      - Goeminne clock explain
      - which proteins drive organ age

Organ Aging Studio

You are **Organ Aging Studio**, a ClawBio skill that makes proteomic biological age clocks **inspectable**. Every prediction decomposes into:

predicted_age = intercept + Σ (protein_NPX × coefficient)

Trigger

**Fire this skill when the user says any of:**

• "organ aging studio" or "explain my organ age"
• "which proteins drive biological age"
• "protein breakdown for Goeminne clock"
• "interactive proteomic aging" or "filter proteins by coefficient"

**Do NOT fire when:**

• User only wants batch predictions without breakdown → route to `proteomics-clock`
• User asks about methylation / DNAm clocks → route to `methylation-clock`
• User asks about differential abundance → route to `affinity-proteomics`

Why This Exists

| Without this skill | With this skill | |--------------------|-----------------| | Black-box organ age number | Per-protein contributions ranked by \|coefficient\| | | Full model always applied | `--top-n` and `--min-abs-coef` filters for demos | | Hard to explain to clinicians / judges | `report.md` + `protein_contributions.csv` + JSON for agents |

Built on the same pinned [organAging](https://github.com/ludgergoeminne/organAging) coefficients as `proteomics-clock`. **No invented weights.** Downloaded coefficients are cached locally with SHA-256 sidecar hashes so the same file cannot silently change between runs.

Core Capabilities

1. **Multi-organ** — any organ supported by Goeminne et al. (2025); default demo set Heart, Brain, Liver, Immune, Organismal 2. **Gen1 / Gen2** — chronological age models or mortality hazard → years (Gompertz) 3. **Protein filters** — `--top-n`, `--min-abs-coef`, single `--sample-id` 4. **Structured outputs** — Markdown report, JSON, contribution table, replay `commands.sh`

Scope

One skill, one task. This skill makes Goeminne organ-aging clocks inspectable from Olink NPX input and nothing else. It does not normalise data, do differential abundance, or make clinical claims.

Workflow

1. **Validate** the input as an Olink NPX table with `sample_id` plus protein columns. 2. **Download** the pinned organAging coefficients and organ-protein map from GitHub. 3. **Predict** organ ages, optionally filtering proteins with `--top-n` and `--min-abs-coef`. 4. **Convert** Gen2 log-hazards to years via the Gompertz transform when requested. 5. **Write** `report.md`, `result.json`, `protein_contributions.csv`, and a replayable `commands.sh`.

Input Formats

| Format | Extension | Required columns | |--------|-----------|------------------| | Olink NPX CSV | `.csv` | `sample_id` + protein gene symbols | | Olink NPX TSV | `.tsv` | same | | Compressed | `.csv.gz` | same |

Optional: `age` (for delta = bio − chrono), `sex`.

CLI Reference

# Demo — synthetic Olink data (no download)
python skills/organ-aging-studio/organ_aging_studio.py \
  --demo --output /tmp/studio

# One patient, Heart only, top 5 drivers
python skills/organ-aging-studio/organ_aging_studio.py \
  --input my_olink.csv.gz --output /tmp/studio \
  --organs Heart --sample-id PATIENT_001 --top-n 5

# All demo samples, multiple organs
python skills/organ-aging-studio/organ_aging_studio.py \
  --demo --output /tmp/studio \
  --organs Heart,Brain,Immune,Organismal --generation gen1

Flags

| Flag | Default | Description | |------|---------|-------------| | `--demo` | off | Use bundled synthetic Olink table | | `--organs` | Heart,Brain,Liver,Immune,Organismal | Comma-separated organ list | | `--generation` | gen1 | `gen1` = years; `gen2` = hazard → years | | `--sample-id` | all rows | Analyse one sample | | `--top-n` | all present | Keep top N proteins by \|coef\| | | `--min-abs-coef` | 0 | Drop small coefficients |

Demo

cd ClawBio
uv sync
python skills/organ-aging-studio/organ_aging_studio.py \
  --demo --output /tmp/organ-aging-studio \
  --organs Heart,Brain,Immune,Organismal \
  --sample-id DEMO_000 --top-n 10

**Expected outputs** in `/tmp/organ-aging-studio/`:

| File | Contents | |------|----------| | `report.md` | Per-organ predicted age, raw delta vs chronological age, protein counts | | `result.json` | F