Package: clv-prediction
Customer Lifetime Value PredictionHow it works?Main ConceptThe main concept of customer value prediction is related to calculateReturn Rate,Churn Rate(per customer or general Ratio), then formulize the ratio with the value of each customer per purchase.
Depending on the churn rate, the total value of business somehow can be predicted and it will not be efficient much by using this technique.
This technique, rather than predicting each customer of value, give a general idea of the business what will be the total revenue with the customer.
How about is it changing the methodology, rather than using the general churn rate which is applied for each customer, predicting customers of the selected future time period of possible order dates by using their historical transactions? If we can predict the exact date of each customer by the historic time difference of each customer, we are able to predict the future value of each order per customer.Prediction of Next Purchase (Frequency) per Customer ModelEach customer of historical purchases of date differences is calculated.
There will be accepted patterns related to customers ' behaviors.
Some Users might have a pattern of every Monday.
Some will have Mondays -Wednesdays- Fridays.
There must be an individual predictive model for each customer, and this must be the Time Series model per each customer of historical frequency.
However, it is not an efficient way and there will be a computational cost here. In that case, Deep Learning can handle this problem with LSTM NN (check next_purchase_model.py).
There must be a model that each customer of frequency values are able to be predicted.Prediction Of Customer Value (Value) per Customer ModelCustomer future values of prediction are also crucial to reach the final CLV calculation.
Once frequency values are calculated per customer, by historical users' of purchase values can be predicted via using Deep Learning.
At this process, there is a built-in network (check purchase_amount.py) which is created by using 1 Dimensional Convolutional LSTM NN.Prediction Of NewComers CLV ModelNewcomers are not likely predictable as Engaged users. They probably not have stabilized transactions pattern or they will not have a fitted train model unless they have enough transactions.
At this point, rather than predicting the value of each transaction, predicting the amount of transaction will be more convinient.
By using the historical total purchases per time period (daily), the next time period of total purchase count is able to be predicted.
Assuming that Purchase Amount of Newcomers are Normal Distributed (Hypothesis Test).
In that case, purchase Amount prediction per newcomer is going to be the Mean of Purchase Amounts.Combining Of Next Purchase Model & Purchase Amount Prediction Model & NewComers Prediction ModelWithout predicting the frequency of users, we can not be sure when the customer will have a purchase.
So, by using the next purchase model, customers of future purchase dates have to be predicted.
Before predicting a date, the algorithm makes sure the predicted future order of dates is inselected time period.last purchased date from raw data < predicted purchase date < last purchased date from raw data + time periodThis time period must be assigned when the process is initialized. The time period will have a range between the last transaction date of the dataset and the last transaction date + time period.
It can be detected the users' purchases of dates and the next process will be predicting each purchase of values by using the Purchase Amount model.After combining Of Next Purchase Model & Purchase Amount Prediction Model is done, NewComers of Predictions are merging the results.CLV Prediction Process PipelineKey FeaturesAllows you to predict your business of customers values individually.Predicts customers of next purchase dates.Predicts customers of next purchase amounts.Predicts newcomers of next purchase amounts.Dashboard for visualization predicted values.Running PlatformCLV Prediction Parametersjob :Train, Prediction, Train&Prediction. train process is related to creating a model;
the next steps are going to be the Next Purchase Model and Purchase Amount Model.
Each model of the hyper parameter tuning process will be initialized before models have been initialized.
Once, the hyperparameter has been progressed tunned network parameters are stored intest_paramters.yamlwhere it is inexport_path.
When a model has been run repeatedly (or periodically), the model has been checked whether it has been already built during the ***time_period.
If there are stored models inexport_path, the latest model is imported and move on to the next process without a run for building the model.
When the *predictionprocess is triggered, first, the next purchase per customer is predicted then, the purchase amount is predicted related to the next purchase prediction.order_count :It allows us to create a feature set of the purchase amount model.
(CheckWhy do we need order count as a feature at Purchase Amount Model?for details).
if it is not assigned (it is not a required argument in order to initialize the clv prediction), the platform handles it to decide the optimum order count. Order Count also affects the detection of NewComers.customer_indicator :This parameter indicates which column represents a unique customer identifier on given data.amount_indicator :This parameter indicates which column represents purchase value (integer, float ..) on the given data.time_indicator :This parameter indicates which column represents order checkout date with date format (timestamp) (YYYY/MM/DD hh:mm:ss, YYYY-MM-DD hh:mm:ss, YYYY-MM-DD) on given data.date :This allows us to query the data with a date filter. This removes data that occurs after the given date.
If the date is not assigned there will be no date filtering. date arguments are filtering related to time_indicator column, make sure it is querying with the accurate format.
If clv prediction is running with schedule service, periodically given date is updated and filter with an updated given date.
If the date is not assigned when clv prediction is scheduling, the date will be the current date.data_source :The location where the data is stored or the query (check data source for details).data_query_path :Type of data source to import data to the platform (optional Ms SQL, PostgreSQL, AWS RedShift, Google BigQuery, csv, json, pickle).connector :if there is a connection parameters as user, pasword, host port, this allows us to assign it as dictionary format (e.g {"user": ***, "pw": ****}).export_path :Export path where the outputs are stored. created models (.json format),
tunned parameters (test_parameters.yaml), schedule service arguments (schedule_service.yaml), result data with predicted values per user per predicted order (.csv format) are willing to store at given path. When prediction is initialized, Nex Purchase Model will create folder 'temp_next_purchase_results' and
Purchase Amount Model will create folder 'temp_purchase_amount_results' in order to import results as .csv formattime_period :A period of time which is willing to predict. Supported time periods month, week, '2week', quarter, '6month' (Required).time_schedule :A period of time which handles for running clv_prediction train or prediction process periodically. Supported schedule periods day, year, month, week, 2*week.Data SourceHere is the data source that you can connect with your SQL queries:Ms SQL ServerPostgreSQLAWS RedShiftGoogle BigQuery.csv.jsonpickleConnection PostgreSQL - MS SQL - AWS RedShiftdata_source = "postgresql"
connector = {"user": ***, "password": ***, "server": "127.0.0.1", 
             "port": ****, "db": ***}
