ConsiderationSetMixedLogit

class pymc_marketing.customer_choice.consideration_set_logit.ConsiderationSetMixedLogit(choice_df, utility_equations, depvar, covariates, consideration_instruments, consideration_intercept=False, random_consideration=False, model_config=None, sampler_config=None, group_id=None, instrumental_vars=None, non_centered=True)

Consideration Set Mixed Logit with optional random consideration intercepts.

Extends MixedLogit with a two-stage structure that separates who gets considered from who is preferred conditional on consideration:

Stage 1 (Consideration):

pi_nj = sigmoid([gamma_0j +] sum_k gamma_zjk * z_tilde_njk [+ eta_n])

Stage 2 (Choice):

P(j | n) = softmax(log(pi_nj) + V_nj)

where V_nj is the standard mixed logit utility from the parent class.

The consideration instruments Z must satisfy an exclusion restriction: they must be structurally separate from the utility covariates X. This is the discrete choice analogue of K != V in transformer attention.

Parameters:

choice_dfpd.DataFrame

Wide DataFrame where each row is a choice scenario.

utility_equationslist of str

Utility formulas in Wilkinson notation (see MixedLogit).

depvarstr

Name of the dependent variable column.

covariateslist of str

Base covariate names (e.g., [‘price’, ‘time’]).

consideration_instrumentsConsiderationInstruments

TypedDict that must contain 'Z_tilde': np.ndarray of shape (N, J) for a single instrument per alternative, or (N, J, K_z) for multiple instruments per alternative. Mean-centring is the caller’s responsibility. At z_tilde = 0, pi = sigmoid(0) = 0.5. Optionally contains 'z_instrument_names': list of str of length K_z for labelling the instrument dimensions.

consideration_interceptbool, optional

If True, adds alternative-specific intercepts gamma_0j to the consideration stage. Default False. When True, gamma_0j and alpha_j (utility intercept) are not jointly identifiable without further constraints; use informative priors or fix one set of intercepts.

random_considerationbool, optional

If True, adds a random intercept eta_n to the consideration stage, capturing unobserved individual-level variation in “visibility” across all alternatives. Default False.

model_configdict, optional

Model configuration with Prior specifications.

sampler_configdict, optional

Sampler configuration for pm.sample().

group_idstr, optional

Column name for group identifier (panel data).

instrumental_varsdict, optional

Instrumental variables for price endogeneity (inherited).

non_centeredbool, optional

Non-centered parameterization for random coefficients.

Notes

Identification design:

• By default (consideration_intercept=False), there is no consideration intercept: gamma_0j is aliased with alpha_j. The utility intercept alpha_j absorbs both baseline preference and baseline consideration for each alternative.

• When consideration_intercept=True, gamma_0j is estimated separately. This requires care: gamma_0j and alpha_j compete to explain baseline alternative-specific effects. Use informative priors or constrain one set to zero.

• Z_tilde is mean-centred: at average screening (z_tilde = 0), pi = sigmoid(0) = 0.5. Only the deviation from population-mean screening drives consideration. This is the exclusion restriction.

• When random_consideration=True, the random intercept eta_n has zero mean (not identifiable separately from alpha_j). Only sigma_consider is identified, capturing between-individual dispersion in consideration probability.

Methods

ConsiderationSetMixedLogit.__init__(...[, ...])	Initialize model configuration and sampler configuration for the model.
ConsiderationSetMixedLogit.apply_intervention(...)	Apply intervention, optionally updating consideration instruments.
ConsiderationSetMixedLogit.attrs_to_init_kwargs(attrs)	Convert the model configuration and sampler configuration from the attributes to keyword arguments.
ConsiderationSetMixedLogit.build_from_idata(idata)	Build model from loaded InferenceData.
ConsiderationSetMixedLogit.build_model(**kwargs)	Build model using stored choice_df and utility_equations.
ConsiderationSetMixedLogit.calculate_share_change(...)	Calculate difference in market share due to intervention.
ConsiderationSetMixedLogit.create_idata_attrs()	Create attributes for the InferenceData object.
ConsiderationSetMixedLogit.fit([choice_df, ...])	Fit the discrete choice model.
ConsiderationSetMixedLogit.graphviz(**kwargs)	Get the graphviz representation of the model.
ConsiderationSetMixedLogit.idata_to_init_kwargs(idata)	Create the model configuration and sampler configuration from the InferenceData to keyword arguments.
ConsiderationSetMixedLogit.load(fname[, check])	Create a ModelBuilder instance from a file.
ConsiderationSetMixedLogit.load_from_idata(idata)	Create a ModelBuilder instance from an InferenceData object.
ConsiderationSetMixedLogit.make_beta_matrix(...)	Combine random and non-random coefficients into full coefficient matrix.
ConsiderationSetMixedLogit.make_choice_prob(U)	Compute choice probabilities via softmax transformation.
ConsiderationSetMixedLogit.make_consideration_probs(...)	Compute consideration probabilities via independent sigmoid per alternative.
ConsiderationSetMixedLogit.make_control_function(...)	Create control function for price endogeneity correction.
ConsiderationSetMixedLogit.make_fixed_coefs(...)	Create alternative-varying coefficients for fixed (non-varying) covariates.
ConsiderationSetMixedLogit.make_intercepts()	Create alternative-specific intercepts with reference alternative set to zero.
ConsiderationSetMixedLogit.make_model(X, F, y)	Build consideration set mixed logit model.
ConsiderationSetMixedLogit.make_non_random_coefs()	Create coefficients for non-random alternative-specific covariates.
ConsiderationSetMixedLogit.make_random_coefs(n_obs)	Create random coefficients that vary across individuals.
ConsiderationSetMixedLogit.make_utility(...)	Compute total systematic utility for each alternative.
ConsiderationSetMixedLogit.parse_formula(df, ...)	Parse the three-part structure of a mixed logit formula specification.
ConsiderationSetMixedLogit.plot_change(change_df)	Plot change induced by a market intervention.
ConsiderationSetMixedLogit.prepare_X_matrix(df, ...)	Prepare the design matrices for the utility equations.
ConsiderationSetMixedLogit.preprocess_model_data(...)	Pre-process the model initiation inputs into PyMC-ready format.
ConsiderationSetMixedLogit.sample([...])	Sample all the things.
ConsiderationSetMixedLogit.sample_posterior_predictive([...])	Sample from posterior predictive, updating consideration instruments if needed.
ConsiderationSetMixedLogit.sample_prior_predictive([...])	Sample from prior predictive distribution.
ConsiderationSetMixedLogit.save(fname, **kwargs)	Save the model's inference data to a file.
ConsiderationSetMixedLogit.set_idata_attrs([idata])	Set attributes on an InferenceData object.
ConsiderationSetMixedLogit.table(...)	Get the summary table of the model.

Attributes

default_model_config	Default model configuration including consideration stage priors.
default_sampler_config	Default sampler configuration.
fit_result	Get the posterior fit_result.
id	Generate a unique hash value for the model.
output_var	The output variable of the model.
posterior	Access the 'posterior' attribute of the InferenceData object.
posterior_predictive	Access the 'posterior_predictive' attribute of the InferenceData object.
predictions	Access the 'predictions' attribute of the InferenceData object.
prior	Access the 'prior' attribute of the InferenceData object.
prior_predictive	Access the 'prior_predictive' attribute of the InferenceData object.
version
idata
sampler_config
model_config