Metadata-Version: 2.4
Name: isograph
Version: 0.1.4
Summary: A Python framework for discovering isoform-switch and splicing modules from bulk RNA-seq by combining gene-local compositional modeling with splice-graph-aware latent network inference.
License: Apache License
                                    Version 2.0, January 2004
                                 http://www.apache.org/licenses/
         
            TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
         
            1. Definitions.
         
               "License" shall mean the terms and conditions for use, reproduction,
               and distribution as defined by Sections 1 through 9 of this document.
         
               "Licensor" shall mean the copyright owner or entity authorized by
               the copyright owner that is granting the License.
         
               "Legal Entity" shall mean the union of the acting entity and all
               other entities that control, are controlled by, or are under common
               control with that entity. For the purposes of this definition,
               "control" means (i) the power, direct or indirect, to cause the
               direction or management of such entity, whether by contract or
               otherwise, or (ii) ownership of fifty percent (50%) or more of the
               outstanding shares, or (iii) beneficial ownership of such entity.
         
               "You" (or "Your") shall mean an individual or Legal Entity
               exercising permissions granted by this License.
         
               "Source" form shall mean the preferred form for making modifications,
               including but not limited to software source code, documentation
               source, and configuration files.
         
               "Object" form shall mean any form resulting from mechanical
               transformation or translation of a Source form, including but
               not limited to compiled object code, generated documentation,
               and conversions to other media types.
         
               "Work" shall mean the work of authorship made available under
               the License, as indicated by a copyright notice that is included in
               or attached to the work (an example is provided in the Appendix below).
         
               "Derivative Works" shall mean any work, whether in Source or Object
               form, that is based on (or derived from) the Work and for which the
               editorial revisions, annotations, elaborations, or other modifications
               represent, as a whole, an original work of authorship. For the purposes
               of this License, Derivative Works shall not include works that remain
               separable from, or merely link (or bind by name) to the interfaces of,
               the Work and Derivative Works thereof.
         
               "Contribution" shall mean, as submitted to the Licensor for inclusion
               in the Work by the copyright owner or by an individual or Legal Entity
               authorized to submit on behalf to the Licensor, the copyright owner.
         
               "Contributor" shall mean Licensor and any Legal Entity on behalf of
               whom a Contribution has been received by the Licensor and included
               within the Work.
         
            2. Grant of Copyright License. Subject to the terms and conditions of
               this License, each Contributor hereby grants to You a perpetual,
               worldwide, non-exclusive, no-charge, royalty-free, irrevocable
               copyright license to reproduce, prepare Derivative Works of,
               publicly display, publicly perform, sublicense, and distribute the
               Work and such Derivative Works in Source or Object form.
         
            3. Grant of Patent License. Subject to the terms and conditions of
               this License, each Contributor hereby grants to You a perpetual,
               worldwide, non-exclusive, no-charge, royalty-free, irrevocable
               (except as stated in this section) patent license to make, have made,
               use, offer to sell, sell, import, and otherwise transfer the Work,
               where such license applies only to those patent claims licensable
               by such Contributor that are necessarily infringed by their
               Contribution(s) alone or by the combination of their Contributions
               with the Work to which such Contributions were submitted. If You
               institute patent litigation against any entity (including a
               cross-claim or counterclaim in a lawsuit) alleging that the Work
               or a Contribution incorporated within the Work constitutes direct
               or contributory patent infringement, then any patent licenses
               granted to You under this License for that Work shall terminate
               as of the date such litigation is filed.
         
            4. Redistribution. You may reproduce and distribute copies of the
               Work or Derivative Works thereof in any medium, with or without
               modifications, and in Source or Object form, provided that You
               meet the following conditions:
         
               (a) You must give any other recipients of the Work or Derivative
                   Works a copy of this License; and
         
               (b) You must cause any modified files to carry prominent notices
                   stating that You changed the files; and
         
               (c) You must retain, in the Source form of any Derivative Works
                   that You distribute, all copyright, patent, trademark, and
                   attribution notices from the Source form of the Work,
                   excluding those notices that do not pertain to any part of
                   the Derivative Works; and
         
               (d) If the Work includes a "NOTICE" text file, as part of the
                   distribution, You must include a readable copy of the
                   attribution notices contained within such NOTICE file, in
                   at least one of the following places: within a NOTICE text
                   file distributed as part of the Derivative Works; within
                   the Source form or documentation, if provided along with the
                   Derivative Works; or, within a display generated by the
                   Derivative Works, if and wherever such third-party notices
                   normally appear. The contents of the NOTICE file are for
                   informational purposes only and do not modify the License.
                   You may add Your own attribution notices within Derivative
                   Works that You distribute, alongside or in addition to the
                   NOTICE text from the Work, provided that such additional
                   attribution notices cannot be construed as modifying the License.
         
               You may add Your own license statement for Your modifications and
               may provide additional grant of rights to use, copy, modify, merge,
               publish, distribute, sublicense, and/or sell copies of the
               Contribution.
         
            5. Submission of Contributions. Unless You explicitly state otherwise,
               any Contribution intentionally submitted for inclusion in the Work
               by You to the Licensor shall be under the terms and conditions of
               this License, without any additional terms or conditions.
               Notwithstanding the above, nothing herein shall supersede or modify
               the terms of any separate license agreement you may have executed
               with Licensor regarding such Contributions.
         
            6. Trademarks. This License does not grant permission to use the trade
               names, trademarks, service marks, or product names of the Licensor,
               except as required for reasonable and customary use in describing the
               origin of the Work and reproducing the content of the NOTICE file.
         
            7. Disclaimer of Warranty. Unless required by applicable law or
               agreed to in writing, Licensor provides the Work (and each
               Contributor provides its Contributions) on an "AS IS" BASIS,
               WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
               implied, including, without limitation, any conditions of TITLE,
               NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
               PURPOSE. You are solely responsible for determining the
               appropriateness of using or reproducing the Work and assume any
               risks associated with Your exercise of permissions under this License.
         
            8. Limitation of Liability. In no event and under no legal theory,
               whether in tort (including negligence), contract, or otherwise,
               unless required by applicable law (such as deliberate and grossly
               negligent acts) or agreed to in writing, shall any Contributor be
               liable to You for damages, including any direct, indirect, special,
               incidental, or exemplary damages of any character arising as a
               result of this License or out of the use or inability to use the
               Work (even if such Contributor has been advised of the possibility
               of such damages).
         
            9. Accepting Warranty or Additional Liability. While redistributing
               the Work or Derivative Works thereof, You may choose to offer,
               and charge a fee for, acceptance of support, warranty, indemnity,
               or other liability obligations and/or rights consistent with this
               License. However, in accepting such obligations, You may offer only
               conditions consistent with this License.
         
            END OF TERMS AND CONDITIONS
         
            Copyright 2024-2026 Kynon J Benjamin
         
            Licensed under the Apache License, Version 2.0 (the "License");
            you may not use this file except in compliance with the License.
            You may obtain a copy of the License at
         
                http://www.apache.org/licenses/LICENSE-2.0
         
            Unless required by applicable law or agreed to in writing, software
            distributed under the License is distributed on an "AS IS" BASIS,
            WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
            See the License for the specific language governing permissions and
            limitations under the License.
