modelmatrix 0.1.0__tar.gz

modelmatrix-0.1.0/.github/workflows/build_docs.yml

@@ -0,0 +1,86 @@
+# This builds and deploys the modelmatrix docs
+
+name: Build docs
+
+on:
+  workflow_dispatch:
+    inputs: null
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0   # setuptools_scm takes the version from the tags
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      # Jupyter Book 2 (mystmd) runs on Node
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+
+      # Install
+      - name: Install dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y r-base
+          pip install .[doc]
+          # the data of the pages (ISLP's load_data, without its dependencies)
+          pip install --no-deps ISLP
+
+      # The narrative docs: Jupyter Book 2, notebooks executed.
+      # BASE_URL: the site is served from https://<owner>.github.io/modelmatrix/
+      - name: Make book
+        env:
+          BASE_URL: /${{ github.event.repository.name }}
+        run: |
+          cd docs
+          jupyter-book build --html --execute --ci
+          test -f _build/html/index.html
+
+      # The API reference: Sphinx autodoc, into api/ next to the book
+      - name: Make API reference
+        run: |
+          sphinx-build -b html docs/api docs/_build/html/api
+          test -f docs/_build/html/api/index.html
+
+      # Store the output
+      - name: Upload docs
+        uses: actions/upload-artifact@v7
+        with:
+          name: modelmatrix_docs
+          path: docs/_build/html
+          retention-days: 5
+          if-no-files-found: error
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+
+    steps:
+    - uses: actions/download-artifact@v8
+      with:
+        name: modelmatrix_docs
+        path: .
+    - uses: actions/configure-pages@v6
+
+    - uses: actions/upload-pages-artifact@v5
+      with:
+        path: .
+    - id: deployment
+      uses: actions/deploy-pages@v5

modelmatrix-0.1.0/.github/workflows/build_test.yml

