from _api_doc_utils import *InteractiveFixedEffects
Factor-model panel counterfactual helper
1 Where it fits
Group: Causal inference
InteractiveFixedEffects estimates a low-rank factor structure in a balanced panel. It is closest to a lightweight fect helper: remove additive components according to force, estimate factors, and reconstruct fitted untreated outcomes.
2 Objective and decomposition
For a balanced \(T\times N\) outcome matrix, the model is
\[ Y_{ti} = \mu+\alpha_i+\xi_t+f_t'\lambda_i+e_{ti}. \]
The grand mean \(\mu\) is always removed, including when force is zero. Force values one and three include column effects \(\alpha_i\); values two and three include row effects \(\xi_t\). After those additive effects are removed, the estimator solves the rank-constrained approximation
\[ \min_{\operatorname{rank}(L)\leq r} \|Y-\mu\mathbf1\mathbf1'-\mathbf1\alpha'-\xi\mathbf1'-L\|_F^2. \]
With the exact method, \(L\) is the rank-\(r\) truncated SVD. Factors are normalized as \(F=\sqrt{T}U_r\) and loadings as \(\Lambda=V_r\operatorname{diag}(s_r)/\sqrt{T}\), so \(L=F\Lambda'\). The randomized method substitutes a randomized range finder and truncated SVD controlled by oversampling and power iterations.
3 Inference and scope
This class is a matrix decomposition, not a treatment-effect estimator. It returns the in-sample fitted matrix, residuals, additive effects, factors, loadings, and normalized singular-value matrix. It does not select rank, estimate coefficient covariance, provide standard errors, handle missing entries, or extrapolate to new rows or columns. Factor and loading rotations are not separately identified even though their product is.
4 Performance and numerical behavior
Exact dense SVD costs approximately \(O(\min\{TN^2,T^2N\})\) and stores the full panel. Randomized SVD reduces the leading work to roughly \(O(TN(r+s)(q+1))\) for rank \(r\), oversampling \(s\), and power count \(q\), but is approximate and still stores dense matrices. Rank must not exceed \(\min(T,N)\). Because only complete balanced panels are accepted, use MatrixCompletion when treated or otherwise missing cells must be excluded from fitting.
5 Python API
Constructor: cm.InteractiveFixedEffects
Use InteractiveFixedEffects(rank=0, force=3, ...), then fit(y). predict() reconstructs the fitted panel. summary() reports low-rank pieces, additive effects, singular values, chosen rank, and diagnostics.
print(inspect.signature(cm.InteractiveFixedEffects))(rank=0, force=3, factor_method=Ellipsis, factor_oversamples=10, factor_power_iter=1, factor_seed=None)cls = cm.InteractiveFixedEffects
display(HTML(html_table(["Public method"], public_methods(cls))))| Public method |
|---|
fit(self, /, y) |
predict(self, /) |
summary(self, /) |
6 Minimal example
rng = np.random.default_rng(19)
y = rng.normal(size=(12, 16)) + rng.normal(size=(12, 1)) + rng.normal(size=(1, 16))
model = cm.InteractiveFixedEffects(rank=2)
model.fit(y)
print(model.summary()['rank'])
print(model.predict().shape)2
(12, 16)7 summary() contract
The table below is generated by fitting the live class in this repository and then inspecting summary(). Shapes are shown because most values are plain NumPy arrays or scalars.
rng = np.random.default_rng(119)
y = rng.normal(size=(10, 12)) + rng.normal(size=(10, 1)) + rng.normal(size=(1, 12))
model = cm.InteractiveFixedEffects(rank=2)
model.fit(y)
summary = model.summary()
display(HTML(html_table(["summary() key", "shape"], summary_shape_rows(summary))))| summary() key | shape |
|---|---|
fit |
(10, 12) |
residuals |
(10, 12) |
mu |
() |
alpha |
(12,) |
xi |
(10,) |
factor |
(10, 2) |
loading |
(12, 2) |
vnt |
(2, 2) |
rank |
() |
force |
() |
factor_method |
() |
factor_oversamples |
() |
factor_power_iter |
() |