In bachmannpatrick/CLVTools: Tools for Customer Lifetime Value Estimation

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

The CLVTools Package

Today, customer lifetime value (CLV) is the central metric for valuing customers. It describes the long-term economic value of customers and gives managers an idea of how customers will evolve over time. To model CLVs in continuous non-contractual business settings such as retailers, probabilistic customer attrition models are the preferred choice in literature and practice.

The R package CLVTools provides an efficient and easy to use implementation framework for probabilistic customer attrition models in non-contractual settings. Building up on the learnings of other implementations, the package adopts S4 classes to allow constructing rich and rather complex models that nevertheless still are easy to apply for the end user. The framework is capable to accommodate a variety of probabilistic customer attrition models for non-contractual settings in continuous and discrete time.

Currently, CLVTools implements the following probabilistic models:

(1) Standard Pareto/NBD model (Schmittlein, Morrison & Colombo 1987)

(2) Pareto/NBD model with time-invariant contextual factors (Fader & Hardie 2007)

(3) Pareto/NBD model with time-varying contextual factors (Bachmann, Meierer & Näf 2021)

(4) Standard BG/NBD model (Fader, Hardie, & Lee 2005)

(5) BG/NBD model with time-invariant contextual factors (Fader & Hardie 2007)

(6) Standard Gamma/Gompertz/NBD (Bemmaor & Glady 2012)

(7) Gamma/Gompertz/NBD model with time-invariant contextual factors (Näf, Bachmann & Meierer 2020)

(8) Gamma/Gamma model to estimate customer spending (Colombo & Jiang 1999; Fader, Hardie & Lee 2005; Fader & Hardie 2013)

In future versions of CLVTools the following models are added. See GitHub Issues for a time-line.

(9) Standard BG/BB model (Fader, Hardie, & Shang 2010)

In addition the framework features a system of layers between the optimizer and the log-likelihood function to allow the flexible addition of model extensions during the model fitting process. Currently these layers include:

• Correlation of the purchase and the attrition process

• L2 regularization for parameters of contextual factors

• Equality constraints between parameters of contextual factors for the purchase and the attrition process.

Installation

Install the most recent stable release from CRAN:

install.packages("CLVTools")

Install the development version from GitHub (using the devtools package):

devtools::install_github("bachmannpatrick/CLVTools", ref = "development")

To compile the package from source, please be advised that CLVTools relies on an external C++ library called GSL. This library has to be installed on your computer to be able to compile CLVTools from source. Follow these 3 steps:

1. Update to the latest version of R.

2. Install the external dependency (GSL):

For Linux: :

apt-get update
apt-get install libgsl0-dev

If you are using an R Docker container with Linux (e.g. rocker/tidyverse), you can build up on these Docker images as follows

FROM rocker/tidyverse
RUN apt-get update -qq && apt-get -y install \
    libgsl0-dev

Alternatively, follow the instruction in the section "Installing Dependencies external to the R system" at https://ropenscilabs.github.io/r-docker-tutorial/03-install-packages.html to install GSL in a running Docker container with Linux.

For Mac with Intel chip: :

brew install gsl

For Mac with Apple Silicon: :

1. Download gsl-latest.tar.gz from https://ftp.gnu.org/gnu/gsl/ and unzip it.

2. Navigate to the unziped folder, e.g. cd ~/Downloads/gsl-2.7.1

3. run the following commands line by line:

sudo make clean
sudo chown -R $USER .
./configure && make
make install

For Windows: : First, install RTools through https://cran.r-project.org/bin/windows/Rtools/ (> v4.0). Next, use the new RTools package manager to install the GSL library (see https://github.com/r-windows/docs/blob/master/rtools40.md#readme) by using pacman through the RTools Bash:

pacman -S mingw-w64-{i686,x86_64}-gsl

1. Install the development version from source:

devtools::install_github("bachmannpatrick/CLVTools", ref = "development")

General workflow

Independent of the latent attrition model applied in CLVTools, the general workflow consists of three main steps:

1. Create a clv.data object containing the dataset and required meta-information such as date formats and column names in the dataset. After initializing the object, there is the option to add additional information on covariates in a separate step.

2. Fit the model on the data provided.

3. Use the estimated model parameters to predict future customer purchase behavior.

CLVTools provides two ways for evaluating latent attrition models: you can use of the provided formula interface or you can use standard functions (non-formula interface). Both offer the same functionality, however the formula interface is especially helpful when covariates are included in the model. We will illustrate both options.

Reporting and plotting results is facilitated by the implementation of well-known generic methods such as plot(), print() and summary(). These commands adapt their output according to the model state and may be used at any point of the workflow.

A Minimal Example

For detailed instructions and all available options and model variations see the detailed walkthrough and the manual.

Start by loading the package:

library("CLVTools")

As Input data CLVTools requires customers' transaction history. Every transaction record consists of a purchase date and customer ID.

data("apparelTrans")
apparelTrans

Before we estimate a model, we are required to initialize a data object using the clvdata() command. The data object contains the prepared transactional data and is later used as input for model fitting. Additionally we specify options for the date and time units, estimation duration and variable names (see Walkthrough for details). Make sure to store the generated object in a variable, e.g. in our example clv.apparel.

clv.apparel <- clvdata(apparelTrans,  
                       date.format="ymd", 
                       time.unit = "week",
                       estimation.split = 40,
                       name.id = "Id",
                       name.date = "Date",
                       name.price = "Price")

Be aware that probabilistic models such as the ones implemented in CLVTools are usually applied to specific customer cohorts. That means, you analyze customer that have joined your company at the same time (usually same day, week, month, or quarter). For more information on cohort analysis, see also here. Consequently, the data apparelTrans in this example is not the full transaction records of a fashion retailer, but rather only the customer cohort of 250 customers purchasing for the first time at this business on the day of 2005-01-03.

As a first probabilistic latent attrition model we estimate the standard Pareto/NBD model and therefore, use the command pnbd() to fit the model and estimate model parameters. Other models such as the BG/NBD model (bgnbd()) and the GGomp/NBD (ggomnbd()) are also available.

Estimating the model using formula interface:

   est.pnbd <- latentAttrition(~pnbd(), 
                               data=clv.apparel)
   est.pnbd

Estimating the model using non-formula interface:

est.pnbd <- pnbd(clv.data = clv.apparel)
est.pnbd

You can always use summary() to get details on CLVTools object (also before they are estimated):

#Full detailed summary of the parameter estimates
summary(est.pnbd)

Once the model parameters are estimated, we are able to predict future customer behavior on an individual level. To do so, we use predict() on the object with the estimated parameters (i.e. est.pnbd). In general, probabilistic customer attrition model predict three expected characteristics for every customer:

• "conditional expected transactions" (CET), which is the number of transactions to expect form a customer during the prediction period,
• "probability of a customer being alive" (PAlive) at the end of the estimation period and
• "discounted expected residual transactions" (DERT) for every customer, which is the total number of transactions for the residual lifetime of a customer discounted to the end of the estimation period.

If spending information was provided when initializing the clvdata-object, also "customer lifetime value" (CLV) is predicted.

results <- predict(est.pnbd)
print(results)

clvdata objects may be plotted using the plot() command. Similar to summary(), the output of plot() adapts to the current modeling step.

plot(est.pnbd)

Contributions

Feedback and contributions to this package are welcome! Please use GitHub Issues for filing bug reports. Provide your contributions in the form of Pull Requests. See also these general guidelines to contribute to Open Source projects on GitHub.

bachmannpatrick/CLVTools documentation built on Oct. 29, 2023, 2:16 p.m.