Merge pull request #2 from maragkakislab/dev

Revise proteomics set and update machine learning parameters

Author: katarinagresova

README.md

@@ -1,2 +1,67 @@
-# wf-bulk-senescence
-Detecting cellular senescence using transcriptomic and proteomic data.
+# Machine learning guided identification of senescence markers
+
+This repository provides a reproducible workflow for identifying robust senescence markers from SenCat transcriptomic and proteomic data and for validating marker-based scoring in external IMR90 fibroblast datasets.
+
+## Workflow
+
+The workflow standardizes transcriptomic and proteomic measurements, applies consistent preprocessing, and uses a cross-cell-type machine learning strategy to identify markers that remain informative across biological contexts. A refined marker set is then used to derive stable marker weights and generate sample-level senescence scores in both reference and external validation datasets, with all primary outputs written to the analysis and plotting directories.
+
+## Inputs
+
+- **SenCat transcriptomic data**: primary RNA-level input used for marker discovery.
+- **SenCat proteomic data**: primary protein-level input used for marker discovery.
+- **External validation data**: IMR90 fibroblast datasets used to evaluate score transferability.
+- **Workflow configuration**: centralized settings for inputs, analysis profiles, and output locations.
+
+## ML markers
+
+- **Transcriptomics markers**: `analysis/transcriptomics.transcriptomics_loose5000f_tuned_common_features.results.csv`.
+- **Proteomics markers**: `analysis/proteomics.proteomics_loose5000f_tuned_common_features.results.csv`.
+
+## Using ML markers for senescence scoring
+
+You can use our senescence markers to score your data for senescence.
+
+### Prepare data
+
+The scoring is performed on `h5ad` file containing normalized transcriptomics or proteomics counts. Expected `h5ad` structure:
+
+- `adata.X`: sample-by-feature expression matrix
+- `adata.var_names`: feature identifiers matching the marker IDs in the marker CSV index
+
+If your data are not normalized, you can use `normalize_counts.py` script:
+
+```python
+python workflow/scripts/data/normalize_counts.py \
+    --input-h5ad INPUT_H5AD \
+    --design DESIGN_FACTORS \
+    --output-h5ad NORMALIZED_H5AD \
+    --log logs/my_data.normalize.log \
+    --log-level INFO
+```
+
+- `INPUT_H5AD` specifies a path to your input `h5ad` file
+- `DESIGN_FACTORS` specifies design factors for DESeq2, in the format `x + z` or `~x+z`.
+- `NORMALIZED_H5AD` specifies a path where your normalized data will be saved
+
+## Get senescence scores
+
+```python
+python workflow/scripts/cls/marker_classifier.py \
+    --markers PATH_TO_ML_MARKERS \
+    --input-h5ad NORMALIZED_H5AD \
+    --output-results-csv OUTPUT_CSV 
+```
+
+- `PATH_TO_ML_MARKERS` specifies path to ML markers. Use `analysis/transcriptomics.transcriptomics_loose5000f_tuned_common_features.results.csv` for transcriptomics and `analysis/proteomics.proteomics_loose5000f_tuned_common_features.results.csv` for proteomics
+- `NORMALIZED_H5AD` specifies path to your normalized `h5ad` data
+- `OUTPUT_CSV` specifies path to output csv file with per-sample `score` values (higher values indicate stronger similarity to the senescence-associated signature).
+
+Notes:
+
+- `marker_classifier.py` applies `log1p` internally.
+- Marker matching is based on `adata.var_names`; non-overlapping markers are skipped automatically.
+
+## Manuscript
+
+Anerillas, Carlos, et al. "SenCat: Cataloging human cell senescence through multiomic profiling of multiple senescent primary cell types." bioRxiv (2026): 2026-02. [https://doi.org/10.64898/2026.02.05.703986](https://doi.org/10.64898/2026.02.05.703986)

analysis/proteomics.proteomics_loose5000f_tuned_common_features.results.csv

@@ -0,0 +1,193 @@
+obs,label,score
+WI38_P_1,0,-11.538828996768714
+WI38_P_2,0,-12.680862914726818
+WI38_P_3,0,-13.515741337374628
+WI38_P_4,0,-13.80908626869857
+WI38_CTIS_1,1,9.976109588163506
+WI38_CTIS_2,1,9.843645499837072
+WI38_CTIS_3,1,8.055420123720474
+WI38_CTIS_4,1,10.455420203602774
+WI38_IRIS_1,1,8.76446644078101
+WI38_IRIS_2,1,9.523357238727188
+WI38_IRIS_3,1,11.598354228476754
+WI38_IRIS_4,1,9.555065497539788
+WI38_OSIS_1,1,6.040993789963847
+WI38_OSIS_2,1,7.254767615045569
+WI38_OSIS_3,1,6.165637985157343
+WI38_OSIS_4,1,6.529893317067662
+WI38_EV_1,0,-4.782665348751444
+WI38_EV_2,0,-5.884829690295969
+WI38_EV_3,0,-6.234597061709163
+WI38_EV_4,0,-6.336933294992674
+WI38_OIS_1,1,6.799686306306363
+WI38_OIS_2,1,7.391797609179027
+WI38_OIS_3,1,5.216593771889272
+WI38_OIS_4,1,6.813066292960044
+BJ_P_1,0,-4.504449738693516
+BJ_P_2,0,-6.910898689808129
+BJ_P_3,0,-6.012232863989395
+BJ_P_4,0,-4.273641766054479
+BJ_CTIS_1,1,10.167934098654316
+BJ_CTIS_2,1,9.150842370496653
+BJ_CTIS_3,1,5.798574261490091
+BJ_CTIS_4,1,8.708248502686843
+BJ_IRIS_1,1,5.586745005682415
+BJ_IRIS_2,1,5.856049114520757
+BJ_IRIS_3,1,6.012991583916754
+BJ_IRIS_4,1,6.293086612028366
+BJ_OSIS_1,1,6.514881110180604
+BJ_OSIS_2,1,5.899112143500289
+BJ_OSIS_3,1,7.141317815028896
+BJ_OSIS_4,1,7.125964747596695
+BJ_EV_1,0,-4.7445031865403
+BJ_EV_2,0,-3.8630445722604465
+BJ_EV_3,0,-4.458858326106522
+BJ_EV_4,0,-6.059969375264109
+BJ_OIS_1,1,6.099999570754001
+BJ_OIS_2,1,4.652404752136463
+BJ_OIS_3,1,3.7548549139644627
+BJ_OIS_4,1,4.189128834496064
+HSAEC_P_1,0,-7.516757882919095
+HSAEC_P_2,0,-5.76287090122295
+HSAEC_P_3,0,-6.328329028280637
+HSAEC_P_4,0,-6.6986503454765485
+HSAEC_CTIS_1,1,8.80063410848882
+HSAEC_CTIS_2,1,8.743069771180759
+HSAEC_CTIS_3,1,8.715339636412093
+HSAEC_CTIS_4,1,8.386509486284409
+HSAEC_IRIS_1,1,8.165664558211054
+HSAEC_IRIS_2,1,6.90186582850553
+HSAEC_IRIS_3,1,5.904552204754607
+HSAEC_IRIS_4,1,6.3298656672416
+HEKn_P_1,0,-9.852561570548659
+HEKn_P_2,0,-9.981158177068274
+HEKn_P_3,0,-8.511943681036325
+HEKn_P_4,0,-9.540988380050143
+HEKn_CTIS_1,1,12.304916113481543
+HEKn_CTIS_2,1,11.761078708241792
+HEKn_CTIS_3,1,11.947732431597434
+HEKn_CTIS_4,1,12.544549322821881
+HEKn_IRIS_1,1,7.350849604945093
+HEKn_IRIS_2,1,6.860549755187968
+HEKn_IRIS_3,1,7.037442506966663
+HEKn_IRIS_4,1,6.806072686024458
+HCAEC_P_1,0,-4.157625575802478
+HCAEC_P_2,0,-7.8975503032894645
+HCAEC_P_3,0,-7.434982759396354
+HCAEC_P_4,0,-7.796409649740869
+HCAEC_CTIS_1,1,5.276929478069843
+HCAEC_CTIS_2,1,5.6548208491236664
+HCAEC_CTIS_3,1,4.857828261539319
+HCAEC_CTIS_4,1,6.162042762881479
+HCAEC_IRIS_1,1,9.292152544408026
+HCAEC_IRIS_2,1,8.364336711398892
+HCAEC_IRIS_3,1,8.228884161589338
+HCAEC_IRIS_4,1,8.493619551744727
+HUVEC_P_1,0,-7.207455334526678
+HUVEC_P_2,0,-7.576688905562343
+HUVEC_P_3,0,-6.816803012539782
+HUVEC_P_4,0,-6.875734140688108
+HUVEC_CTIS_1,1,9.137605081186898
+HUVEC_CTIS_2,1,10.53115220079936
+HUVEC_CTIS_3,1,9.046926795904163
+HUVEC_CTIS_4,1,9.437879822889416
+HUVEC_IRIS_1,1,5.9766356891366765
+HUVEC_IRIS_2,1,5.6979156512389775
+HUVEC_IRIS_3,1,5.661906263663141
+HUVEC_IRIS_4,1,5.675259494214629
+BMMSC_P_1,0,-8.176191846593678
+BMMSC_P_2,0,-8.279875684216606
+BMMSC_P_3,0,-8.545187626351273
+BMMSC_P_4,0,-9.002198852475061
+BMMSC_CTIS_1,1,5.477808479327356
+BMMSC_CTIS_2,1,6.636714454438904
+BMMSC_CTIS_3,1,5.691496435146608
+BMMSC_CTIS_4,1,6.4297194469528876
+BMMSC_IRIS_1,1,7.189968161029601
+BMMSC_IRIS_2,1,7.988945217501708
+BMMSC_IRIS_3,1,8.932761868849422
+BMMSC_IRIS_4,1,9.015141772948196
+HVSMC_P_1,0,-4.7212080471390765
+HVSMC_P_2,0,-4.496966667188161
+HVSMC_P_3,0,-5.8694982121022505
+HVSMC_P_4,0,-5.388814468123448
+HVSMC_CTIS_1,1,6.064729034752284
+HVSMC_CTIS_2,1,6.621491887611016
+HVSMC_CTIS_3,1,6.500885699925798
+HVSMC_CTIS_4,1,5.834681318410981
+HVSMC_IRIS_1,1,7.834533134124193
+HVSMC_IRIS_2,1,7.673343701354595
+HVSMC_IRIS_3,1,8.228171459940071
+HVSMC_IRIS_4,1,6.629298270242274
+HSKM_P_1,0,-8.574730734407458
+HSKM_P_2,0,-7.607446649837656
+HSKM_P_3,0,-9.379604728192938
+HSKM_P_4,0,-8.436637607235772
+HSKM_CTIS_1,1,8.891124076398677
+HSKM_CTIS_2,1,6.984936897178207
+HSKM_CTIS_3,1,7.606722861061789
+HSKM_CTIS_4,1,8.90944213888411
+HSKM_IRIS_1,1,5.225771102667557
+HSKM_IRIS_2,1,7.987018759582699
+HSKM_IRIS_3,1,7.07395764468443
+HSKM_IRIS_4,1,6.423080101371189
+PBMC_P_1,0,-11.286929069951588
+PBMC_P_2,0,-8.53977875547799
+PBMC_P_3,0,-8.475962758421906
+PBMC_P_4,0,-6.827553294455234
+PBMC_CTIS_1,1,5.187083718713232
+PBMC_CTIS_2,1,6.323060984657073
+PBMC_CTIS_3,1,5.575313663261117
+PBMC_CTIS_4,1,4.9551096134840416
+PBMC_IRIS_1,1,8.34699935401728
+PBMC_IRIS_2,1,8.643825535457637
+PBMC_IRIS_3,1,6.701784785040235
+PBMC_IRIS_4,1,8.898688098819003
+PreAdipo_P_1,0,-4.766951532411659
+PreAdipo_P_2,0,-4.643554862061235
+PreAdipo_P_3,0,-7.855656894624351
+PreAdipo_P_4,0,-4.5112007527617815
+PreAdipo_CTIS_1,1,13.099591564820118
+PreAdipo_CTIS_2,1,12.371837229170726
+PreAdipo_CTIS_3,1,8.004149908189088
+PreAdipo_CTIS_4,1,8.152527688585261
+PreAdipo_IRIS_1,1,11.335309114854754
+PreAdipo_IRIS_2,1,11.493084528307334
+PreAdipo_IRIS_3,1,11.395985110235083
+PreAdipo_IRIS_4,1,9.850866207148075
+NHO_P_1,0,-6.894779821956949
+NHO_P_2,0,-7.358869888964169
+NHO_P_3,0,-5.62518013554725
+NHO_P_4,0,-6.222317633289193
+NHO_CTIS_1,1,11.547394735704373
+NHO_CTIS_2,1,12.02648922404535
+NHO_CTIS_3,1,11.851122479222656
+NHO_CTIS_4,1,12.421568506098126
+NHO_IRIS_1,1,9.040847814888474
+NHO_IRIS_2,1,8.252338848223598
+NHO_IRIS_3,1,8.854967392843722
+NHO_IRIS_4,1,7.585584476958637
+NHA_P_1,0,-8.439846690173383
+NHA_P_2,0,-5.649021047198002
+NHA_P_3,0,-7.381991923834658
+NHA_P_4,0,-5.58432621825511
+NHA_CTIS_1,1,6.47963554567552
+NHA_CTIS_2,1,7.653796414126066
+NHA_CTIS_3,1,7.436622497961107
+NHA_CTIS_4,1,6.598421587689202
+NHA_IRIS_1,1,6.399342421257272
+NHA_IRIS_2,1,5.41159088667826
+NHA_IRIS_3,1,6.3497501330251485
+NHA_IRIS_4,1,7.5772660804756615
+HEMn_P_1,0,-4.016132218377048
+HEMn_P_2,0,-3.3433269142227697
+HEMn_P_3,0,-3.703078739193815
+HEMn_P_4,0,-3.7991737833017742
+HEMn_CTIS_1,1,7.713736200138218
+HEMn_CTIS_2,1,7.0118705849924785
+HEMn_CTIS_3,1,7.188450185221983
+HEMn_CTIS_4,1,6.83998595192966
+HEMn_IRIS_1,1,5.042549804199654
+HEMn_IRIS_2,1,5.108973793311555
+HEMn_IRIS_3,1,4.6213183403579094
+HEMn_IRIS_4,1,4.278458537945517