diff_diff.meridian_calibration_mask#

diff_diff.meridian_calibration_mask(*, media_times, media_channels, channel, window)[source]

Build Meridian’s boolean roi_calibration_period mask for an experiment.

Returns a (len(media_times), len(media_channels)) bool array: the experiment channel’s column(s) are True exactly on the selected window, and every OTHER channel’s column is all-True - Meridian’s documented convention (“any media channels not specified … will utilize all available periods for ROI calibration”, configure-model guide); an all-False column would zero that channel’s aggregated calibration spend. Suitable to pass straight to Meridian’s spec.ModelSpec(roi_calibration_period=...), or to MeridianROIPrior.to_code(), which serializes it into the generated snippet. Valid for roi_m priors only: Meridian 1.7.0 rejects a non-None roi_calibration_period unless the media prior type is 'roi'.

Window convention: a 2-TUPLE is (start, end) INCLUSIVE bounds; any OTHER sequence (list, ndarray, Series, Index) is a set of explicit time labels. To select exactly two labels, pass a list [a, b], not a tuple.

Parameters:

  • media_times (list, tuple, ndarray, Series, or Index) – The MMM’s time coordinate labels, taken VERBATIM in model order (str dates, datetimes, periods, or ints; unique, no missing labels; these five container types are the accepted forms - materialize e.g. a range with list(...)). Meridian’s n_media_times can exceed len(data.time) when max_lag > 0 adds lagged leading periods, yet Google’s own configure-model example builds the mask with len(data.time) rows - this builder does not resolve that nuance: pass whichever coordinate list your ModelSpec expects, and the mask gets one row per entry. String labels order-compare lexicographically under a bounds window - right for zero-padded ISO dates ('2021-11-01'), wrong for '1/2/2021'-style formats (use explicit labels or datetime labels there).

  • media_channels (list, tuple, ndarray, Series, or Index of str) – Channel names in the Meridian InputData media-channel order (the same contract as to_code(media_channels=)); unique, non-empty. The mask’s columns are positioned by this order - keep the SAME list, in the same order, for the builder and for to_code.

  • channel (str or sequence of str) – The experiment channel(s) whose columns carry the window - here a sequence means “the set of mask columns to mark for THIS experiment” (unlike to_pymc_marketing_lift_test(channel=...), where a sequence is one channel per experiment row; the builder has no per-row axis). Every name must be in media_channels.

  • window (tuple or sequence) – Either (start, end) inclusive bounds - selected by order comparison against media_times, with pd.to_datetime coercion of the values when media_times is datetime-like (timezone mismatches fail closed in both directions) - or a sequence of explicit time labels, every one of which must be present in media_times. Must select at least one time. Selection is by label VALUE at its position, so an unsorted media_times is well-defined.

Returns:

Boolean, shape (len(media_times), len(media_channels)).

Return type:

np.ndarray

Raises:

  • TypeError – On wrong-typed inputs (string/Mapping/scalar/MultiIndex/non-1-D-array containers, a scalar or Mapping window, an array-valued window bound).

  • ValueError – On empty inputs, duplicate or missing labels, unknown channels, malformed or empty-selection windows, and unorderable or timezone- mismatched bounds.