data_main_path ="""
                   SELECT                             
                    customer_indicator,
                    amount_indicator,
                    time_indicator,
                   FROM table
               """Connection Google BigQuerydata_source = "googlebigquery"
connector = {"data_main_path": "./json_file_where_you_stored", 
             "db": "flash-clover-*********.json"}
data_main_path ="""
           SELECT                             
                customer_indicator,
                amount_indicator,
                time_indicator,
            FROM tablee
       """Connection csv - .json - .pickledata_source = "csv"
data_main_path = "./data_where_you_store/***.csv"Data PreparationEach model has unique aggregation in order to prepare data to create model.1. Next Purchase Model Data PreparationTime difference of each order per customer is calculated as day diffrence of orders per user.Normalized each time difference values related to Min-Max Normalization Method. Each customer of Min-Max Normalization individually.Regarding oflaheadparameter of LSTM model, data set is shaped per customer.Iterativelly each customer of data set is collected individually. the process is parallelized according to CPU count.When model data has been prepared per customer, it is splitted according to split ratio into the train and test data set (train_x, train_y, test_x, test_y).customerslag 3lag 2lag 1yuser_10,40,81,71,2user_10,81,71,21,4user_11,71,21,41,6user_11,21,41,62,8user_11,41,62,82,9user_11,62,82,93,0user_25,45,85,75,2user_25,85,75,25,4user_25,75,25,45,6user_25,25,45,65,8user_25,45,65,85,9user_25,65,85,95,02. Purchase Amount Model Data Preparationorder_countparameter refers us for the model of the feature count.previous orders of purchase amounts of each customer is collected from fow data.Regarding oflaheadparamter of LSTM model, data set is shaped per customer.Iterativelly each customer of data set is collected individually. the process is parallelized according to CPU count.When model data has been prepared per customer, it is splitted according to split ratio into the train and test data set (train_x, train_y, test_x, test_y).Why do we need order count as a feature at Purchase Amount Model?Order count is also the feature number of the purchase amount model.!!! Caution !!!Order count must be inserted into the test_parameters.yaml in order not to allow for changing later on prediction.Once the model is built with calculated order_count it must be predicted with the same order count.!!! Why we need an order count of a decision? !!!It is a crucial parameter for the purchase amount model.The purchase amount is a 1 Dimensional Conv NN. It works with kernel sizes and they are related to feature size.At the purchase amount model features are sequential orders.For instance if we assign order count as 5, time_period.user_1, user_2, user_3, user_4 have 100, 101, 300, 2 orders.The data set will be;user_1: 95th, 96th, 97th, 98th, 99th, 100th  ordersuser_2: 96th, 97th, 98th, 99th, q00th, 101st  ordersuser_3: 295th, 296th, 297th, 298th, 299th, 300th  ordersuser_4: only have 2 orders first 9 orders will be 0 and this will affect the model process.It is now crucial to have a minimum 0 assigned order as user_4However, it is also a crucial point to get as much previous order count for make kernel size larger.The order count must be optimized even sending to the platform as an argument. If this argument is not using, the platform hamdles for deciding order_count.customersLast 5Last 4Last 3Last 2Last Order (y)user_110,413,418,411,415,4user_250,852,854,856,858,8user_330,725,715,710,78,7user_420,223.526,227,229,2user_51,41,41,41,41,4user_612,630,612,630,612,63. NewComers Model Data Preparationorder_countparameter is calculated as feature count on Purchase Amount Train Process.
Detection of order count parameters relies on detecting the minimum number of order count per customer which covers the maximum number of customers from the data set.Customers who have order count lower than than the calculated order count parameters are NewComers.Why do we need order count as a feature at NewComers CLV Model?It is a crucial parameter for NewComers Model;Users who have an order count less than ** order_count ** are not included in Combined of Next Purchase - Purchase Amount Models.NewComers are individually predicted according to a dependent value isorder_count.Main concept of Newcomers is for predicting orders count daily.Feature value is going to be total number of order count for all NewComers.Normalized each order count values related to Min-Max Normalization Method per day.Regarding oflaheadparamter of LSTM model, data set is shaped just like below;customerslag 3lag 2lag 1y  (total order count of Newcomers)2021-05-0125510202021-05-0251020302021-05-03102030402021-05-04203040602021-05-05304060702021-05-06406070902021-05-07607090100When model data has been prepared per customer, it is splitted according to split ratio into the train and test data set (train_x, train_y, test_x, test_y).LSTM model will be implemented for the data just like above.Prediction process is calculated sequentially per day. Each day model has been regenerated (store .json format) with updated coefficient matrix (stored as .h5 format).
LSTM allows us to predict next step values regarding your lags. While we are predicting further prediction,
models of coefficients must be updated and the previous prediction values must be merged just like actual values.
But, just like the recent prediction and model, the Tuned parameters are will also be used for further future days of predictions.Parameter TuningParameters of networks (LSTM NN & ! Dimensional Conv NN) are tuned via Keras Turner Library. However,batch_sizeandepochare tuned individually.epochhyper parameters are sorting as ascending andbatch_sizehyper parameters are sorting as descending.
Each iteration sorted paramters are used and loss values are calculated.
We aim here to capture the best of the minimumepochand the best of the maximumbatch_size.epochandbatch_sizeare iteratively checking by loss values of last epoch by using Keras- TensorFlow API history.
This iteration will be processed until the iteration is lower thanparameter_tuning_trials.If the last epoch of loss value is less thanaccept_threshold_for_loss_diff, then it is excepted as optimumepochandbatch_size.Trainjob == 'train'Next Purchase Model, Purchase Amount Model and NewComer Model of the train process are progressed via tensorflow - Keras.It is a Recurrent NN, LSTM NN.Trained model stored atexport_pathwith.jsonformat..jsontrained file has  a file name withtime_preiod, name of the model, trained date (current date).
e.g; trained_purchase_amount_model_20210101_month.jsonBefore initialize the training process previously-stored model are checked which have been stored atexport_pathThe most recent trained must be picked. Model name andtime_periodalso must be matched.
e.g; recent model: trained_purchase_amount_model_20210101_month.json, model name: purchase_amount, time_period: month,
current date 2020-01-30. This model trained 29 days before which is accepted range (accepted range 0 - 30 (one month)).Prediction Processjob == 'prediction'First, the next purchase of dates are calculated related to prediction values from the next purchase model per customer individually.
Next, the purchase model will predict the time difference of the next order.
By using time difference it is possible to find the exact date of the purchase.
If the purchase date is in the range between the last purchase transaction date of the raw data and the last purchase transaction date +time_period.After the next purchased orders are predicted, the next purchase of the values are predicted by the purchase amount
mode for each user who has purchases related to the next purchase prediction result data.NewComers of Predictions are not dependent just like Nex Purchase Amount and Next Purchase Processes.
However, In order to determine NewComer, it usesfeature count (optimum order count)parameter that has been detected when Purchase Amount Model is built.
NewComers are customers who have an order count less thanfeature count (optimum order count). NewComers of the total number of order count is predicted for ClV Time Period per day. Next, the Average Payment Amount is assigned as the predicted Payment Amount value for NewComers and multiplied with the predicted order count.
Next, the result of the multiplied payment amount is merged to the Purchase Amount model of results.Result data is stored atexport_path. Once a previous result data stored not related to current time_preiod,
but it is related to previoustime_period, it is merged with current result data.Result data file name: result_data_month.csvTrain-Prediction Processjob == 'train_prediction'Each model process is trained then predicted sequentially. At the end 3 models have been generalized, 3 models of parameters tunning have been applied and 3 models of predictions are calculated.Running CLV Predictioncustomer_indicator = "user_id"
    amount_indicator = "transaction_value"
    time_indicator = "days"
    time_period = 'month'
    job = "train" # prediction or train_prediction
    date = '2021-01-01'
    order_count = 15
    data_source = "postgresql"
    data_query_path="""
                select user_id, 
                       transaction_value,
                       days
                from purchases
    """
    export_path =  './data'
    connector = {"db": "c****s", 
                 "password": "******", 
                 "port": "5**3", 
                 "server": "127.0.0.1", 
                 "user": "*******"}
                 
    from clv.executor import CLV
    clv = CLV(customer_indicator=customer_indicator,
              amount_indicator=amount_indicator,
              job=job,
              date=date,
              order_count=order_count,
              data_source=data_source,
              data_query_path=data_query_path,
              time_period=time_period,
              time_indicator=time_indicator,
              export_path=export_path,
              connector=connector)
    clv.clv_prediction()Collecting Prediction Result DataOnce, prediction process has been initialized (job: 'prediction' or 'train_prediction'), It can be collected viaget_result_data.
