InteractiveFixedEffects

Factor-model panel counterfactual helper

from _api_doc_utils import *

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 Implementation walkthrough

The additive decomposition, exact factor normalization, and randomized alternative are package-owned dense linear algebra.

fit() requires a finite nonempty balanced matrix. It always subtracts the grand mean. With force 1 or 3 it then subtracts column means from that centered matrix; with force 2 or 3 it subsequently subtracts row means. Under force=3, the second means are computed after the first removal, giving the usual two-way additive decomposition.
Rank zero is a real model: it returns empty factor and loading matrices and a zero interactive component. The fitted surface then consists only of the requested additive pieces.
Exact factor fitting chooses the smaller covariance matrix. If \(T<N\), it decomposes \(EE'/(NT)\), sets \(F=\sqrt{T}U_r\), and obtains \(\Lambda=E'F/T\). If \(T\geq N\), it decomposes \(E'E/(NT)\), sets \(\Lambda=\sqrt{N}V_r\), and obtains \(F=E\Lambda/N\). This avoids an SVD of the larger Gram matrix while enforcing the stated normalizations.
The exact vnt diagonal stores the leading eigenvalues of that scaled Gram matrix. The reconstructed interaction is always the direct product \(F\Lambda'\).
Randomized mode instead calls the native randomized SVD of the demeaned \(E\): a Rademacher range sketch, optional alternating power iterations with QR reorthogonalization, and a small projected SVD. It sets \(F=\sqrt{T}U_r\), \(\Lambda_{jk}=V_{jk}s_k/\sqrt{T}\), and stores \(s_k^2/(NT)\) on the vnt diagonal.
The final fitted matrix starts from the interactive product, adds the grand mean to every cell, then broadcasts column and row effects according to the decomposition. Residuals are the original matrix minus this in-sample reconstruction. predict() simply returns the stored fitted panel; there is no transform for new units or periods.

Both exact branches and the randomized branch produce the same normalization target, though signs and rotations remain arbitrary. The exact smaller-Gram route squares the singular-value condition number; the randomized direct-SVD route trades exactness for fewer passes when rank is small.

4 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.

5 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.

6 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, /)`

7 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)

8 `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`	`()`