{"id":8277,"library":"lifetimes","title":"Lifetimes","description":"Lifetimes is a Python library for measuring customer lifetime value (CLV) using probabilistic models. It provides implementations of various statistical models like BG/NBD, Pareto/NBD, and Gamma-Gamma, along with utilities for data preparation, fitting, and prediction. The current version is 0.11.3, and it has a moderate release cadence with several updates per year.","status":"active","version":"0.11.3","language":"en","source_language":"en","source_url":"https://github.com/CamDavidsonPilon/lifetimes","tags":["customer lifetime value","clv","marketing analytics","probabilistic models","bayesian","customer retention"],"install":[{"cmd":"pip install lifetimes","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for data manipulation; version >= 0.24.0 since lifetimes 0.11.1.","package":"pandas","optional":false},{"reason":"Used for automatic differentiation in model fitting, improving convergence and speed since lifetimes 0.11.0.","package":"autograd","optional":false},{"reason":"Core numerical computations.","package":"scipy","optional":false},{"reason":"Core numerical computations.","package":"numpy","optional":false},{"reason":"Used for plotting functionalities.","package":"matplotlib","optional":true}],"imports":[{"symbol":"BetaGeoFitter","correct":"from lifetimes import BetaGeoFitter"},{"symbol":"GammaGammaFitter","correct":"from lifetimes import GammaGammaFitter"},{"symbol":"ParetoNBDFitter","correct":"from lifetimes import ParetoNBDFitter"},{"symbol":"summary_data_from_transaction_data","correct":"from lifetimes.utils import summary_data_from_transaction_data"},{"symbol":"plot_period_transactions","correct":"from lifetimes.plotting import plot_period_transactions"}],"quickstart":{"code":"import pandas as pd\nfrom lifetimes import BetaGeoFitter\nfrom lifetimes.utils import summary_data_from_transaction_data\n\n# Sample transaction data (replace with your actual data)\ntransactions = pd.DataFrame({\n    'customer_id': ['A', 'A', 'B', 'B', 'C', 'D'],\n    'transaction_id': [1, 2, 3, 4, 5, 6],\n    'date': pd.to_datetime(['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-10', '2023-03-01', '2023-01-05']),\n    'price': [10.0, 20.0, 15.0, 25.0, 30.0, 5.0]\n})\n\n# Convert transaction data to RFM (Recency, Frequency, Monetary) format\n# The observation_period_end can be adjusted to your data's last date\nrfm_data = summary_data_from_transaction_data(\n    transactions, \n    customer_id_col='customer_id', \n    datetime_col='date',\n    observation_period_end=pd.to_datetime('2023-03-31')\n)\n\nprint(\"RFM Data:\\n\", rfm_data.head())\n\n# Initialize and fit the BetaGeoFitter model\nbgf = BetaGeoFitter(penalizer_coef=0.1) # Add a penalizer for stability\nbgf.fit(rfm_data['frequency'], rfm_data['recency'], rfm_data['T'])\n\nprint(\"\\nModel Parameters:\\n\", bgf.params_)\n\n# Predict future purchases for the next 7 periods\n# (e.g., if T is in days, this is 7 days)\nprediction_days = 7\npredicted_purchases = bgf.predict(\n    prediction_days, rfm_data['frequency'], rfm_data['recency'], rfm_data['T']\n)\n\nprint(f\"\\nPredicted purchases in the next {prediction_days} days:\\n\", predicted_purchases.head())\n\n# Calculate customer probability of being 'alive'\n# This is useful for understanding customer churn/retention\nalive_prob = bgf.conditional_probability_of_being_alive(\n    rfm_data['frequency'], rfm_data['recency'], rfm_data['T']\n)\nprint(\"\\nProbability of being alive:\\n\", alive_prob.head())\n","lang":"python","description":"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'."},"warnings":[{"fix":"Access parameters using dictionary-like or attribute access suitable for a Pandas Series (e.g., `model.params_['r']` or `model.params_.r`) instead of methods exclusive to `OrderedDict`.","message":"Since version 0.11.0, the `params_` attribute on fitted models (e.g., `BetaGeoFitter.params_`) is no longer an `OrderedDict` but a `pandas.Series`. Code expecting `OrderedDict`-specific methods or behavior (e.g., `keys()`, `values()` in a specific order) will break.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Replace `n_custs` with `weights` when calling `BetaGeoBetaBinomFitter.fit()`.","message":"In `BetaGeoBetaBinomFitter.fit()`, the parameter `n_custs` was renamed to `weights` in version 0.10.0 to align with other statistical libraries. Using `n_custs` will result in a `TypeError`.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Initialize `GammaGammaFitter` with `q_constraint=True` (e.g., `GammaGammaFitter(q_constraint=True)`) to ensure `q` remains greater than 1 during fitting, which was introduced in 0.10.1 to address this issue.","message":"The `GammaGammaFitter` can produce an infinite mean for certain datasets if its `q` parameter converges to a value less than 1. This can lead to nonsensical CLV predictions.","severity":"gotcha","affected_versions":">=0.10.1"},{"fix":"Ensure your Pandas installation is up-to-date by running `pip install \"pandas>=0.24.0\"`.","message":"The minimum required version for Pandas increased to `pandas>=0.24.0` as of `lifetimes` version 0.11.1. Older Pandas versions may cause unexpected errors or compatibility issues.","severity":"breaking","affected_versions":">=0.11.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use `weights` instead of `n_custs` in the call to `fit()`: `model.fit(..., weights=your_weights)`.","cause":"The parameter `n_custs` in `BetaGeoBetaBinomFitter.fit()` was renamed to `weights` in `lifetimes` version 0.10.0.","error":"TypeError: fit() got an unexpected keyword argument 'n_custs'"},{"fix":"When initializing `GammaGammaFitter`, add the `q_constraint=True` argument: `gmf = GammaGammaFitter(q_constraint=True)`. This enforces `q > 1` during the fitting process.","cause":"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.","error":"ValueError: q must be > 1.0"},{"fix":"Access 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`.","cause":"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`.","error":"AttributeError: 'Series' object has no attribute 'keys'"},{"fix":"Ensure 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.","cause":"`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.","error":"KeyError: 'date'"}]}