Linear Regression as Polars Expr

Linear Models Related Queries

Linear Regression Related Expressions in Polars.

Functions:

Name	Description
lin_reg	Computes linear regression solution to the equation Ax = y where y is the target (or multiple targets).
lin_reg_report	Creates an ordinary least square report with more stats about each coefficient.
lin_reg_w_rcond	Uses SVD to compute linear regression. During the process, singular values will be set to 0
logistic_reg	Fits a logistic regression and returns the coefficients. This uses the L-BFGS algorithm as the solver.
recursive_lin_reg	Using the first start_with rows of data as basis, start computing the least square solutions
rolling_lin_reg	Using every window_size rows of data as feature matrix, and computes least square solutions
rolling_lin_reg_1d	Exponentially weighted rolling regression for one predictor and an intercept.
simple_lin_reg	Simple least square with 1 predictive variable and 1 target.

lin_reg(*x, target, add_bias=False, weights=None, return_pred=False, l1_reg=0.0, l2_reg=0.0, tol=1e-05, solver='qr', max_iter=200, null_policy='skip', positive=False, singular_x_tol=None)

Computes linear regression solution to the equation Ax = y where y is the target (or multiple targets). If l1_reg is > 0, then this performs Lasso regression. If l2_reg is > 0, this performs Ridge regression. If both are > 0, then this is elastic net regression. If none of the cases above is true, as is the default case, then a normal regression will be performed.

If add_bias is true, it will be the last coefficient in the output and output will have len(variables) + 1.

If you only want to do simple linear regression (one predictive x variable and one target) and null policy doesn't matter, then simple_lin_reg is a faster alternative.

Parameters:

Name	Type	Description	Default
x	str | Expr	The variables used to predict target	()
target	str | Expr | List[str | Expr]	The target variable, or a list of targets for a multi-target linear regression	required
add_bias	bool	Whether to add a bias term	False
weights	str | Expr | None	Whether to perform a weighted linear regression or not. If this is weighted, then it will ignore l1_reg or l2_reg parameters. This doesn't work if this is multi-target.	None
return_pred	bool	If true, return prediction and residue. If false, return coefficients. Note that for coefficients, it reduces to one output (like max/min), but for predictions and residue, it will return the same number of rows as in input.	False
l1_reg	float	Regularization factor for Lasso. This is ignored if this is multi-target.	0.0
l2_reg	float	Regularization factor for Ridge.	0.0
tol	float	For Lasso or elastic net regression, if maximum coordinate update is < tol, the algorithm is considered to have converged. If not, it will run for at most 2000 iterations. This doesn't work if this is multi-target.	1e-05
solver	LRSolverMethods	Only applies when this is normal or l2 regression. One of ['svd', 'qr']. Both 'svd' and 'qr' can handle rank deficient cases relatively well.	'qr'
max_iter	int	Only used for Non-negative or Elastic net regression. The max iteration for the algorithm.	200
null_policy	NullPolicy	One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target columns. If this is multi-target, fill will fail if there are nulls in any of the targets.	'skip'
positive	bool	If true, this will perform non-negative linear regression. Not used in multi-target case.	False
singular_x_tol	float | None	Rank-deficiency gate for ordinary/ridge regression (solver in ['svd', 'qr', 'cholesky']; not used for non-negative, lasso or elastic net). Lets degenerate designs (perfectly collinear regressors, near-constant windows) return null instead of an arbitrary min-norm or explosive coefficient vector — useful for per-group fits, e.g. group_by(...).agg(lin_reg(...)). The gate fires when the relative determinant |det(XᵀX)| / Π diag(XᵀX) <= singular_x_tol, a scale-invariant rank check. The metric is evaluated in log-space (overflow-safe) and reuses the solver's own factorization; a non-positive diag(XᵀX) (zero-variance column) is always gated. The default (None) is dtype-aware — 1e-12 for f64 and 1e-6 for f32, since f32 cannot resolve a relative determinant below its machine epsilon (~1e-7). Pass 0.0 to disable the gate entirely (restoring the pre-gate behavior of always returning a finite solution).	None

Source code in python/polars_ds/exprs/expr_linear.py

