turtles-glms 1.0.0__tar.gz

turtles_glms-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Adam Motzel
+
+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.

turtles_glms-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: turtles-glms
+Version: 1.0.0
+Summary: GLMs in Python.
+Author-email: Adam Motzel <motzel.adam@gmail.com>
+Project-URL: Homepage, https://github.com/adammotzel/pyglms
+Project-URL: Issues, https://github.com/adammotzel/pyglms/issues
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: matplotlib>=3.9.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.4; extra == "dev"
+Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
+Requires-Dist: scikit-learn>=1.6.1; extra == "dev"
+Requires-Dist: statsmodels>=0.14.4; extra == "dev"
+Requires-Dist: ipykernel>=6.29.5; extra == "dev"
+Dynamic: license-file
+
+![CI](https://github.com/adammotzel/pyglms/actions/workflows/ci.yaml/badge.svg)
+![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
+![Python](https://img.shields.io/badge/python-3.10%20--%203.13-blue)
+![License](https://img.shields.io/github/license/adammotzel/pyglms)
+ ![PyPI](https://img.shields.io/pypi/v/turtles-glms.svg)
+
+
+# PyGLMs (Turtles)
+
+An implementation of various Generalized Linear Models (GLMs), written in Python.
+
+I created this package as a refresher on GLMs and the underlying optimization techniques. It's intended as a learning tool and a reference for building and understanding these models from the ground up.
+
+
+## Overview
+
+The code is packaged as a Python library named `turtles` ([I like turtles](https://www.youtube.com/watch?v=CMNry4PE93Y)), making the code easy to integrate into your own projects.
+
+The package is written using `numpy` for linear algebra operations, `scipy` for (some) optimization, `pandas` for displaying tabular results, and `matplotlib` for plots.
+
+The following models have been implemented:
+
+1. Multiple Linear Regression (`turtles.stats.glms.MLR` class)
+2. Logistic Regression (`turtles.stats.glms.LogReg` class, uses `GLM` parent class)
+3. Poisson Regression (`turtles.stats.glms.PoissonReg` class, uses `GLM` parent class)
+
+The `GLM` parent class supports three optimization methods for parameter estimation: Momentum-based Gradient Descent for first-order optimization, Newton's Method for second-order optimization, and Limited-memory Broyden–Fletcher–Goldfarb–Shanno (L-BFGS). The user can specify the desired optimization `method` during class instantiation.
+
+Momentum-based Gradient Descent and Newton's Method are implemented in Python as part of the `turtles` distribution. L-BFGS is implemented using `scipy.optimize`; it's a quasi-Newton method that approximates the Hessian (instead of fully computing it, like Newton's Method), so it's quite fast.
+
+See `examples/{class name}_example.ipynb` for simple examples of using each model class and various supporting functions.
+
+
+## Usage
+
+You can pip install the package from PyPI:
+
+```bash
+pip install turtles-glms
+```
+
+
+## Contributing
+
+To run (and edit) this project locally, clone the repo and create your virtual environment from project root using your global (or local) Python version. This project requires Python 3.10+.
+
+```bash
+python -m venv
+```
+
+Activate the env (`source .venv/Scripts/activate` for Windows OS, `source .venv/bin/activate` for Linux) and install dependencies:
+
+```bash
+pip install -e .[dev]
+```
+
+Optionally, you can execute `scripts/env.sh` to create and activate a virtual environment using `uv`. The `uv` package manager must be installed for this to work.
+
+
+### Adding GLMs
+
+To add more GLM classes, use the `GLM` parent class for inheritence (see `PoissonReg` and `LogReg` as examples). The GLM parent class provides a solid framework for implementing new child classes and should be used whenever possible. Unimplemented GLMs include Negative Binomial, Gamma, and Tweedie.
+
+
+## Testing
+
+All tests are contained within `tests` directories for each module. You can simply execute the `pytest` command from project root to run all unit tests.
+
+```bash
+pytest
+```
+
+**Notes on Test Coverage:**
+- Plotting functions from `turtles.plotting` are tested, but plotting methods in GLM classes 
+(like `MLR`) are ignored. Those class methods are essentially just wrappers around `matplotlib` 
+and `turtles.plotting` functions.
+- `GLM` class methods that are meant to be implemented by child classes are ignored.

turtles_glms-1.0.0/README.md

@@ -0,0 +1,77 @@
+![CI](https://github.com/adammotzel/pyglms/actions/workflows/ci.yaml/badge.svg)
+![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
+![Python](https://img.shields.io/badge/python-3.10%20--%203.13-blue)
+![License](https://img.shields.io/github/license/adammotzel/pyglms)
+ ![PyPI](https://img.shields.io/pypi/v/turtles-glms.svg)
+
+
+# PyGLMs (Turtles)
+
+An implementation of various Generalized Linear Models (GLMs), written in Python.
+
+I created this package as a refresher on GLMs and the underlying optimization techniques. It's intended as a learning tool and a reference for building and understanding these models from the ground up.
+
+
+## Overview
+
+The code is packaged as a Python library named `turtles` ([I like turtles](https://www.youtube.com/watch?v=CMNry4PE93Y)), making the code easy to integrate into your own projects.
+
+The package is written using `numpy` for linear algebra operations, `scipy` for (some) optimization, `pandas` for displaying tabular results, and `matplotlib` for plots.
+
+The following models have been implemented:
+
+1. Multiple Linear Regression (`turtles.stats.glms.MLR` class)
+2. Logistic Regression (`turtles.stats.glms.LogReg` class, uses `GLM` parent class)
+3. Poisson Regression (`turtles.stats.glms.PoissonReg` class, uses `GLM` parent class)
+
+The `GLM` parent class supports three optimization methods for parameter estimation: Momentum-based Gradient Descent for first-order optimization, Newton's Method for second-order optimization, and Limited-memory Broyden–Fletcher–Goldfarb–Shanno (L-BFGS). The user can specify the desired optimization `method` during class instantiation.
+
+Momentum-based Gradient Descent and Newton's Method are implemented in Python as part of the `turtles` distribution. L-BFGS is implemented using `scipy.optimize`; it's a quasi-Newton method that approximates the Hessian (instead of fully computing it, like Newton's Method), so it's quite fast.
+
+See `examples/{class name}_example.ipynb` for simple examples of using each model class and various supporting functions.
+
+
+## Usage
+
+You can pip install the package from PyPI:
+
+```bash
+pip install turtles-glms
+```
+
+
+## Contributing
+
+To run (and edit) this project locally, clone the repo and create your virtual environment from project root using your global (or local) Python version. This project requires Python 3.10+.
+
+```bash
+python -m venv
+```
+
+Activate the env (`source .venv/Scripts/activate` for Windows OS, `source .venv/bin/activate` for Linux) and install dependencies:
+
+```bash
+pip install -e .[dev]
+```
+
+Optionally, you can execute `scripts/env.sh` to create and activate a virtual environment using `uv`. The `uv` package manager must be installed for this to work.
+
+
+### Adding GLMs
+
+To add more GLM classes, use the `GLM` parent class for inheritence (see `PoissonReg` and `LogReg` as examples). The GLM parent class provides a solid framework for implementing new child classes and should be used whenever possible. Unimplemented GLMs include Negative Binomial, Gamma, and Tweedie.
+
+
+## Testing
+
+All tests are contained within `tests` directories for each module. You can simply execute the `pytest` command from project root to run all unit tests.
+
+```bash
+pytest
+```
+
+**Notes on Test Coverage:**
+- Plotting functions from `turtles.plotting` are tested, but plotting methods in GLM classes 
+(like `MLR`) are ignored. Those class methods are essentially just wrappers around `matplotlib` 
+and `turtles.plotting` functions.
+- `GLM` class methods that are meant to be implemented by child classes are ignored.

turtles_glms-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "turtles-glms"
+version = "1.0.0"
+requires-python = ">= 3.10"
+dependencies = [
+    "numpy>=2.0.2",
+    "pandas>=2.2.3",
+    "scipy>=1.13.1",
+    "matplotlib>=3.9.4",
+]
+description = "GLMs in Python."
+readme = "README.md"
+license = {file = "LICENSE.txt"}
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+authors = [
+    {name = "Adam Motzel", email = "motzel.adam@gmail.com"}
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-cov>=6.2.1",
+    "scikit-learn>=1.6.1",
+    "statsmodels>=0.14.4",
+    "ipykernel>=6.29.5"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+exclude = ["tests", "*tests*", "examples", "scripts"]
+
+[project.urls]
+Homepage = "https://github.com/adammotzel/pyglms"
+Issues = "https://github.com/adammotzel/pyglms/issues"

turtles_glms-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

turtles_glms-1.0.0/turtles/__init__.py

@@ -0,0 +1,17 @@
+"""
+Configure global settings for package.
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("turtles-glms")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+# modules
+__all__ = [
+    "preprocess",
+    "stats",
+    "plotting"
+]

turtles_glms-1.0.0/turtles/_utils.py

@@ -0,0 +1,110 @@
+"""
+General utility functions.
+"""
+
+from typing import (
+    Dict, 
+    Tuple, 
+    Any, 
+    Union
+)
+
+import numpy as np
+
+
+def _shape_check(x: np.ndarray, var_name: str, dim: int = 1):
+    """
+    Check if numpy array has at least `dim` dimensions.
+
+    x : np.ndarray
+        Numpy matrix.
+    var_name : str
+        The variable name to return in the error message.
+    dim : int, default 2
+        The min number of dimensions in the array.
+
+    Raises
+    ------
+    ValueError
+        If the array has less than `dim` dimensions.
+
+    Returns
+    -------
+    None
+    """
+
+    if np.ndim(x) == 1 or x.shape[1] < dim:
+        raise ValueError(
+            f"'{var_name}' must contain more than {dim} dimensions."
+        )
+    
+
+def _validate_args(
+    map: Dict[str, Tuple[Any, Union[type, Tuple[type, ...]]]]
+):
+    """
+    Simple type validation of a set of input arguments.
+
+    Parameters
+    ----------
+    map : Dict[str, Tuple[Any, Union[type, Tuple[type, ...]]]]
+        A dictionary where keys are the argument names and the values are 
+        tuples containing:
+        - the object to check
+        - the expected type or a tuple of types
+
+    Raises
+    ------
+    TypeError
+        If the type of an argument does not match the expected type.
+
+    Example
+    -------
+    _validate_args(
+        {
+            'X': (X, np.array), 
+            'Y': (Y, (int, float))
+        }
+    )
+    """
+    for key, (obj, expected_type) in map.items():
+        if isinstance(expected_type, tuple):
+            if not any(isinstance(obj, t) for t in expected_type):
+                raise TypeError(
+                    f"Parameter '{key}' must be one of the types {expected_type}; "
+                    f"received {type(obj)}"
+                )
+        else:
+            if not isinstance(obj, expected_type):
+                raise TypeError(
+                    f"Parameter '{key}' must be of type {expected_type}; "
+                    f"received {type(obj)}"
+                )
+
+
+def _add_intercept(X: np.ndarray) -> np.ndarray:
+    """
+    Add intercept to the design matrix. The intercept is simply
+    a column of ones.
+
+    Parameters
+    ----------
+    X : np.ndarray, shape (M, N)
+        Design matrix with M rows (samples) and N columns (features).
+
+    Returns
+    -------
+    np.ndarray, shape (M, N+1)
+        Design matrix with the intercept as the first column.
+    """
+
+    _validate_args(
+        {
+            "X": (X, np.ndarray)
+        }
+    )
+    
+    m = X.shape[0]
+    intercept = np.ones(m).reshape(m, 1)
+    X = np.concatenate((intercept, X), axis=1)
+    return X

turtles_glms-1.0.0/turtles/plotting/__init__.py

@@ -0,0 +1,14 @@
+"""
+Plotting module.
+
+Contains various plotting functions.
+"""
+
+from ._plotting import (
+    plot_y_vs_x
+)
+
+
+__all__ = [
+    "plot_y_vs_x"
+]

turtles_glms-1.0.0/turtles/plotting/_plotting.py

@@ -0,0 +1,61 @@
+"""
+Plotting functions.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from .._utils import _validate_args
+
+
+def plot_y_vs_x(
+        x: np.ndarray, 
+        y: np.ndarray, 
+        title: str = "Dependent vs. Independent",
+        xlabel: str = "Independent",
+        ylabel: str = "Dependent"
+):
+    """
+    Scatter plot of a variable (y) against another variable (x).
+
+    Input arrays must be the same shape.
+
+    Parameters
+    ----------
+    x : np.ndarray
+        Input array for x-axis.
+    y : np.ndarray
+        Input aray for y-axis.
+    title : str
+        Plot title. Defaults to 'Dependent vs. Independent'.
+    xlabel : str
+        Plot label for x-axis. Defaults to 'Independent'.
+    ylabel : str
+        Plot label for y axis. Defaults to 'Dependent'.
+
+    Returns
+    -------
+    None
+        Displays scatter plot.
+    """
+
+    _validate_args(
+        {
+            "x": (x, np.ndarray),
+            "y": (y, np.ndarray),
+            "title": (title, str),
+            "xlabel": (xlabel, str),
+            "ylabel": (ylabel, str)
+        }
+    )
+
+    plt.scatter(
+        x=x,
+        y=y,
+        color="blue", 
+        edgecolor="black"
+    )
+    plt.title(title)
+    plt.xlabel(xlabel)
+    plt.ylabel(ylabel)
+    plt.show()

turtles_glms-1.0.0/turtles/preprocess/__init__.py

@@ -0,0 +1,17 @@
+"""
+Preprocess module.
+
+Functions support common data transformation tasks to prep datasets
+for GLMs.
+"""
+
+from ._transform import (
+    one_hot_encode
+)
+from .._utils import _add_intercept as add_intercept
+
+
+__all__ = [
+    "one_hot_encode",
+    "add_intercept"
+]

turtles_glms-1.0.0/turtles/preprocess/_transform.py

@@ -0,0 +1,81 @@
+"""
+Functions to support preprocessing/transformations.
+"""
+
+from typing import List, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+from .._utils import (
+    _validate_args,
+)
+
+
+def one_hot_encode(
+    df: pd.DataFrame, 
+    columns: List[str],
+    drop_first: bool = True,
+    return_df: bool = True
+) -> Union[pd.DataFrame, Tuple[np.ndarray, List[str]]]:
+    """
+    One Hot Encode categorical variables in a Pandas DataFrame, also known
+    as dummy variables or indicator variables.
+
+    This is essentially just a wrapper around the Pandas `get_dummies()`
+    function, but it optioanlly returns a Numpy matrix, making the resulting 
+    object immediately compatible with the `turtles` GLM classes.
+
+    https://pandas.pydata.org/docs/reference/api/pandas.get_dummies.html
+
+    Parameters
+    ----------
+    df : pd.DataFrame, shape (M, N)
+        Pandas DataFrame containing data to be encoded.
+    columns : List[str]
+        List of column names in `df` to be encoded. Column values must be 
+        strings or categorical.
+    drop_first : bool, default True
+        Whether to drop the first category from the resulting table. Dropping
+        the first category is useful when building a GLM, because the dropped
+        category will then be treated as the 'base case' or 'reference category' 
+        for model coefficient interpretation.
+    return_df : bool, default True
+        Optionally return a pandas DataFrame. If False, a Tuple of a numpy 
+        matrix and resulting column names is returned.
+
+    Returns
+    -------
+    Union[pd.DataFrame, Tuple[np.ndarray, List[str]]]
+    
+        If `return_df` = True, a pandas DataFrame is returned, containing the 
+        encoded columns.
+        
+        If `return_df` = False, a Tuple is returned, where the new matrix is 
+        in position [0] and the list of new column names in position [1].
+    """
+    
+    _validate_args(
+        {
+            "df": (df, pd.DataFrame),
+            "columns": (columns, list),
+            "drop_first": (drop_first, bool),
+            "return_df": (return_df, bool)
+        }
+    )
+
+    temp = df.copy()
+
+    one_hot_encoded_df = pd.get_dummies(
+        temp, 
+        columns=columns,
+        drop_first=drop_first,
+        dtype=int
+    )
+
+    if return_df:
+        return one_hot_encoded_df
+    
+    column_names = list(one_hot_encoded_df.columns)
+    
+    return one_hot_encoded_df.to_numpy(), column_names

turtles_glms-1.0.0/turtles/stats/__init__.py

@@ -0,0 +1,23 @@
+"""
+Stats module.
+
+These functions support various statistical tasks.
+"""
+
+from ._stats import (
+    calculate_errors,
+    variance_inflation_factor,
+    pearson_corr,
+    covariance_matrix,
+    pca
+)
+
+
+__all__ = [
+    "glms",  # submodule
+    "calculate_errors",
+    "variance_inflation_factor",
+    "pearson_corr",
+    "covariance_matrix",
+    "pca"
+]