turtles-glms 1.0.0__py3-none-any.whl

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/_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/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/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/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/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/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"
+]

turtles/stats/_stats.py

@@ -0,0 +1,276 @@
+"""
+Various statistical functions.
+"""
+
+from typing import Optional, Tuple, Dict, List
+
+import numpy as np
+import pandas as pd
+from scipy.stats import pearsonr
+from scipy.sparse.linalg import eigs
+
+from .._utils import (
+    _validate_args,
+    _add_intercept,
+    _shape_check
+)
+
+
+def calculate_errors(
+    y_true: np.ndarray, 
+    y_pred: np.ndarray, 
+    m: Optional[int] = None
+) -> Dict[str, float]:
+    """
+    Calculate errors for arrays containing continuous values. Not suitable
+    for classification cases.
+
+        1. Sum of Squared Errors (or Residual Sum of Squares)
+        2. Mean Squared Error
+        3. Root Mean Squared Error
+
+    Parameters
+    ----------
+    y_true : np.ndarray
+        True target array. Must be the same shape as y_pred and have 1 dimension
+        or be flattened.
+    y_pred : np.ndarray
+        Predicted values target array. Must be the same shape as y_true and have 
+        1 dimension or be flattened.
+    m : int
+        Number of observations. If using this function to calculate model fit 
+        statistics, 'm' should be the degrees of freedom.
+
+    Returns
+    -------
+    Dict[str, float]
+        Dictionary where {key:value} is {"error name": value}.
+    """
+
+    m = m or max(y_true.shape)
+
+    _validate_args(
+        {
+            "y_true": (y_true, np.ndarray),
+            "y_pred": (y_pred, np.ndarray),
+            "m": (m, int)
+        }
+    )
+
+    errors = y_true - y_pred
+    sse = np.sum(errors ** 2).item()
+    mse = sse / m
+    rmse = np.sqrt(mse).item()
+
+    response = {
+        "Sum of Squared Errors": sse,
+        "Mean Squared Error": mse,
+        "Root Mean Squared Error": rmse
+    }
+
+    return response
+
+
+def variance_inflation_factor(
+    X: np.ndarray,
+    var_names: Optional[List[str]] = None
+) -> pd.DataFrame:
+    """
+    Calculate Variance Inflation Factor (VIF) for all predictors in the 
+    input matrix.
+
+    Fits one linear model for each dimension, where that single dimension 
+    is the dependent variable, and all other dimensions (including an intercept) 
+    are the independent variables.
+
+    Parameters
+    ----------
+    X : np.ndarray, shape (m, n)
+        Design matrix. Should not include an intercept.
+    var_names : Optional[List[str]]
+        Variable names. If not passed, defaults to `x_i` where `i` is the order 
+        of the dimension in the input matrix. Names must appear in the order 
+        that they do in the input matrix.
+
+    Returns
+    -------
+    pd.DataFrame
+        Pandas DataFrame containing the Coefficient (str), R-squared (float),
+        VIF (float).
+    """
+
+    _validate_args(
+        {
+            "X": (X, np.ndarray)
+        }
+    )
+    _shape_check(X, "X", 1)
+
+    vifs = {
+        "Coefficient": [],
+        "R-squared": [],
+        "VIF": []
+    }
+
+    for idx in range(X.shape[1]):
+        # create design matrix -- all except one predictor
+        exog = np.delete(X, idx, axis=1)
+        # target -- the one predictor
+        endog = X[:, idx]
+        
+        # add intercept to design matrix
+        exog = _add_intercept(exog)
+
+        # fit model -- one predictor vs all others
+        coefs = np.linalg.inv(exog.T @ exog) @ exog.T @ endog
+
+        # calculate residuals
+        fitted_vals = exog @ coefs.T
+        residuals = endog - fitted_vals
+
+        # Redisual Sum of Squares and Sum of Squares Total
+        rss = np.sum(residuals ** 2)
+        sst = np.sum((endog - np.mean(endog))**2)
+
+        # R-squared
+        r2 = 1 - rss / sst
+        vifs["R-squared"].append(r2.item())
+
+        # VIF
+        vif = 1 / (1 - r2)
+        vifs["VIF"].append(vif.item())
+
+        vifs["Coefficient"].append(f"x{idx}")
+
+    if var_names is not None:
+        vifs["Coefficient"] = var_names 
+
+    return pd.DataFrame(vifs)
+
+
+def pearson_corr(
+    x: np.ndarray, 
+    y: np.ndarray, 
+) -> Tuple[float, float]:
+    """
+    Calculate the Pearson Correlation Coefficient.
+
+    This is basically a wrapper around the SciPy function.
+
+    https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.pearsonr.html
+
+    Parameters
+    ----------
+    x : np.ndarray
+        First input array. Usually a single independent variable.
+    y : np.ndarray
+        Second input array. A single independent or dependent variable.
+
+    Returns
+    -------
+    Tuple[float, float]
+        Tuple containing the correlation coefficient in position [0],
+        and the p-value in position [1].
+    """
+
+    _validate_args(
+        {
+            "x": (x, np.ndarray),
+            "y": (y, np.ndarray)
+        }
+    )
+
+    result = pearsonr(x=x.flatten(), y=y.flatten())
+    return (result.statistic.item(), result.pvalue.item())
+
+
+def covariance_matrix(X: np.ndarray, return_xc=False) -> np.ndarray:
+    """
+    Calculate the covariance between variables in a matrix.
+
+    Parameters
+    ----------
+    X : np.ndarray
+        Design matrix of shape (M, N).
+    return_xc : bool, defaults to False
+        Optionally return the centered matrix.
+
+    Returns
+    -------
+    C : np.ndarray
+        Covariance matrix of size (N, N).
+    X_c : np.ndarray
+        Centered input matrix.
+    """
+
+    _validate_args(
+        {
+            "X": (X, np.ndarray),
+            "return_xc": (return_xc, bool)
+        }
+    )
+    _shape_check(X, "X", 2)
+
+    # estimate mean for each variable / column
+    m = X.shape[0]
+    X_t = X.T
+    avg = np.mean(X_t, axis=1)
+
+    # 'center' the matrix
+    X_c = X_t - avg[:, None]
+
+    # covariance matrix
+    C = (X_c @ X_c.T)/m
+
+    if return_xc:
+        return C, X_c
+    
+    return C
+
+
+def pca(X: np.ndarray, p: int) -> np.ndarray:
+    """
+    Principal Component Analysis.
+
+    Parameters
+    ----------
+    X : np.ndarray, shape (M, N)
+        Input data (design matrix) for calculating pricipal components.
+    p : int
+        Number of principle components to return. Must be less than or 
+        equal to the number of dimensions in X.
+
+    Raises
+    ------
+    ValueError
+        If the requested number of principal components exceeds the number 
+        of dimensions in the input matrix.
+
+    Returns
+    -------
+    np.ndarray, shape (M, p)
+        Matrix with p dimensions.
+    """
+
+    _validate_args(
+        {
+            "X": (X, np.ndarray),
+            "p": (p, int)
+        }
+    )
+    _shape_check(X, "X", 2)
+
+    if p > X.shape[1]:
+        raise ValueError("'p' must be <= 'X' dimensions.")
+
+    # get covariance matrix
+    C, X_c = covariance_matrix(X, return_xc=True)
+
+    # calculate eigenvalues, eigenvectors
+    s, w = eigs(C, p)
+    s = s.real
+    s = np.reshape(s, (p, 1))
+    w = w.real
+    pca = w.T @ X_c
+
+    return pca.T

turtles/stats/glms/__init__.py

@@ -0,0 +1,14 @@
+"""
+GLMs submodule.
+"""
+
+from ._mlr import MLR
+from ._logreg import LogReg
+from ._poisson import PoissonReg
+
+
+__all__ = [
+    "MLR",
+    "LogReg",
+    "PoissonReg"
+]