rustystats 0.1.5__cp313-cp313-manylinux_2_34_x86_64.whl

rustystats/links.py

@@ -0,0 +1,221 @@
+"""
+Link Functions for GLMs
+=======================
+
+Link functions connect the linear predictor (η = Xβ) to the mean (μ).
+They're written as:
+
+    η = g(μ)    or equivalently    μ = g⁻¹(η)
+
+Why Do We Need Link Functions?
+------------------------------
+
+Different types of responses need different transformations:
+
+1. **Continuous data**: Use identity link (η = μ)
+   - No transformation needed
+   - Predictions can be any real value
+
+2. **Count data**: Use log link (η = log(μ))
+   - Ensures predictions are always positive (μ = exp(η) > 0)
+   - Gives multiplicative interpretation to coefficients
+
+3. **Binary data**: Use logit link (η = log(μ/(1-μ)))
+   - Ensures predictions are probabilities (0 < μ < 1)
+   - Coefficients are log-odds ratios
+
+Choosing a Link Function
+------------------------
+
++------------------+-------------------+-------------------+--------------------+
+| Family           | Canonical Link    | Common Alternative| Interpretation     |
++==================+===================+===================+====================+
+| Gaussian         | Identity          | Log               | Additive effects   |
+| Poisson          | Log               | -                 | Multiplicative     |
+| Binomial         | Logit             | Probit, Cloglog   | Odds ratios        |
+| Gamma            | Inverse (1/μ)     | Log               | Multiplicative     |
++------------------+-------------------+-------------------+--------------------+
+
+In actuarial practice, the **log link** is extremely common because:
+- It ensures positive predictions (important for counts and amounts)
+- Coefficients have multiplicative interpretation (rate relativities!)
+- It's consistent across frequency and severity models
+
+Examples
+--------
+>>> import rustystats as rs
+>>> import numpy as np
+>>>
+>>> # Log link example
+>>> log_link = rs.links.Log()
+>>> eta = np.array([0.0, 0.5, 1.0])  # Linear predictor values
+>>> mu = log_link.inverse(eta)
+>>> print(mu)  # [1.0, 1.649, 2.718] - always positive!
+>>>
+>>> # Logit link example  
+>>> logit_link = rs.links.Logit()
+>>> eta = np.array([-2.0, 0.0, 2.0])
+>>> mu = logit_link.inverse(eta)
+>>> print(mu)  # [0.119, 0.5, 0.881] - always between 0 and 1!
+"""
+
+# Import the Rust implementations
+from rustystats._rustystats import (
+    IdentityLink as _IdentityLink,
+    LogLink as _LogLink,
+    LogitLink as _LogitLink,
+)
+
+
+def Identity():
+    """
+    Identity link function: η = μ
+    
+    The simplest link - no transformation at all.
+    
+    Properties
+    ----------
+    - Link: η = μ
+    - Inverse: μ = η  
+    - Derivative: dη/dμ = 1
+    
+    When to Use
+    -----------
+    - Gaussian family (standard linear regression)
+    - When you want to model the mean directly
+    - When predictions can be any real value
+    
+    Interpretation
+    --------------
+    Coefficients have an additive interpretation:
+    
+    - If β = 10 for variable X
+    - Then a 1-unit increase in X increases the predicted mean by 10
+    
+    Example
+    -------
+    >>> link = rs.links.Identity()
+    >>> mu = np.array([1.0, 2.0, 3.0])
+    >>> eta = link.link(mu)  # [1.0, 2.0, 3.0] - unchanged
+    """
+    return _IdentityLink()
+
+
+def Log():
+    """
+    Log link function: η = log(μ)
+    
+    Ensures predictions are always positive. The workhorse of actuarial GLMs.
+    
+    Properties
+    ----------
+    - Link: η = log(μ)
+    - Inverse: μ = exp(η)
+    - Derivative: dη/dμ = 1/μ
+    
+    When to Use
+    -----------
+    - Poisson family (claim frequency)
+    - Gamma family (claim severity)
+    - Whenever the response must be positive
+    
+    Multiplicative Interpretation (Important!)
+    ------------------------------------------
+    Coefficients represent MULTIPLICATIVE effects (rate relativities):
+    
+    - If β = 0.2 for "young driver" indicator
+    - Then exp(0.2) ≈ 1.22
+    - Young drivers have 1.22× the expected count/amount (22% higher)
+    
+    This is why log link is standard in insurance pricing:
+    - Base rate × relativity_1 × relativity_2 × ...
+    - On log scale: log(base) + β₁ + β₂ + ...
+    
+    Combining Frequency and Severity
+    --------------------------------
+    If both models use log link:
+    - Frequency: log(μ_freq) = X β_freq
+    - Severity: log(μ_sev) = X β_sev
+    - Pure Premium: log(μ_freq × μ_sev) = X (β_freq + β_sev)
+    
+    The pure premium coefficients are just the SUM!
+    
+    Example
+    -------
+    >>> link = rs.links.Log()
+    >>> 
+    >>> # If linear predictor η = 0, predicted count/amount = exp(0) = 1
+    >>> # If η increases by 0.1, prediction multiplied by exp(0.1) ≈ 1.105
+    >>> 
+    >>> eta = np.array([0.0, 0.1, 0.2])
+    >>> mu = link.inverse(eta)
+    >>> print(mu)  # [1.0, 1.105, 1.221]
+    """
+    return _LogLink()
+
+
+def Logit():
+    """
+    Logit link function: η = log(μ/(1-μ))
+    
+    Transforms probabilities to the log-odds scale.
+    The foundation of logistic regression.
+    
+    Properties
+    ----------
+    - Link: η = log(μ/(1-μ)) [the "log-odds"]
+    - Inverse: μ = 1/(1+exp(-η)) [the "sigmoid" or "logistic" function]
+    - Derivative: dη/dμ = 1/(μ(1-μ))
+    
+    When to Use
+    -----------
+    - Binomial family (binary outcomes)
+    - Modeling probabilities
+    - Yes/no, claim/no-claim type questions
+    
+    Understanding Log-Odds
+    ----------------------
+    If μ = 0.8 (80% probability):
+    - Odds = μ/(1-μ) = 0.8/0.2 = 4 ("4-to-1 odds")
+    - Log-odds = log(4) ≈ 1.39
+    
+    The logit function maps:
+    - μ = 0.5 → η = 0 (even odds)
+    - μ → 0 maps to η → -∞
+    - μ → 1 maps to η → +∞
+    
+    Odds Ratio Interpretation
+    -------------------------
+    Coefficients represent LOG odds ratios:
+    
+    - If β = 0.5 for "previous claims" indicator
+    - Then exp(0.5) ≈ 1.65
+    - People with previous claims have 1.65× the ODDS of claiming
+    - This is NOT the same as 1.65× the probability!
+    
+    Converting to Probability Change
+    --------------------------------
+    The effect on probability depends on the baseline probability:
+    
+    - At baseline μ=0.1: a β=0.5 coefficient changes probability to ~0.15
+    - At baseline μ=0.5: the same β changes probability to ~0.62
+    
+    This is why we report odds ratios, not probability ratios.
+    
+    Example
+    -------
+    >>> link = rs.links.Logit()
+    >>> 
+    >>> # η = 0 means 50% probability
+    >>> # η = 2 means high probability (about 88%)
+    >>> # η = -2 means low probability (about 12%)
+    >>> 
+    >>> eta = np.array([-2.0, 0.0, 2.0])
+    >>> mu = link.inverse(eta)
+    >>> print(mu)  # [0.119, 0.5, 0.881]
+    """
+    return _LogitLink()
+
+
+# For backwards compatibility and convenience
+__all__ = ["Identity", "Log", "Logit"]

