svemnet 0.1.0__tar.gz

svemnet-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "17 6 3 * *" # monthly canary against latest deps
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[test]"
+      - name: Test
+        run: python -m pytest tests -q

svemnet-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release to PyPI
+
+# Releasing is: git tag v0.1.0 && git push origin v0.1.0
+# Requires a PyPI "trusted publisher" configured for this repository and a
+# GitHub environment named "pypi" (see RELEASING.md).
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

svemnet-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.coverage
+htmlcov/
+.ipynb_checkpoints/
+validation/output/

svemnet-0.1.0/CITATION.cff

@@ -0,0 +1,47 @@
+cff-version: 1.2.0
+message: >-
+  If you use this software, please cite the SVEMnet paper (preferred
+  citation below) for the software and Lemkus et al. (2021) for the SVEM
+  method.
+type: software
+title: "svemnet: Self-Validated Ensemble Models (SVEM) for Python"
+authors:
+  - family-names: Karl
+    given-names: Andrew T.
+    email: akarl@asu.edu
+    orcid: "https://orcid.org/0000-0002-5933-8706"
+license: MIT
+repository-code: "https://github.com/akarl46556/svemnet-python"
+keywords:
+  - SVEM
+  - self-validated ensemble models
+  - design of experiments
+  - lasso
+  - elastic net
+  - forward selection
+  - chemometrics
+preferred-citation:
+  type: article
+  title: "SVEMnet: Self-Validated Ensemble Models in R"
+  authors:
+    - family-names: Karl
+      given-names: Andrew T.
+  journal: "Chemometrics and Intelligent Laboratory Systems"
+  year: 2026
+  doi: 10.1016/j.chemolab.2026.105660
+references:
+  - type: article
+    title: "Self-Validated Ensemble Models for design of experiments"
+    authors:
+      - family-names: Lemkus
+        given-names: Trent
+      - family-names: Gotwalt
+        given-names: Christopher
+      - family-names: Ramsey
+        given-names: Philip
+      - family-names: Weese
+        given-names: Maria L.
+    journal: "Chemometrics and Intelligent Laboratory Systems"
+    volume: 219
+    year: 2021
+    doi: 10.1016/j.chemolab.2021.104439

svemnet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew T. Karl
+
+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.

