triger 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- triger-1.0.0/.gitignore +7 -0
- triger-1.0.0/CHANGELOG.md +19 -0
- triger-1.0.0/CITATION.cff +32 -0
- triger-1.0.0/LICENSE +21 -0
- triger-1.0.0/PKG-INFO +133 -0
- triger-1.0.0/README.md +98 -0
- triger-1.0.0/pyproject.toml +55 -0
- triger-1.0.0/src/triger/__init__.py +16 -0
- triger-1.0.0/src/triger/association.py +170 -0
- triger-1.0.0/src/triger/greedy_peeling.py +405 -0
- triger-1.0.0/src/triger/plotting.py +222 -0
- triger-1.0.0/tests/fixtures/README.md +13 -0
- triger-1.0.0/tests/fixtures/three_step_P.csv +70 -0
- triger-1.0.0/tests/fixtures/three_step_R.csv +70 -0
- triger-1.0.0/tests/fixtures/three_step_blocks.csv +35 -0
- triger-1.0.0/tests/fixtures/x.csv +50 -0
- triger-1.0.0/tests/fixtures/x_blocks.csv +21 -0
- triger-1.0.0/tests/fixtures/x_density.csv +3 -0
- triger-1.0.0/tests/fixtures/xy.csv +60 -0
- triger-1.0.0/tests/fixtures/xy_blocks.csv +61 -0
- triger-1.0.0/tests/fixtures/xy_density.csv +3 -0
- triger-1.0.0/tests/test_association.py +93 -0
- triger-1.0.0/tests/test_fixtures.py +59 -0
- triger-1.0.0/tests/test_triger.py +121 -0
triger-1.0.0/.gitignore
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.0
|
|
4
|
+
|
|
5
|
+
First release on PyPI.
|
|
6
|
+
|
|
7
|
+
- `triger()` runs the full pipeline on two omics layers given as NumPy arrays
|
|
8
|
+
or pandas DataFrames, matches DataFrame samples by index, and returns
|
|
9
|
+
feature names with each module.
|
|
10
|
+
- `association_matrices()` computes the signed correlation and -log10 p-value
|
|
11
|
+
matrices used by `greedy_3step()`.
|
|
12
|
+
- Results are `Block`, `Community`, `Module` and `TrigerResult` records
|
|
13
|
+
(named tuples).
|
|
14
|
+
- `greedy_peeling_XY_all()` and `greedy_3step()` take `max_blocks`, the
|
|
15
|
+
maximum number of blocks returned (default 5). `greedy_3step()` returns the
|
|
16
|
+
block density.
|
|
17
|
+
- Invalid input raises `ValueError`.
|
|
18
|
+
- Tests compare the peeling functions with reference outputs shared with the
|
|
19
|
+
R package.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use TriGer, please cite the paper below."
|
|
3
|
+
type: software
|
|
4
|
+
title: "TriGer: structured cross-omics interaction discovery with a triple-graph model (Python package)"
|
|
5
|
+
authors:
|
|
6
|
+
- family-names: Yu
|
|
7
|
+
given-names: Jiaao
|
|
8
|
+
- family-names: Lin
|
|
9
|
+
given-names: Huang
|
|
10
|
+
orcid: "https://orcid.org/0000-0002-4892-7871"
|
|
11
|
+
repository-code: "https://github.com/MATRIX-Research-Lab/TriGer-PyPI"
|
|
12
|
+
url: "https://pypi.org/project/triger/"
|
|
13
|
+
license: MIT
|
|
14
|
+
keywords:
|
|
15
|
+
- multi-omics
|
|
16
|
+
- data integration
|
|
17
|
+
- dense subgraph
|
|
18
|
+
preferred-citation:
|
|
19
|
+
type: article
|
|
20
|
+
title: "Structured cross-omics interaction discovery with a triple-graph model"
|
|
21
|
+
authors:
|
|
22
|
+
- family-names: Yu
|
|
23
|
+
given-names: Jiaao
|
|
24
|
+
- family-names: Lin
|
|
25
|
+
given-names: Huang
|
|
26
|
+
orcid: "https://orcid.org/0000-0002-4892-7871"
|
|
27
|
+
- family-names: Chen
|
|
28
|
+
given-names: Shuo
|
|
29
|
+
journal: bioRxiv
|
|
30
|
+
year: 2026
|
|
31
|
+
doi: "10.64898/2026.09.10.749540"
|
|
32
|
+
url: "https://www.biorxiv.org/content/10.64898/2026.09.10.749540v1"
|
triger-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jiaao Yu and Huang Lin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
triger-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: triger
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Structured cross-omics interaction discovery with a triple-graph model
|
|
5
|
+
Project-URL: Homepage, https://github.com/MATRIX-Research-Lab/TriGer-PyPI
|
|
6
|
+
Project-URL: Issues, https://github.com/MATRIX-Research-Lab/TriGer-PyPI/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/MATRIX-Research-Lab/TriGer-PyPI/blob/main/CHANGELOG.md
|
|
8
|
+
Project-URL: Paper, https://doi.org/10.64898/2026.09.10.749540
|
|
9
|
+
Project-URL: R package, https://github.com/MATRIX-Research-Lab/TriGer
|
|
10
|
+
Project-URL: MATLAB code, https://github.com/jy2941/TriGer
|
|
11
|
+
Author-email: Jiaao Yu <jy2941@umd.edu>, Huang Lin <huanglinfrederick@gmail.com>
|
|
12
|
+
Maintainer-email: Huang Lin <huanglinfrederick@gmail.com>
|
|
13
|
+
License-Expression: MIT
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Keywords: biclustering,dense subgraph,greedy peeling,integration,multi-omics
|
|
16
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
17
|
+
Classifier: Intended Audience :: Science/Research
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
26
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
27
|
+
Requires-Python: >=3.10
|
|
28
|
+
Requires-Dist: matplotlib>=3.5
|
|
29
|
+
Requires-Dist: numpy>=1.21
|
|
30
|
+
Requires-Dist: scipy>=1.8
|
|
31
|
+
Provides-Extra: test
|
|
32
|
+
Requires-Dist: pandas>=1.4; extra == 'test'
|
|
33
|
+
Requires-Dist: pytest>=7; extra == 'test'
|
|
34
|
+
Description-Content-Type: text/markdown
|
|
35
|
+
|
|
36
|
+
# TriGer
|
|
37
|
+
|
|
38
|
+
[](https://github.com/MATRIX-Research-Lab/TriGer-PyPI/actions/workflows/tests.yml)
|
|
39
|
+
[](https://pypi.org/project/triger/)
|
|
40
|
+
[](https://doi.org/10.64898/2026.09.10.749540)
|
|
41
|
+
[](https://github.com/MATRIX-Research-Lab/TriGer-PyPI/blob/main/LICENSE)
|
|
42
|
+
|
|
43
|
+
| Platform | Repository | Installation |
|
|
44
|
+
|----------|------------|--------------|
|
|
45
|
+
| R | [MATRIX-Research-Lab/TriGer](https://github.com/MATRIX-Research-Lab/TriGer) | `remotes::install_github("MATRIX-Research-Lab/TriGer")` |
|
|
46
|
+
| Python | [MATRIX-Research-Lab/TriGer-PyPI](https://github.com/MATRIX-Research-Lab/TriGer-PyPI) (this repository) | `pip install triger` |
|
|
47
|
+
| MATLAB | [jy2941/TriGer](https://github.com/jy2941/TriGer) | Clone the repository and add `matlab/methods` and `matlab/visualization` to the MATLAB path |
|
|
48
|
+
|
|
49
|
+
The R and Python packages give identical results on the same input; both are
|
|
50
|
+
tested against shared reference outputs. The MATLAB repository also contains
|
|
51
|
+
the code for the simulations and the real-data analyses of the paper.
|
|
52
|
+
|
|
53
|
+
Python package `triger` for **TriGer**, from the paper *Structured cross-omics
|
|
54
|
+
interaction discovery with a triple-graph model*.
|
|
55
|
+
|
|
56
|
+
TriGer finds modules of features that are densely associated across two omics
|
|
57
|
+
layers (X and Y) and coherent within each layer. It peels dense blocks from the
|
|
58
|
+
cross-omics association matrix, then refines large blocks using the
|
|
59
|
+
within-omics correlation matrices.
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
pip install triger
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The development version:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pip install git+https://github.com/MATRIX-Research-Lab/TriGer-PyPI.git
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Quick start
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
import triger
|
|
77
|
+
|
|
78
|
+
# X: samples x m features, Y: samples x n features (NumPy arrays or pandas
|
|
79
|
+
# DataFrames; DataFrames are matched by sample index and keep feature names)
|
|
80
|
+
res = triger.triger(X, Y, lambda1=1.1, lambda2=1.8, lambda3=1.8,
|
|
81
|
+
X_size=(10, 15), Y_size=(10, 250))
|
|
82
|
+
|
|
83
|
+
for mod in res.modules:
|
|
84
|
+
print(len(mod.X), "X features,", len(mod.Y), "Y features")
|
|
85
|
+
print(res.modules[0].X_names)
|
|
86
|
+
|
|
87
|
+
# Cross- and within-omics correlations of the module features
|
|
88
|
+
m = res.m
|
|
89
|
+
triger.plot3in1_v1(res.R[:m, :m], res.R[m:, m:], res.R[:m, m:], res.modules,
|
|
90
|
+
line=True)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The lower-level functions work on precomputed matrices:
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
a = triger.association_matrices(X, Y) # signed R and -log10 p P
|
|
97
|
+
blocks = triger.greedy_3step(a.P, a.R, a.m, a.n, lambda1=1.1, lambda2=1.8,
|
|
98
|
+
lambda3=1.8, X_size=(10, 15), Y_size=(10, 250))
|
|
99
|
+
x_idx, y_idx, density = blocks[0] # or blocks[0].X, .Y, .density
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Functions
|
|
103
|
+
|
|
104
|
+
| Function | Description |
|
|
105
|
+
|----------|-------------|
|
|
106
|
+
| `triger` | Full pipeline on two omics layers |
|
|
107
|
+
| `association_matrices` | Signed correlation and -log10 p-value matrices over both layers |
|
|
108
|
+
| `greedy_3step` | Full pipeline on precomputed association matrices |
|
|
109
|
+
| `greedy_peeling_XY_one` / `greedy_peeling_XY_all` | Dense blocks in a cross-omics (X-Y) matrix |
|
|
110
|
+
| `greedy_peeling_X_one` / `greedy_peeling_X_all` | Dense communities in a within-omics (symmetric) matrix |
|
|
111
|
+
| `sort_result` / `sort_result_XandY` | Order features within each block |
|
|
112
|
+
| `plot3in1_v1` | X-Y heatmap with the X-X and Y-Y matrices as triangles |
|
|
113
|
+
| `plot_all_result` | Heatmap of the detected blocks |
|
|
114
|
+
|
|
115
|
+
Blocks are returned as `Block(X, Y, density)` records, communities as
|
|
116
|
+
`Community(X, density)`, and the modules of `triger` as
|
|
117
|
+
`Module(X, Y, density, X_names, Y_names)`. All indices are 0-based.
|
|
118
|
+
|
|
119
|
+
`lambda1` is the cross-omics size penalty and `lambda2` / `lambda3` are the
|
|
120
|
+
within-omics penalties for X and Y (λ₀, λ₁, λ₂ in the paper); higher values give
|
|
121
|
+
smaller, denser blocks. `max_blocks` is the maximum number of blocks found in
|
|
122
|
+
the cross-omics step (default 5). The CRC and IBD analyses of the paper, run
|
|
123
|
+
with the MATLAB code, correspond to `max_blocks=4`.
|
|
124
|
+
|
|
125
|
+
## Citation
|
|
126
|
+
|
|
127
|
+
Yu J, Lin H, Chen S (2026). Structured cross-omics interaction discovery with a
|
|
128
|
+
triple-graph model. *bioRxiv*.
|
|
129
|
+
[doi:10.64898/2026.09.10.749540](https://doi.org/10.64898/2026.09.10.749540)
|
|
130
|
+
|
|
131
|
+
## License
|
|
132
|
+
|
|
133
|
+
MIT
|
triger-1.0.0/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# TriGer
|
|
2
|
+
|
|
3
|
+
[](https://github.com/MATRIX-Research-Lab/TriGer-PyPI/actions/workflows/tests.yml)
|
|
4
|
+
[](https://pypi.org/project/triger/)
|
|
5
|
+
[](https://doi.org/10.64898/2026.09.10.749540)
|
|
6
|
+
[](https://github.com/MATRIX-Research-Lab/TriGer-PyPI/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
| Platform | Repository | Installation |
|
|
9
|
+
|----------|------------|--------------|
|
|
10
|
+
| R | [MATRIX-Research-Lab/TriGer](https://github.com/MATRIX-Research-Lab/TriGer) | `remotes::install_github("MATRIX-Research-Lab/TriGer")` |
|
|
11
|
+
| Python | [MATRIX-Research-Lab/TriGer-PyPI](https://github.com/MATRIX-Research-Lab/TriGer-PyPI) (this repository) | `pip install triger` |
|
|
12
|
+
| MATLAB | [jy2941/TriGer](https://github.com/jy2941/TriGer) | Clone the repository and add `matlab/methods` and `matlab/visualization` to the MATLAB path |
|
|
13
|
+
|
|
14
|
+
The R and Python packages give identical results on the same input; both are
|
|
15
|
+
tested against shared reference outputs. The MATLAB repository also contains
|
|
16
|
+
the code for the simulations and the real-data analyses of the paper.
|
|
17
|
+
|
|
18
|
+
Python package `triger` for **TriGer**, from the paper *Structured cross-omics
|
|
19
|
+
interaction discovery with a triple-graph model*.
|
|
20
|
+
|
|
21
|
+
TriGer finds modules of features that are densely associated across two omics
|
|
22
|
+
layers (X and Y) and coherent within each layer. It peels dense blocks from the
|
|
23
|
+
cross-omics association matrix, then refines large blocks using the
|
|
24
|
+
within-omics correlation matrices.
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pip install triger
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The development version:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install git+https://github.com/MATRIX-Research-Lab/TriGer-PyPI.git
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Quick start
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import triger
|
|
42
|
+
|
|
43
|
+
# X: samples x m features, Y: samples x n features (NumPy arrays or pandas
|
|
44
|
+
# DataFrames; DataFrames are matched by sample index and keep feature names)
|
|
45
|
+
res = triger.triger(X, Y, lambda1=1.1, lambda2=1.8, lambda3=1.8,
|
|
46
|
+
X_size=(10, 15), Y_size=(10, 250))
|
|
47
|
+
|
|
48
|
+
for mod in res.modules:
|
|
49
|
+
print(len(mod.X), "X features,", len(mod.Y), "Y features")
|
|
50
|
+
print(res.modules[0].X_names)
|
|
51
|
+
|
|
52
|
+
# Cross- and within-omics correlations of the module features
|
|
53
|
+
m = res.m
|
|
54
|
+
triger.plot3in1_v1(res.R[:m, :m], res.R[m:, m:], res.R[:m, m:], res.modules,
|
|
55
|
+
line=True)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The lower-level functions work on precomputed matrices:
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
a = triger.association_matrices(X, Y) # signed R and -log10 p P
|
|
62
|
+
blocks = triger.greedy_3step(a.P, a.R, a.m, a.n, lambda1=1.1, lambda2=1.8,
|
|
63
|
+
lambda3=1.8, X_size=(10, 15), Y_size=(10, 250))
|
|
64
|
+
x_idx, y_idx, density = blocks[0] # or blocks[0].X, .Y, .density
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Functions
|
|
68
|
+
|
|
69
|
+
| Function | Description |
|
|
70
|
+
|----------|-------------|
|
|
71
|
+
| `triger` | Full pipeline on two omics layers |
|
|
72
|
+
| `association_matrices` | Signed correlation and -log10 p-value matrices over both layers |
|
|
73
|
+
| `greedy_3step` | Full pipeline on precomputed association matrices |
|
|
74
|
+
| `greedy_peeling_XY_one` / `greedy_peeling_XY_all` | Dense blocks in a cross-omics (X-Y) matrix |
|
|
75
|
+
| `greedy_peeling_X_one` / `greedy_peeling_X_all` | Dense communities in a within-omics (symmetric) matrix |
|
|
76
|
+
| `sort_result` / `sort_result_XandY` | Order features within each block |
|
|
77
|
+
| `plot3in1_v1` | X-Y heatmap with the X-X and Y-Y matrices as triangles |
|
|
78
|
+
| `plot_all_result` | Heatmap of the detected blocks |
|
|
79
|
+
|
|
80
|
+
Blocks are returned as `Block(X, Y, density)` records, communities as
|
|
81
|
+
`Community(X, density)`, and the modules of `triger` as
|
|
82
|
+
`Module(X, Y, density, X_names, Y_names)`. All indices are 0-based.
|
|
83
|
+
|
|
84
|
+
`lambda1` is the cross-omics size penalty and `lambda2` / `lambda3` are the
|
|
85
|
+
within-omics penalties for X and Y (λ₀, λ₁, λ₂ in the paper); higher values give
|
|
86
|
+
smaller, denser blocks. `max_blocks` is the maximum number of blocks found in
|
|
87
|
+
the cross-omics step (default 5). The CRC and IBD analyses of the paper, run
|
|
88
|
+
with the MATLAB code, correspond to `max_blocks=4`.
|
|
89
|
+
|
|
90
|
+
## Citation
|
|
91
|
+
|
|
92
|
+
Yu J, Lin H, Chen S (2026). Structured cross-omics interaction discovery with a
|
|
93
|
+
triple-graph model. *bioRxiv*.
|
|
94
|
+
[doi:10.64898/2026.09.10.749540](https://doi.org/10.64898/2026.09.10.749540)
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
MIT
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "triger"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Structured cross-omics interaction discovery with a triple-graph model"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "Jiaao Yu", email = "jy2941@umd.edu" },
|
|
15
|
+
{ name = "Huang Lin", email = "huanglinfrederick@gmail.com" },
|
|
16
|
+
]
|
|
17
|
+
maintainers = [{ name = "Huang Lin", email = "huanglinfrederick@gmail.com" }]
|
|
18
|
+
keywords = ["multi-omics", "integration", "biclustering", "dense subgraph", "greedy peeling"]
|
|
19
|
+
classifiers = [
|
|
20
|
+
"Development Status :: 5 - Production/Stable",
|
|
21
|
+
"Intended Audience :: Science/Research",
|
|
22
|
+
"Operating System :: OS Independent",
|
|
23
|
+
"Programming Language :: Python :: 3",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"Programming Language :: Python :: 3.13",
|
|
28
|
+
"Programming Language :: Python :: 3.14",
|
|
29
|
+
"Programming Language :: Python :: 3.15",
|
|
30
|
+
"Topic :: Scientific/Engineering :: Bio-Informatics",
|
|
31
|
+
]
|
|
32
|
+
dependencies = ["numpy>=1.21", "scipy>=1.8", "matplotlib>=3.5"]
|
|
33
|
+
|
|
34
|
+
[project.optional-dependencies]
|
|
35
|
+
test = ["pytest>=7", "pandas>=1.4"]
|
|
36
|
+
|
|
37
|
+
[project.urls]
|
|
38
|
+
Homepage = "https://github.com/MATRIX-Research-Lab/TriGer-PyPI"
|
|
39
|
+
Issues = "https://github.com/MATRIX-Research-Lab/TriGer-PyPI/issues"
|
|
40
|
+
Changelog = "https://github.com/MATRIX-Research-Lab/TriGer-PyPI/blob/main/CHANGELOG.md"
|
|
41
|
+
Paper = "https://doi.org/10.64898/2026.09.10.749540"
|
|
42
|
+
"R package" = "https://github.com/MATRIX-Research-Lab/TriGer"
|
|
43
|
+
"MATLAB code" = "https://github.com/jy2941/TriGer"
|
|
44
|
+
|
|
45
|
+
[tool.hatch.version]
|
|
46
|
+
path = "src/triger/__init__.py"
|
|
47
|
+
|
|
48
|
+
[tool.hatch.build.targets.wheel]
|
|
49
|
+
packages = ["src/triger"]
|
|
50
|
+
|
|
51
|
+
[tool.hatch.build.targets.sdist]
|
|
52
|
+
include = ["src/triger", "tests", "README.md", "CHANGELOG.md", "LICENSE", "CITATION.cff"]
|
|
53
|
+
|
|
54
|
+
[tool.pytest.ini_options]
|
|
55
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""TriGer: structured cross-omics interaction discovery with a triple-graph model."""
|
|
2
|
+
from .greedy_peeling import (Block, Community, greedy_peeling_XY_one,
|
|
3
|
+
greedy_peeling_XY_all, greedy_peeling_X_one,
|
|
4
|
+
greedy_peeling_X_all, sort_result,
|
|
5
|
+
sort_result_XandY, greedy_3step)
|
|
6
|
+
from .association import (Association, Module, TrigerResult,
|
|
7
|
+
association_matrices, triger)
|
|
8
|
+
from .plotting import plot3in1_v1, plot_all_result, matlab_jet
|
|
9
|
+
|
|
10
|
+
__version__ = "1.0.0"
|
|
11
|
+
__all__ = ["triger", "association_matrices", "greedy_3step",
|
|
12
|
+
"greedy_peeling_XY_one", "greedy_peeling_XY_all",
|
|
13
|
+
"greedy_peeling_X_one", "greedy_peeling_X_all", "sort_result",
|
|
14
|
+
"sort_result_XandY", "plot3in1_v1", "plot_all_result",
|
|
15
|
+
"matlab_jet", "Block", "Community", "Module", "Association",
|
|
16
|
+
"TrigerResult"]
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
"""
|
|
2
|
+
TriGer on data: association matrices for two omics layers and the full
|
|
3
|
+
pipeline. All indices are 0-based.
|
|
4
|
+
"""
|
|
5
|
+
from typing import List, NamedTuple, Optional
|
|
6
|
+
|
|
7
|
+
import numpy as np
|
|
8
|
+
from scipy import stats
|
|
9
|
+
|
|
10
|
+
from .greedy_peeling import _as_matrix, greedy_3step
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class Association(NamedTuple):
|
|
14
|
+
"""Association matrices over the features of two omics layers: signed
|
|
15
|
+
correlations ``R``, -log10 p-values ``P``, feature names, and the
|
|
16
|
+
numbers of X and Y features."""
|
|
17
|
+
R: np.ndarray
|
|
18
|
+
P: np.ndarray
|
|
19
|
+
names: List[str]
|
|
20
|
+
m: int
|
|
21
|
+
n: int
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class Module(NamedTuple):
|
|
25
|
+
"""A cross-omics module: X and Y indices, the penalized density of the
|
|
26
|
+
step-1 block, and the X and Y feature names."""
|
|
27
|
+
X: np.ndarray
|
|
28
|
+
Y: np.ndarray
|
|
29
|
+
density: float
|
|
30
|
+
X_names: List[str]
|
|
31
|
+
Y_names: List[str]
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class TrigerResult(NamedTuple):
|
|
35
|
+
"""Output of :func:`triger`: the modules and the association matrices."""
|
|
36
|
+
modules: List[Module]
|
|
37
|
+
R: np.ndarray
|
|
38
|
+
P: np.ndarray
|
|
39
|
+
names: List[str]
|
|
40
|
+
m: int
|
|
41
|
+
n: int
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _feature_names(x, prefix):
|
|
45
|
+
cols = getattr(x, "columns", None)
|
|
46
|
+
if cols is not None:
|
|
47
|
+
return [str(c) for c in cols]
|
|
48
|
+
return [f"{prefix}{i}" for i in range(np.shape(x)[1])]
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def association_matrices(X, Y, method="pearson") -> Association:
|
|
52
|
+
"""Association matrices for two omics layers.
|
|
53
|
+
|
|
54
|
+
Computes the signed correlation matrix and the matrix of -log10
|
|
55
|
+
two-sided p-values over the features of two omics layers measured on
|
|
56
|
+
the same samples. These are the inputs ``R`` and ``P`` of
|
|
57
|
+
:func:`triger.greedy_3step`.
|
|
58
|
+
|
|
59
|
+
The p-value of a correlation coefficient r estimated from N samples is
|
|
60
|
+
computed from ``t = |r| * sqrt((N - 2) / (1 - r**2))`` with N - 2
|
|
61
|
+
degrees of freedom, as in ``scipy.stats.pearsonr`` (for Spearman
|
|
62
|
+
correlations, the same t approximation). ``r**2`` is capped at
|
|
63
|
+
``1 - 1e-12`` so that perfectly correlated features receive a large
|
|
64
|
+
finite value, and the diagonal of P is set to 0.
|
|
65
|
+
|
|
66
|
+
Parameters
|
|
67
|
+
----------
|
|
68
|
+
X : array_like or pandas.DataFrame, shape (N, m)
|
|
69
|
+
First omics layer, samples in rows and features in columns.
|
|
70
|
+
Y : array_like or pandas.DataFrame, shape (N, n)
|
|
71
|
+
Second omics layer, with the same samples in the same order.
|
|
72
|
+
method : {"pearson", "spearman"}
|
|
73
|
+
Correlation coefficient.
|
|
74
|
+
|
|
75
|
+
Returns
|
|
76
|
+
-------
|
|
77
|
+
Association
|
|
78
|
+
``R`` and ``P``, both ``(m + n, m + n)`` with the m features of X
|
|
79
|
+
first; ``names``, the column names of X and Y for DataFrames and
|
|
80
|
+
``X0, X1, ...`` and ``Y0, Y1, ...`` otherwise; ``m`` and ``n``.
|
|
81
|
+
"""
|
|
82
|
+
if method not in ("pearson", "spearman"):
|
|
83
|
+
raise ValueError("`method` must be 'pearson' or 'spearman'")
|
|
84
|
+
names = _feature_names(X, "X") + _feature_names(Y, "Y")
|
|
85
|
+
X = _as_matrix(X, "X")
|
|
86
|
+
Y = _as_matrix(Y, "Y")
|
|
87
|
+
if X.shape[0] != Y.shape[0]:
|
|
88
|
+
raise ValueError("`X` and `Y` must have the same number of samples "
|
|
89
|
+
"(rows)")
|
|
90
|
+
N = X.shape[0]
|
|
91
|
+
if N < 3:
|
|
92
|
+
raise ValueError("at least 3 samples are required")
|
|
93
|
+
XY = np.hstack([X, Y])
|
|
94
|
+
constant = np.all(XY == XY[0], axis=0)
|
|
95
|
+
if constant.any():
|
|
96
|
+
bad = [names[i] for i in np.flatnonzero(constant)[:5]]
|
|
97
|
+
raise ValueError("features with zero variance: " + ", ".join(bad))
|
|
98
|
+
if method == "spearman":
|
|
99
|
+
XY = np.apply_along_axis(stats.rankdata, 0, XY)
|
|
100
|
+
R = np.corrcoef(XY, rowvar=False)
|
|
101
|
+
t = np.abs(R) * np.sqrt((N - 2) / (1 - np.minimum(R ** 2, 1 - 1e-12)))
|
|
102
|
+
log_p = np.log(2) + stats.t.logsf(t, df=N - 2)
|
|
103
|
+
P = -log_p / np.log(10)
|
|
104
|
+
np.fill_diagonal(P, 0.0)
|
|
105
|
+
return Association(R, P, names, X.shape[1], Y.shape[1])
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _match_samples(X, Y):
|
|
109
|
+
ix = getattr(X, "index", None)
|
|
110
|
+
iy = getattr(Y, "index", None)
|
|
111
|
+
if ix is None or iy is None:
|
|
112
|
+
return Y
|
|
113
|
+
if (not ix.is_unique or not iy.is_unique
|
|
114
|
+
or set(ix) != set(iy)):
|
|
115
|
+
raise ValueError("the sample names (index) of `X` and `Y` must be "
|
|
116
|
+
"unique and identical")
|
|
117
|
+
return Y.loc[ix]
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def triger(X, Y, lambda1=1.5, lambda2=1.5, lambda3=1.5, X_size=(10, 200),
|
|
121
|
+
Y_size=(10, 200), method="pearson", **kwargs) -> TrigerResult:
|
|
122
|
+
"""Detect cross-omics modules with TriGer.
|
|
123
|
+
|
|
124
|
+
Runs the TriGer pipeline on two omics layers measured on the same
|
|
125
|
+
samples. :func:`association_matrices` computes the cross- and
|
|
126
|
+
within-omics correlations and their -log10 p-values, and
|
|
127
|
+
:func:`triger.greedy_3step` finds blocks of X and Y features that are
|
|
128
|
+
densely associated across the two layers and refines large blocks by
|
|
129
|
+
within-omics peeling.
|
|
130
|
+
|
|
131
|
+
When X and Y are both pandas DataFrames, samples are matched by index
|
|
132
|
+
and Y is reordered to the sample order of X. Otherwise, the samples must
|
|
133
|
+
be in the same order.
|
|
134
|
+
|
|
135
|
+
Parameters
|
|
136
|
+
----------
|
|
137
|
+
X, Y : array_like or pandas.DataFrame
|
|
138
|
+
The two omics layers, samples in rows and features in columns.
|
|
139
|
+
lambda1 : float
|
|
140
|
+
Cross-omics size penalty (step 1). Higher values give smaller,
|
|
141
|
+
denser blocks.
|
|
142
|
+
lambda2, lambda3 : float
|
|
143
|
+
Within-omics size penalties for X and Y (steps 2 and 3).
|
|
144
|
+
X_size, Y_size : (min, max)
|
|
145
|
+
Passed to :func:`triger.greedy_3step`: blocks with ``min`` or fewer
|
|
146
|
+
features on either side are dropped, and sides with more than
|
|
147
|
+
``max`` features are refined.
|
|
148
|
+
method : {"pearson", "spearman"}
|
|
149
|
+
Correlation coefficient.
|
|
150
|
+
**kwargs
|
|
151
|
+
Further arguments to :func:`triger.greedy_3step`:
|
|
152
|
+
``min_community_size``, ``keep_unrefined_if_empty``, ``max_blocks``.
|
|
153
|
+
|
|
154
|
+
Returns
|
|
155
|
+
-------
|
|
156
|
+
TrigerResult
|
|
157
|
+
``modules``, a list of :class:`Module` records with indices into
|
|
158
|
+
the features of X and Y and their names, and the association
|
|
159
|
+
matrices ``R``, ``P``, ``names``, ``m`` and ``n``.
|
|
160
|
+
"""
|
|
161
|
+
Y = _match_samples(X, Y)
|
|
162
|
+
assoc = association_matrices(X, Y, method=method)
|
|
163
|
+
m, n = assoc.m, assoc.n
|
|
164
|
+
blocks = greedy_3step(assoc.P, assoc.R, m, n, lambda1=lambda1,
|
|
165
|
+
lambda2=lambda2, lambda3=lambda3, X_size=X_size,
|
|
166
|
+
Y_size=Y_size, **kwargs)
|
|
167
|
+
x_names, y_names = assoc.names[:m], assoc.names[m:]
|
|
168
|
+
modules = [Module(b.X, b.Y, b.density, [x_names[i] for i in b.X],
|
|
169
|
+
[y_names[j] for j in b.Y]) for b in blocks]
|
|
170
|
+
return TrigerResult(modules, *assoc)
|