rustystats/splines.py

@@ -0,0 +1,367 @@
+"""
+Spline basis functions for non-linear continuous effects in GLMs.
+
+This module provides B-splines and natural splines, which are essential
+for modeling non-linear relationships between continuous predictors
+and the response variable.
+
+Key Functions
+-------------
+- `bs()` - B-spline basis (flexible piecewise polynomials)
+- `ns()` - Natural spline basis (linear extrapolation at boundaries)
+
+Example
+-------
+>>> import rustystats as rs
+>>> import numpy as np
+>>> 
+>>> # Create spline basis for age with 5 degrees of freedom
+>>> age = np.array([25, 35, 45, 55, 65])
+>>> age_basis = rs.bs(age, df=5)
+>>> print(age_basis.shape)
+(5, 4)
+
+>>> # Use in formula API
+>>> result = rs.glm(
+...     "y ~ bs(age, df=5) + C(region)",
+...     data=data,
+...     family="poisson"
+... ).fit()
+
+When to Use Each Type
+---------------------
+**B-splines (`bs`):**
+- More flexible at boundaries
+- Good when you don't need to extrapolate
+- Standard choice for most applications
+
+**Natural splines (`ns`):**
+- Linear extrapolation beyond boundaries
+- Better for prediction on new data outside training range
+- More stable parameter estimates at boundaries
+- Recommended for actuarial applications
+
+Performance Note
+----------------
+Spline basis computation is implemented in Rust with parallel
+evaluation over observations, making it very fast even for
+large datasets.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union, List, Tuple, TYPE_CHECKING
+import numpy as np
+
+if TYPE_CHECKING:
+    import polars as pl
+
+# Import Rust implementations
+from rustystats._rustystats import (
+    bs_py as _bs_rust,
+    ns_py as _ns_rust,
+    bs_knots_py as _bs_knots_rust,
+    bs_names_py as _bs_names_rust,
+    ns_names_py as _ns_names_rust,
+)
+
+
+def bs(
+    x: np.ndarray,
+    df: int = 5,
+    degree: int = 3,
+    knots: Optional[List[float]] = None,
+    boundary_knots: Optional[Tuple[float, float]] = None,
+    include_intercept: bool = False,
+) -> np.ndarray:
+    """
+    Compute B-spline basis matrix.
+    
+    B-splines (basis splines) are piecewise polynomial functions that provide
+    a flexible way to model non-linear relationships. They are the foundation
+    for many modern smoothing techniques.
+    
+    Parameters
+    ----------
+    x : array-like
+        Data points to evaluate the basis at. Will be converted to 1D numpy array.
+    df : int, default=5
+        Degrees of freedom, i.e., number of basis functions to generate.
+        Higher df = more flexible fit but risk of overfitting.
+        Typical range: 3-10 for most applications.
+    degree : int, default=3
+        Polynomial degree of the splines:
+        - 0: Step functions (not smooth)
+        - 1: Linear splines (continuous but not smooth)
+        - 2: Quadratic splines (smooth first derivative)
+        - 3: Cubic splines (smooth first and second derivatives, most common)
+    knots : list, optional
+        Interior knot positions. If not provided, knots are placed at
+        quantiles of x based on the df parameter.
+    boundary_knots : tuple, optional
+        (min, max) defining the boundary of the spline basis.
+        If not provided, uses the range of x.
+    include_intercept : bool, default=False
+        Whether to include the intercept (constant) basis function.
+        Usually False when used in regression models that already have
+        an intercept term.
+    
+    Returns
+    -------
+    numpy.ndarray
+        Basis matrix of shape (n, k) where n is the length of x and
+        k is the number of basis functions (df or df-1 depending on
+        include_intercept).
+    
+    Notes
+    -----
+    The number of basis functions is:
+    - df if include_intercept=True
+    - df-1 if include_intercept=False (default)
+    
+    B-splines have the "partition of unity" property: the basis functions
+    sum to 1 at any point. They are also non-negative and have local support
+    (each basis function is non-zero only over a limited range).
+    
+    Examples
+    --------
+    >>> import rustystats as rs
+    >>> import numpy as np
+    >>> 
+    >>> # Basic usage
+    >>> x = np.linspace(0, 10, 100)
+    >>> basis = rs.bs(x, df=5)
+    >>> print(basis.shape)
+    (100, 4)
+    
+    >>> # With explicit knots
+    >>> basis = rs.bs(x, knots=[2.5, 5.0, 7.5], degree=3)
+    >>> print(basis.shape)
+    (100, 7)
+    
+    >>> # For use in regression with intercept already present
+    >>> X = np.column_stack([np.ones(100), rs.bs(x, df=4)])
+    
+    See Also
+    --------
+    ns : Natural spline basis (linear at boundaries)
+    """
+    # Convert to numpy array
+    x = np.asarray(x, dtype=np.float64).ravel()
+    
+    if knots is not None:
+        # Use explicit knots
+        return _bs_knots_rust(x, knots, degree, boundary_knots)
+    else:
+        # Compute knots automatically based on df
+        return _bs_rust(x, df, degree, boundary_knots, include_intercept)
+
+
+def ns(
+    x: np.ndarray,
+    df: int = 5,
+    knots: Optional[List[float]] = None,
+    boundary_knots: Optional[Tuple[float, float]] = None,
+    include_intercept: bool = False,
+) -> np.ndarray:
+    """
+    Compute natural cubic spline basis matrix.
+    
+    Natural splines are cubic splines with the additional constraint that
+    the function is linear beyond the boundary knots. This constraint:
+    - Reduces the effective degrees of freedom by 2
+    - Provides more sensible extrapolation behavior
+    - Often gives more stable parameter estimates
+    
+    Parameters
+    ----------
+    x : array-like
+        Data points to evaluate the basis at.
+    df : int, default=5
+        Degrees of freedom. The number of basis functions generated
+        will be df (or df-1 if include_intercept=False).
+    knots : list, optional
+        Interior knot positions. If not provided, knots are placed at
+        quantiles of x.
+    boundary_knots : tuple, optional
+        (min, max) defining the boundary. Beyond these points, the
+        spline is constrained to be linear.
+    include_intercept : bool, default=False
+        Whether to include an intercept basis function.
+    
+    Returns
+    -------
+    numpy.ndarray
+        Basis matrix of shape (n, k).
+    
+    Notes
+    -----
+    Natural splines impose the constraint that the second derivative
+    is zero at the boundaries. This means:
+    
+    1. The spline is linear (not curved) outside the boundary knots
+    2. Extrapolation beyond the data range is more sensible
+    3. The fit is often more stable near the boundaries
+    
+    For these reasons, natural splines are often preferred for:
+    - Prediction on new data that may be outside the training range
+    - Actuarial applications where extrapolation is common
+    - When boundary behavior needs to be controlled
+    
+    Examples
+    --------
+    >>> import rustystats as rs
+    >>> import numpy as np
+    >>> 
+    >>> # Basic usage
+    >>> age = np.array([20, 30, 40, 50, 60, 70])
+    >>> basis = rs.ns(age, df=4)
+    >>> print(basis.shape)
+    (6, 3)
+    
+    >>> # For an age effect in a GLM
+    >>> # The spline will be linear for ages below 20 and above 70
+    >>> basis = rs.ns(age, df=4, boundary_knots=(20, 70))
+    
+    See Also
+    --------
+    bs : B-spline basis (more flexible at boundaries)
+    """
+    # Convert to numpy array
+    x = np.asarray(x, dtype=np.float64).ravel()
+    
+    # Natural splines don't support explicit interior knots in our implementation
+    # (knots are computed from df)
+    return _ns_rust(x, df, boundary_knots, include_intercept)
+
+
+def bs_names(
+    var_name: str,
+    df: int,
+    include_intercept: bool = False,
+) -> List[str]:
+    """
+    Generate column names for B-spline basis functions.
+    
+    Parameters
+    ----------
+    var_name : str
+        Name of the original variable (e.g., "age")
+    df : int
+        Degrees of freedom used
+    include_intercept : bool, default=False
+        Whether intercept was included
+    
+    Returns
+    -------
+    list of str
+        Names like ['bs(age, 1/5)', 'bs(age, 2/5)', ...]
+    
+    Example
+    -------
+    >>> rs.bs_names("age", df=5)
+    ['bs(age, 2/5)', 'bs(age, 3/5)', 'bs(age, 4/5)', 'bs(age, 5/5)']
+    """
+    return _bs_names_rust(var_name, df, include_intercept)
+
+
+def ns_names(
+    var_name: str,
+    df: int,
+    include_intercept: bool = False,
+) -> List[str]:
+    """
+    Generate column names for natural spline basis functions.
+    
+    Parameters
+    ----------
+    var_name : str
+        Name of the original variable
+    df : int
+        Degrees of freedom used
+    include_intercept : bool, default=False
+        Whether intercept was included
+    
+    Returns
+    -------
+    list of str
+        Names like ['ns(age, 1/5)', 'ns(age, 2/5)', ...]
+    """
+    return _ns_names_rust(var_name, df, include_intercept)
+
+
+class SplineTerm:
+    """
+    Represents a spline term for use in formula parsing.
+    
+    This class stores the specification for a spline transformation
+    and can compute the basis matrix when given data.
+    
+    Attributes
+    ----------
+    var_name : str
+        Name of the variable to transform
+    spline_type : str
+        Either 'bs' or 'ns'
+    df : int
+        Degrees of freedom
+    degree : int
+        Polynomial degree (for B-splines)
+    boundary_knots : tuple or None
+        Boundary knot positions
+    """
+    
+    def __init__(
+        self,
+        var_name: str,
+        spline_type: str = "bs",
+        df: int = 5,
+        degree: int = 3,
+        boundary_knots: Optional[Tuple[float, float]] = None,
+    ):
+        self.var_name = var_name
+        self.spline_type = spline_type.lower()
+        self.df = df
+        self.degree = degree
+        self.boundary_knots = boundary_knots
+        
+        if self.spline_type not in ("bs", "ns"):
+            raise ValueError(f"spline_type must be 'bs' or 'ns', got '{spline_type}'")
+    
+    def transform(self, x: np.ndarray) -> Tuple[np.ndarray, List[str]]:
+        """
+        Compute the spline basis for the given data.
+        
+        Parameters
+        ----------
+        x : np.ndarray
+            Data values to transform
+        
+        Returns
+        -------
+        basis : np.ndarray
+            Basis matrix
+        names : list of str
+            Column names for the basis
+        """
+        if self.spline_type == "bs":
+            basis = bs(x, df=self.df, degree=self.degree, 
+                      boundary_knots=self.boundary_knots, include_intercept=False)
+            names = bs_names(self.var_name, self.df, include_intercept=False)
+        else:
+            basis = ns(x, df=self.df, boundary_knots=self.boundary_knots,
+                      include_intercept=False)
+            names = ns_names(self.var_name, self.df, include_intercept=False)
+        
+        # Ensure names match columns
+        if len(names) != basis.shape[1]:
+            names = [f"{self.spline_type}({self.var_name}, {i+1}/{basis.shape[1]})" 
+                    for i in range(basis.shape[1])]
+        
+        return basis, names
+    
+    def __repr__(self) -> str:
+        if self.spline_type == "bs":
+            return f"bs({self.var_name}, df={self.df}, degree={self.degree})"
+        else:
+            return f"ns({self.var_name}, df={self.df})"