def lin_reg(
    *x: str | pl.Expr,
    target: str | pl.Expr | List[str | pl.Expr],
    add_bias: bool = False,
    weights: str | pl.Expr | None = None,
    return_pred: bool = False,
    l1_reg: float = 0.0,
    l2_reg: float = 0.0,
    tol: float = 1e-5,
    solver: LRSolverMethods = "qr",
    max_iter: int = 200,
    null_policy: NullPolicy = "skip",
    positive: bool = False,
    singular_x_tol: float | None = None,
) -> pl.Expr:
    """
    Computes linear regression solution to the equation Ax = y where y is the target (or multiple targets).
    If l1_reg is > 0, then this performs Lasso regression. If l2_reg is > 0, this performs Ridge regression.
    If both are > 0, then this is elastic net regression. If none of the cases above is true, as is the default case,
    then a normal regression will be performed.

    If add_bias is true, it will be the last coefficient in the output and output will have len(variables) + 1.

    If you only want to do simple linear regression (one predictive x variable and one target) and null policy doesn't
    matter, then `simple_lin_reg` is a faster alternative.

    Parameters
    ----------
    x
        The variables used to predict target
    target
        The target variable, or a list of targets for a multi-target linear regression
    add_bias
        Whether to add a bias term
    weights
        Whether to perform a weighted linear regression or not. If this is weighted, then it will ignore
        l1_reg or l2_reg parameters. This doesn't work if this is multi-target.
    return_pred
        If true, return prediction and residue. If false, return coefficients. Note that
        for coefficients, it reduces to one output (like max/min), but for predictions and
        residue, it will return the same number of rows as in input.
    l1_reg
        Regularization factor for Lasso. This is ignored if this is multi-target.
    l2_reg
        Regularization factor for Ridge.
    tol
        For Lasso or elastic net regression, if maximum coordinate update is < tol, the algorithm is considered
        to have converged. If not, it will run for at most 2000 iterations. This doesn't work if this is multi-target.
    solver
        Only applies when this is normal or l2 regression. One of ['svd', 'qr'].
        Both 'svd' and 'qr' can handle rank deficient cases relatively well.
    max_iter
        Only used for Non-negative or Elastic net regression. The max iteration for the algorithm.
    null_policy: Literal['raise', 'skip', 'zero', 'one', 'ignore']
        One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to
        fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if
        the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target
        columns. If this is multi-target, fill will fail if there are nulls in any of the targets.
    positive
        If true, this will perform non-negative linear regression. Not used in multi-target case.
    singular_x_tol
        Rank-deficiency gate for ordinary/ridge regression (solver in ['svd', 'qr', 'cholesky'];
        not used for non-negative, lasso or elastic net). Lets degenerate designs (perfectly
        collinear regressors, near-constant windows) return null instead of an arbitrary min-norm
        or explosive coefficient vector — useful for per-group fits, e.g.
        `group_by(...).agg(lin_reg(...))`. The gate fires when the relative determinant
        `|det(XᵀX)| / Π diag(XᵀX) <= singular_x_tol`, a scale-invariant rank check. The metric
        is evaluated in log-space (overflow-safe) and reuses the solver's own factorization;
        a non-positive `diag(XᵀX)` (zero-variance column) is always gated. The default (`None`)
        is dtype-aware — `1e-12` for f64 and `1e-6` for f32, since f32 cannot resolve a relative
        determinant below its machine epsilon (~1e-7). Pass `0.0` to disable the gate entirely
        (restoring the pre-gate behavior of always returning a finite solution).
    """

    if cfg.LIN_REG_EXPR_F64:
        dtype = pl.Float64
    else:
        dtype = pl.Float32

    if singular_x_tol is None:
        # f32 can't resolve below ~machine eps (1e-7); use a coarser singular floor.
        singular_x_tol = 1e-12 if cfg.LIN_REG_EXPR_F64 else 1e-6

    if isinstance(target, list):
        n_targets = len(target)
        if n_targets == 0:
            raise ValueError("If `target` is a list, it cannot be empty.")
        elif n_targets == 1:
            return lin_reg(
                *x,
                target=target[0],
                add_bias=add_bias,
                weights=weights,
                return_pred=return_pred,
                l1_reg=l1_reg,
                l2_reg=l2_reg,
                tol=tol,
                solver=solver,
                null_policy=null_policy,
                singular_x_tol=singular_x_tol,
            )
        else:
            cols = [lr_formula(t).alias(f"target_{i}").cast(dtype) for i, t in enumerate(target)]
            multi_target_lr_kwargs = {
                "bias": add_bias,
                "null_policy": null_policy,
                "solver": solver,
                "last_target_idx": n_targets,
                "l2_reg": l2_reg,
                "singular_x_tol": singular_x_tol,
            }
            cols.extend(lr_formula(z) for z in x)
            if return_pred:
                return pl_plugin(
                    symbol=cfg._which_lin_reg("pl_lr_multi_pred"),
                    args=cols,
                    kwargs=multi_target_lr_kwargs,
                    pass_name_to_apply=True,
                ).alias("lr_pred")
            else:
                return pl_plugin(
                    symbol=cfg._which_lin_reg("pl_lr_multi"),
                    args=cols,
                    kwargs=multi_target_lr_kwargs,
                    returns_scalar=True,
                    pass_name_to_apply=True,
                ).alias("coeffs")
    else:
        if max_iter <= 0:
            raise ValueError("Input `max_iter` must be a positive.")

        weighted = weights is not None
        lr_kwargs = {
            "bias": add_bias,
            "null_policy": null_policy,
            "l1_reg": l1_reg,
            "l2_reg": l2_reg,
            "solver": solver,
            "tol": tol,
            "max_iter": max_iter,
            "weighted": weighted,
            "positive": positive,
            "singular_x_tol": singular_x_tol,
        }

        if weighted:
            cols = [
                lr_formula(weights).cast(dtype).rechunk(),
                lr_formula(target).cast(dtype),
            ]
        else:
            cols = [lr_formula(target).cast(dtype)]

        cols.extend(lr_formula(z) for z in x)

        if return_pred:
            return pl_plugin(
                symbol=cfg._which_lin_reg("pl_lr_pred"),
                args=cols,
                kwargs=lr_kwargs,
                pass_name_to_apply=True,
            ).alias("lr_pred")
        else:
            return pl_plugin(
                symbol=cfg._which_lin_reg("pl_lr"),
                args=cols,
                kwargs=lr_kwargs,
                returns_scalar=True,
                pass_name_to_apply=True,
            ).alias("coeffs")

lin_reg_report(*x, target, weights=None, add_bias=False, null_policy='raise', std_err='se')

Creates an ordinary least square report with more stats about each coefficient.

Note: if columns are not linearly independent, some numerical issue may occur. This uses the closed form solution to compute the least square report.

Parameters:

Name	Type	Description	Default
x	str | Expr	The variables used to predict target	()
target	str | Expr	The target variable	required
weights	str | Expr | None	If not None, this will then compute the stats for a weights least square.	None
add_bias	bool	Whether to add a bias term. If bias is added, it is always the last feature.	False
null_policy	NullPolicy	One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target columns.	'raise'
std_err	Literal['se', 'hc0', 'hc1', 'hc2', 'hc3']	One of "se", "hc0", "hc1", "hc2", "hc3", where "se" means we compute the standard error under the assumption of homoskedasticity, and the hc options are different options for heteroskedasticity. The hc0-hc3 are called Heteroskedasticity-Consistent Standard Errors, and their formulas can be found here: https://jslsoc.sitehost.iu.edu/files_research/testing_tests/hccm/00TAS.pdf. This won't be used if weights are used (The author is not super familiar with the theory). If any other string is provided, it will default to "se".	'se'

Source code in python/polars_ds/exprs/expr_linear.py

def lin_reg_report(
    *x: str | pl.Expr,
    target: str | pl.Expr,
    weights: str | pl.Expr | None = None,
    add_bias: bool = False,
    null_policy: NullPolicy = "raise",
    std_err: Literal["se", "hc0", "hc1", "hc2", "hc3"] = "se",
) -> pl.Expr:
    """
    Creates an ordinary least square report with more stats about each coefficient.

    Note: if columns are not linearly independent, some numerical issue may occur. This uses
    the closed form solution to compute the least square report.

    Parameters
    ----------
    x
        The variables used to predict target
    target
        The target variable
    weights
        If not None, this will then compute the stats for a weights least square.
    add_bias
        Whether to add a bias term. If bias is added, it is always the last feature.
    null_policy: Literal['raise', 'skip', 'zero', 'one', 'ignore']
        One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to
        fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if
        the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target
        columns.
    std_err
        One of "se", "hc0", "hc1", "hc2", "hc3", where "se" means we compute the standard error
        under the assumption of homoskedasticity, and the hc options are different options for
        heteroskedasticity. The hc0-hc3 are called Heteroskedasticity-Consistent Standard Errors, and their
        formulas can be found here: https://jslsoc.sitehost.iu.edu/files_research/testing_tests/hccm/00TAS.pdf.
        This won't be used if weights are used (The author is not super familiar with the theory). If any other
        string is provided, it will default to "se".
    """

    lr_kwargs = {
        "bias": add_bias,
        "null_policy": null_policy,
        "l1_reg": 0.0,
        "l2_reg": 0.0,
        "solver": "qr",
        "tol": 0.0,
        "std_err": std_err.lower(),
    }

    if cfg.LIN_REG_EXPR_F64:
        dtype = pl.Float64
    else:
        dtype = pl.Float32

    t = lr_formula(target).cast(dtype)
    if weights is None:
        cols = [t.var(), t]
        cols.extend(lr_formula(z) for z in x)
        symbol = cfg._which_lin_reg("pl_lin_reg_report")
    else:
        w = lr_formula(weights)
        cols = [w.cast(dtype).rechunk(), t.var(), t]
        cols.extend(lr_formula(z) for z in x)
        symbol = cfg._which_lin_reg("pl_wls_report")

    return pl_plugin(
        symbol=symbol,
        args=cols,
        kwargs=lr_kwargs,
        changes_length=True,
        pass_name_to_apply=True,
    )

lin_reg_w_rcond(*x, target, add_bias=False, rcond=0.0, l2_reg=0.0, null_policy='raise')

Uses SVD to compute linear regression. During the process, singular values will be set to 0 if it is smaller than rcond * max singular value (of X). This will return the coefficients as well as singular values of X as the output. The number of nonzero singular values is the rank of X.

Note: the singular values return will be the values before applying the rcond cut off.

Parameters:

Name	Type	Description	Default
x	str | Expr	The variables used to predict target	()
target	str | Expr	The target variable	required
add_bias	bool	Whether to add a bias term	False
rcond	float	Cut-off ratio for small singular values. If rcond < machine precision * MAX(M,N), it will be set to machine precision * MAX(M,N).	0.0
l2_reg	float	The L2 regularization factor. If this is > 0, then a Ridge regression will be performed.	0.0
null_policy	NullPolicy	One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target columns.	'raise'

Source code in python/polars_ds/exprs/expr_linear.py

def lin_reg_w_rcond(
    *x: str | pl.Expr,
    target: str | pl.Expr,
    add_bias: bool = False,
    rcond: float = 0.0,
    l2_reg: float = 0.0,
    null_policy: NullPolicy = "raise",
) -> pl.Expr:
    """
    Uses SVD to compute linear regression. During the process, singular values will be set to 0
    if it is smaller than rcond * max singular value (of X). This will return the coefficients as well
    as singular values of X as the output. The number of nonzero singular values is the rank of X.

    Note: the singular values return will be the values before applying the rcond cut off.

    Parameters
    ----------
    x
        The variables used to predict target
    target
        The target variable
    add_bias
        Whether to add a bias term
    rcond
        Cut-off ratio for small singular values. If rcond < machine precision * MAX(M,N),
        it will be set to machine precision * MAX(M,N).
    l2_reg
        The L2 regularization factor. If this is > 0, then a Ridge regression will be performed.
    null_policy: Literal['raise', 'skip', 'zero', 'one', 'ignore']
        One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to
        fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if
        the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target
        columns.
    """
    if cfg.LIN_REG_EXPR_F64:
        dtype = pl.Float64
    else:
        dtype = pl.Float32

    cols = [lr_formula(target).cast(dtype)]
    cols.extend(lr_formula(z) for z in x)
    lr_kwargs = {
        "bias": add_bias,
        "null_policy": null_policy,
        "l1_reg": 0.0,
        "l2_reg": l2_reg,
        "solver": "",
        "tol": abs(rcond),
    }
    return pl_plugin(
        symbol=cfg._which_lin_reg("pl_lr_w_rcond"),
        args=cols,
        kwargs=lr_kwargs,
        pass_name_to_apply=True,
    )

logistic_reg(*x, target, add_bias=True, l1_reg=0.0, l2_reg=0.0, tol=1e-05, max_iter=200, null_policy='skip', return_pred=False)

Fits a logistic regression and returns the coefficients. This uses the L-BFGS algorithm as the solver. This does a data copy internally.

Only supports binary target and the target must be 0s and 1s and the user must ensure this. Otherwise, the output will be nonsensical.

If add_bias is true and return_pred is False, the bias term will be the last coefficient in the output and output will have len(variables) + 1.

Note: This is meant to be a quick logistic regression check and will not persist the model. You have to manually save the coefficents elsewhere.

Parameters:

Name	Type	Description	Default
x	str | Expr	The variables used to predict target	()
target	str | Expr	The target variable, or a list of targets for a multi-target linear regression	required
add_bias	bool	Whether to add a bias term	True
l1_reg	float	L1 regularization term. If this is > 0, it will switch to OWL-QN method.	0.0
l2_reg	float	L2 regularization factor.	0.0
null_policy	NullPolicy	One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target columns.	'skip'
tol	float	The algorithm stops if the norm of the gradient is < tol.	1e-05
max_iter	int	Max iter for the algorithm.	200
return_pred	bool	If true, this will return a column of predicted probabilities. If false, this will return the coefficients.	False

Source code in python/polars_ds/exprs/expr_linear.py

def logistic_reg(
    *x: str | pl.Expr,
    target: str | pl.Expr,
    add_bias: bool = True,
    l1_reg: float = 0.0,
    l2_reg: float = 0.0,
    tol: float = 1e-5,
    max_iter: int = 200,
    null_policy: NullPolicy = "skip",
    return_pred: bool = False,
) -> pl.Expr:
    """
    Fits a logistic regression and returns the coefficients. This uses the L-BFGS algorithm as the solver.
    This does a data copy internally.

    Only supports binary target and the target must be 0s and 1s and the user must ensure this. Otherwise,
    the output will be nonsensical.

    If add_bias is true and return_pred is False, the bias term will be the last coefficient in the output
    and output will have len(variables) + 1.

    Note: This is meant to be a quick logistic regression check and will not persist the model. You have to
    manually save the coefficents elsewhere.

    Parameters
    ----------
    x
        The variables used to predict target
    target
        The target variable, or a list of targets for a multi-target linear regression
    add_bias
        Whether to add a bias term
    l1_reg
        L1 regularization term. If this is > 0, it will switch to OWL-QN method.
    l2_reg
        L2 regularization factor.
    null_policy: Literal['raise', 'skip', 'zero', 'one', 'ignore']
        One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to
        fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if
        the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target
        columns.
    tol
        The algorithm stops if the norm of the gradient is < tol.
    max_iter
        Max iter for the algorithm.
    return_pred
        If true, this will return a column of predicted probabilities. If false, this will return
        the coefficients.
    """
    if max_iter <= 0:
        raise ValueError("Input `max_iter` must be a positive.")

    lr_kwargs = {
        "bias": add_bias,
        "null_policy": null_policy,
        "l1_reg": l1_reg,
        "l2_reg": l2_reg,
        "solver": "",
        "tol": abs(tol),
        "max_iter": max_iter,
    }
    cols = [lr_formula(target).cast(pl.Float64)]
    cols.extend(lr_formula(z) for z in x)
    if return_pred:
        return pl_plugin(
            symbol="pl_logistic_pred",
            args=cols,
            kwargs=lr_kwargs,
            pass_name_to_apply=True,
        ).alias("__pred__")
    else:
        return pl_plugin(
            symbol="pl_logistic_coeffs",
            args=cols,
            kwargs=lr_kwargs,
            pass_name_to_apply=True,
        ).alias("__coeffs__")

recursive_lin_reg(*x, target, start_with, add_bias=False, l2_reg=0.0, null_policy='raise')

Using the first start_with rows of data as basis, start computing the least square solutions by updating the betas per row. A prediction for that row will also be included in the output. This uses the famous Sherman-Morrison-Woodbury Formula under the hood.

Note: You have to be careful about the order of data when using this in aggregation contexts.

Parameters:

Name	Type	Description	Default
x	str | Expr	The variables used to predict target	()
target	str | Expr	The target variable	required
start_with	int	Must be >= 1. You start_with n rows of data to train the first linear regression. If start_with = N, the first N-1 rows will be null. If you start with N < # features, result will be numerically very unstable and potentially wrong.	required
add_bias	bool	Whether to add a bias term	False
l2_reg	float	The L2 regularization factor. If this is > 0, then a Ridge regression will be performed.	0.0
null_policy	NullPolicy	One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target columns. If null_policy is skip or fill, and nulls exist, it will keep skipping until we have scanned start_at many valid rows. And if subsequently we get a row with null values, then null will be returned for that row.	'raise'

Source code in python/polars_ds/exprs/expr_linear.py

def recursive_lin_reg(
    *x: str | pl.Expr,
    target: str | pl.Expr,
    start_with: int,
    add_bias: bool = False,
    l2_reg: float = 0.0,
    null_policy: NullPolicy = "raise",
) -> pl.Expr:
    """
    Using the first `start_with` rows of data as basis, start computing the least square solutions
    by updating the betas per row. A prediction for that row will also be included in the output.
    This uses the famous Sherman-Morrison-Woodbury Formula under the hood.

    Note: You have to be careful about the order of data when using this in aggregation contexts.

    Parameters
    ----------
    x:
        The variables used to predict target
    target:
        The target variable
    start_with:
        Must be >= 1. You `start_with` n rows of data to train the first linear regression. If `start_with` = N,
        the first N-1 rows will be null. If you start with N < # features, result will be numerically very
        unstable and potentially wrong.
    add_bias
        Whether to add a bias term
    l2_reg
        The L2 regularization factor. If this is > 0, then a Ridge regression will be performed.
    null_policy: Literal['raise', 'skip', 'zero', 'one', 'ignore']
        One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to
        fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: if
        the target column has null, the rows with nulls will always be dropped. Null-fill only applies to non-target
        columns. If null_policy is `skip` or `fill`, and nulls exist, it will keep skipping until we have
        scanned `start_at` many valid rows. And if subsequently we get a row with null values, then null will
        be returned for that row.
    """

    if cfg.LIN_REG_EXPR_F64:
        dtype = pl.Float64
    else:
        dtype = pl.Float32

    if start_with < 1:
        raise ValueError("You must start with >= 1 rows for recursive linear regression.")

    cols = [lr_formula(target).cast(dtype)]
    features = [lr_formula(z) for z in x]
    if len(features) > start_with:
        warnings.warn(
            "# features > number of rows for the initial fit. Outputs may be off.", stacklevel=2
        )

    cols.extend(features)
    kwargs = {
        "null_policy": null_policy,
        "n": start_with,
        "bias": add_bias,
        "lambda": abs(l2_reg),
        "min_size": 0,  # Not used for recursive
    }
    return pl_plugin(
        symbol=cfg._which_lin_reg("pl_recursive_lr"),
        args=cols,
        kwargs=kwargs,
        pass_name_to_apply=True,
    )

rolling_lin_reg(*x, target, window_size, add_bias=False, l2_reg=0.0, min_valid_rows=None, null_policy='raise', half_life=None)

Using every window_size rows of data as feature matrix, and computes least square solutions by rolling the window. A prediction for that row will also be included in the output. Without exponential weighting, this uses the Sherman-Morrison-Woodbury formula. With half_life, it updates weighted cross-products with periodic rebuilding.

Input order is preserved. Sort data before applying the expression in grouped contexts.

Parameters:

