gin-multiomics 0.2.0__tar.gz

gin_multiomics-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GINv3 authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gin_multiomics-0.2.0/NOTICE.md

@@ -0,0 +1,18 @@
+# Third-party data notices
+
+This package redistributes **derived** network and omics artifacts for manuscript
+reproduction. Upstream licenses and attribution remain with the source databases:
+
+- **GIN** bipartite prior (`data/GINv3.11a.sifi.gz`, default toolkit prior) —
+  original GIN / lab build lineage; do not treat as a re-license of source
+  pathway DBs.
+- **ENCODE / Roadmap** chromHMM emissions and related weights under
+  `runtime/chromhmm/` — follow ENCODE / Roadmap terms of use.
+- **ChIP-Atlas / related TF evidence** summarized as H1 allowlists under
+  `runtime/chip_gin_align/` — not raw peak beds; cite ChIP-Atlas / original
+  experiments as appropriate.
+- Cell-line RNA / metabolite place levels under `runtime/omics_seed/` — derived
+  expression features used for SigPN seeding.
+
+Code under `gin_tool/` and `scbionet/spn/` is MIT (see `LICENSE`) unless a file
+header states otherwise.

gin_multiomics-0.2.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: gin-multiomics
+Version: 0.2.0
+Summary: Global Integrative Network (GIN) multi-omics toolkit: context extraction and SigPN (signaling Petri net; not stochastic PN), with GINv3.11a p53 recipes
+Author-email: Chi Xu <chix@big.ac.cn>
+Maintainer-email: Chi Xu <chix@big.ac.cn>
+License: MIT
+Project-URL: Homepage, https://github.com/BIGchix/GINv3-publication
+Project-URL: Repository, https://github.com/BIGchix/GINv3-publication
+Project-URL: Issues, https://github.com/BIGchix/GINv3-publication/issues
+Project-URL: Changelog, https://github.com/BIGchix/GINv3-publication/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/BIGchix/GINv3-publication/blob/main/docs/USER_GUIDE.md
+Keywords: GIN,Global Integrative Network,multi-omics,systems biology,signaling,Petri net,SigPN,p53,context subgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.11
+Requires-Dist: networkx>=3.2
+Provides-Extra: sim
+Requires-Dist: pandas>=2.0; extra == "sim"
+Requires-Dist: matplotlib>=3.8; extra == "sim"
+Requires-Dist: seaborn>=0.13; extra == "sim"
+Requires-Dist: scikit-learn>=1.3; extra == "sim"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pandas>=2.0; extra == "dev"
+Requires-Dist: matplotlib>=3.8; extra == "dev"
+Requires-Dist: seaborn>=0.13; extra == "dev"
+Requires-Dist: scikit-learn>=1.3; extra == "dev"
+Dynamic: license-file
+
+# GINv3-publication
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+Multi-omics **Global Integrative Network (GIN)** context extraction and **SigPN**
+(**signaling** Petri net — not stochastic PN) simulation for mechanism-oriented
+analyses. This repository is the manuscript **Code Availability** package:
+an installable toolkit (`gin-multiomics`) plus a recipe that **recomputes** the
+p53 / GINv3.11a publication numbers.
+
+The GIN prior ships as **`data/GINv3.11a.sifi.gz`** (~75 MB). The toolkit and
+publication recipe read it **directly** — no unpack step is required.
+
+---
+
+## Citation
+
+Upon publication, please cite the accompanying paper (title / journal / DOI to
+be updated here). Until then, cite this repository and the manuscript that
+points to it under Code Availability.
+
+---
+
+## Overview
+
+- Extract a **mechanistic context** subgraph from the GINv3 prior given gene
+  (or GIN node) seeds.
+- Optionally prune TF→promoter edges with a **cell-specific ChIP allowlist**
+  to obtain a cell-line network.
+- Run **SigPN** Monte-Carlo simulations for signaling interventions.
+- **Recompute** the manuscript Stage A / prune / Pulse pipeline and assert
+  against published fingerprints (locks under `docs/locks/`).
+
+---
+
+## Requirements
+
+| Item | Notes |
+|------|--------|
+| OS | Linux recommended for bit-identical Stage A; macOS works for toolkit use |
+| Python | ≥ 3.9 |
+| Disk | Bundled `data/GINv3.11a.sifi.gz` (~75 MB) |
+| RAM / CPU | Context with `--context-n-jobs 20` is cluster-scale; small demos run on a laptop |
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/BIGchix/GINv3-publication.git
+cd GINv3-publication
+python3 -m venv .venv && source .venv/bin/activate
+pip install -U pip && pip install -e ".[sim]"
+export PYTHONHASHSEED=0
+python scripts/reproduce_publication.py --steps prepare
+# → verifies data/GINv3.11a.sifi.gz (sha256 f9bb23c4…)
+```
+
+After install, the CLI is available as:
+
+```bash
+python -m gin_tool.cli -h
+# or: gin-multiomics -h
+```
+
+Default `--sifi` is `data/GINv3.11a.sifi.gz` (included in the clone).
+Standalone download (Release does not attach the ~75 MB asset):
+[raw v0.2.0](https://github.com/BIGchix/GINv3-publication/raw/v0.2.0/data/GINv3.11a.sifi.gz)
+· [data/README.md](data/README.md). More detail:
+[docs/USER_GUIDE.md](docs/USER_GUIDE.md).
+
+---
+
+## Quick start
+
+**1. Context subgraph** (default prior = compressed GIN):
+
+```bash
+python -m gin_tool.cli \
+  --seeds "TP53,MDM2,CDKN1A" \
+  --out-dir gin_out/my_context \
+  --context-mech-depth 2 \
+  --context-n-jobs 8 \
+  --node-list-dir ./nodeList \
+  --no-debias
+# → gin_out/my_context/subgraph_edges.tsv
+```
+
+```bash
+bash examples/01_custom_context.sh
+```
+
+**2. SigPN demo** (bundled toy network; **no** GIN prior required):
+
+```bash
+bash examples/03_sigpn_demo.sh
+# → gin_out/example_sigpn_demo/spn.graphml
+# → gin_out/example_sigpn_demo/spn_sim_demo/…
+```
+
+See [examples/](examples/) for more scripts.
+
+---
+
+## Workflow
+
+```text
+seeds + data/GINv3.11a.sifi.gz
+        │
+        ▼
+  context subgraph  ──►  (optional) ChIP prune  ──►  SigPN simulation
+```
+
+1. **Context** — seeds + GIN prior → mechanistic neighborhood (`python -m gin_tool.cli`).
+2. **Cell prune** (optional) — ChIP allowlist → cell-specific edges
+   ([docs/CHIP_ALLOWLIST.md](docs/CHIP_ALLOWLIST.md)).
+3. **SigPN** — export the Petri net and run Monte-Carlo (demo below). The
+   manuscript H1 B0 Pulse is a special-case intervention script; for other
+   designs reuse the same engine
+   ([docs/SIGPN_CUSTOM_SIMULATIONS.md](docs/SIGPN_CUSTOM_SIMULATIONS.md)).
+
+### From subgraph to SigPN (executable demo)
+
+Bundled toy data under `examples/demo_sigpn/` (TP53 / MDM2 / CDKN1A edges
+excerpted from the publication H1-pruned network). Laptop-scale defaults:
+`runs=2`, `blocks=10`.
+
+```bash
+# One-liner
+bash examples/03_sigpn_demo.sh
+
+# Equivalent explicit steps
+mkdir -p gin_out/example_sigpn_demo
+cp examples/demo_sigpn/subgraph_edges.tsv gin_out/example_sigpn_demo/
+cp examples/demo_sigpn/place_levels.tsv   gin_out/example_sigpn_demo/
+
+python examples/run_sigpn_demo.py \
+  --subgraph-dir gin_out/example_sigpn_demo \
+  --place-levels gin_out/example_sigpn_demo/place_levels.tsv \
+  --chromhmm-emission-tsv runtime/chromhmm/panel_emissions/h1_wa01_E003_promoter_emission.tsv \
+  --runs 2 \
+  --blocks 10 \
+  --seed 0
+```
+
+On your own context (after CLI or prune), point `--subgraph-dir` at a folder
+that contains `subgraph_edges.tsv` (and optionally `place_levels.tsv`).
+
+---
+
+## Reproduce manuscript results
+
+Recompute the publication pipeline (prior stays compressed throughout):
+
+```bash
+export PYTHONHASHSEED=0
+python scripts/reproduce_publication.py --steps prepare
+python scripts/reproduce_publication.py --steps stage_a --n-jobs 20
+python scripts/assert_p53_pub_gin11a_lock.py
+
+# Full pipeline (cluster-scale: prune + Pulse, etc.)
+python scripts/reproduce_publication.py --steps all --n-jobs 20
+```
+
+Stage A lock target: **11,368** edges (details in `docs/locks/`).  
+`expected/` is for **assert / CI**, not the primary reproduction path.  
+Platform notes (e.g. Linux freeze host vs macOS): see
+[docs/experiments/p53_stageA_server_vs_mac_repro_20261014.md](docs/experiments/p53_stageA_server_vs_mac_repro_20261014.md)
+and the step-by-step guide [REPRODUCE.md](REPRODUCE.md).
+
+---
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | Getting started for custom analyses |
+| [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) | Recommended CLI options |
+| [docs/CHIP_ALLOWLIST.md](docs/CHIP_ALLOWLIST.md) | Cell ChIP allowlist format and use |
+| [docs/SIGPN_CUSTOM_SIMULATIONS.md](docs/SIGPN_CUSTOM_SIMULATIONS.md) | SigPN reuse; Pulse as a special case |
+| [REPRODUCE.md](REPRODUCE.md) | Full manuscript recompute recipe |
+| [MANIFEST.md](MANIFEST.md) | Package contents checklist |
+
+---
+
+## Repository layout
+
+| Path | Role |
+|------|------|
+| `gin_tool/` | Context / HME / dogma / SigPN CLI |
+| `scbionet/spn/` | Vendored SigPN engine |
+| `data/GINv3.11a.sifi.gz` | Frozen GIN prior (default `--sifi`) |
+| `nodeList/` · `seedLists/` | Layer lists and seeds |
+| `runtime/chip_gin_align/` | Example H1 allowlist |
+| `runtime/omics_seed/` · `runtime/chromhmm/` | Example place levels / emissions |
+| `examples/` | Context / Stage A / SigPN demos (`demo_sigpn/` toy data) |
+| `scripts/reproduce_publication.py` | Manuscript driver (recomputes) |
+| `expected/` | Gold fingerprints for assert |
+| `docs/` | Guides, locks, experiment notes |
+
+Historical path prefixes such as `runtime/spn_phys5/` still mean **SigPN**.
+
+---
+
+## License
+
+MIT for code (see [LICENSE](LICENSE)). Network and omics artifacts: see
+[NOTICE.md](NOTICE.md).
+
+---
+
+## Contact
+
+- Email: [chix@big.ac.cn](mailto:chix@big.ac.cn)
+- GitHub Issues on this repository (once published under Code Availability)

gin_multiomics-0.2.0/README.md

@@ -0,0 +1,216 @@
+# GINv3-publication
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+Multi-omics **Global Integrative Network (GIN)** context extraction and **SigPN**
+(**signaling** Petri net — not stochastic PN) simulation for mechanism-oriented
+analyses. This repository is the manuscript **Code Availability** package:
+an installable toolkit (`gin-multiomics`) plus a recipe that **recomputes** the
+p53 / GINv3.11a publication numbers.
+
+The GIN prior ships as **`data/GINv3.11a.sifi.gz`** (~75 MB). The toolkit and
+publication recipe read it **directly** — no unpack step is required.
+
+---
+
+## Citation
+
+Upon publication, please cite the accompanying paper (title / journal / DOI to
+be updated here). Until then, cite this repository and the manuscript that
+points to it under Code Availability.
+
+---
+
+## Overview
+
+- Extract a **mechanistic context** subgraph from the GINv3 prior given gene
+  (or GIN node) seeds.
+- Optionally prune TF→promoter edges with a **cell-specific ChIP allowlist**
+  to obtain a cell-line network.
+- Run **SigPN** Monte-Carlo simulations for signaling interventions.
+- **Recompute** the manuscript Stage A / prune / Pulse pipeline and assert
+  against published fingerprints (locks under `docs/locks/`).
+
+---
+
+## Requirements
+
+| Item | Notes |
+|------|--------|
+| OS | Linux recommended for bit-identical Stage A; macOS works for toolkit use |
+| Python | ≥ 3.9 |
+| Disk | Bundled `data/GINv3.11a.sifi.gz` (~75 MB) |
+| RAM / CPU | Context with `--context-n-jobs 20` is cluster-scale; small demos run on a laptop |
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/BIGchix/GINv3-publication.git
+cd GINv3-publication
+python3 -m venv .venv && source .venv/bin/activate
+pip install -U pip && pip install -e ".[sim]"
+export PYTHONHASHSEED=0
+python scripts/reproduce_publication.py --steps prepare
+# → verifies data/GINv3.11a.sifi.gz (sha256 f9bb23c4…)
+```
+
+After install, the CLI is available as:
+
+```bash
+python -m gin_tool.cli -h
+# or: gin-multiomics -h
+```
+
+Default `--sifi` is `data/GINv3.11a.sifi.gz` (included in the clone).
+Standalone download (Release does not attach the ~75 MB asset):
+[raw v0.2.0](https://github.com/BIGchix/GINv3-publication/raw/v0.2.0/data/GINv3.11a.sifi.gz)
+· [data/README.md](data/README.md). More detail:
+[docs/USER_GUIDE.md](docs/USER_GUIDE.md).
+
+---
+
+## Quick start
+
+**1. Context subgraph** (default prior = compressed GIN):
+
+```bash
+python -m gin_tool.cli \
+  --seeds "TP53,MDM2,CDKN1A" \
+  --out-dir gin_out/my_context \
+  --context-mech-depth 2 \
+  --context-n-jobs 8 \
+  --node-list-dir ./nodeList \
+  --no-debias
+# → gin_out/my_context/subgraph_edges.tsv
+```
+
+```bash
+bash examples/01_custom_context.sh
+```
+
+**2. SigPN demo** (bundled toy network; **no** GIN prior required):
+
+```bash
+bash examples/03_sigpn_demo.sh
+# → gin_out/example_sigpn_demo/spn.graphml
+# → gin_out/example_sigpn_demo/spn_sim_demo/…
+```
+
+See [examples/](examples/) for more scripts.
+
+---
+
+## Workflow
+
+```text
+seeds + data/GINv3.11a.sifi.gz
+        │
+        ▼
+  context subgraph  ──►  (optional) ChIP prune  ──►  SigPN simulation
+```
+
+1. **Context** — seeds + GIN prior → mechanistic neighborhood (`python -m gin_tool.cli`).
+2. **Cell prune** (optional) — ChIP allowlist → cell-specific edges
+   ([docs/CHIP_ALLOWLIST.md](docs/CHIP_ALLOWLIST.md)).
+3. **SigPN** — export the Petri net and run Monte-Carlo (demo below). The
+   manuscript H1 B0 Pulse is a special-case intervention script; for other
+   designs reuse the same engine
+   ([docs/SIGPN_CUSTOM_SIMULATIONS.md](docs/SIGPN_CUSTOM_SIMULATIONS.md)).
+
+### From subgraph to SigPN (executable demo)
+
+Bundled toy data under `examples/demo_sigpn/` (TP53 / MDM2 / CDKN1A edges
+excerpted from the publication H1-pruned network). Laptop-scale defaults:
+`runs=2`, `blocks=10`.
+
+```bash
+# One-liner
+bash examples/03_sigpn_demo.sh
+
+# Equivalent explicit steps
+mkdir -p gin_out/example_sigpn_demo
+cp examples/demo_sigpn/subgraph_edges.tsv gin_out/example_sigpn_demo/
+cp examples/demo_sigpn/place_levels.tsv   gin_out/example_sigpn_demo/
+
+python examples/run_sigpn_demo.py \
+  --subgraph-dir gin_out/example_sigpn_demo \
+  --place-levels gin_out/example_sigpn_demo/place_levels.tsv \
+  --chromhmm-emission-tsv runtime/chromhmm/panel_emissions/h1_wa01_E003_promoter_emission.tsv \
+  --runs 2 \
+  --blocks 10 \
+  --seed 0
+```
+
+On your own context (after CLI or prune), point `--subgraph-dir` at a folder
+that contains `subgraph_edges.tsv` (and optionally `place_levels.tsv`).
+
+---
+
+## Reproduce manuscript results
+
+Recompute the publication pipeline (prior stays compressed throughout):
+
+```bash
+export PYTHONHASHSEED=0
+python scripts/reproduce_publication.py --steps prepare
+python scripts/reproduce_publication.py --steps stage_a --n-jobs 20
+python scripts/assert_p53_pub_gin11a_lock.py
+
+# Full pipeline (cluster-scale: prune + Pulse, etc.)
+python scripts/reproduce_publication.py --steps all --n-jobs 20
+```
+
+Stage A lock target: **11,368** edges (details in `docs/locks/`).  
+`expected/` is for **assert / CI**, not the primary reproduction path.  
+Platform notes (e.g. Linux freeze host vs macOS): see
+[docs/experiments/p53_stageA_server_vs_mac_repro_20261014.md](docs/experiments/p53_stageA_server_vs_mac_repro_20261014.md)
+and the step-by-step guide [REPRODUCE.md](REPRODUCE.md).
+
+---
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | Getting started for custom analyses |
+| [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) | Recommended CLI options |
+| [docs/CHIP_ALLOWLIST.md](docs/CHIP_ALLOWLIST.md) | Cell ChIP allowlist format and use |
+| [docs/SIGPN_CUSTOM_SIMULATIONS.md](docs/SIGPN_CUSTOM_SIMULATIONS.md) | SigPN reuse; Pulse as a special case |
+| [REPRODUCE.md](REPRODUCE.md) | Full manuscript recompute recipe |
+| [MANIFEST.md](MANIFEST.md) | Package contents checklist |
+
+---
+
+## Repository layout
+
+| Path | Role |
+|------|------|
+| `gin_tool/` | Context / HME / dogma / SigPN CLI |
+| `scbionet/spn/` | Vendored SigPN engine |
+| `data/GINv3.11a.sifi.gz` | Frozen GIN prior (default `--sifi`) |
+| `nodeList/` · `seedLists/` | Layer lists and seeds |
+| `runtime/chip_gin_align/` | Example H1 allowlist |
+| `runtime/omics_seed/` · `runtime/chromhmm/` | Example place levels / emissions |
+| `examples/` | Context / Stage A / SigPN demos (`demo_sigpn/` toy data) |
+| `scripts/reproduce_publication.py` | Manuscript driver (recomputes) |
+| `expected/` | Gold fingerprints for assert |
+| `docs/` | Guides, locks, experiment notes |
+
+Historical path prefixes such as `runtime/spn_phys5/` still mean **SigPN**.
+
+---
+
+## License
+
+MIT for code (see [LICENSE](LICENSE)). Network and omics artifacts: see
+[NOTICE.md](NOTICE.md).
+
+---
+
+## Contact
+
+- Email: [chix@big.ac.cn](mailto:chix@big.ac.cn)
+- GitHub Issues on this repository (once published under Code Availability)