License-File: LICENSE
License-File: LICENSE-DATA
Keywords: RNA-seq,isoform switching,splicing,co-expression,network inference,bioinformatics,transcriptomics,vae
Author: Kynon J Benjamin
Author-email: kj.benjamin90@gmail.com
Requires-Python: >=3.11,<3.15
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: torch-explain
Requires-Dist: PyYAML (>=6,<7)
Requires-Dist: captum (>=0.7) ; extra == "torch-explain"
Requires-Dist: hydra-core (>=1.3,<2)
Requires-Dist: hypothesis (>=6.112,<7) ; extra == "dev"
Requires-Dist: matplotlib (>=3.5,<4)
Requires-Dist: mlflow-skinny (>=2.16,<3) ; extra == "dev"
Requires-Dist: mpmath (>=1.3,<2)
Requires-Dist: myst-parser (>=3,<4) ; extra == "docs"
Requires-Dist: networkx (>=3.3,<4)
Requires-Dist: numpy (>=1.26,<3)
Requires-Dist: pandas (>=2.2,<3)
Requires-Dist: patsy (>=0.5,<1)
Requires-Dist: pyarrow (>=17,<25)
Requires-Dist: pydantic (>=2.8,<3)
Requires-Dist: pytest (>=8.3,<9) ; extra == "dev"
Requires-Dist: scikit-learn (>=1.5,<2)
Requires-Dist: scipy (>=1.13,<2)
Requires-Dist: sphinx (>=7,<8) ; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints (>=2,<3) ; extra == "docs"
Requires-Dist: sphinx-rtd-theme (>=3,<4) ; extra == "docs"
Project-URL: Bug Tracker, https://github.com/heart-gen/IsoGraph/issues
Project-URL: Documentation, https://isograph.readthedocs.io/en/latest/
Project-URL: Homepage, https://github.com/heart-gen/IsoGraph
Project-URL: Repository, https://github.com/heart-gen/IsoGraph
Description-Content-Type: text/markdown

