Repository navigation
docs(revenue_tree): document the contribution formulas #586
Description
Noticed while using the package.
What: calc_tree_kpis (revenue_tree.py:119-193, main @ c5f4b2a) computes the *_contrib columns with formulas that are documented nowhere: not in the module, function or class docstrings, and not in docs/analysis_modules.md. To interpret the output you have to reverse-engineer the code.
They work out to the following (verified numerically against RevenueTree(...).df). C = customers, S = spend/customer, T = transactions/customer, A = spend/transaction, U = units/transaction, P = price/unit, Δx = x_p2 − x_p1, x̄ = (x_p1 + x_p2) / 2:
| column | formula |
|---|---|
customers_contrib |
ΔC · S̄ |
spend_per_customer_contrib |
ΔS · C̄ |
transactions_per_customer_contrib |
ΔT · Ā · C_p2 − ΔC·ΔS/4 |
spend_per_transaction_contrib |
ΔA · T̄ · C_p2 − ΔC·ΔS/4 |
units_per_transaction_contrib |
(ΔU · P̄ · T_p2 − ΔT·ΔA/4) · C_p2 − ΔC·ΔS/8 |
price_per_unit_contrib |
(ΔP · Ū · T_p2 − ΔT·ΔA/4) · C_p2 − ΔC·ΔS/8 |
Each pair of children sums exactly to its parent's contribution: the top pair sums to Δrevenue. The top level is the symmetric midpoint (two-factor Shapley) split. Lower levels are not symmetric: they are weighted by period-2 values (C_p2, T_p2), and the parent's interaction term is split in equal halves. So transactions_per_customer_contrib ≠ ΔT · Ā · C̄, which is what a reader would likely assume.
Ask: put these formulas in the calc_tree_kpis / RevenueTree docstrings, including the parent-sum property and the p2 weighting. If the asymmetry is unintended, say so and it becomes a bug. Related: #342 (refactor of the same block).
Activity