Add _expected_retention_elasticity to ShiftedBetaGeoModel (#2028)

* add expected_retention_elasticity

* docstrings

* unit tests

Author: ColtAllen

pymc_marketing/clv/models/shifted_beta_geo.py

@@ -42,7 +42,7 @@ class ShiftedBetaGeoModel(CLVModel):
     This model requires data to be summarized by *recency*, *T*, and *cohort* for each customer.
     Modeling assumptions require *1 <= recency <= T*, and *T >= 2*.
 
-    First introduced by Fader & Hardie in [1]_.
+    First introduced by Fader & Hardie in [1]_, with additional expressions described in [2]_.
 
     Parameters
     ----------
@@ -98,23 +98,39 @@ class ShiftedBetaGeoModel(CLVModel):
             model.fit(method="mcmc")
             model.fit_summary()
 
+
             # Predict probability customers are still active
             expected_alive_probability = model.expected_probability_alive(
                 active_customers,
                 future_t=0,
             )
 
-            # Predict retention rate of a given cohort in the current time period
+            # Predict retention rate for a specific cohort
+            cohort_name = "2025-02-01"
+
             expected_alive_probability = model.expected_retention_rate(
                 future_t=0,
-            ).sel(cohort=cohort)
+            ).sel(cohort=cohort_name)
+
+            # Predict expected remaining lifetime for all customers with a 5% discount rate
+            expected_alive_probability = model.expected_residual_lifetime(
+                discount_rate=0.05,
+            )
+
+            # Predict expected retention elasticity for all customers in a specific cohort
+            expected_alive_probability = model.expected_retention_elasticity(
+                discount_rate=0.05,
+            ).sel(cohort=cohort_name)
 
 
     References
     ----------
-    .. [1] Fader, P. S., & Hardie, B. G. (2007). How to project customer retention.
-           Journal of Interactive Marketing, 21(1), 76-90.
-           https://faculty.wharton.upenn.edu/wp-content/uploads/2012/04/Fader_hardie_jim_07.pdf
+    .. [1] Fader, P. S., & Hardie, B. G. (2007). "How to project customer retention."
+        Journal of Interactive Marketing, 21(1), 76-90.
+        https://faculty.wharton.upenn.edu/wp-content/uploads/2012/04/Fader_hardie_jim_07.pdf
+    .. [2] Fader, P. S., & Hardie, B. G. (2010). "Customer-Base Valuation in a Contractual Setting:
+        The Perils of Ignoring Heterogeneity." Marketing Science, 29(1), 85-93.
+    https://faculty.wharton.upenn.edu/wp-content/uploads/2012/04/Fader_hardie_contractual_mksc_10.pdf
     """
 
     _model_type = "Shifted Beta-Geometric"
@@ -328,7 +344,10 @@ def expected_retention_rate(
         *,
         future_t: int | np.ndarray | pd.Series | None = None,
     ) -> xarray.DataArray:
-        """Compute expected retention rate by cohort.
+        """Compute expected retention rate for each customer.
+
+        This is the percentage of customers who were active in the previous time period
+        and are still active in the current period. Retention rates are expected to increase over time.
 
         The *data* parameter is only required for out-of-sample customers.
 
@@ -346,7 +365,7 @@ def expected_retention_rate(
 
         References
         ----------
-        .. [1] Fader, P. S., & Hardie, B. G. (2007). How to project customer retention.
+        .. [1] Fader, P. S., & Hardie, B. G. (2007). "How to project customer retention."
             Journal of Interactive Marketing, 21(1), 76-90.
             https://faculty.wharton.upenn.edu/wp-content/uploads/2012/04/Fader_hardie_jim_07.pdf
         """
@@ -376,7 +395,7 @@ def expected_probability_alive(
         *,
         future_t: int | np.ndarray | pd.Series | None = None,
     ) -> xarray.DataArray:
-        """Compute expected probability of contract renewal by cohort.
+        """Compute expected probability of contract renewal for each customer.
 
         The *data* parameter is only required for out-of-sample customers.
 
