##### Perturbation modeling

Cross-study drug-perturbation transcriptomics on Tahoe-100M + LINCS
Level 2 (and appended DRUG-seq): harmonize compounds and gene symbols
onto a shared "pert_compound" label and gene panel, train a modlyn
linear classifier on a "MappedCollection", then enrich and interpret
top genes per perturbation.

Reusable logic lives in the "perturbation_modeling" library. Thin
tracked scripts on the instance import it ("build_collection",
"append_dataset", "train_feature_selection", "enrich_top_genes",
"build_evidence_report") instead of copying pipeline code.

A key pattern: **append a new study to an existing collection and
retrain**. After Tahoe + LINCS were harmonized, DRUG-seq was aligned
to the same "pert_compound" label and gene-symbol panel (including
when "var_names" are Ensembl IDs), versioned into the collection, and
the classifier was retrained on the expanded "MappedCollection" —
without rebuilding the upstream library.

**Instance:** laminlabs/perturbation-modeling · **Repo:** laminlabs
/perturbation-modeling

#### Harmonize & append

Tahoe compounds are kept when they appear in **any** LINCS phase (not
the intersection of every phase). Outputs use the "demo/" key prefix.

| --- | --- | --- |
| Step | Transform | Outputs |
| =================================== | =================================== | =================================== |
| Build Tahoe + LINCS collection | 01_harmonize_and_append.py | collection · compounds · Tahoe |
| --- | --- | --- |
| Append DRUG-seq | 01_harmonize_and_append.py | collection · DRUG-seq |
| --- | --- | --- |

#### Modeling & interpretation

Retrain on the updated collection after each append so new compounds
and cells enter the feature-selection model. The interpretation script
loads those tables, calls "build_evidence_report" for the evidence
block, and puts compound notes in "extra_sections".

| --- | --- | --- |
| Step | Transform | Outputs |
| =================================== | =================================== | =================================== |
| Train / retrain SimpleLogReg | 02_train_feature_selection.py | weights · train summary |
| (modlyn) |
| --- | --- | --- |
| Gene-module enrichment | 03_run_enrichment.py | top genes · enrichment · top |
| terms |
| --- | --- | --- |
| Interpretation report (agent) | 04_interpret_modlyn.py · agent | report |
| run |
| --- | --- | --- |