predict.clv.fitted.transactions {CLVTools}R Documentation

Predict CLV from a fitted transaction model


Probabilistic customer attrition models predict in general three expected characteristics for every customer:

In order to derive a monetary value such as CLV, customer spending has to be considered. If the object contains spending information, customer spending can be predicted using a Gamma/Gamma spending model for parameter predict.spending and the predicted CLV is be calculated (if the transaction model supports DERT/DECT). In this case, the prediction additionally contains the following two columns:


## S3 method for class 'clv.fitted.transactions'
  newdata = NULL,
  prediction.end = NULL,
  predict.spending = gg, = 0.1,
  verbose = TRUE,

## S4 method for signature 'clv.fitted.transactions'
  newdata = NULL,
  prediction.end = NULL,
  predict.spending = gg, = 0.1,
  verbose = TRUE,



A fitted clv transaction model for which prediction is desired.


A clv data object for which predictions should be made with the fitted model. If none or NULL is given, predictions are made for the data on which the model was fit.


Until what point in time to predict. This can be the number of periods (numeric) or a form of date/time object. See details.


Whether and how to predict spending and based on it also CLV, if possible. See details.

continuous discount factor to use to calculate DERT/DECT


Show details about the running of the function.




predict.spending indicates whether to predict customers' spending and if so, the spending model to use. Accepted inputs are either a logical (TRUE/FALSE), a method to fit a spending model (i.e. gg), or an already fitted spending model. If provided TRUE, a Gamma-Gamma model is fit with default options. If argument newdata is provided, the spending model is fit on newdata. Predicting spending is only possible if the transaction data contains spending information. See examples for illustrations of valid inputs.

The newdata argument has to be a clv data object of the exact same class as the data object on which the model was fit. In case the model was fit with covariates, newdata needs to contain identically named covariate data.

The use case for newdata is mainly two-fold: First, to estimate model parameters only on a sample of the data and then use the fitted model object to predict or plot for the full data set provided through newdata. Second, for models with dynamic covariates, to provide a clv data object with longer covariates than contained in the data on which the model was estimated what allows to predict or plot further. When providing newdata, some models might require additional steps that can significantly increase runtime.

prediction.end indicates until when to predict or plot and can be given as either a point in time (of class Date, POSIXct, or character) or the number of periods. If prediction.end is of class character, the date/time format set when creating the data object is used for parsing. If prediction.end is the number of periods, the end of the fitting period serves as the reference point from which periods are counted. Only full periods may be specified. If prediction.end is omitted or NULL, it defaults to the end of the holdout period if present and to the end of the estimation period otherwise.

The first prediction period is defined to start right after the end of the estimation period. If for example weekly time units are used and the estimation period ends on Sunday 2019-01-01, then the first day of the first prediction period is Monday 2019-01-02. Each prediction period includes a total of 7 days and the first prediction period therefore will end on, and include, Sunday 2019-01-08. Subsequent prediction periods again start on Mondays and end on Sundays. If prediction.end indicates a timepoint on which to end, this timepoint is included in the prediction period. allows to adjust the discount rate used to estimated the discounted expected transactions (DERT/DECT). The default value is 0.1 (=10%). Note that a continuous rate needs to be provided.


An object of class data.table with columns:


The respective customer identifier


First timepoint of prediction period


Last timepoint of prediction period


Number of time units covered by the period indicated by period.first and period.last (including both ends).


Probability to be alive at the end of the estimation period


The Conditional Expected Transactions


Discounted Expected Residual Transactions or Discounted Expected Conditional Transactions for dynamic covariates models


Actual number of transactions until prediction.end. Only if there is a holdout period and the prediction ends in it, otherwise it is not reported.

Actual total spending until prediction.end. Only if there is a holdout period and the prediction ends in it, otherwise it is not reported.


The mean spending per transactions as predicted by the spending model.


Customer Lifetime Value based on DERT/DECT and predicted.mean.spending.

See Also

models to predict transactions: pnbd, bgnbd, ggomnbd.

models to predict spending: gg.

predict for spending models


# Fit pnbd standard model on data, WITH holdout
apparel.holdout <- clvdata(apparelTrans, time.unit="w",
                           estimation.split=37, date.format="ymd")
apparel.pnbd <- pnbd(apparel.holdout)

# Predict until the end of the holdout period

# Predict until 10 periods (weeks in this case) after
#   the end of the 37 weeks fitting period
predict(apparel.pnbd, prediction.end = 10) # ends on 2010-11-28

# Predict until 31th Dec 2016 with the timepoint as a character
predict(apparel.pnbd, prediction.end = "2016-12-31")

# Predict until 31th Dec 2016 with the timepoint as a Date
predict(apparel.pnbd, prediction.end = lubridate::ymd("2016-12-31"))

# Predict future transactions but not spending and CLV
predict(apparel.pnbd, predict.spending = FALSE)

# Predict spending by fitting a Gamma-Gamma model
predict(apparel.pnbd, predict.spending = gg)

# Fit a spending model separately and use it to predict spending <- gg(apparel.holdout, remove.first.transaction = FALSE)
predict(apparel.pnbd, predict.spending =

# Fit pnbd standard model WITHOUT holdout
pnc <- pnbd(clvdata(apparelTrans, time.unit="w", date.format="ymd"))

# This fails, because without holdout, a prediction.end is required
## Not run: 

## End(Not run)

# But it works if providing a prediction.end
predict(pnc, prediction.end = 10) # ends on 2016-12-17

[Package CLVTools version 0.9.0 Index]