uam

uam combines aggregated attribution and customer journey attribution in a single workflow.

The aggregated baseline is now computed through the unified mmm_attribution engine. If df_paths is not provided, uam returns the aggregated baseline. If df_paths is provided, uam adjusts that baseline with Markov conversion-rate information from customer journeys.

Current UAM behavior

The current public behavior is a Markov-limited adjustment of the aggregated baseline:

baseline attribution from mmm_attribution
→ Markov conversion-rate signal from paths
→ channel-level adjustment multiplier
→ row normalization back to the baseline total

The diagnostic formula is:

baseline_model_times_channel_weighted_markov_norm

The public mode is:

adjusted_baseline

Input structure

df_aggr must contain:

• a timestamp column, or enough information for the wrapper to create/resolve the timestamp internally;
• the target column passed through target;
• one or more aggregated signal columns.

target is required and must be the name of an existing column in df_aggr.

D_variables must contain one row per non-target signal variable and these columns:

COLUMN	DESCRIPTION
variable	Name of the signal column in df_aggr.
channel	Final attribution channel associated with the signal. Multiple variables can map to the same channel.
measure	Measure label for the signal. Measure labels are free and do not need to belong to a predefined cap table.

df_paths is optional. When supplied, it can contain either:

• already aggregated customer journey paths, with columns such as path, total_conversions, and optionally total_null; or
• event-level customer journeys, with columns such as id_path, timestamp, and touchpoint.

For event-level journeys, the touchpoint column is expected to be named touchpoint.

Parameters

PARAMETER	TYPE	DEFAULT	DESCRIPTION
df_aggr	data.frame		Aggregated dataset with timestamp, target, and input signal columns.
D_variables	data.frame / table		Table with variable, channel, and measure columns.
target	str	required	Name of the target column in df_aggr.
df_paths	data.frame	NULL / None	Optional customer journey data used to adjust the aggregated baseline.
baseline_model	str	"reward"	Baseline engine passed to mmm_attribution. Allowed public values are "reward", "copula", and "linear".
var_path	str	"path"	Column containing serialized journeys when aggregated paths are provided.
var_conv	str	"total_conversions"	Column containing conversions associated with each aggregated path.
var_null	str	"total_null"	Column containing null-path counts when available.
channel_conv	str	"((CONV))"	Conversion marker used in event-level customer journey data.
max_p	int	12	Maximum lag length considered by the aggregated baseline.
nsim	int	1000	Simulation parameter used by the copula baseline and kept for a consistent API.
seed	int	1234567	Random seed for reproducible results.
verbose	int / bool	1	Controls runtime logging.
order	int	1	Markov model order used for the path-based component.
sep	str	">"	Path separator used inside serialized journey strings.
ncore	int	1	Number of cores used by the path-based computation.
server	str / list[str]	hosted endpoint	Server endpoint used by the hosted computation service.
password	str	NULL / None	Authentication token for the hosted service.
return_diagnostics	bool	FALSE / False	If enabled, returns attribution together with diagnostic objects.

Legacy baseline_model aliases may still be accepted for compatibility, but new examples should use reward, copula, or linear.

Baseline-only mode

When df_paths = NULL / None, uam runs mmm_attribution internally and returns the baseline attribution.

Path-adjusted mode

When df_paths is provided, UAM:

1. computes the aggregated baseline using mmm_attribution;
2. runs markov_model(..., type="cr") on the path data;
3. maps Markov path signals back to channels declared in D_variables;
4. estimates a channel adjustment weight from path support and baseline/path alignment;
5. applies a bounded channel-level multiplier to the baseline;
6. normalizes each row back to the original baseline row total.

The current implementation does not perform a variable-aware row-by-row recomposition from raw variable attribution. It applies a final channel-level adjustment to the channel baseline.

Output

In the current public wrappers, uam returns a list/dict containing:

OUTPUT	TYPE	DESCRIPTION
attribution	data.frame	Final channel attribution by time period.

If return_diagnostics = TRUE, the returned list/dict may also include:

OUTPUT	TYPE	DESCRIPTION
baseline_model	str	Resolved baseline model: reward, copula, or linear.
model_score_target	str	Internal automatic/blended score target mode.
parameters_mmm	list / dict	Diagnostics from the mmm_attribution baseline.
parameters_baseline	list / dict	Alias for baseline diagnostics.
parameters_mta_raw	list / dict	Raw Markov output.
parameters_mta_adjusted	data.frame / object	Channel-level final Markov adjustment parameters.
parameters_mta_channel_measure_alignment	data.frame / object	Diagnostic alignment between aggregated data and path support by channel/measure.
parameters_mta_channel_weights	data.frame / object	Channel-level Markov blend weights.
parameters_mta_markov_blend_summary	data.frame / object	Baseline/final share comparison by channel.
mode	str	Diagnostic execution mode, such as <baseline_model>_baseline_markov_limited_adjustment.
mode_public	str	Public mode label, such as adjusted_baseline.
row_sum_check	list / dict	Diagnostics checking that row sums remain consistent after adjustment.