HierarchicalLaunchITS

class causalpy.pymc_models.HierarchicalLaunchITS

Hierarchical Bayesian interrupted time series model for multi-unit panels with unit-specific treatment (launch) times.

Each unit (e.g. a product) has its own launch time. Per-unit intercepts, covariate effects and launch “lift” are partially pooled toward shared population-level hyperparameters, which lets sparse units borrow strength from well-observed ones and yields a posterior distribution over the population lift that can be used to forecast the effect of a new unit.

Three effect parameterizations are supported via the experiment layer:

• "instant": a single post-launch level shift per unit, lift[unit] ~ Normal(mu_lift, sigma_lift).

• "event_study": per-unit dynamic coefficients delta[unit, event_bin] over user-specified post-launch event-time bins (pre-launch is the implicit reference).

• "placebo": the event-study form extended with pre-launch leads; the most negative leads serve as placebos that should be indistinguishable from zero if the no-anticipation assumption holds.

All hierarchical parameters use a non-centered parametrization.

Expected inputs

• X : xr.DataArray with dims ["obs_ind", "coeffs"] holding the standardized covariate design (built by the experiment from a patsy formula, without an intercept — the hierarchical alpha plays that role).

• y : xr.DataArray with dims ["obs_ind", "treated_units"]; the single treated_units entry is retained for API consistency with the rest of CausalPy — the per-unit hierarchy is indexed via the unit coord instead.

• aux (passed to fit()/predict()) : dict with keys effect_type, unit_idx (int array of length n_obs) and, as appropriate, F (Fourier basis), post (0/1 indicator) and D (one-hot event-bin design).

See causalpy.experiments.hierarchical_interrupted_time_series.HierarchicalInterruptedTimeSeries for the user-facing experiment wrapper that assembles aux from a long panel DataFrame.

Methods

HierarchicalLaunchITS.__init__([...])
HierarchicalLaunchITS.add_coord(name[, ...])	Register a dimension coordinate with the model.
HierarchicalLaunchITS.add_coords(coords, *)	Vectorized version of Model.add_coord.
HierarchicalLaunchITS.add_named_variable(var)	Add a random graph variable to the named variables of the model.
HierarchicalLaunchITS.build_model(X, y, coords)
HierarchicalLaunchITS.calculate_cumulative_impact(impact)
HierarchicalLaunchITS.calculate_impact(...)	Calculate the causal impact as the difference between observed and predicted values.
HierarchicalLaunchITS.check_start_vals(...)	Check that the logp is defined and finite at the starting point.
HierarchicalLaunchITS.compile_d2logp([vars, ...])	Compiled log probability density hessian function.
HierarchicalLaunchITS.compile_dlogp([vars, ...])	Compiled log probability density gradient function.
HierarchicalLaunchITS.compile_fn(outs, *[, ...])
HierarchicalLaunchITS.compile_logp([vars, ...])	Compiled log probability density function.
HierarchicalLaunchITS.copy()	Clone the model.
HierarchicalLaunchITS.create_value_var(...)	Create a TensorVariable that will be used as the random variable's "value" in log-likelihood graphs.
HierarchicalLaunchITS.d2logp([vars, ...])	Hessian of the models log-probability w.r.t.
HierarchicalLaunchITS.debug([point, fn, verbose])	Debug model function at point.
HierarchicalLaunchITS.dlogp([vars, jacobian])	Gradient of the models log-probability w.r.t.
HierarchicalLaunchITS.eval_rv_shapes()	Evaluate shapes of untransformed AND transformed free variables.
HierarchicalLaunchITS.fit(X, y[, coords, aux])	Fit the hierarchical launch ITS model.
HierarchicalLaunchITS.get_context([...])
HierarchicalLaunchITS.initial_point([...])	Compute the initial point of the model.
HierarchicalLaunchITS.logp([vars, jacobian, sum])	Elemwise log-probability of the model.
HierarchicalLaunchITS.logp_dlogp_function([...])	Compile a PyTensor function that computes logp and gradient.
HierarchicalLaunchITS.make_obs_var(rv_var, ...)	Create a TensorVariable for an observed random variable.
HierarchicalLaunchITS.name_for(name)	Check if name has prefix and adds if needed.
HierarchicalLaunchITS.name_of(name)	Check if name has prefix and deletes if needed.
HierarchicalLaunchITS.point_logps([point, ...])	Compute the log probability of point for all random variables in the model.
HierarchicalLaunchITS.predict(X[, coords, ...])	Posterior predictive using the supplied aux bundle.
HierarchicalLaunchITS.print_coefficients(labels)	Print the model coefficients with their labels.
HierarchicalLaunchITS.priors_from_data(X, y)	Data-adaptive priors keyed to the scale of y.
HierarchicalLaunchITS.profile(outs, *[, n, ...])	Compile and profile a PyTensor function which returns outs and takes values of model vars as a dict as an argument.
HierarchicalLaunchITS.register_data_var(data)	Register a data variable with the model.
HierarchicalLaunchITS.register_rv(rv_var, ...)	Register an (un)observed random variable with the model.
HierarchicalLaunchITS.replace_rvs_by_values(...)	Clone and replace random variables in graphs with their value variables.
HierarchicalLaunchITS.score(X, y[, coords])	Score the Bayesian \(R^2\) given inputs X and outputs y.
HierarchicalLaunchITS.set_data(name, values)	Change the values of a data variable in the model.
HierarchicalLaunchITS.set_dim(name, new_length)	Update a mutable dimension.
HierarchicalLaunchITS.set_initval(rv_var, ...)	Set an initial value (strategy) for a random variable.
HierarchicalLaunchITS.shape_from_dims(dims)
HierarchicalLaunchITS.to_graphviz(*[, ...])	Produce a graphviz Digraph from a PyMC model.

Attributes

basic_RVs	List of random variables the model is defined in terms of.
continuous_value_vars	All the continuous value variables in the model.
coords	Coordinate values for model dimensions.
datalogp	PyTensor scalar of log-probability of the observed variables and potential terms.
default_priors
dim_lengths	The symbolic lengths of dimensions in the model.
discrete_value_vars	All the discrete value variables in the model.
isroot
observedlogp	PyTensor scalar of log-probability of the observed variables.
parent
potentiallogp	PyTensor scalar of log-probability of the Potential terms.
prefix
root
unobserved_RVs	List of all random variables, including deterministic ones.
unobserved_value_vars	List of all random variables (including untransformed projections), as well as deterministics used as inputs and outputs of the model's log-likelihood graph.
value_vars	List of unobserved random variables used as inputs to the model's log-likelihood (which excludes deterministics).
varlogp	PyTensor scalar of log-probability of the unobserved random variables (excluding deterministic).
varlogp_nojac	PyTensor scalar of log-probability of the unobserved random variables (excluding deterministic) without jacobian term.

__init__(sample_kwargs=None, priors=None)

Parameters:

• sample_kwargs (dict[str, Any] | None) – Dictionary of kwargs that get unpacked and passed to the pymc.sample() function. Defaults to an empty dictionary if None.

• priors (dict[str, Any] | None) – Dictionary of priors for the model. Defaults to None, in which case default priors are used.

Return type:

None

classmethod __new__(*args, **kwargs)