Install & Compatibility
Where this runs
tested against v0.11.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 3.308s · 310.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 11.5s · import 3.093s · 298MB
309MB installed
● package 309MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BetaGeoFitter
✓ from lifetimes import BetaGeoFitter
GammaGammaFitter
✓ from lifetimes import GammaGammaFitter
ParetoNBDFitter
✓ from lifetimes import ParetoNBDFitter
summary_data_from_transaction_data
✓ from lifetimes.utils import summary_data_from_transaction_data
plot_period_transactions
✓ from lifetimes.plotting import plot_period_transactions
This quickstart demonstrates how to prepare transaction data into a Recency, Frequency, Monetary (RFM) format using `summary_data_from_transaction_data`, fit a `BetaGeoFitter` model, and then use the fitted model to predict future purchases and calculate the probability of customers being 'alive'.
import pandas as pd
from lifetimes import BetaGeoFitter
from lifetimes.utils import summary_data_from_transaction_data
# Sample transaction data (replace with your actual data)
transactions = pd.DataFrame({
'customer_id': ['A', 'A', 'B', 'B', 'C', 'D'],
'transaction_id': [1, 2, 3, 4, 5, 6],
'date': pd.to_datetime(['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-10', '2023-03-01', '2023-01-05']),
'price': [10.0, 20.0, 15.0, 25.0, 30.0, 5.0]
})
# Convert transaction data to RFM (Recency, Frequency, Monetary) format
# The observation_period_end can be adjusted to your data's last date
rfm_data = summary_data_from_transaction_data(
transactions,
customer_id_col='customer_id',
datetime_col='date',
observation_period_end=pd.to_datetime('2023-03-31')
)
print("RFM Data:\n", rfm_data.head())
# Initialize and fit the BetaGeoFitter model
bgf = BetaGeoFitter(penalizer_coef=0.1) # Add a penalizer for stability
bgf.fit(rfm_data['frequency'], rfm_data['recency'], rfm_data['T'])
print("\nModel Parameters:\n", bgf.params_)
# Predict future purchases for the next 7 periods
# (e.g., if T is in days, this is 7 days)
prediction_days = 7
predicted_purchases = bgf.predict(
prediction_days, rfm_data['frequency'], rfm_data['recency'], rfm_data['T']
)
print(f"\nPredicted purchases in the next {prediction_days} days:\n", predicted_purchases.head())
# Calculate customer probability of being 'alive'
# This is useful for understanding customer churn/retention
alive_prob = bgf.conditional_probability_of_being_alive(
rfm_data['frequency'], rfm_data['recency'], rfm_data['T']
)
print("\nProbability of being alive:\n", alive_prob.head())
Errors
Common errors & fixes
TypeError: fit() got an unexpected keyword argument 'n_custs'
The parameter `n_custs` in `BetaGeoBetaBinomFitter.fit()` was renamed to `weights` in `lifetimes` version 0.10.0.
fixUse `weights` instead of `n_custs` in the call to `fit()`: `model.fit(..., weights=your_weights)`.
ValueError: q must be > 1.0
The `GammaGammaFitter` produced a `q` parameter less than or equal to 1, which leads to an infinite mean. This typically happens with certain dataset distributions.
fixWhen initializing `GammaGammaFitter`, add the `q_constraint=True` argument: `gmf = GammaGammaFitter(q_constraint=True)`. This enforces `q > 1` during the fitting process.
AttributeError: 'Series' object has no attribute 'keys'
Attempting to use `OrderedDict`-specific methods (like `keys()`) on the `params_` attribute of a fitted model. Since version 0.11.0, `params_` is a `pandas.Series`.
fixAccess parameters using `Series` or dictionary-like methods (e.g., `model.params_.index` to get keys, or `model.params_.values` for values). Individual parameters can be accessed like `model.params_['r']` or `model.params_.r`.
KeyError: 'date'
`summary_data_from_transaction_data` expects a column named 'date' (or specified by `datetime_col`) and 'customer_id' (or specified by `customer_id_col`) in the input DataFrame, and they were not found or not correctly specified.
fixEnsure your input DataFrame for `summary_data_from_transaction_data` has a column with transaction dates (e.g., named 'date') and customer identifiers (e.g., 'customer_id'), and these columns are correctly passed to `datetime_col` and `customer_id_col` respectively. Also, ensure the date column is of `datetime` type.
Upgrade
Version history
0.11.3latest on PyPI · released Jul 6, 2020
Audit
Dependencies
pandasrequiredRequired for data manipulation; version >= 0.24.0 since lifetimes 0.11.1.
autogradrequiredUsed for automatic differentiation in model fitting, improving convergence and speed since lifetimes 0.11.0.
scipyrequiredCore numerical computations.
numpyrequiredCore numerical computations.
matplotliboptionalUsed for plotting functionalities.