Name	Type	Description	Default
x	str | Expr	The variables used to predict target	()
target	str | Expr	The target variable	required
window_size	int	Must be >= 2. Window size for the rolling regression	required
add_bias	bool	Whether to add a bias term	False
l2_reg	float	The L2 regularization factor. If this is > 0, then a Ridge regression will be performed.	0.0
min_valid_rows	int | None	Minimum number of valid rows to evaluate the model. This is only used when null policy is skip. E.g. if there are nulls in the windows, the window must have at least min_valid_rows valid rows in order to produce a result. Otherwise, null will be returned.	None
null_policy	NullPolicy	One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: For rolling linear regression, null-fill only works when target doesn't have nulls, and WILL NOT drop rows where the target is null.	'raise'
half_life	float | None	Optional positive, finite half-life for exponentially weighted least squares. Measured in original row positions within each group. An observation of age a has weight 2 ** (-a / half_life). Only the last window_size rows, including the current row, contribute. None preserves the existing behavior. Exponential weighting currently requires l2_reg=0 and null_policy equal to 'skip' or 'raise'; unsupported combinations raise ValueError.	None

Notes

With exponential weighting, 'skip' excludes a row if any predictor or target is null, NaN or infinite, while retaining its window position and age. 'raise' rejects any such row, including during warm-up. A fit requires at least min_valid_rows valid observations and enough independent observations for all coefficients, including the intercept. With min_valid_rows=None, the default is the number of predictors (at least one). The first window_size - 1 rows always have null fields; a smaller minimum does not enable partial windows. Empty inputs return empty outputs, and groups shorter than the window return only null fields. Sorting is the caller's responsibility; each group is independent.

Output remains a struct with coeffs (intercept last) and pred. Insufficient or numerically degenerate windows have null fields and can recover in later windows. A missing current target does not prevent prediction when current predictors are valid. Any invalid current predictor makes pred null. The prediction uses the current window's coefficients, including the current target when it is valid.

Accumulation, solving and outputs follow LIN_REG_EXPR_F64. As in lin_reg, a relative Gram determinant at or below 1e-12 (Float64) or 1e-6 (Float32) is treated as numerically degenerate. Weights are normalized to the newest valid observation to avoid underflow during missing stretches. Extremely small half-lives can still underflow older weights relative to newer valid observations. See maths/rolling_ewls.md in the repository for the recurrence, numerical safeguards and complexity.

Examples:

>>> panel.sort(["asset", "date"]).with_columns(
...     rolling_lin_reg(
...         "market_return",
...         target="stock_return",
...         window_size=504,
...         half_life=126.0,
...         min_valid_rows=126,
...         add_bias=True,
...         null_policy="skip",
...     )
...     .over("asset")
...     .alias("fit")
... )

Source code in python/polars_ds/exprs/expr_linear.py

