Proteomics Structural

---
# AUTO-GENERATED header from skill.yaml — do not edit by hand.
# Edit skill.yaml, then run: python scripts/generate_skill_md.py <skill_dir>
name: proteomics-structural
description: Load when summarising cross-linking MS (XL-MS) results — intra/inter-protein link split,
  optional FDR filtering, distance-constraint validation against a per-crosslinker (DSS / BS3 / EDC /
  DSSO / DSBU) max distance. Skip when raw spectra are the input (run XlinkX / pLink / xiSEARCH first);
  no XL-MS experiment was performed.
version: 0.5.0
author: OmicsClaw
license: MIT
emoji: 🏗️
tags:
- proteomics
- structural
- xl-ms
- crosslinking
- dss
- bs3
- dsso
- dsbu
- edc
requires:
- numpy
- pandas
---

# proteomics-structural

## When to use

The user has a cross-linking MS (XL-MS) results CSV (from XlinkX,
pLink, xiSEARCH, etc.) and wants a summary: intra- vs inter-protein
classification, optional FDR filtering, and distance-constraint
validation against the per-crosslinker max distance (Rappsilber
(2011) Cα-Cα bounds).

`--crosslinker {DSS,BS3,EDC,DSSO,DSBU}` (default `DSS`) sets the
max-distance threshold (`CROSSLINKER_CONSTRAINTS` at
`struct_proteomics.py:43-49`: DSS/BS3/DSSO/DSBU = 30 Å, EDC =
20 Å). `--fdr` (default 0.05) filters by the `fdr` column when
present.

This skill does NOT run an XL-MS search engine — feed it the
already-searched results.

## Inputs & Outputs

<!-- AUTO-GENERATED from skill.yaml (interface) — do not edit by hand. Regenerate: python scripts/generate_skill_md.py <skill_dir> -->

**Inputs**

- File types: `.csv`

**Outputs**

- `tables/crosslinks.csv`
- `tables/inter_protein_crosslinks.csv`
- `report.md`
- `result.json`

## Flow

1. Load CSV (`--input <crosslinks.csv>`) or generate a demo at `output_dir/demo_crosslinks.csv` (`struct_proteomics.py:102`).
2. If `fdr` column present, filter to `df[df["fdr"] <= --fdr]` (`struct_proteomics.py:126`); otherwise pass-through (`:130`).
3. Derive `link_type` from `protein_a == protein_b` comparison when both columns are present (`struct_proteomics.py:134-141`); otherwise count all rows as intra (`:142-145`).
4. If `distance_angstrom` column present, compute satisfaction rate vs `CROSSLINKER_CONSTRAINTS[--crosslinker]` (`struct_proteomics.py:147-167`); add per-row `constraint_satisfied` boolean column.
5. Write `tables/crosslinks.csv` (`struct_proteomics.py:282`) + `tables/inter_protein_crosslinks.csv` (only if non-empty, `:287`) + `report.md` + `result.json` (`:290`).

## Gotchas

- **Required input columns are `protein_a` and `protein_b`** (lowercase, with underscore-letter — NOT `protein1` / `protein2`). `struct_proteomics.py:134` checks `{"protein_a", "protein_b"}.issubset(df_filtered.columns)`. Without both, ALL rows silently classify as `intra-protein` (`:142-145`) — n_inter = 0 even on a real inter-protein dataset. XlinkX exports use `Protein A` / `Protein B`; rename first.
- **`--crosslinker` drives the distance-constraint check, NOT just metadata.** `struct_proteomics.py:148` sets `max_distance = CROSSLINKER_CONSTRAINTS.get(crosslinker.upper(), 30.0)` — the active threshold for `constraint_satisfied` column + `constraint_satisfaction_rate` summary. Choices: DSS / BS3 / DSSO / DSBU = 30 Å, EDC = 20 Å (Rappsilber 2011 Cα-Cα bounds).
- **Distance check is OPT-IN by `distance_angstrom` column presence.** Without that column, `constraint_satisfaction_rate` defaults to 100% (`struct_proteomics.py:170`) — the constraint feature is silently skipped, not failed. Pass `distance_angstrom` (Cα-Cα predicted distance from a 3D model) for a real check.
- **`fdr` filter is OPT-IN by column presence.** `struct_proteomics.py:126` only filters when `fdr` exists — without that column, EVERY input row is kept regardless of `--fdr`. Pre-add an `fdr` column (or a placeholder of zeros) if you need the filter to bite.
- **`--input` REQUIRED unless `--demo`.** `struct_proteomics.py:270` raises `ValueError("--input required when not using --demo")`.
- **`tables/inter_protein_crosslinks.csv` only appears when there ARE inter-protein links.** A purely-intra dataset writes only `tables/crosslinks.csv`. Downstream consumers should check file existence.

## Key CLI

```bash
# Demo
python omicsclaw.py run proteomics-structural --demo --output /tmp/xl_demo

# Real XL-MS data, default DSS / 5% FDR
python omicsclaw.py run proteomics-structural \
  --input crosslinks.csv --output results/

# DSBU at 1% FDR
python omicsclaw.py run proteomics-structural \
  --input crosslinks.csv --output results/ \
  --crosslinker DSBU --fdr 0.01

# EDC (zero-length, 20 Å threshold)
python omicsclaw.py run proteomics-structural \
  --input crosslinks.csv --output results/ \
  --crosslinker EDC --fdr 0.05
```

## See also

- `references/parameters.md` — every CLI flag
- `references/methodology.md` — XL-MS workflow, Rappsilber Cα-Cα bounds, FDR caveats
- `references/output_contract.md` — `tables/crosslinks.csv` schema, derived columns
- Adjacent skills: `proteomics-data-import` (parallel — peptide / protein-level workflows), `proteomics-ptm` (parallel — PTM analysis), `proteomics-quantification` (parallel — protein abundance), `proteomics-enrichment` (downstream — pathway enrichment on inter-protein partners)