Robyn: Continuos & Semi Automated MMM

What is Robyn?

Robyn is an open-source Marketing Mix Modeling (MMM) package developed by Meta Marketing Science. It leverages AI/ML algorithms to improve marketing optimization and decision-making.

Designed for large-scale, granular datasets, making it particularly useful for advertisers with many independent variables and complex marketing environments.
Through AI-powered automation, Robyn supports efficient, near real-time marketing decisions.
Originally written in R, but it also provides a Python API via Nevergrad, enabling use across different environments.

Note (How to use the Robyn API in Python)

Overall workflow:

[Robyn hosted on R] → [API exposed via R/plumber] → [Python client]

Prerequisites:

Install R
Install R packages: Robyn, plumber, and supporting dependencies
Install Python
Install Nevergrad (Meta’s gradient-free optimization library)

Steps:

brew install r

# Install Robyn (R package from GitHub)
Rscript -e 'remotes::install_github("facebookexperimental/Robyn/R")'

# Install required dependencies
Rscript -e 'install.packages(c("arrow", "dplyr", "plumber", "ggplot2", "jsonlite", "tibble"))'

# Follow setup instructions for Nevergrad:
# https://github.com/facebookexperimental/Robyn/blob/main/demo/install_nevergrad.R

Key Features

Automation & AI Integration Uses multi-objective evolutionary algorithms for hyperparameter optimization, automating key modeling processes.
Time-Series Decomposition Decomposes trends and seasonality in time-series data, essential for long-term marketing strategy.
Ridge Regression Employs regularized regression for model fitting, improving stability and interpretability in high-dimensional datasets.
Gradient-Based Optimizer Automatically optimizes budget allocation across multiple marketing channels based on ROI objectives.

Code Example 1

Here’s a minimal example showing how to use Nevergrad with Pyomo models, similar to how Robyn integrates optimization into MMM workflows:

Note (What is Nevergrad?)

Nevergrad is an open-source Python library developed by Meta for derivative-free optimization. It is used in this case to call Robyn’s optimization routines from Python.

1
import pyomo.environ as pyo
2
import nevergrad as ng
3
import nevergrad.functions.pyomo as ng_pyomo
4

5
# Define variables
6
A = ['hammer', 'wrench', 'screwdriver', 'towel']
7
b = {'hammer': 8, 'wrench': 3, 'screwdriver': 6, 'towel': 11}  # benefit values
8
w = {'hammer': 5, 'wrench': 7, 'screwdriver': 4, 'towel': 3}   # weights
9
w_max = 14  # capacity constraint
10

11
# Define Pyomo model
12
model = pyo.ConcreteModel()
13
model.x = pyo.Var(A, domain=pyo.Binary)  # binary decision variables
14

15
# Objective function: maximize benefit (minimize negative benefit)
16
model.obj = pyo.Objective(expr = -sum(b[i] * model.x[i] for i in A))
17

18
# Constraint: total weight ≤ max
19
model.constr = pyo.Constraint(expr = sum(w[i] * model.x[i] for i in A) <= w_max)
20

21
# Convert Pyomo model into a Nevergrad-compatible function
22
func = ng_pyomo.Pyomo(model)
23

24
# Choose optimizer (BFGS-CMA hybrid in this case)
25
optimizer = ng.optimizers.BFGSCMA(parametrization=func.parametrization, budget=100)
26

27
# Run optimization
28
recommend = optimizer.minimize(func.function)
29

30
# View recommended solution
31
recommend.kwargs
32
# Example output: {'hammer': 1.0, 'wrench': 0.0, 'screwdriver': 1.0, 'towel': 1.0}

Code Example 2

Here’s a more complete example showing how to run a full Robyn MMM analysis using the Python API:

1
import robyn
2
from robyn import robyn_api, pandas_builder
3

4
dt_simulated_weekly = pandas_builder (robyn_api('dt_simulated_weekly'))
5
dt_prophet_holidays = pandas_builder(robyn_api("dt_prophet_holidays"))
6

7
# specify input variables
8
inputArgs = {
9
   "date_var": "DATE", # date format must be "2020-01-01"
10
   "dep_var": "revenue", # there should be only one dependent variable
11
   "dep_var_type": "revenue" # "revenue" (ROI) or "conversion" (CPA)
12
   "prophet_vars": ["trend", "season", "holiday"] # "trend", "season", "weekday" & "holiday"
13
   "prophet_country": "DE", # input country code. Check: dt_prophet_holidays
14
   "context_vars" : ["competitor_sales_B", "events"], # e.g. competitors, discount, unemployment etc
15
   "paid_media_spends": ["tv_S", "ooh_S", "search_S", "social_S"], # media spend variables
16
   "paid_media_vars": ["tv_exposure", "ooh_exposure", "search_exposure", "social_exposure"], # media exposure variables
17
   # paid_media_vars must have same order as paid _media_spends. Use media exposure metrics like
18
   # impressions, GRP etc. If not applicable, use spend instead.
19
   "organic_vars" : "newsletter", # marketing activity without media spend
20
   # "factor_vars" : ["events"], # force variables in context_vars or organic_vars to be categorical
21
   "window_start": "2016-01-01",
22
   "window_end": "2018-12-31",
23
   "adstock": "geometric" # geometric, weibull_cdf or weibull_pdf.
24
}
25