@@ -0,0 +1,83 @@
+name: Build and test
+
+# Linux (Python 3.12) on pull requests, into any branch; on pushes to main
+# (merges) and by hand, macOS and Windows (3.12) and Linux at the oldest and
+# newest Pythons (3.11, 3.14), and the sdist and wheel build. The package is
+# pure Python, so this is enough. Changes only to the docs or Markdown files
+# do not run the tests.
+on:
+  push:
+    branches: [main]
+    paths-ignore: ['docs/**', '**.md']
+  pull_request:
+    paths-ignore: ['docs/**', '**.md']
+  workflow_dispatch:
+
+# a new push to a branch cancels the run still going for it
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: build (${{ matrix.os }}, ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include: >-
+          ${{ fromJSON(github.event_name == 'pull_request' && '[
+            {"os": "ubuntu-latest", "python-version": "3.12"}
+          ]' || '[
+            {"os": "windows-latest", "python-version": "3.12"},
+            {"os": "macos-latest", "python-version": "3.12"},
+            {"os": "ubuntu-latest", "python-version": "3.11"},
+            {"os": "ubuntu-latest", "python-version": "3.14"}
+          ]') }}
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0   # setuptools_scm takes the version from the tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install Project
+        run: uv sync --dev --python ${{ matrix.python-version }}
+
+      - name: Lint with flake8
+        run: |
+          uv run flake8 modelmatrix --count --select=E9,F63,F7,F82,W605 --show-source --statistics
+          uv run flake8 modelmatrix --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+      - name: Test with pytest
+        timeout-minutes: 10
+        shell: bash
+        run: |
+          args=()
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            args+=(--cov=modelmatrix --cov-report=term-missing)
+          fi
+          uv run pytest "${args[@]}"
+
+  build-dist:
+    # the sdist and wheel build, and the wheel installs and imports
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.3.0
+      - run: uv build
+      - run: |
+          uv venv -p 3.12 /tmp/venv
+          uv pip install -p /tmp/venv dist/*.whl
+          /tmp/venv/bin/python -c "import modelmatrix; print(modelmatrix.__version__)"

modelmatrix-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+modelmatrix/_version.py

modelmatrix-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 (2026-10-26)
+
+`ModelSpec`, from [ISLP](https://github.com/intro-stat-learning/ISLP) 0.6.0,
+as its own package, with the history of its files. ISLP 0.7 depends on it,
+and `from ISLP.models import ModelSpec` keeps working there.
+
+### Changes from ISLP 0.6.0
+
+- **`intercept` defaults to `False`:** pass `intercept=True` for a column
+  of ones named `'intercept'`, as statsmodels' models (`OLS`, `GLM`, ...)
+  need. Most scikit-learn estimators fit the intercept themselves.
+- No `FutureWarning` of the move.
+- Import from `modelmatrix` (`ModelSpec`, `Column`, `Feature`, `Contrast`,
+  `Ordinal`, `poly`, `ns`, `bs`, `pca`, `contrast`, `ordinal`,
+  `derived_feature`, `build_columns`); the transforms are in
+  `modelmatrix.transforms`.
+- The docs: the guide to `ModelSpec`, the pages on polynomials, splines,
+  PCA and ANOVA, and the comparison with `ColumnTransformer`, patsy and
+  formulaic, from ISLP's docs, as a Jupyter Book 2 site (as glmstar's),
+  with a Sphinx API reference.
+
+For the changes up to ISLP 0.6.0, see
+[ISLP's changelog](https://github.com/intro-stat-learning/ISLP/blob/main/CHANGELOG.md).
+
+Requires Python 3.11 or later.

modelmatrix-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    (1) Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer. 
+
+    (2) Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.  
+    
+    (3)The name of the author may not be used to
+    endorse or promote products derived from this software without
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE. 

modelmatrix-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: modelmatrix
+Version: 0.1.0
+Summary: Model matrices from tabular data, as scikit-learn transformers
+Author-email: Jonathan Taylor <jonathan.taylor@stanford.edu>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/intro-stat-learning/modelmatrix
+Project-URL: Documentation, https://intro-stat-learning.github.io/modelmatrix
+Project-URL: Changelog, https://github.com/intro-stat-learning/modelmatrix/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.7.1
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=0.9
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: narwhals>=1.26
+Requires-Dist: joblib
+Provides-Extra: doc
+Requires-Dist: jupyter-book<3,>=2; extra == "doc"
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: sphinx-book-theme; extra == "doc"
+Requires-Dist: statsmodels; extra == "doc"
+Requires-Dist: patsy; extra == "doc"
+Requires-Dist: formulaic; extra == "doc"
+Requires-Dist: polars; extra == "doc"
+Requires-Dist: rpy2; extra == "doc"
+Requires-Dist: jupytext; extra == "doc"
+Dynamic: license-file
+
+# modelmatrix
+
+Model matrices from tabular data, as scikit-learn transformers.
+
+`ModelSpec` builds a design matrix from a `pd.DataFrame` (or a polars or
+pyarrow frame, or an `np.ndarray`) from a list of terms: columns,
+categorical encodings, polynomials, splines, principal components and
+their interactions. It is a scikit-learn transformer, so it goes in a
+`Pipeline`, is cloned and cross-validated, and the parameters of its
+terms are tuned with `GridSearchCV`.
+
+```python
+from modelmatrix import ModelSpec, ns, poly
+from sklearn.linear_model import LinearRegression
+from sklearn.model_selection import GridSearchCV
+from sklearn.pipeline import make_pipeline
+
+spec = ModelSpec([ns('age', df=4), poly('year', 2), 'education',
+                  ('age', 'education')])
+X = spec.fit_transform(Wage)
+
+pipe = make_pipeline(spec, LinearRegression())
+grid = GridSearchCV(pipe, {'modelspec__terms__0__df': [2, 4, 8]})
+grid.fit(Wage, Wage['wage'])
+```
+
+`ModelSpec` was written for the labs of
+[An Introduction to Statistical Learning with Python](https://www.statlearning.com),
+and `from ISLP.models import ModelSpec` still works there.
+
+Documentation: https://intro-stat-learning.github.io/modelmatrix
+
+## Install
+
+```
+pip install modelmatrix
+```
+
+Requires Python 3.11 or later. BSD licensed.

modelmatrix-0.1.0/README.md

@@ -0,0 +1,39 @@
+# modelmatrix
+
+Model matrices from tabular data, as scikit-learn transformers.
+
+`ModelSpec` builds a design matrix from a `pd.DataFrame` (or a polars or
+pyarrow frame, or an `np.ndarray`) from a list of terms: columns,
+categorical encodings, polynomials, splines, principal components and
+their interactions. It is a scikit-learn transformer, so it goes in a
+`Pipeline`, is cloned and cross-validated, and the parameters of its
+terms are tuned with `GridSearchCV`.
+
+```python
+from modelmatrix import ModelSpec, ns, poly
+from sklearn.linear_model import LinearRegression
+from sklearn.model_selection import GridSearchCV
+from sklearn.pipeline import make_pipeline
+
+spec = ModelSpec([ns('age', df=4), poly('year', 2), 'education',
+                  ('age', 'education')])
+X = spec.fit_transform(Wage)
+
+pipe = make_pipeline(spec, LinearRegression())
+grid = GridSearchCV(pipe, {'modelspec__terms__0__df': [2, 4, 8]})
+grid.fit(Wage, Wage['wage'])
+```
+
+`ModelSpec` was written for the labs of
+[An Introduction to Statistical Learning with Python](https://www.statlearning.com),
+and `from ISLP.models import ModelSpec` still works there.
+
+Documentation: https://intro-stat-learning.github.io/modelmatrix
+
+## Install
+
+```
+pip install modelmatrix
+```
+
+Requires Python 3.11 or later. BSD licensed.

modelmatrix-0.1.0/docs/.gitignore

@@ -0,0 +1,2 @@
+# MyST build outputs
+_build

modelmatrix-0.1.0/docs/PCA.md

@@ -0,0 +1,97 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.19.6
+kernelspec:
+  display_name: python3
+  language: python
+  name: python3
+---
+
+# Derived features: using PCA on a subset of columns
+
+The modelling tools in `modelmatrix` allow for
+construction of transformers applied to features.
+
+```{code-cell} ipython3
+import numpy as np
+from sklearn.decomposition import PCA
+
+from ISLP import load_data
+from modelmatrix import (ModelSpec, 
+                         pca, 
+                         Feature, 
+                         derived_feature,
+                         build_columns)
+```
+
+```{code-cell} ipython3
+Carseats = load_data('Carseats')
+Carseats.columns
+```
+
+Let's create a `ModelSpec` that is aware of all of the relevant columns.
+
+```{code-cell} ipython3
+design = ModelSpec(Carseats.columns.drop(['Sales']), intercept=True).fit(Carseats)
+```
+
+Suppose we want to make a `Feature` representing the first 3 principal components of the
+ features `['CompPrice', 'Income', 'Advertising', 'Population', 'Price']`.
+
++++
+
+We first make a `Feature` that represents these five features columns, then `pca`
+can be used to compute a new `Feature` that returns the first three principal components.
+
+```{code-cell} ipython3
+grouped = Feature(('CompPrice', 'Income', 'Advertising', 'Population', 'Price'), name='grouped', encoder=None)
+sklearn_pca = PCA(n_components=3, whiten=True)
+```
+
+We can now fit `sklearn_pca` and create our new feature.
+
+```{code-cell} ipython3
+grouped_features = build_columns(design.column_info_,
+                                 Carseats,
+                                 grouped)[0]
+sklearn_pca.fit(grouped_features) 
+pca_var = derived_feature(['CompPrice', 'Income', 'Advertising', 'Population', 'Price'],
+                           name='pca(grouped)', encoder=sklearn_pca)
+derived_features, _ = build_columns(design.column_info_,
+                                    Carseats, 
+                                    pca_var,
+                                    encoders=design.encoders_)
+```
+
+## Helper function
+
+The function `pca` encompasses these steps into a single function for convenience.
+
+```{code-cell} ipython3
+group_pca = pca(['CompPrice', 'Income', 'Advertising', 'Population', 'Price'], 
+                n_components=3, 
+                whiten=True, 
+                name='grouped')
+```
+
+```{code-cell} ipython3
+pca_design = ModelSpec([group_pca], intercept=False)
+mm_features = pca_design.fit_transform(Carseats)
+mm_features.columns
+```
+
+## Direct comparison
+
+```{code-cell} ipython3
+X = np.asarray(Carseats[['CompPrice', 'Income', 'Advertising', 'Population', 'Price']])
+sklearn_features = sklearn_pca.fit_transform(X)
+```
+
+```{code-cell} ipython3
+np.linalg.norm(mm_features - sklearn_features), np.linalg.norm(mm_features - np.asarray(derived_features))
+```

modelmatrix-0.1.0/docs/anova.md

@@ -0,0 +1,103 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.19.6
+kernelspec:
+  display_name: python3
+  language: python
+  name: python3
+---
+
+# ANOVA using `ModelSpec`
+
+
+We illustrate how to run specific ANOVA analyses
+using `ModelSpec`, with statsmodels' `anova_lm`.
+
+```{code-cell} ipython3
+import numpy as np
+import pandas as pd
+
+from statsmodels.api import OLS
+from statsmodels.stats.anova import anova_lm
+
+from ISLP import load_data
+from modelmatrix import ModelSpec, derived_feature
+```
+
+We will carry out two simple ANOVA analyses of the `Hitters` data.
+We wish to predict a baseball player’s `Salary` on the
+basis of various statistics associated with performance in the
+previous year.
+
+```{code-cell} ipython3
+Hitters = load_data('Hitters')
+np.isnan(Hitters['Salary']).sum()
+```
+
+    
+ We see that `Salary` is missing for 59 players. The
+`dropna()`  method of data frames removes all of the rows that have missing
+values in any variable (by default --- see  `Hitters.dropna?`).
+
+```{code-cell} ipython3
+Hitters = Hitters.dropna()
+Hitters.columns
+```
+
+## Grouping variables
+
+A look at the [description](https://islp.readthedocs.io/en/latest/datasets/Hitters.html) of the data shows
+that there are both career and 1986 offensive stats, as well as some defensive stats.
+
+Let's group the offensive into recent and career offensive stats, as well as a group of defensive variables.
+
+```{code-cell} ipython3
+confounders = derived_feature(['Division', 'League', 'NewLeague'],
+                              name='confounders')
+offense_career = derived_feature(['CAtBat', 'CHits', 'CHmRun', 'CRuns', 'CRBI', 'CWalks'],
+                                 name='offense_career')
+offense_1986 = derived_feature(['AtBat', 'Hits', 'HmRun', 'Runs', 'RBI', 'Walks'],
+                               name='offense_1986')
+defense_1986 = derived_feature(['PutOuts', 'Assists', 'Errors'],
+                               name='defense_1986')
+```
+
+We'll first do a sequential ANOVA where terms are added sequentially
+
+```{code-cell} ipython3
+design = ModelSpec([confounders, offense_career, defense_1986, offense_1986], intercept=True).fit(Hitters)
+Y = np.array(Hitters['Salary'])
+X = design.transform(Hitters)
+```
+
+```{code-cell} ipython3
+M = OLS(Y, X).fit()
+M.summary().tables[1]
+```
+
+We'll first produce the sequential, or Type I ANOVA results. This builds up a model sequentially and compares
+two successive models.
+
+```{code-cell} ipython3
+df = anova_lm(*[OLS(Y, D).fit() for D in design.build_sequence(Hitters, anova_type='sequential')])
+df.index = design.names
+df
+```
+
+We can similarly compute the Type II ANOVA results which drops each term and compares to the full model.
+
+```{code-cell} ipython3
+D_full = design.transform(Hitters)
+OLS_full = OLS(Y, D_full).fit()
+dfs = []
+for d in design.build_sequence(Hitters, anova_type='drop'):
+    dfs.append(anova_lm(OLS(Y,d).fit(), OLS_full).iloc[1:])
+df = pd.concat(dfs)
+df.index = design.names
+df
+```

modelmatrix-0.1.0/docs/api/ModelSpec.rst

@@ -0,0 +1,7 @@
+ModelSpec
+=========
+
+.. autoclass:: modelmatrix.ModelSpec
+    :members:
+    :inherited-members:
+    :show-inheritance:

modelmatrix-0.1.0/docs/api/conf.py

@@ -0,0 +1,41 @@
+# Sphinx configuration for the modelmatrix API reference.
+#
+# The narrative docs are a Jupyter Book 2 (MyST) site, which has no autodoc;
+# this small Sphinx project builds the API reference from docstrings into
+# docs/_build/html/api, next to the book. See .github/workflows/build_docs.yml.
+#
+# Build:  sphinx-build -b html docs/api docs/_build/html/api
+
+project = 'modelmatrix API Reference'
+author = 'Jonathan Taylor'
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+]
+
+autodoc_default_options = {
+    'members': True,
+    'show-inheritance': True,
+}
+
+html_theme = 'sphinx_book_theme'
+html_title = 'modelmatrix API Reference'
+html_theme_options = {
+    'repository_url': 'https://github.com/intro-stat-learning/modelmatrix',
+    'use_repository_button': True,
+    'home_page_in_toc': True,
+}
+
+
+def _skip_sklearn_metadata_routing(app, what, name, obj, skip, options):
+    # scikit-learn's metadata-routing plumbing (set_{fit,transform,...}_request,
+    # added to every estimator subclass, and get_metadata_routing) is not part of
+    # the modelmatrix API
+    if (name.startswith('set_') and name.endswith('_request')) or name == 'get_metadata_routing':
+        return True
+    return None
+
+
+def setup(app):
+    app.connect('autodoc-skip-member', _skip_sklearn_metadata_routing)

modelmatrix-0.1.0/docs/api/index.rst

@@ -0,0 +1,12 @@
+modelmatrix API Reference
+=========================
+
+API reference for the ``modelmatrix`` Python package.
+For the guide and examples, see the `modelmatrix documentation <../>`_.
+
+.. toctree::
+   :maxdepth: 1
+
+   ModelSpec
+   terms
+   transforms

modelmatrix-0.1.0/docs/api/terms.rst

@@ -0,0 +1,29 @@
+Terms
+=====
+
+Helpers that make terms
+-----------------------
+
+.. autofunction:: modelmatrix.poly
+.. autofunction:: modelmatrix.ns
+.. autofunction:: modelmatrix.bs
+.. autofunction:: modelmatrix.pca
+.. autofunction:: modelmatrix.contrast
+.. autofunction:: modelmatrix.ordinal
+.. autofunction:: modelmatrix.derived_feature
+.. autofunction:: modelmatrix.build_columns
+
+Terms and columns
+-----------------
+
+.. autoclass:: modelmatrix.Feature
+.. autoclass:: modelmatrix.Column
+    :members: get_columns
+
+Encoders of categoricals
+------------------------
+
+.. autoclass:: modelmatrix.Contrast
+    :members: fit, transform
+.. autoclass:: modelmatrix.Ordinal
+    :members: fit, transform

modelmatrix-0.1.0/docs/api/transforms.rst

@@ -0,0 +1,6 @@
+Transforms
+==========
+
+.. automodule:: modelmatrix.transforms
+   :members: Poly, BSpline, NaturalSpline, Interaction
+   :show-inheritance: