perpetual

Perpetual includes specialized modules designed for causal inference, treatment effect estimation, and interpretable decision-making. The available solution guides and modules include:

• uplift: For uplift modeling and estimating individual treatment effects.
• dml: Double Machine Learning for causal inference.
• policy: For policy learning and decision optimization.
• iv: Instrumental Variable methods for causal estimation.
• risk: For risk-based causal analysis.
• fairness: For assessing and ensuring fairness in causal models.

The Perpetual ML Suite is a managed ML platform for experiment tracking, metric monitoring, and model drift management.

For a serverless experience, you can use app.perpetual-ml.com, which includes:

• Serverless Marimo Notebooks: Interactive, reactive notebooks without infrastructure management.
• Serverless ML Endpoints: One-click deployment of models as production-ready real-time inference endpoints.

Perpetual is also available as a native application on the Snowflake Marketplace, with upcoming support for Databricks and other major data warehouses.

PerpetualBooster is a gradient boosting machine (GBM) designed to eliminate the need for manual hyperparameter optimization. Instead of tuning multiple parameters, it uses a single budget parameter to control predictive power.

How to use the budget parameter:

• Increasing the budget increases the algorithm's predictive power and performance on unseen data.
• Strategy: Start with a small budget (e.g., 0.5) and increase it (e.g., 1.0) once you are confident in your feature set.
• If increasing the budget no longer yields improvements, you have likely extracted the maximum predictive power available from your data.

model = PerpetualBooster(objective="SquaredLoss", budget=0.5)

The perpetual_r package includes a vendored copy of Rust dependencies located in the src/v directory. This is a deliberate design choice required to ensure successful offline compilation on CRAN and R-universe.

Important: Do not remove the contents of src/v. Removing these dependencies will cause the package build to fail during the CRAN/R-universe check process.

Perpetual detects drift by comparing the distribution of samples across decision tree nodes during training against the distribution observed in new data. It supports two types of drift:

1. Data Drift (Multivariate): Calculates the average Chi-squared statistic across all internal nodes. This detects if feature distributions have shifted in a way that changes the paths samples take through the trees.
2. Concept Drift: Focuses on nodes that are parents of leaves. This detects if the relationship between features and the target is shifting by monitoring changes in final decision-level node distributions.

This method is unsupervised, meaning you do not need target values (y) for the new data to calculate drift scores.

When using continual learning (reset=False), it is critical to provide cumulative data (all data seen so far) to the .fit() method.

Even though the model keeps its existing trees, it uses them to make initial predictions on the provided data and then adds new trees to correct the residuals. If you only provide the new batch of data, the model will focus on minimizing error for that specific batch, which causes it to forget patterns learned from previous batches (catastrophic forgetting).

Perpetual is optimized for high-performance data handling, specifically through a zero-copy interface for columnar data:

• Polars Integration: When using a Polars DataFrame with fit or predict, Perpetual utilizes the fit_columnar path. This allows the Rust core to read the underlying memory buffers of the DataFrame directly, avoiding expensive data copies.
• Numpy/Pandas: Standard Numpy arrays and Pandas DataFrames are supported via a contiguous array interface. Note that these may involve data copying if the input is not already in the required memory layout (e.g., if it is not C-contiguous).

To maximize performance, it is recommended to use Polars DataFrames when passing data to the model.

Perpetual provides standard Meta-Learners for cases requiring more control or simpler algorithms:

• S-Learner: Uses a single model including the treatment as a feature.
• T-Learner: Uses two separate models, one for treatment and one for control.
• X-Learner: A multi-stage learner that is particularly effective when treatment groups are imbalanced.

from perpetual.meta_learners import XLearner

model = XLearner(budget=0.5)
model.fit(X, w, y)
cate = model.predict(X_test)

Double Machine Learning (DML) is a causal inference method designed to handle high-dimensional confounding variables.

In the perpetual implementation, the DMLEstimator follows these core principles:

1. Neyman-orthogonality: It uses a Neyman-orthogonal score to combine estimates, which helps protect the treatment effect estimate from biases in the nuisance parameter models (the models predicting outcome and treatment).
2. Cross-fitting: The estimator uses separate cross-fitted models for the outcome ($y \sim X$) and the treatment assignment ($w \sim X$). This prevents overfitting and ensures that the residuals used for the final effect estimation are not biased by the same data used to train the nuisance models.
3. Gradient Boosting: The underlying models for the nuisance tasks are powered by Gradient Boosting.