@@ -394,7 +413,7 @@ def expected_probability_alive(
 
         References
         ----------
-        .. [1] Fader, P. S., & Hardie, B. G. (2007). How to project customer retention.
+        .. [1] Fader, P. S., & Hardie, B. G. (2007). "How to project customer retention."
             Journal of Interactive Marketing, 21(1), 76-90.
             https://faculty.wharton.upenn.edu/wp-content/uploads/2012/04/Fader_hardie_jim_07.pdf
         """
@@ -431,10 +450,11 @@ def expected_residual_lifetime(
         *,
         discount_rate: float | np.ndarray | pd.Series | None = 0.0,
     ) -> xarray.DataArray:
-        """Compute expected residual lifetime of customers by cohort.
+        """Compute expected residual lifetime of each customer.
 
         This is the expected number of periods a customer will remain active after the current time period,
-        given a discount rate. If no discount rate is provided, infinite lifetime estimates may be returned.
+        subject to a discount rate for net present value (NPV) calculations.
+        It is recommended to set a discount rate > 0 to avoid infinite lifetime estimates.
 
         Adapted from equation (6) in [1]_.
 
@@ -450,8 +470,8 @@ def expected_residual_lifetime(
 
         References
         ----------
-        .. [1] Fader, P. S., & Hardie, B. G. (2010). Customer-Base Valuation in a Contractual Setting:
-            The Perils of Ignoring Heterogeneity. Marketing Science, 29(1), 85-93.
+        .. [1] Fader, P. S., & Hardie, B. G. (2010). "Customer-Base Valuation in a Contractual Setting:
+            The Perils of Ignoring Heterogeneity". Marketing Science, 29(1), 85-93.
             https://faculty.wharton.upenn.edu/wp-content/uploads/2012/04/Fader_hardie_contractual_mksc_10.pdf
         """
         if data is None:
@@ -476,6 +496,58 @@ def expected_residual_lifetime(
             "chain", "draw", "customer_id", "cohort", missing_dims="ignore"
         )
 
+    def expected_retention_elasticity(
+        self,
+        data: pd.DataFrame | None = None,
+        *,
+        discount_rate: float | np.ndarray | pd.Series | None = 0.0,
+    ) -> xarray.DataArray:
+        """Compute expected retention elasticity for each customer.
+
+        This is the percent increase in expected residual lifetime given a 1% increase in the retention rate,
+        subject to a discount rate for net present value (NPV) calculations.
+        It is recommended to set a discount rate > 0 to avoid infinite retention elasticity estimates.
+
+        Adapted from equation (8) in [1]_.
+
+        Parameters
+        ----------
+        discount_rate : float
+            Discount rate to apply for net present value estimations.
+        data : ~pandas.DataFrame
+            Optional dataframe containing the following columns:
+            * `customer_id`: Unique customer identifier
+            * `T`: Number of time periods customer has been active
+            * `cohort`: Customer cohort label
+
+        References
+        ----------
+        .. [1] Fader, P. S., & Hardie, B. G. (2010). "Customer-Base Valuation in a Contractual Setting:
+            The Perils of Ignoring Heterogeneity". Marketing Science, 29(1), 85-93.
+            https://faculty.wharton.upenn.edu/wp-content/uploads/2012/04/Fader_hardie_contractual_mksc_10.pdf
+        """
+        if data is None:
+            data = self.data
+
+        if discount_rate is not None:
+            data = data.assign(discount_rate=discount_rate)
+
+        dataset = self._extract_predictive_variables(
+            data, customer_varnames=["T", "discount_rate"]
+        )
+
+        alpha = dataset["alpha"]
+        beta = dataset["beta"]
+        T = dataset["T"]
+        d = dataset["discount_rate"]
+
+        retention_elasticity = hyp2f1(
+            1, beta + T - 1, alpha + beta + T - 1, 1 / (1 + d)
+        )
+        return retention_elasticity.transpose(
+            "chain", "draw", "customer_id", "cohort", missing_dims="ignore"
+        )
+
 
 class ShiftedBetaGeoModelIndividual(CLVModel):
     """Shifted Beta Geometric model for individual customers.

tests/clv/models/test_shifted_beta_geo.py

@@ -609,6 +609,115 @@ def test_expected_residual_lifetime(self, prediction_targets, erl_test_data):
             expected_residual_lifetime_case2, residual_lifetime_case2_obs, rtol=1e-2
         )
 
+    def test_expected_retention_elasticity(self, erl_test_data):
+        """Test expected_retention_elasticity against Table 3 values from the paper.
+        Note no values for retention elasticity are provided in the paper,
+        but can be derived from the DERL and retention rate:
+        retention_elasticity(T) = DERL(T-1) / retention_rate(T)
+        """
+        # Compute expected retention elasticity from the model with discount_rate=0.1
+        expected_retention_elasticity_cohorts = (
+            self.erl_model.expected_retention_elasticity(
+                erl_test_data,
+                discount_rate=0.1,
+            ).mean(("chain", "draw"))
+        )
+
+        # Extract elasticity predictions by cohort
+        expected_retention_elasticity_case1 = expected_retention_elasticity_cohorts.sel(
+            cohort="case1"
+        ).values
+        expected_retention_elasticity_case2 = expected_retention_elasticity_cohorts.sel(
+            cohort="case2"
+        ).values
+
+        ### DERIVE VALUES FROM OTHER EXPRESSIONS FOR VALIDATION ###
+
+        # compute expected retention rates for T (current period)
+        expected_retention_rate_cohorts = self.erl_model.expected_retention_rate(
+            erl_test_data,
+            future_t=0,
+        ).mean(("chain", "draw"))
+
+        expected_retention_rate_case1 = expected_retention_rate_cohorts.sel(
+            cohort="case1"
+        ).values
+        expected_retention_rate_case2 = expected_retention_rate_cohorts.sel(
+            cohort="case2"
+        ).values
+
+        # Create test data for DERL T-1 (one period earlier) to compute DERL(T-1)
+        erl_test_data_T_minus_1 = erl_test_data.copy()
+        erl_test_data_T_minus_1["T"] = erl_test_data_T_minus_1["T"] - 1
+        # Filter out T=0 (can't have T < 1 in the model)
+        erl_test_data_T_minus_1 = erl_test_data_T_minus_1[
+            erl_test_data_T_minus_1["T"] >= 1
+        ]
+
+        # Compute DERL for T-1
+        expected_residual_lifetime_cohorts_T_minus_1 = (
+            self.erl_model.expected_residual_lifetime(
+                erl_test_data_T_minus_1,
+                discount_rate=0.1,
+            ).mean(("chain", "draw"))
+        )
+
+        expected_residual_lifetime_case1_T_minus_1 = (
+            expected_residual_lifetime_cohorts_T_minus_1.sel(cohort="case1").values
+        )
+        expected_residual_lifetime_case2_T_minus_1 = (
+            expected_residual_lifetime_cohorts_T_minus_1.sel(cohort="case2").values
+        )
+
+        # Compute expected elasticity using the formula: DERL(T-1) / retention_rate(T)
+        # Skip T=1 since we don't have T-1=0
+        expected_elasticity_case1_formula = (
+            expected_residual_lifetime_case1_T_minus_1
+            / expected_retention_rate_case1[1:]
+        )
+        expected_elasticity_case2_formula = (
+            expected_residual_lifetime_case2_T_minus_1
+            / expected_retention_rate_case2[1:]
+        )
+
+        ### ASSERTIONS ###
+        # Compare model's elasticity against the formula-based elasticity
+        # Skip first value (T=1) since formula needs T-1
+        np.testing.assert_allclose(
+            expected_retention_elasticity_case1[1:],
+            expected_elasticity_case1_formula,
+            rtol=1e-1,
+            err_msg="Case1: Model elasticity doesn't match DERL(T-1)/retention_rate(T)",
+        )
+        np.testing.assert_allclose(
+            expected_retention_elasticity_case2[1:],
+            expected_elasticity_case2_formula,
+            rtol=2.0,  # T=1 variance is very high, but var for T=5 is 1e-2
+            err_msg="Case2: Model elasticity doesn't match DERL(T-1)/retention_rate(T)",
+        )
+
+        # Additional validation: elasticity properties
+        # The elasticity should be positive
+        assert np.all(expected_retention_elasticity_case1 > 0)
+        assert np.all(expected_retention_elasticity_case2 > 0)
+
+        # Elasticity should generally be higher for the low retention case
+        # (customers with lower retention are more sensitive to retention changes)
+        assert np.mean(expected_retention_elasticity_case2) > np.mean(
+            expected_retention_elasticity_case1
+        )
+
+        # Verify retention rates are valid (between 0 and 1) and increasing with T
+        assert np.all(
+            (expected_retention_rate_case1 > 0) & (expected_retention_rate_case1 < 1)
+        )
+        assert np.all(
+            (expected_retention_rate_case2 > 0) & (expected_retention_rate_case2 < 1)
+        )
+        # Retention rates should increase over time (with more renewals)
+        assert np.all(np.diff(expected_retention_rate_case1) >= 0)
+        assert np.all(np.diff(expected_retention_rate_case2) >= 0)
+
 
 class TestShiftedBetaGeoModelIndividual:
     @classmethod