# IsoGraph

IsoGraph discovers co-regulated transcript programs from bulk RNA-seq by treating gene
abundance and isoform switching as separate channels in a multiplex network. Starting
from transcript-level counts, it builds gene-local switch coordinates from compositional
transcript usage and a standardized abundance signal per gene, infers sparse gene-module
structure via a VAE or linear backend, classifies each module gene by the channel driving
its membership (switching, abundance, coupled, or discordant), and links modules to
phenotypic traits. All steps are benchmark-validated and reproducible.

## Core Capabilities

- **Multiplex network inference** — builds a typed feature graph with separate abundance
  and switch channels per gene, calibrated edge thresholds, and gene channel role
  classification (`coupled`, `switch_only`, `abundance_only`, `discordant`).
- **Five interchangeable backends** — `baseline`, `latent`, `graph`, `vae` (default),
  and `wgcna`; all support multiplex mode and the full benchmark suite.
- **Benchmark validation** — three fixture suites: `core_v1` (24–800 genes),
  `scale_v1` (6k–12k genes), and `multiplex_v1` (typed abundance + switch ground truth).
  An optional `xxlarge_multiplex_v1` fixture (12k genes, 240 samples) tests at full scale.
- **Module explanation** — `isograph explain-module` produces gene driver tables,
  transcript polarity tables, high-vs-low contrasts, publication-ready PDF plots, optional
  VAE decoder attribution, and Captum Integrated Gradients encoder attribution.
- **Structural annotation** — `isograph annotate-structure` labels switch pairs with
  GTF-derived exon, CDS/UTR, biotype, and coding-status changes.
- **Reproducibility** — fixture-driven, seed-controlled, version-locked YAML configs;
  compact JSON reports as durable evidence; real-data freeze via `freeze-real`.

## Installation

Install the core package from PyPI:

```bash
pip install isograph
```

The core package supports Python `3.11` through `3.14`.

### Optional backends

IsoGraph installs `mpmath`, which is required by modern SymPy releases. The
`vae` backend also requires PyTorch, but PyTorch is intentionally not installed
by IsoGraph because CPU/GPU/CUDA builds are platform-specific. Install the build
that matches your system before using it:

```bash
pip install torch
```

