pyhuge 0.2.1__tar.gz

pyhuge-0.2.1/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## 0.2.1
+
+- Fix CI e2e runtime dependency installation by installing `Rcpp`, `RcppEigen`, and `igraph` in `R_LIBS_USER`.
+- Make e2e pass criteria robust to pytest output formatting changes.
+- Migrate rpy2 conversion calls to `get_conversion()` API to avoid deprecation warnings.
+- Decouple docs build from `rpy2`/R runtime requirements and restrict docs deploy to the upstream repository.
+- Update repository/documentation links and docs deployment target to `Gatech-Flash/huge`.
+
+
+## 0.2.0
+
+- Prepare first publish-ready `pyhuge` release line.
+- Reframe repository and package documentation to cover both R (`huge`) and Python (`pyhuge`) variants.
+- Add `docs/man/` function manual pages (one page per public API), analogous to R `man/` lookup style.
+- Add docs website deployment workflow (`python-package-docs`) and integrate manual pages into MkDocs navigation.
+- Add runtime readiness helper `pyhuge.test(require_runtime=...)` and corresponding public API tests.
+- Add packaging metadata and manifest improvements for release/distribution (`MANIFEST.in`, project URLs, include-package-data).
+- Keep Python test matrix and optional R-runtime e2e path aligned with current wrapper scope.
+
+
+## 0.1.0
+
+- Initial Python wrapper package `pyhuge`.
+- Implemented APIs:
+  - `huge`
+  - `huge_mb`
+  - `huge_glasso`
+  - `huge_ct`
+  - `huge_tiger`
+  - `huge_select`
+  - `huge_npn`
+  - `huge_generator`
+  - `huge_inference`
+  - `huge_roc`
+- Added utility APIs:
+  - `huge_summary`
+  - `huge_select_summary`
+  - `huge_plot_sparsity`
+  - `huge_plot_roc`
+  - `huge_plot_graph_matrix`
+  - `huge_plot_network`
+  - `test` (runtime readiness probe)
+- Added strict argument validation with clear `PyHugeError` messages.
+- Expanded optional end-to-end tests (`tests/test_e2e_optional.py`) to cover:
+  - method wrappers (`mb`, `ct`, `tiger`, `glasso`)
+  - model selection (`ric`, `stars`, `ebic`)
+  - `huge_npn`, `huge_generator`, `huge_roc`, `huge_inference`
+  - summary helpers and network plotting
+- Added CI split:
+  - `unit` matrix job (pure Python tests)
+  - `e2e-r-runtime` job (R+rpy2 integration tests)
+- Added Python package release automation:
+  - `scripts/bump_version.py`
+  - `scripts/build_dist.sh`
+  - `scripts/release.sh`
+  - `.github/workflows/python-package-release.yml`
+- Added Python docs website workflow:
+  - `.github/workflows/python-package-docs.yml`
+  - strict MkDocs build and GitHub Pages deployment
+- Added result dataclasses:
+  - `HugeResult`
+  - `HugeSelectResult`
+- Added MkDocs documentation set, including release process and architecture troubleshooting.
+- Added docs pages for tutorials, performance notes, citation, and changelog index.
+- Added `docs/man/` function manual pages (one page per public API function), analogous to R `man/` style lookup.
+- Added packaging support files:
+  - `MANIFEST.in`
+  - Python package `.gitignore`
+- Added examples and pytest test suite.

pyhuge-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing (Python Wrapper)
+
+## Local setup
+
+```bash
+cd python-package
+pip install -e ".[dev]"
+```
+
+## Run tests
+
+```bash
+pytest
+```
+
+## Run end-to-end tests with local R runtime
+
+```bash
+export R_LIBS_USER=/Users/tourzhao/Desktop/huge-master/.Rlib
+R CMD INSTALL /Users/tourzhao/Desktop/huge-master
+pytest tests/test_e2e_optional.py -rA
+```
+
+## Run docs locally
+
+```bash
+mkdocs serve
+```
+
+## Validate docs build (CI-equivalent)
+
+```bash
+mkdocs build --strict
+```
+
+## Build wheel/sdist for release
+
+```bash
+bash scripts/build_dist.sh
+```
+
+## Bump version and prepare release
+
+```bash
+python scripts/bump_version.py 0.2.0
+bash scripts/release.sh 0.2.0
+```
+
+## CI workflows
+
+- Tests: `.github/workflows/python-wrapper-tests.yml`
+- Docs website: `.github/workflows/python-package-docs.yml`
+- Package release: `.github/workflows/python-package-release.yml`
+
+## Code principles
+
+- Keep public API aligned with R package semantics.
+- Preserve backward compatibility in result fields.
+- Convert graph outputs to SciPy sparse matrices when possible.
+- Keep `raw` R objects available for advanced users.