This data will be represented with raw data per customer of next purchase orders.from clv.executor import CLV
    clv = CLV(customer_indicator=customer_indicator,
              amount_indicator=amount_indicator,
              date=date,
              order_count=order_count,
              data_source=data_source,
              data_query_path=data_query_path,
              time_period=time_period,
              time_indicator=time_indicator,
              export_path=export_path,
              connector=connector)
    results = clv.get_result_data()customersdata_typetime_indicatoramount_indicatoruser_1actual2021-01-0710,4user_1actual2021-01-1415,4user_1actual2021-01-2820,4user_1prediction2021-02-0525,4user_1prediction2021-02-0630,8user_2prediction2021-02-058,7user_3prediction2021-02-0529,2user_4prediction2021-02-051,4user_4prediction2021-02-0618,6newcomersprediction2021-02-0512,6newcomersprediction2021-02-0612,6Dashboard for CLV PredictionHere are examples of dashboardHow does it work?from clv.executor import CLV
  clv = CLV(customer_indicator=customer_indicator,
            amount_indicator=amount_indicator,
            date=date,
            order_count=order_count,
            data_source=data_source,
            data_query_path=data_query_path,
            time_period=time_period,
            time_indicator=time_indicator,
            export_path=export_path,
            connector=connector)
  clv.show_dashboard()Dashboard of Components1. CLV Prediction Time LineRelated to result_data.csv file, all previously calculated results are combined and showed in the line chart.2. Churn Customers Of Purchase TimeLineAccording to the selected date fromCLV Prediction Time Line, the customers who have purchased before the selected date but never had an order in prediction time periods are detected.
These are the churn customers of the selected date.3. Newcomer Customers Of Purchase TimeLineAccording to the selected date fromCLV Prediction Time Line, the customers, who are newcomers at the selected date and haven`t purchased before the selected date, are detected.
These are the churn customers of the selected date.4. Top 100 the Least Engaged Customers Of Sum Values per monthThe customers who have fewer purchase amounts than others of purchase amounts sum/mean values in the timeline.
These customers are able to be selected individually from the filter,Worst Customer List.5. Top 100 the Most Engaged Customers Of Sum Values per monthThe customers who have more purchase amounts than others of purchase amount sum/mean values in the timeline.
These customers are able to be selected individually from the filter,Top Customer List.6. Churn Rate and Newcomer Rate per monthThese pie charts refer to Newcomer and Churn Rate of the Business According to selected date inCLV Prediction Timeline.