Add baselined saturation

[ferrine]

Baselined Tanh Saturation.

An alternative parameterization of the reach function is given by:

$$ \begin{align} c_0 &= \frac{r}{g \cdot \arctan(r)} \\ \beta &= \frac{g \cdot x_0}{r} \\ \text{saturation}(x, \beta, c_0) &= \beta \cdot \tanh \left( \frac{x}{c_0 \cdot \beta} \right) \end{align} $$

where:

• $x_0$ is the "reference point". This is a point chosen
  by the user (not given a prior) where they expect most of their data to lie (median recommended).
  For example, if you're spending between 50 and 150 dollars on a particular channel,
  you might choose $x_0 = 100$.

• $g$ is the "gain", which is the value of the CAC ($c_0$) at the reference point.
  You have to set a prior on what you think the CAC is when you spend $x_0 = 100$.
  Imagine you have four advertising channels, and you acquired 1000 new users.
  If each channel performed equally well, and advertising drove all sales, you might expect
  that you gained 250 users from each channel. Here, your "gain" would be $250 / 100 = 2.5$.

• $r$, the overspend fraction is telling you where the reference point is.

  • $0$ - we can increase our budget by a lot to reach the saturated region,
    the deminishing returns are not visible yet.
  • $1$ - the reference point is already in the saturation region
    and additional dollar spend will not lead to any new users.
  • $0.8$, you can still increase acquired users by $50%$ as much
    you get in the reference point by increasing the budget.
    $x_0$ effect is 20% way from saturation

Key benefits

• Works in equally well in saturated and undersaturated scenarios
• Observed to have less sampling issues
• Priors for $g$ and $r$ can be set using domain expertise easier than for the original parameterization

Origins

The original reach or saturation function used in an MMM is formulated as

$$ \text{saturation}(x, \beta, c_0) = \beta \cdot \tanh \left( \frac{x}{c_0 \cdot \beta} \right) $$

where:

• $\beta$ is the saturation, or the limit of the total number
  of new users obtained when an infinite number of dollars are spent on that channel.
• $c_0$ is the cost per acquisition (CAC0), so the initial cost per new user.
• $\frac{1}{c_0}$ is the inverse of the CAC0, so it's the number of new
  users we might expect after spending our first dollar.

Description

The PR adds novel parameterization that is easier to use for industry applications where domain knowledge is an essence

Code example

  import pymc as pm
  import numpy as np

  x_in = np.exp(3+np.random.randn(100))
  true_cac = 1
  true_saturation = 100
  y_out = abs(np.random.normal(tanh_saturation(x_in, true_saturation, true_cac).eval(), 0.1))

  with pm.Model() as model_reparam:
      r = pm.Uniform("r")
      gain = pm.Exponential("gain", 1)
      input = pm.ConstantData("spent", x_in)
      response = pm.ConstantData("response", y_out)
      sigma = pm.HalfNormal("n")
      output = tanh_saturation_baselined(input, np.median(x_in), gain, r)
      pm.Normal("output", output, sigma, observed=response)
      trace = pm.sample()

Related Issue

• Closes #
• Related to #

Checklist

• Checked that the pre-commit linting/style checks pass
• Included tests that prove the fix is effective or that the new feature works
• Added necessary documentation (docstrings and/or example notebooks)
• If you are a pro: each commit corresponds to a relevant logical change

Modules affected

• MMM
• CLV

Type of change

• New feature / enhancement
• Bug fix
• Documentation
• Maintenance
• Other (please specify): novel methodology

---

📚 Documentation preview 📚: https://pymc-marketing--498.org.readthedocs.build/en/498/

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (eee06ac) 90.87% compared to head (e660740) 91.24%.
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #498      +/-   ##
==========================================
+ Coverage   90.87%   91.24%   +0.37%     
==========================================
  Files          21       21              
  Lines        1983     2044      +61     
==========================================
+ Hits         1802     1865      +63     
+ Misses        181      179       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[bwengals]

thanks for the writeup!!! Should be sure to mention that the reference point x0 has to be set within the range of the actual spends. As in, you buy ads three times and spend 5, 6 and 7 dollars, x0 has to be set within [5, 7], so not 4 not 8. Otherwise the posterior of r and gain becomes a skinny diagonal line. I got stuck on that one, and it could be very relevant if there is very little spend observations for a particular channel.

[juanitorduz]

@ferrine this is amazing! Thanks! I think once you add @bwengals 's suggestion we are ready to merge!

More of a general question: Where would the adstock transformation come in? I guess before applying this one right?

Also, maybe for a next PR we can create another MMM model subclass to make sure users can use the API :)

[bwengals]

Why not just do:

def tanh_saturation_baseline(x, x0, gain, r):
    saturation = (gain * x0) / r
    cac0 = r / (gain * pt.arctanh(r))
    return tanh_saturation(x, cac0, saturation)

Only 4 lines! What functionality is the dataclass for the params and baseline and debaseline adding?

Also: I don't understand the name "baseline", or how this is "baselined". Maybe something else would be a clearer name (sorry to critique without suggestions, I can't think of anything though!)

[ferrine]

Why not just do:

def tanh_saturation_baseline(x, x0, gain, r):
    saturation = (gain * x0) / r
    cac0 = r / (gain * pt.arctanh(r))
    return tanh_saturation(x, cac0, saturation)

Only 4 lines! What functionality is the dataclass for the params and baseline and debaseline adding?

Also: I don't understand the name "baseline", or how this is "baselined". Maybe something else would be a clearer name (sorry to critique without suggestions, I can't think of anything though!)

The dataclasses are the helpers in case you need to visualize not just gain or r, but cac, saturation, calculate it for a different x0, etc. they can just sit there and serve for those who needs them.

[ferrine]

More of a general question: Where would the adstock transformation come in? I guess before applying this one right?

The adstock will be in just the same order

Also, maybe for a next PR we can create another MMM model subclass to make sure users can use the API :)

Why not a boolean parameter?

[juanitorduz]

Also, maybe for a next PR we can create another MMM model subclass to make sure users can use the API :)

Why not a boolean parameter?

I could imagine in the future, we would have many different models with different plotting functions, optimizations, depending on the functional forms ... just thinking ahead :)

[juanitorduz]

LGTM! Thanks!

As a side comment, personally (so not necessarily true ;) ) I like the NamedTuple structure. It has crossed my mind to even use pydantic for parameter and data validation.

[ferrine]

LGTM! Thanks!

As a side comment, personally (so not necessarily true ;) ) I like the NamedTuple structure. It has crossed my mind to even use pydantic for parameter and data validation.

Pydantic is great and I appreciate anyone taking effort to refactor everything to Pydantic, just not now. WDYT?

[juanitorduz]

I created a discussion issue #502 . I will be happy to work on this :)