pyhuge-0.2.1/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include scripts *.py *.sh
+recursive-include tests *.py
+recursive-include pyhuge *.py
+global-exclude __pycache__ *.py[cod]

pyhuge-0.2.1/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: pyhuge
+Version: 0.2.1
+Summary: Python wrapper for the R package huge
+Author-email: Tuo Zhao <tourzhao@gatech.edu>
+License: GPL-2.0-only
+Project-URL: Homepage, https://github.com/Gatech-Flash/huge
+Project-URL: Repository, https://github.com/Gatech-Flash/huge
+Project-URL: Documentation, https://gatech-flash.github.io/huge/
+Project-URL: Issues, https://github.com/Gatech-Flash/huge/issues
+Project-URL: Changelog, https://github.com/Gatech-Flash/huge/blob/master/python-package/CHANGELOG.md
+Keywords: graphical-model,graphical-lasso,sparse,statistics,rpy2
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Requires-Dist: rpy2>=3.5
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: matplotlib>=3.8; extra == "dev"
+Requires-Dist: networkx>=3.2; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Requires-Dist: mkdocs>=1.5; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5; extra == "dev"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == "viz"
+Requires-Dist: networkx>=3.2; extra == "viz"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.1; extra == "release"
+
+# pyhuge Python Package
+
+[![Python wrapper tests](https://github.com/Gatech-Flash/huge/actions/workflows/python-wrapper-tests.yml/badge.svg)](https://github.com/Gatech-Flash/huge/actions/workflows/python-wrapper-tests.yml)
+[![Python docs](https://github.com/Gatech-Flash/huge/actions/workflows/python-package-docs.yml/badge.svg)](https://github.com/Gatech-Flash/huge/actions/workflows/python-package-docs.yml)
+[![Python package release](https://github.com/Gatech-Flash/huge/actions/workflows/python-package-release.yml/badge.svg)](https://github.com/Gatech-Flash/huge/actions/workflows/python-package-release.yml)
+
+`pyhuge` is the Python wrapper for the
+[`huge`](https://cran.r-project.org/package=huge) package:
+High-dimensional Undirected Graph Estimation.
+
+## Table of contents
+
+- [Background](#background)
+- [Directory structure](#directory-structure)
+- [What this package provides](#what-this-package-provides)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Documentation and tutorials](#documentation-and-tutorials)
+- [Performance notes](#performance-notes)
+- [Implemented APIs](#implemented-apis)
+- [For developer](#for-developer)
+- [Citation](#citation)
+- [References](#references)
+
+## Background
+
+`huge` is widely used for sparse undirected graphical model estimation in high dimensions.
+`pyhuge` keeps the original R/C++ backend and exposes a Python API via `rpy2` so Python users can:
+
+- call the same core methods (`mb`, `glasso`, `ct`, `tiger`);
+- run model selection (`ric`, `stars`, `ebic`);
+- access simulation, ROC, and inference helpers;
+- work with `numpy` and `scipy.sparse` objects directly.
+
+## Directory structure
+
+The Python package directory is organized as:
+
+- `pyhuge/`: Python wrapper source code
+- `tests/`: unit/runtime/e2e tests
+- `examples/`: runnable scripts
+- `docs/`: MkDocs documentation pages
+- `scripts/`: release and docs build scripts
+
+## What this package provides
+
+- Thin and stable bridge to mature `huge` backend.
+- Argument validation with explicit `PyHugeError` messages.
+- Typed result objects.
+- Plot helpers including node-edge network visualization (`huge_plot_network`).
+- Tests, documentation website workflow, and release automation scripts.
+
+## Requirements
+
+- Python `>=3.9`
+- R installed and available in PATH
+- R package `huge` installed (with `Rcpp`, `RcppEigen`, `igraph`, etc.)
+- Python and R architecture must match (both `arm64` or both `x86_64`)
+
+## Installation
+
+Install from source:
+
+```bash
+git clone https://github.com/Gatech-Flash/huge.git
+cd huge/python-package
+pip install -e .
+```
+
+Install directly from GitHub:
+
+```bash
+pip install "git+https://github.com/Gatech-Flash/huge.git#subdirectory=python-package"
+```
+
+Optional extras:
+
+```bash
+pip install -e ".[viz]"      # matplotlib + networkx
+pip install -e ".[release]"  # build + twine
+pip install -e ".[dev]"      # test + docs + release deps
+```
+
+Runtime check:
+
+```bash
+python -c "import pyhuge; print(pyhuge.test())"
+```
+
+If `runtime=False`, verify `R_LIBS_USER`, architecture match, and `huge` visibility in R.
+
+## Usage
+
+```python
+import numpy as np
+from pyhuge import huge, huge_npn, huge_select
+
+rng = np.random.default_rng(1)
+x = rng.normal(size=(120, 30))
+x_npn = huge_npn(x, npn_func="shrinkage", verbose=False)
+
+fit = huge(x_npn, method="mb", nlambda=8, verbose=False)
+sel = huge_select(fit, criterion="ric", verbose=False)
+print(fit.method, len(fit.path), sel.opt_lambda, sel.opt_sparsity)
+```
+
+Network visualization:
+
+```python
+import matplotlib.pyplot as plt
+from pyhuge import huge_plot_network
+
+fig, ax = plt.subplots(figsize=(5, 5))
+huge_plot_network(fit, index=-1, ax=ax, layout="spring")
+plt.show()
+```
+
+## Documentation and tutorials
+
+- Website: <https://gatech-flash.github.io/huge/>
+- Docs source: `python-package/docs`
+- Function manual directory: `python-package/docs/man` (R `man/`-style layout)
+- Tutorial scripts: `python-package/examples`
+
+Build docs locally:
+
+```bash
+cd python-package
+mkdocs serve
+```
+
+Run tutorials/examples:
+
+```bash
+cd python-package
+python examples/run_huge_mb.py
+python examples/run_summary_and_plot.py
+python examples/run_network_plot.py
+```
+
+If you use custom R library path:
+
+```bash
+R_LIBS_USER=/Users/tourzhao/Desktop/huge-master/.Rlib \
+python examples/run_huge_mb.py
+```
+
+## Performance notes
+
+`pyhuge` runtime is dominated by R backend solve time for medium/large problems.
+For many tiny repeated calls, Python-R bridge overhead can matter.
+Benchmark backend and end-to-end workflows separately when tuning performance.
+
+## Implemented APIs
+
+- `huge`, `huge_mb`, `huge_glasso`, `huge_ct`, `huge_tiger`
+- `huge_select`, `huge_npn`
+- `huge_generator`, `huge_inference`, `huge_roc`
+- `huge_summary`, `huge_select_summary`
+- `huge_plot_sparsity`, `huge_plot_roc`, `huge_plot_graph_matrix`, `huge_plot_network`
+- `test`
+
+## For developer
+
+```bash
+cd python-package
+pip install -e ".[dev]"
+pytest
+mkdocs build --strict
+bash scripts/build_docs.sh
+bash scripts/build_dist.sh
+```
+
+Optional e2e run with local R runtime:
+
+```bash
+export R_LIBS_USER=/Users/tourzhao/Desktop/huge-master/.Rlib
+export PYHUGE_REQUIRE_RUNTIME=1
+pytest tests/test_e2e_optional.py -rA
+```
+
+Workflows:
+
+- `.github/workflows/python-wrapper-tests.yml`
+- `.github/workflows/python-package-docs.yml`
+- `.github/workflows/python-package-release.yml`
+
+## Citation
+
+If you use `huge` / `pyhuge` in research, cite:
+
+```bibtex
+@article{zhao2012huge,
+  title   = {The huge Package for High-dimensional Undirected Graph Estimation in R},
+  author  = {Zhao, Tuo and Liu, Han and Roeder, Kathryn and Lafferty, John and Wasserman, Larry},
+  journal = {Journal of Machine Learning Research},
+  volume  = {13},
+  pages   = {1059--1062},
+  year    = {2012}
+}
+```
+
+## References
+
+- T. Zhao, H. Liu, K. Roeder, J. Lafferty, and L. Wasserman,
+  *The huge Package for High-dimensional Undirected Graph Estimation in R*,
+  JMLR 13:1059-1062, 2012.
+- Huge CRAN page: <https://cran.r-project.org/package=huge>
+- Repository: <https://github.com/Gatech-Flash/huge>

pyhuge-0.2.1/README.md

@@ -0,0 +1,210 @@
+# pyhuge Python Package
+
+[![Python wrapper tests](https://github.com/Gatech-Flash/huge/actions/workflows/python-wrapper-tests.yml/badge.svg)](https://github.com/Gatech-Flash/huge/actions/workflows/python-wrapper-tests.yml)
+[![Python docs](https://github.com/Gatech-Flash/huge/actions/workflows/python-package-docs.yml/badge.svg)](https://github.com/Gatech-Flash/huge/actions/workflows/python-package-docs.yml)
+[![Python package release](https://github.com/Gatech-Flash/huge/actions/workflows/python-package-release.yml/badge.svg)](https://github.com/Gatech-Flash/huge/actions/workflows/python-package-release.yml)
+
+`pyhuge` is the Python wrapper for the
+[`huge`](https://cran.r-project.org/package=huge) package:
+High-dimensional Undirected Graph Estimation.
+
+## Table of contents
+
+- [Background](#background)
+- [Directory structure](#directory-structure)
+- [What this package provides](#what-this-package-provides)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Documentation and tutorials](#documentation-and-tutorials)
+- [Performance notes](#performance-notes)
+- [Implemented APIs](#implemented-apis)
+- [For developer](#for-developer)
+- [Citation](#citation)
+- [References](#references)
+
+## Background
+
+`huge` is widely used for sparse undirected graphical model estimation in high dimensions.
+`pyhuge` keeps the original R/C++ backend and exposes a Python API via `rpy2` so Python users can:
+
+- call the same core methods (`mb`, `glasso`, `ct`, `tiger`);
+- run model selection (`ric`, `stars`, `ebic`);
+- access simulation, ROC, and inference helpers;
+- work with `numpy` and `scipy.sparse` objects directly.
+
+## Directory structure
+
+The Python package directory is organized as:
+
+- `pyhuge/`: Python wrapper source code
+- `tests/`: unit/runtime/e2e tests
+- `examples/`: runnable scripts
+- `docs/`: MkDocs documentation pages
+- `scripts/`: release and docs build scripts
+
+## What this package provides
+
+- Thin and stable bridge to mature `huge` backend.
+- Argument validation with explicit `PyHugeError` messages.
+- Typed result objects.
+- Plot helpers including node-edge network visualization (`huge_plot_network`).
+- Tests, documentation website workflow, and release automation scripts.
+
+## Requirements
+
+- Python `>=3.9`
+- R installed and available in PATH
+- R package `huge` installed (with `Rcpp`, `RcppEigen`, `igraph`, etc.)
+- Python and R architecture must match (both `arm64` or both `x86_64`)
+
+## Installation
+
+Install from source:
+
+```bash
+git clone https://github.com/Gatech-Flash/huge.git
+cd huge/python-package
+pip install -e .
+```
+
+Install directly from GitHub:
+
+```bash
+pip install "git+https://github.com/Gatech-Flash/huge.git#subdirectory=python-package"
+```
+
+Optional extras:
+
+```bash
+pip install -e ".[viz]"      # matplotlib + networkx
+pip install -e ".[release]"  # build + twine
+pip install -e ".[dev]"      # test + docs + release deps
+```
+
+Runtime check:
+
+```bash
+python -c "import pyhuge; print(pyhuge.test())"
+```
+
+If `runtime=False`, verify `R_LIBS_USER`, architecture match, and `huge` visibility in R.
+
+## Usage
+
+```python
+import numpy as np
+from pyhuge import huge, huge_npn, huge_select
+
+rng = np.random.default_rng(1)
+x = rng.normal(size=(120, 30))
+x_npn = huge_npn(x, npn_func="shrinkage", verbose=False)
+
+fit = huge(x_npn, method="mb", nlambda=8, verbose=False)
+sel = huge_select(fit, criterion="ric", verbose=False)
+print(fit.method, len(fit.path), sel.opt_lambda, sel.opt_sparsity)
+```
+
+Network visualization:
+
+```python
+import matplotlib.pyplot as plt
+from pyhuge import huge_plot_network
+
+fig, ax = plt.subplots(figsize=(5, 5))
+huge_plot_network(fit, index=-1, ax=ax, layout="spring")
+plt.show()
+```
+
+## Documentation and tutorials
+
+- Website: <https://gatech-flash.github.io/huge/>
+- Docs source: `python-package/docs`
+- Function manual directory: `python-package/docs/man` (R `man/`-style layout)
+- Tutorial scripts: `python-package/examples`
+
+Build docs locally:
+
+```bash
+cd python-package
+mkdocs serve
+```
+
+Run tutorials/examples:
+
+```bash
+cd python-package
+python examples/run_huge_mb.py
+python examples/run_summary_and_plot.py
+python examples/run_network_plot.py
+```
+
+If you use custom R library path:
+
+```bash
+R_LIBS_USER=/Users/tourzhao/Desktop/huge-master/.Rlib \
+python examples/run_huge_mb.py
+```
+
+## Performance notes
+
+`pyhuge` runtime is dominated by R backend solve time for medium/large problems.
+For many tiny repeated calls, Python-R bridge overhead can matter.
+Benchmark backend and end-to-end workflows separately when tuning performance.
+
+## Implemented APIs
+
+- `huge`, `huge_mb`, `huge_glasso`, `huge_ct`, `huge_tiger`
+- `huge_select`, `huge_npn`
+- `huge_generator`, `huge_inference`, `huge_roc`
+- `huge_summary`, `huge_select_summary`
+- `huge_plot_sparsity`, `huge_plot_roc`, `huge_plot_graph_matrix`, `huge_plot_network`
+- `test`
+
+## For developer
+
+```bash
+cd python-package
+pip install -e ".[dev]"
+pytest
+mkdocs build --strict
+bash scripts/build_docs.sh
+bash scripts/build_dist.sh
+```
+
+Optional e2e run with local R runtime:
+
+```bash
+export R_LIBS_USER=/Users/tourzhao/Desktop/huge-master/.Rlib
+export PYHUGE_REQUIRE_RUNTIME=1
+pytest tests/test_e2e_optional.py -rA
+```
+
+Workflows:
+
+- `.github/workflows/python-wrapper-tests.yml`
+- `.github/workflows/python-package-docs.yml`
+- `.github/workflows/python-package-release.yml`
+
+## Citation
+
+If you use `huge` / `pyhuge` in research, cite:
+
+```bibtex
+@article{zhao2012huge,
+  title   = {The huge Package for High-dimensional Undirected Graph Estimation in R},
+  author  = {Zhao, Tuo and Liu, Han and Roeder, Kathryn and Lafferty, John and Wasserman, Larry},
+  journal = {Journal of Machine Learning Research},
+  volume  = {13},
+  pages   = {1059--1062},
+  year    = {2012}
+}
+```
+
+## References
+
+- T. Zhao, H. Liu, K. Roeder, J. Lafferty, and L. Wasserman,
+  *The huge Package for High-dimensional Undirected Graph Estimation in R*,
+  JMLR 13:1059-1062, 2012.
+- Huge CRAN page: <https://cran.r-project.org/package=huge>
+- Repository: <https://github.com/Gatech-Flash/huge>