26
# build the payload for the robyn_inputs()
27
payload = {
28
   'dt_input': asSerialisedFeather(dt_simulated_weekly),
29
   'dt_holidays': asSerialisedFeather(dt_prophet_holidays),
30
   'jsonInputArgs': json.dumps (inputArgs)
31
}
32

33
InputCollect = robyn_api('robyn_inputs', payload=payload)
34

35
# define hyperparameters
36

37
payload = {
38
   'adstock': InputCollect['adstock'],
39
   'all_media': json.dumps(InputCollect['all_media'])
40
}
41

42
hyper_names = robyn_api('hyper_names', payload=payload)
43
inputArgs = {
44
   "hyper_parameters": {
45
      "facebook_S_alphas": [0.5, 3],
46
      "facebook_S_gammas": [0.3, 31],
47
      "facebook_S_thetas": [0.1, 11],
48

49
      "print_S_alphas": [0.5, 3],
50
      "print_S_gammas": [0.3, 31],
51
      "print_S_thetas": [0.1, 11],
52

53
      "tv_S_alphas": [0.5, 3],
54
      "tv_S_gammas": [0.3, 31],
55
      "tv_S_thetas": [0.1, 11],
56

57
      "search_S_alphas": [0.5, 3],
58
      "search_S_gammas": [0.3, 31],
59
      "search_S_thetas": [0.1, 11],
60

61
      "ooh_S_alphas": [0.5, 3],
62
      "ooh_S_gammas": [0.3, 31],
63
      "ooh_S_thetas": [0.1, 11],
64

65
      "newsletter_alphas": [0.5, 3],
66
      "newsletter_gammas": [0.3, 31],
67
      "newsletter_thetas": [0.1, 11],
68

69
      "train_size": [0.5, 0.8]
70
   }
71
}
72

73
payload = {
74
   'InputCollect': json.dumps(InputCollect),
75
   'jsonInputArgs': json.dumps(inputArgs)
76
}
77
InputCollect = robyn_api('robyn_inputs', payload=payload)
78

79

80
# Build initial models
81
runArgs = {
82
   "iterations": 2000, #nevergrad
83
   "trials": 5, # nevergrad
84
   "ts_validation": True,
85
   "add_penalty_factor": False
86
}
87

88
payload = {
89
   'InputCollect': json.dumps(InputCollect),
90
   'jsonRunArgs': json.dumps(runArgs)
91
}
92

93
OutputModels = robyn_api('robyn_run', payload=payload)
94

95
plot_outputgraphs(OutputModels, graphytype='moo_distrb_plot', max_size=(1000, 1500))
96
plot_outputgraphs(OutputModels, graphytype='moo_cloud_plot', max_size=(1000, 1500))
97
plot_outputgraphs(OutputModels, graphytype='ts_validation_plot', max_size=(1000, 1500))
98

99

100
# evaluate models - robyn_outputs
101

102
outputArgs = {
103
   "pareto_fronts": "auto",
104
   "csv_out": "pareto"
105
   "cluster": True,
106
   "export": create_files,
107
   "plot_folder": robyn_directory,
108
   "plot_pareto": create_files,
109
}
110

111
payload = {
112
   'InputCollect': json.dumps(InputCollect),
113
   'OutputModels': json.dumps(OutputModels),
114
   'jsonOutputArgs': json.dumps(outputArgs)
115
}
116

117
OutputCollect = robyn_api('robyn_outputs', payload=payload)
118

119
for i in OutputCollect['clusters']['models']:
120
   print(i['solID'])
121

122
# select & save model
123
load_onepager (top_pareto=True,sol='all' ,   InputJson=InputCollect,OutputJson=OutputCollect, path=robyn_directory)
124

125
# budget allocation
126
InputCollect['paid_media_spends'] # ['tv_S', 'ooh_S', 'search_S', 'social_S']
127
select_model = '2_143_11'
128
allocatorArgs = {
129
   'select_model': select_model,
130
   # 'date_range': InputCollect['date_range'],
131
   # 'total_budget': InputCollect['total_budget'],
132
   'channel_constr_low': 0.7,
133
   'channel_constr_up': 1.2,
134
   'channel_constr_multiplier': 3,
135
   'scenario': 'max_response'
136
}
137

138
payload = {
139
   'InputCollect': json.dumps(InputCollect),
140
   'OutputCollect': json.dumps(OutputCollect),
141
   'jsonAllocatorArgs': json.dumps(allocatorArgs),
142
   'dpi': 100,
143
   'width': 15,
144
   'height': 15
145
}
146

147
allocator = robyn_api('robyn_allocator', payload=payload)
148

149
# plot the graphs again...