Metadata-Version: 2.4
Name: mossn
Version: 0.1.6
Summary: MOSSN: uniform-baseline reweighting of a reference PPI network for individual samples
Author: Zihao Chen
License-Expression: LicenseRef-Research-Only
Keywords: bioinformatics,network,ppi,multi-omics,gene-expression
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.10
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# mossn

[![PyPI version](https://img.shields.io/pypi/v/mossn.svg)](https://pypi.org/project/mossn/)
[![Python versions](https://img.shields.io/pypi/pyversions/mossn.svg)](https://pypi.org/project/mossn/)

`mossn` implements **MOSSN** (Multi-Omics Single-Sample Network reweighting),
a framework for generating sample-specific protein-interaction network
(ssPIN) edge weights from a fixed reference PPI topology.

MOSSN does not infer new protein interactions. The input PPI supplies the
reference edge set and topology only: every retained PPI edge starts at a
uniform weight of `1.0`. Its final, sample-specific weight is determined by
within-sample molecular signals and network propagation.

## Highlights

- Single-sample and multi-sample workflows for sample-specific network scoring
- Works with either a PPI links table or a custom `networkx.Graph`
- Direct-coupled multi-omics workflow for integrating matched CNV/MET layers
  alongside expression
- Bundled example dataset (TCGA-BLCA expression + STRING PPI) for quick
  experiments and reproducible demos

## Method Overview

For each sample, MOSSN:

1. Filters the reference PPI and expression matrix down to their shared
   genes.
2. IQR-normalizes expression and applies a sigmoid edge correction, scaled by
   `lam`.
3. Runs random walk with restart (RWR), seeded from genes above the
   `seed_quantile` expression percentile (or a uniform prior when seeding is
   disabled).
4. Rank-normalizes node importance and combines it with the edge correction
   to produce one `FinalWeight` per reference PPI edge.

## Installation

```bash
pip install mossn
```

For local development:

```bash
pip install -e .[test]
```

## Core API

- `prepare_data(...)`: build the uniform-weight background network from a
  links table or a `networkx.Graph`
- `run_single_sample(...)`: score one sample against that network
- `run_samples(...)`: run the single-omics workflow across multiple samples
- `prepare_data_direct_coupled(...)`: build a direct-coupled multi-omics
  graph (expression + CNV/MET)
- `run_direct_coupled_single_sample(...)`: score one sample in the
  direct-coupled multi-omics setting

## Input Format

- `expression_data`: a genes × samples `pandas.DataFrame`.
- `links`: a dataframe containing `protein1` and `protein2`. Additional
  confidence-score columns are allowed but are ignored by MOSSN.

Gene identifiers must match between the expression matrix and the PPI
network.

## Single-Omics MOSSN

```python
import pandas as pd
from mossn import prepare_data, run_single_sample

links = pd.DataFrame({
    "protein1": ["A", "A", "B"],
    "protein2": ["B", "C", "C"],
})
expression = pd.DataFrame(
    {"sample_1": [4.2, 7.1, 3.5], "sample_2": [5.3, 6.4, 2.8]},
    index=["A", "B", "C"],
)

graph, base_weights, expression = prepare_data(expression, links=links)
edge_table = run_single_sample("sample_1", graph, base_weights, expression)
```

To process every sample in the expression matrix, use `run_samples(...)`
instead — it accepts the same keyword arguments as `run_single_sample(...)`.

### Parameters

- `lam` (default `2.0`): strength of expression-based edge correction
- `rwr_alpha` (default `0.3`): restart probability in the random walk
- `seed_quantile` (default `0.9`): expression quantile used to define seed
  genes

### Ablation switches

- `use_correction=False` — disable edge correction (`noCorr`)
- `use_rwr=False` — disable the random walk, use edge correction alone
  (`noRWR`)
- `use_seed=False` — use a uniform restart prior instead of expression-based
  seeds (`noSeed`)

## Multi-Omics: MOSSN-Direct

All multi-omics functions expect an `omic_data` dictionary containing
`"EXP"` and, as needed, `"MET"` and/or `"CNV"` gene × sample dataframes.
Sample IDs are normalized by replacing `-` with `_` and keeping the first 12
characters, matching the analysis workflow.

MOSSN-Direct maintains a PPI graph only for the expression layer. Each
auxiliary MET/CNV node is connected solely to its corresponding expression
gene, and cross-layer edge weights are based on within-sample cross-omics
concordance.

```python
from mossn import prepare_data_direct_coupled, run_direct_coupled_single_sample

graph, base_weights, omics, exp_genes = prepare_data_direct_coupled(
    links, {"EXP": expression, "CNV": cnv}, coupled_omics=["CNV"]
)
edge_table = run_direct_coupled_single_sample(
    "sample_1", graph, base_weights, omics, exp_genes, coupled_omics=["CNV"]
)
```

## Output Format

Both workflows return a tidy edge table:

| Column        | Meaning                                            |
|---------------|-----------------------------------------------------|
| `Sample`      | Sample identifier                                    |
| `Node1`       | First endpoint of the interaction                     |
| `Node2`       | Second endpoint of the interaction                     |
| `BaseWeight`  | Background-network edge weight (`1.0` for standard MOSSN) |
| `FinalWeight` | Sample-specific edge score returned by MOSSN            |

## Bundled Example Data

```python
from mossn.example_data import load_example_expression, load_example_links

expression = load_example_expression()
links = load_example_links()
```

## License

`mossn` is distributed under a research-only license. Non-commercial
research, teaching, and evaluation use are allowed. Commercial use requires
prior written permission from the copyright holder.