svemnet-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: svemnet
+Version: 0.1.0
+Summary: Self-Validated Ensemble Models (SVEM) for small-sample design-of-experiments regression: SVEM lasso / elastic net and SVEM forward selection with validation-weighted information criteria.
+Project-URL: Homepage, https://github.com/akarl46556/svemnet-python
+Project-URL: Source, https://github.com/akarl46556/svemnet-python
+Project-URL: Issues, https://github.com/akarl46556/svemnet-python/issues
+Project-URL: R package (CRAN), https://CRAN.R-project.org/package=SVEMnet
+Project-URL: SVEMnet paper (Karl 2026), https://doi.org/10.1016/j.chemolab.2026.105660
+Project-URL: SVEM method paper (Lemkus 2021), https://doi.org/10.1016/j.chemolab.2021.104439
+Project-URL: Whole-model test (Karl 2024), https://doi.org/10.1016/j.chemolab.2024.105122
+Author-email: "Andrew T. Karl" <akarl@asu.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: DOE,JMP,SVEM,SVEMnet,chemometrics,design of experiments,elastic net,forward selection,fractional random weights,lasso,self-validated ensemble,small sample
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.6
+Provides-Extra: formula
+Requires-Dist: formulaic>=1.1; extra == 'formula'
+Requires-Dist: pandas>=2.0; extra == 'formula'
+Provides-Extra: test
+Requires-Dist: formulaic>=1.1; extra == 'test'
+Requires-Dist: pandas>=2.0; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# svemnet — Self-Validated Ensemble Models (SVEM) for Python
+
+**SVEM regression for small-sample design of experiments (DOE):** lasso /
+elastic-net and forward-selection ensembles tuned by validation-weighted
+information criteria, with bootstrap prediction intervals.
+
+`svemnet` is the Python implementation of the Self-Validated Ensemble Model
+method (Lemkus, Gotwalt, Ramsey, and Weese 2021) by the author of the
+[R package SVEMnet](https://CRAN.R-project.org/package=SVEMnet). SVEM is
+designed for the small-*n*, wide-model regime typical of designed
+experiments — mixture formulations, process optimization, chemometrics —
+where cross-validation is unstable: instead of holding data out, every run
+appears in *both* the training and validation roles through anti-correlated
+fractional random weights, and predictions are ensembled across bootstrap
+replicates.
+
+## Install
+
+```bash
+pip install svemnet            # core: numpy + scikit-learn
+pip install "svemnet[formula]" # + R-style formula interface (formulaic, pandas)
+```
+
+## Quickstart (formula interface, closest to R / JMP)
+
+```python
+import pandas as pd
+import svemnet
+
+df = pd.read_csv("experiment.csv")  # columns: y, X1, X2, X3, ...
+
+# SVEM with lasso / elastic-net base learners (the SVEMnet default)
+model = svemnet.svem("y ~ (X1 + X2 + X3)**2 + I(X1**2)", df, seed=1)
+preds = model.predict(new_df)
+
+# SVEM with forward-selection base learners
+model = svemnet.svem("y ~ (X1 + X2 + X3)**2", df, method="forward", seed=1)
+model.selection_frequencies          # per-term bootstrap selection rates
+model.coef_table()                   # coefficients + % bootstraps nonzero
+
+# Bootstrap percentile intervals
+out = model.predict(new_df, interval=True, level=0.90)
+out["fit"], out["lwr"], out["upr"]
+
+# Deterministic forward selection by AICc (single-model benchmark)
+bench = svemnet.forward_aicc("y ~ (X1 + X2 + X3)**2", df)
+bench.selected_terms
+```
+
+Categorical predictors: mark them as pandas `Categorical` (or leave them as
+strings) and they are treatment-coded automatically, like R factors. Their
+contrast columns enter and leave forward-selection paths **together** as
+whole effects.
+
+`(X1 + X2 + X3)**2` expands to main effects plus two-way interactions,
+matching R's `(X1 + X2 + X3)^2`. The helper
+`svemnet.response_surface_formula("y", continuous=["X1","X2"], nominal=["F"])`
+builds standard response-surface formulas.
+
+## Quickstart (scikit-learn interface)
+
+```python
+from svemnet import SVEMRegressor
+
+est = SVEMRegressor(method="forward", n_boot=200, random_state=0)
+est.fit(X, y)                        # numeric matrix, no intercept column
+y_pred = est.predict(X_new)
+y_pred, intervals = est.predict_interval(X_new, confidence_level=0.9)
+```
+
+`SVEMRegressor` is a conformant scikit-learn estimator: it works in
+`Pipeline`, `cross_val_score`, and `GridSearchCV`, and handles categoricals
+the scikit-learn way (`ColumnTransformer` / `OneHotEncoder`).
+
+## Coming from R SVEMnet or JMP
+
+| R SVEMnet | svemnet (Python) |
+|---|---|
+| `SVEMnet(y ~ ..., data)` | `svemnet.svem("y ~ ...", df)` |
+| `svem_forward(y ~ ..., data)` | `svemnet.svem("y ~ ...", df, method="forward")` |
+| `forward_aicc(y ~ ..., data)` | `svemnet.forward_aicc("y ~ ...", df)` |
+| `predict(fit, newdata, se.fit=, interval=)` | `model.predict(new_df, se_fit=, interval=)` |
+| `coef(fit)` / `svem_nonzero(fit)` | `model.coef_table()` |
+| `bigexp_terms(...)` | `svemnet.response_surface_formula(...)` |
+| `objective = "wAIC"/"wBIC"/"wSSE"` | same |
+| `weight_scheme = "SVEM"/"FRW_plain"/"Identity"` | same |
+| `debias = TRUE` at predict | `debias=True` at fit or predict |
+
+The Gaussian fitting mathematics match the published SVEM conventions used
+by the R package: anti-correlated FRW train/validation weights rescaled to
+mean one, validation-weighted wSSE/wAIC/wBIC path selection with the Kish
+effective-sample-size admissibility guardrail, intercept-only fallback,
+coefficient averaging across the ensemble, and optional linear debiasing.
+The forward-selection engines here and the R functions `forward_aicc()` /
+`svem_forward()` (SVEMnet ≥ 3.5.0) are ports of the same reference
+implementation and validate against each other numerically. The lasso /
+elastic-net base learners use scikit-learn's coordinate descent rather than
+glmnet, so individual path fits can differ slightly in lambda gridding;
+ensemble predictions agree closely in practice.
+
+**Scope.** This package is intentionally minimal: Gaussian responses,
+lasso/elastic-net and forward-selection base learners, prediction with
+bootstrap uncertainty. For binomial responses, whole-model significance
+testing, mixture-constrained random-search optimization, and
+Thompson-sampling batch design, use the
+[R package SVEMnet](https://CRAN.R-project.org/package=SVEMnet); JMP Pro
+users have SVEM built into Generalized Regression.
+
+## References
+
+- Lemkus, T., Gotwalt, C., Ramsey, P., & Weese, M. L. (2021). Self-Validated
+  Ensemble Models for design of experiments. *Chemometrics and Intelligent
+  Laboratory Systems*, 219, 104439.
+  [doi:10.1016/j.chemolab.2021.104439](https://doi.org/10.1016/j.chemolab.2021.104439)
+- Karl, A. T. (2024). A randomized permutation whole-model test for SVEM.
+  *Chemometrics and Intelligent Laboratory Systems*, 249, 105122.
+  [doi:10.1016/j.chemolab.2024.105122](https://doi.org/10.1016/j.chemolab.2024.105122)
+- Karl, A. T. (2026). SVEMnet: Self-Validated Ensemble Models in R.
+  *Chemometrics and Intelligent Laboratory Systems*.
+  [doi:10.1016/j.chemolab.2026.105660](https://doi.org/10.1016/j.chemolab.2026.105660)
+- Xu, L., Gotwalt, C., Hong, Y., King, C. B., & Meeker, W. Q. (2020).
+  Applications of the fractional-random-weight bootstrap. *The American
+  Statistician*, 74(4), 345–358.
+  [doi:10.1080/00031305.2020.1731599](https://doi.org/10.1080/00031305.2020.1731599)
+
+If you use this package in published work, please cite Lemkus et al. (2021)
+for the method and Karl (2026) for the software.
+
+## License
+
+MIT. Copyright (c) 2026 Andrew T. Karl.

svemnet-0.1.0/README.md

@@ -0,0 +1,131 @@
+# svemnet — Self-Validated Ensemble Models (SVEM) for Python
+
+**SVEM regression for small-sample design of experiments (DOE):** lasso /
+elastic-net and forward-selection ensembles tuned by validation-weighted
+information criteria, with bootstrap prediction intervals.
+
+`svemnet` is the Python implementation of the Self-Validated Ensemble Model
+method (Lemkus, Gotwalt, Ramsey, and Weese 2021) by the author of the
+[R package SVEMnet](https://CRAN.R-project.org/package=SVEMnet). SVEM is
+designed for the small-*n*, wide-model regime typical of designed
+experiments — mixture formulations, process optimization, chemometrics —
+where cross-validation is unstable: instead of holding data out, every run
+appears in *both* the training and validation roles through anti-correlated
+fractional random weights, and predictions are ensembled across bootstrap
+replicates.
+
+## Install
+
+```bash
+pip install svemnet            # core: numpy + scikit-learn
+pip install "svemnet[formula]" # + R-style formula interface (formulaic, pandas)
+```
+
+## Quickstart (formula interface, closest to R / JMP)
+
+```python
+import pandas as pd
+import svemnet
+
+df = pd.read_csv("experiment.csv")  # columns: y, X1, X2, X3, ...
+
+# SVEM with lasso / elastic-net base learners (the SVEMnet default)
+model = svemnet.svem("y ~ (X1 + X2 + X3)**2 + I(X1**2)", df, seed=1)
+preds = model.predict(new_df)
+
+# SVEM with forward-selection base learners
+model = svemnet.svem("y ~ (X1 + X2 + X3)**2", df, method="forward", seed=1)
+model.selection_frequencies          # per-term bootstrap selection rates
+model.coef_table()                   # coefficients + % bootstraps nonzero
+
+# Bootstrap percentile intervals
+out = model.predict(new_df, interval=True, level=0.90)
+out["fit"], out["lwr"], out["upr"]
+
+# Deterministic forward selection by AICc (single-model benchmark)
+bench = svemnet.forward_aicc("y ~ (X1 + X2 + X3)**2", df)
+bench.selected_terms
+```
+
+Categorical predictors: mark them as pandas `Categorical` (or leave them as
+strings) and they are treatment-coded automatically, like R factors. Their
+contrast columns enter and leave forward-selection paths **together** as
+whole effects.
+
+`(X1 + X2 + X3)**2` expands to main effects plus two-way interactions,
+matching R's `(X1 + X2 + X3)^2`. The helper
+`svemnet.response_surface_formula("y", continuous=["X1","X2"], nominal=["F"])`
+builds standard response-surface formulas.
+
+## Quickstart (scikit-learn interface)
+
+```python
+from svemnet import SVEMRegressor
+
+est = SVEMRegressor(method="forward", n_boot=200, random_state=0)
+est.fit(X, y)                        # numeric matrix, no intercept column
+y_pred = est.predict(X_new)
+y_pred, intervals = est.predict_interval(X_new, confidence_level=0.9)
+```
+
+`SVEMRegressor` is a conformant scikit-learn estimator: it works in
+`Pipeline`, `cross_val_score`, and `GridSearchCV`, and handles categoricals
+the scikit-learn way (`ColumnTransformer` / `OneHotEncoder`).
+
+## Coming from R SVEMnet or JMP
+
+| R SVEMnet | svemnet (Python) |
+|---|---|
+| `SVEMnet(y ~ ..., data)` | `svemnet.svem("y ~ ...", df)` |
+| `svem_forward(y ~ ..., data)` | `svemnet.svem("y ~ ...", df, method="forward")` |
+| `forward_aicc(y ~ ..., data)` | `svemnet.forward_aicc("y ~ ...", df)` |
+| `predict(fit, newdata, se.fit=, interval=)` | `model.predict(new_df, se_fit=, interval=)` |
+| `coef(fit)` / `svem_nonzero(fit)` | `model.coef_table()` |
+| `bigexp_terms(...)` | `svemnet.response_surface_formula(...)` |
+| `objective = "wAIC"/"wBIC"/"wSSE"` | same |
+| `weight_scheme = "SVEM"/"FRW_plain"/"Identity"` | same |
+| `debias = TRUE` at predict | `debias=True` at fit or predict |
+
+The Gaussian fitting mathematics match the published SVEM conventions used
+by the R package: anti-correlated FRW train/validation weights rescaled to
+mean one, validation-weighted wSSE/wAIC/wBIC path selection with the Kish
+effective-sample-size admissibility guardrail, intercept-only fallback,
+coefficient averaging across the ensemble, and optional linear debiasing.
+The forward-selection engines here and the R functions `forward_aicc()` /
+`svem_forward()` (SVEMnet ≥ 3.5.0) are ports of the same reference
+implementation and validate against each other numerically. The lasso /
+elastic-net base learners use scikit-learn's coordinate descent rather than
+glmnet, so individual path fits can differ slightly in lambda gridding;
+ensemble predictions agree closely in practice.
+
+**Scope.** This package is intentionally minimal: Gaussian responses,
+lasso/elastic-net and forward-selection base learners, prediction with
+bootstrap uncertainty. For binomial responses, whole-model significance
+testing, mixture-constrained random-search optimization, and
+Thompson-sampling batch design, use the
+[R package SVEMnet](https://CRAN.R-project.org/package=SVEMnet); JMP Pro
+users have SVEM built into Generalized Regression.
+
+## References
+
+- Lemkus, T., Gotwalt, C., Ramsey, P., & Weese, M. L. (2021). Self-Validated
+  Ensemble Models for design of experiments. *Chemometrics and Intelligent
+  Laboratory Systems*, 219, 104439.
+  [doi:10.1016/j.chemolab.2021.104439](https://doi.org/10.1016/j.chemolab.2021.104439)
+- Karl, A. T. (2024). A randomized permutation whole-model test for SVEM.
+  *Chemometrics and Intelligent Laboratory Systems*, 249, 105122.
+  [doi:10.1016/j.chemolab.2024.105122](https://doi.org/10.1016/j.chemolab.2024.105122)
+- Karl, A. T. (2026). SVEMnet: Self-Validated Ensemble Models in R.
+  *Chemometrics and Intelligent Laboratory Systems*.
+  [doi:10.1016/j.chemolab.2026.105660](https://doi.org/10.1016/j.chemolab.2026.105660)
+- Xu, L., Gotwalt, C., Hong, Y., King, C. B., & Meeker, W. Q. (2020).
+  Applications of the fractional-random-weight bootstrap. *The American
+  Statistician*, 74(4), 345–358.
+  [doi:10.1080/00031305.2020.1731599](https://doi.org/10.1080/00031305.2020.1731599)
+
+If you use this package in published work, please cite Lemkus et al. (2021)
+for the method and Karl (2026) for the software.
+
+## License
+
+MIT. Copyright (c) 2026 Andrew T. Karl.

svemnet-0.1.0/RELEASING.md

@@ -0,0 +1,66 @@
+# Release checklist (for Andrew)
+
+One-time setup, then each release is just a git tag.
+
+## One-time setup
+
+1. **Create the GitHub repository** (suggested name: `svemnet-python`, owner:
+   your GitHub account). Then the URLs below already point at `akarl46556`:
+   - `pyproject.toml` (`[project.urls]`)
+   - `CITATION.cff` (`repository-code`)
+2. **Push this repo**:
+   ```bash
+   git remote add origin https://github.com/akarl46556/svemnet-python.git
+   git push -u origin main
+   ```
+   CI (`.github/workflows/ci.yml`) runs the test suite on Python 3.10–3.13
+   (Linux) and 3.13 (Windows) on every push to `main` and on every pull
+   request, plus a monthly cron canary against the latest
+   numpy/scikit-learn.
+3. **PyPI trusted publisher** (no API tokens needed):
+   - Create/log into your account on https://pypi.org.
+   - Go to *Your projects → Publishing → Add a new pending publisher* and
+     register: project name `svemnet`, owner `akarl46556`, repository
+     `svemnet-python`, workflow `release.yml`, environment `pypi`.
+   - In the GitHub repo: *Settings → Environments → New environment* named
+     `pypi` (optionally require your review before deployments).
+4. **Cross-link from the R package** (optional but recommended): add a line
+   to the CRAN SVEMnet DESCRIPTION/README pointing to
+   `https://pypi.org/project/svemnet/`.
+
+## Each release
+
+```bash
+# bump version in pyproject.toml and src/svemnet/__init__.py, commit, then:
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `release.yml` workflow builds the sdist/wheel and publishes to PyPI via
+trusted publishing.
+
+## Re-running the R cross-validation
+
+With the SVEMnet R package (>= 3.5.0) installed:
+
+```bash
+Rscript validation/run_r_reference.R validation/output
+python validation/compare_python.py validation/output
+```
+
+Tier 1 (deterministic forward selection) and Tier 2 (SVEM forward with
+injected FRW uniforms) must match R exactly; Tier 3 (lasso, cross-solver)
+is statistical. See `validation/output/VALIDATION_REPORT.md`.
+
+## Later milestones (optional, low urgency)
+
+- **conda-forge** (once the API feels stable): submit a grayskull-generated
+  recipe to conda-forge/staged-recipes; afterwards maintenance is merging
+  autotick-bot PRs.
+- **JOSS paper** (6–12 months out): JOSS requires ~6 months of public
+  development history and demonstrated reuse; a JOSS DOI gives Python users
+  a natural citation target.
+- **Scope guard**: the package is deliberately minimal (Gaussian; lasso/enet
+  + forward SVEM; prediction with bootstrap uncertainty). Point requests for
+  binomial, whole-model testing, optimization, etc. at the R package rather
+  than growing this one.