moderndid.compute_ucb#

moderndid.compute_ucb(y, x, w, x_eval=None, alpha=0.05, boot_num=99, basis='tensor', j_x_degree=3, j_x_segments=None, k_w_degree=4, k_w_segments=None, knots='uniform', ucb_h=True, ucb_deriv=True, deriv_index=1, deriv_order=1, w_min=None, w_max=None, x_min=None, x_max=None, seed=None, selection_result=None)[source]#

Compute uniform confidence bands for nonparametric instrumental variables.

Constructs simultaneous confidence bands for the structural function \(h_0\) and its derivatives \(\partial^a h_0\). For a fixed sieve dimension \(J\), the bands are constructed by under-smoothing, which requires \(J\) to be larger than the optimal dimension for estimation. The confidence bands are given by

\[C_{n,J}(x) = \left[\hat{h}_J(x) \pm z_{1-\alpha,J}^* \hat{\sigma}_J(x)\right],\]

where \(\hat{\sigma}_J(x)\) is the estimated standard error and \(z_{1-\alpha,J}^*\) is the \((1-\alpha)\) quantile of the supremum of a multiplier bootstrap process given by

\[\sup_{x \in \mathcal{X}} \left| \frac{D_J^*(x)}{\hat{\sigma}_J(x)} \right| = \sup_{x \in \mathcal{X}} \left| \frac{(\psi^J(x))' \mathbf{M}_J \hat{\mathbf{u}}_J^*}{\hat{\sigma}_J(x)} \right|,\]

where \(\hat{\mathbf{u}}_J^*\) contains residuals multiplied by IID \(N(0,1)\) draws. This approach ensures that the bias of the estimator is asymptotically negligible relative to the sampling uncertainty, but at the cost of slower convergence rates for the confidence bands.

When a data-driven dimension \(\tilde{J}\) is selected, this function routes to the procedure from [2] to construct honest and adaptive uniform confidence bands, which contract at the minimax optimal rate.

Parameters:

ynumpy.ndarray: Dependent variable vector of length \(n\).
xnumpy.ndarray: Endogenous regressor matrix of shape \((n, p_x)\).
wnumpy.ndarray: Instrument matrix of shape \((n, p_w)\).
x_evalnumpy.ndarray, optional: Evaluation points for \(X\). If None, uses \(x\).
alphafloat, default=0.05: Significance level (1-alpha confidence level).
boot_numint, default=99: Number of bootstrap replications.
basis{“tensor”, “additive”, “glp”}, default=”tensor”: Type of basis for multivariate X.
j_x_degreeint, default=3: Degree of B-spline basis for \(X\).
j_x_segmentsint, optional: Number of segments for \(X\) basis. If None, chosen automatically.
k_w_degreeint, default=4: Degree of B-spline basis for \(W\).
k_w_segmentsint, optional: Number of segments for \(W\) basis. If None, chosen automatically.
knots{“uniform”, “quantiles”}, default=”uniform”: Knot placement method.
ucb_hbool, default=True: Whether to compute confidence bands for function estimates.
ucb_derivbool, default=True: Whether to compute confidence bands for derivative estimates.
deriv_indexint, default=1: Index (1-based) of \(X\) variable for derivative computation.
deriv_orderint, default=1: Order of derivative to compute.
w_minfloat, optional: Minimum value for \(W\) range.
w_maxfloat, optional: Maximum value for \(W\) range.
x_minfloat, optional: Minimum value for \(X\) range.
x_maxfloat, optional: Maximum value for \(X\) range.
seedint, optional: Random seed for bootstrap.
selection_resultdict, optional: Result from data-driven selection.

Returns:

NPIVResult: NPIV results with uniform confidence bands included.