def rolling_lin_reg(
    *x: str | pl.Expr,
    target: str | pl.Expr,
    window_size: int,
    add_bias: bool = False,
    l2_reg: float = 0.0,
    min_valid_rows: int | None = None,
    null_policy: NullPolicy = "raise",
    half_life: float | None = None,
) -> pl.Expr:
    """
    Using every `window_size` rows of data as feature matrix, and computes least square solutions
    by rolling the window. A prediction for that row will also be included in the output.
    Without exponential weighting, this uses the Sherman-Morrison-Woodbury formula.
    With `half_life`, it updates weighted cross-products with periodic rebuilding.

    Input order is preserved. Sort data before applying the expression in grouped contexts.

    Parameters
    ----------
    x
        The variables used to predict target
    target
        The target variable
    window_size
        Must be >= 2. Window size for the rolling regression
    add_bias
        Whether to add a bias term
    l2_reg
        The L2 regularization factor. If this is > 0, then a Ridge regression will be performed.
    min_valid_rows
        Minimum number of valid rows to evaluate the model. This is only used when null policy is `skip`. E.g.
        if there are nulls in the windows, the window must have at least `min_valid_rows` valid rows in order to
        produce a result. Otherwise, null will be returned.
    null_policy: Literal['raise', 'skip', 'zero', 'one', 'ignore']
        One of options shown here, but you can also pass in any numeric string. E.g you may pass '1.25' to
        fill nulls with 1.25. If the string cannot be converted to a float, an error will be thrown. Note: For
        rolling linear regression, null-fill only works when target doesn't have nulls, and WILL NOT drop rows where the
        target is null.
    half_life
        Optional positive, finite half-life for exponentially weighted least squares.
        Measured in original row positions within each group. An observation of age
        `a` has weight `2 ** (-a / half_life)`. Only the last `window_size` rows,
        including the current row, contribute. `None` preserves the existing behavior.
        Exponential weighting currently requires `l2_reg=0` and `null_policy` equal
        to 'skip' or 'raise'; unsupported combinations raise ValueError.

    Notes
    -----
    With exponential weighting, 'skip' excludes a row if any predictor or target is
    null, NaN or infinite, while retaining its window position and age. 'raise'
    rejects any such row, including during warm-up. A fit requires at least
    `min_valid_rows` valid observations and enough independent observations for all
    coefficients, including the intercept. With `min_valid_rows=None`, the default
    is the number of predictors (at least one). The first `window_size - 1` rows
    always have null fields; a smaller minimum does not enable partial windows.
    Empty inputs return empty outputs, and groups shorter than the window return
    only null fields. Sorting is the caller's responsibility; each group is independent.

    Output remains a struct with `coeffs` (intercept last) and `pred`. Insufficient or
    numerically degenerate windows have null fields and can recover in later windows.
    A missing current target does not prevent prediction when current predictors are
    valid. Any invalid current predictor makes `pred` null. The prediction uses the
    current window's coefficients, including the current target when it is valid.

    Accumulation, solving and outputs follow `LIN_REG_EXPR_F64`. As in `lin_reg`, a relative Gram determinant
    at or below 1e-12 (Float64) or 1e-6 (Float32) is treated as numerically degenerate.
    Weights are normalized to the newest valid observation to avoid underflow
    during missing stretches. Extremely small half-lives can still underflow
    older weights relative to newer valid observations. See `maths/rolling_ewls.md`
    in the repository for the recurrence, numerical safeguards and complexity.

    Examples
    --------
    >>> panel.sort(["asset", "date"]).with_columns(  # doctest: +SKIP
    ...     rolling_lin_reg(
    ...         "market_return",
    ...         target="stock_return",
    ...         window_size=504,
    ...         half_life=126.0,
    ...         min_valid_rows=126,
    ...         add_bias=True,
    ...         null_policy="skip",
    ...     )
    ...     .over("asset")
    ...     .alias("fit")
    ... )
    """

    if cfg.LIN_REG_EXPR_F64:
        dtype = pl.Float64
    else:
        dtype = pl.Float32

    if window_size < 2:
        raise ValueError("`window_size` must be >= 2.")

    if half_life is not None:
        if not math.isfinite(half_life) or half_life <= 0:
            raise ValueError("`half_life` must be positive and finite.")
        if l2_reg != 0:
            raise ValueError("Exponentially weighted rolling regression requires `l2_reg=0`.")
        if null_policy.lower() not in ("skip", "raise"):
            raise ValueError("EWLS supports only `null_policy='skip'` or 'raise'.")
        if min_valid_rows is not None and not 1 <= min_valid_rows <= window_size:
            raise ValueError("EWLS requires 1 <= min_valid_rows <= window_size.")
        if not x and not add_bias:
            raise ValueError("EWLS requires a predictor or an intercept.")

        if len(x) == 1 and add_bias and null_policy.lower() == "skip":
            return rolling_lin_reg_1d(
                x[0],
                target=target,
                window_size=window_size,
                half_life=half_life,
                min_valid_rows=min_valid_rows,
            )

    cols = [lr_formula(target).cast(dtype)]
    features = [lr_formula(z) for z in x]
    if len(features) > window_size:
        raise ValueError("# features > window size. Linear regression is not well-defined.")

    if min_valid_rows is None:
        min_size = min(len(features), window_size)
    else:
        if min_valid_rows < len(features):
            warnings.warn(
                "# features > min_window_size. Linear regression may not always be well-defined.",
                stacklevel=2,
            )
        min_size = min_valid_rows

    cols.extend(features)
    kwargs = {
        "null_policy": null_policy,
        "n": window_size,
        "bias": add_bias,
        "lambda": abs(l2_reg),
        "min_size": min_size,
    }
    if half_life is not None:
        kwargs["half_life"] = float(half_life)
        kwargs["min_size"] = max(1, min_size)
    return pl_plugin(
        symbol=cfg._which_lin_reg("pl_rolling_lr"),
        args=cols,
        kwargs=kwargs,
        pass_name_to_apply=True,
    )

rolling_lin_reg_1d(x, *, target, window_size, half_life, min_valid_rows=None)

Exponentially weighted rolling regression for one predictor and an intercept.

This specialized implementation uses a staged Polars plan inside the plugin and closed-form scalar formulas. Apply .over(...) to the returned expression for grouped data, after sorting each group into the intended rolling order.

Rows where either input is null, NaN or infinite are excluded from the fit but retain their position and age in the window. The first window_size - 1 outputs are null. A missing current target does not prevent prediction, while an invalid current predictor makes the prediction null.

The output is a struct with coeffs (slope followed by intercept) and pred, matching :func:rolling_lin_reg. This path deliberately supports only the one-predictor, intercept, exponentially weighted skip case.

Parameters:

Name	Type	Description	Default
x	str | Expr	The single predictor.	required
target	str | Expr	The target variable.	required
window_size	int	Number of original row positions in each rolling window. Must be at least 2.	required
half_life	float	Positive, finite exponential-weight half-life, measured in row positions.	required
min_valid_rows	int | None	Minimum valid observations required. Defaults to 2.	None

Examples:

>>> panel.sort(["asset", "date"]).with_columns(
...     rolling_lin_reg_1d(
...         "market_return",
...         target="stock_return",
...         window_size=504,
...         half_life=126.0,
...         min_valid_rows=126,
...     ).over("asset").alias("fit")
... )

Source code in python/polars_ds/exprs/expr_linear.py