See the [PyTorch installation guide](https://pytorch.org/get-started/locally/) for
GPU/CUDA builds.

The `wgcna` backend requires R with the `WGCNA` package and `Rscript` on `PATH`.

## Quickstart

### Step 1 — Validate on bundled fixtures

Run the multiplex benchmark on the toy fixture to confirm your installation (VAE default,
~2 minutes):

```bash
isograph benchmark --config-name stage9_multiplex_vae \
  -- fixture_filter=toy_multiplex_v1 stage_name=readme_smoke
```

This writes artifacts under `artifacts/benchmarks/readme_smoke/toy_multiplex_v1/` and
a JSON report under `artifacts/reports/`, including overall recovery and role-aware
recall (`switch_only`, `abundance_only`, `coupled`, `discordant`).

Run all four backends on the full multiplex suite:

```bash
isograph benchmark --config-name stage9_multiplex_vae
isograph benchmark --config-name stage9_multiplex_graph
isograph benchmark --config-name stage9_multiplex_latent
isograph benchmark --config-name stage9_multiplex_wgcna
```

The optional 12k-gene stress fixture:

```bash
isograph benchmark --config-name stress_multiplex_xxlarge_vae
isograph benchmark --config-name stress_multiplex_xxlarge_wgcna
```

### Step 2 — Fit your own data

IsoGraph expects a prepared dataset bundle with a `manifest.json`, sample metadata,
feature tables, and count matrices. Providing a `gene_counts` matrix activates the
abundance channel alongside the isoform-switch channel.

```bash
isograph fit \
  --dataset-path path/to/my_dataset_bundle \
  --output-dir artifacts/fits/my_dataset
```

With tuning overrides (all after `--`):

```bash
isograph fit \
  --dataset-path path/to/my_dataset_bundle \
  --backend vae \
  --output-dir artifacts/fits/my_dataset_vae \
  -- vae.hidden_dim=256 vae.latent_dim=8 vae.n_epochs=500 \
     vae.alpha=0.70 vae.alpha_switch=0.70 \
     vae.alpha_abundance_grid="[0.60,0.65,0.70,0.75,0.80,0.85,0.90]"
```

**What you get:**

| File | Contents |
|---|---|
| `modules.parquet` | Module assignments per gene |
| `edges.parquet` | Inferred gene-gene edges with weights |
| `traits.parquet` | Module–trait associations and p values |
| `feature_scores.parquet` | Per-gene switch and abundance scores with `feature_type` column |
| `module_gene_roles.parquet` | Per-gene role: `coupled`, `switch_only`, `abundance_only`, `discordant` |

### Step 3 — Explain modules

```bash
isograph explain-module \
  --artifact-dir artifacts/fits/my_dataset \
  --feature-table path/to/feature_scores.parquet \
  --feature-meta path/to/transcript_table.parquet \
  --module-ids M000 M001 \
  --plot --output-format pdf \
  --output-dir artifacts/explain/my_dataset
```

Produces gene driver tables, transcript polarity tables, high-vs-low contrasts, and
publication-ready PDF plots per module.

The detailed walkthroughs live in the Wiki, and the formal data model is documented
in the RTD source tree.

## Documentation

- Details on all of the functions lives in the Read the Docs 
  [API](https://isograph.readthedocs.io/en/latest/).
- Step-by-step tutorials for installation, data preparation, and own-data workflows live
  in the [GitHub Wiki](https://github.com/heart-gen/IsoGraph/wiki).

## Citation

If you use IsoGraph in research, cite the software repository using the metadata in
[CITATION.cff](CITATION.cff). If a manuscript or preprint becomes available later, that
can be added as a preferred citation target without changing the software citation path.

## Acknowledgements

IsoGraph is supported by the National Institute on Minority Health and Health Disparities
award `R00 MD0169640` and the Alzheimer's Association award `25AARG-1413315`.

## Reproducibility and Data Provenance

- The benchmark suite is fixture-driven and designed to preserve regression targets across
  development stages.
- The bundled real-data workflow freezes a reproducible `real_caudate_aa_v1` dataset from
  BrainSEQ-derived inputs and caches intermediate selections under
  `benchmarks/cache/real_data/`.
- Benchmark, calibration, runtime, and snapshot artifacts are written into versioned
  directories under `artifacts/` and `snapshots/`.
- Bulky generated benchmark directories and dataset bundles are ignored by git. Commit
  durable benchmark evidence as compact JSON reports under `artifacts/reports/`.

## Limitations

- The benchmark CLI is optimized for the bundled fixture suite rather than arbitrary
  user-defined suites.
- The VAE backend requires a separate PyTorch installation.
- The WGCNA backend requires R with the `WGCNA` package installed.
- The `freeze-real` workflow depends on BrainSEQ-style source files and is not a
  generic data-ingestion command for arbitrary cohorts.
- VAE decoder attribution (`--vae-attribution`) and Captum Integrated Gradients
  (`--integrated-gradients`) require a VAE checkpoint in the fit artifact directory and,
  for Integrated Gradients, `pip install isograph[torch-explain]`.