def rolling_lin_reg_1d(
    x: str | pl.Expr,
    *,
    target: str | pl.Expr,
    window_size: int,
    half_life: float,
    min_valid_rows: int | None = None,
) -> pl.Expr:
    """Exponentially weighted rolling regression for one predictor and an intercept.

    This specialized implementation uses a staged Polars plan inside the plugin
    and closed-form scalar formulas. Apply ``.over(...)`` to the returned expression
    for grouped data, after sorting each group into the intended rolling order.

    Rows where either input is null, NaN or infinite are excluded from the fit but
    retain their position and age in the window. The first ``window_size - 1``
    outputs are null. A missing current target does not prevent prediction, while
    an invalid current predictor makes the prediction null.

    The output is a struct with ``coeffs`` (slope followed by intercept) and
    ``pred``, matching :func:`rolling_lin_reg`. This path deliberately supports
    only the one-predictor, intercept, exponentially weighted ``skip`` case.

    Parameters
    ----------
    x
        The single predictor.
    target
        The target variable.
    window_size
        Number of original row positions in each rolling window. Must be at least 2.
    half_life
        Positive, finite exponential-weight half-life, measured in row positions.
    min_valid_rows
        Minimum valid observations required. Defaults to 2.

    Examples
    --------
    >>> panel.sort(["asset", "date"]).with_columns(  # doctest: +SKIP
    ...     rolling_lin_reg_1d(
    ...         "market_return",
    ...         target="stock_return",
    ...         window_size=504,
    ...         half_life=126.0,
    ...         min_valid_rows=126,
    ...     ).over("asset").alias("fit")
    ... )
    """
    if window_size < 2:
        raise ValueError("`window_size` must be >= 2.")
    if not math.isfinite(half_life) or half_life <= 0:
        raise ValueError("`half_life` must be positive and finite.")
    if min_valid_rows is None:
        min_valid_rows = 2
    if not 1 <= min_valid_rows <= window_size:
        raise ValueError("`min_valid_rows` must be between 1 and `window_size`.")

    kwargs = {
        "null_policy": "skip",
        "n": window_size,
        "bias": True,
        "lambda": 0.0,
        "min_size": min_valid_rows,
        "half_life": float(half_life),
    }
    dtype = pl.Float64 if cfg.LIN_REG_EXPR_F64 else pl.Float32
    return pl_plugin(
        symbol=cfg._which_lin_reg("pl_rolling_lr_1d_expr"),
        args=[lr_formula(target).cast(dtype), lr_formula(x).cast(dtype)],
        kwargs=kwargs,
        pass_name_to_apply=True,
    )

simple_lin_reg(x, target, add_bias=False, weights=None, return_pred=False)

Simple least square with 1 predictive variable and 1 target.

Parameters:

Name	Type	Description	Default
x	str | Expr	The variables used to predict target	required
target	str | Expr	The target variable	required
add_bias	bool	Whether to add a bias term	False
weights	str | Expr | None	Whether to perform a weighted linear regression or not.	None
return_pred	bool	If true, return prediction and residue. If false, return coefficients. Note that for coefficients, it reduces to one output (like max/min), but for predictions and residue, it will return the same number of rows as in input.	False

Source code in python/polars_ds/exprs/expr_linear.py

def simple_lin_reg(
    x: str | pl.Expr,
    target: str | pl.Expr,
    add_bias: bool = False,
    weights: str | pl.Expr | None = None,
    return_pred: bool = False,
) -> pl.Expr:
    """
    Simple least square with 1 predictive variable and 1 target.

    Parameters
    ----------
    x
        The variables used to predict target
    target
        The target variable
    add_bias
        Whether to add a bias term
    weights
        Whether to perform a weighted linear regression or not.
    return_pred
        If true, return prediction and residue. If false, return coefficients. Note that
        for coefficients, it reduces to one output (like max/min), but for predictions and
        residue, it will return the same number of rows as in input.
    """
    # No test. All forumla here are mathematically correct.
    xx = lr_formula(x)
    yy = lr_formula(target)
    if add_bias:
        if weights is None:
            x_mean = xx.mean()
            y_mean = yy.mean()
            beta = (xx - x_mean).dot(yy - y_mean) / (xx - x_mean).dot(xx - x_mean)
            alpha = y_mean - beta * x_mean
        else:
            w = lr_formula(weights)
            w_sum = w.sum()
            x_wmean = w.dot(xx) / w_sum
            y_wmean = w.dot(yy) / w_sum
            beta = w.dot((xx - x_wmean) * (yy - y_wmean)) / (w.dot((xx - x_wmean).pow(2)))
            alpha = y_wmean - beta * x_wmean

        if return_pred:
            return pl.struct(pred=beta * xx + alpha, resid=yy - (beta * xx + alpha)).alias(
                "lr_pred"
            )
        else:
            return (beta.append(alpha)).implode().alias("coeffs")
    else:
        if weights is None:
            beta = xx.dot(yy) / xx.dot(xx)
        else:
            w = lr_formula(weights)
            beta = w.dot(xx * yy) / w.dot(xx.pow(2))

        if return_pred:
            return pl.struct(pred=beta * xx, resid=yy - (beta * xx)).alias("lr_pred")
        else:
            return beta.implode().alias("coeffs")