LatentFactorGLM

Guide & worked example · Source

LatentFactorGLM(
    family='gaussian',
    rank=2,
    penalty=0.01,
    beta_penalty=0.0,
    optimizer=torch.optim.AdamW,
    optimizer_kwargs=None,
    maxiter=2000,
    tol=1e-06,
    device=None,
)

Latent-factor GLM with factorized optimization.

Supported families are:

• "gaussian": y_it = x_it’ beta + a_i’ b_t + offset_it + eps_it
• "bernoulli": Pr(y_it = 1 | X) = sigmoid(x_it’ beta + a_i’ b_t + offset_it)
• "poisson": E[y_it | X] = exp(x_it’ beta + a_i’ b_t + offset_it)

Parameters

Name	Type	Description	Default
family	str	Outcome family. Supported values are "gaussian", "bernoulli", and "poisson".	"gaussian"
rank	int	Latent factor rank.	2
penalty	float	Ridge penalty applied to unit and time factors.	1e-2
beta_penalty	float	Optional ridge penalty for observed-effect coefficients.	0.0
optimizer	torch optimizer class	Optimizer used for factorized estimation.	torch.optim.AdamW
optimizer_kwargs	dict	Keyword arguments forwarded to the optimizer constructor.	None
maxiter	int	Maximum optimizer iterations.	2000
tol	float	Relative convergence tolerance on the loss history.	1e-6
device	torch.device | str	Computation device.	None

Attributes

Name	Description
POISSON_ETA_MAX
SUPPORTED_FAMILIES
beta_penalty
device
family
history
maxiter
optimizer_class
optimizer_kwargs
params
penalty
rank
tol

Methods

Name	Description
fit	Fit a latent-factor GLM on observed cells.
predict	Predict for dense panels only, matching the BaseEstimator interface.
predict_index	Predict the latent index x’beta + a_i’b_t + offset.
predict_mean	Predict the conditional mean under the configured family.
predict_proba	Predict Bernoulli success probabilities.
summary	Print a concise summary of the fitted latent-factor model.
to	Move model parameters and fitted metadata to a new device.

fit

LatentFactorGLM.fit(
    X,
    y,
    unit_ids=None,
    time_ids=None,
    mask=None,
    offset=None,
    verbose=False,
)

Fit a latent-factor GLM on observed cells.

Parameters

Name	Type	Description	Default
X	torch.Tensor	Either (n_obs, n_features) with explicit unit/time IDs or (n_units, n_times, n_features) for dense panels.	required
y	torch.Tensor	Either (n_obs,) or (n_units, n_times).	required
unit_ids	torch.Tensor	Observation-level unit and time identifiers for sparse layouts.	None
time_ids	torch.Tensor	Observation-level unit and time identifiers for sparse layouts.	None
mask	torch.Tensor	Boolean training mask over observations or dense panel cells.	None
offset	torch.Tensor	Known additive offset with the same shape as y.	None
verbose	bool	Whether to print convergence messages.	False

predict

LatentFactorGLM.predict(X)

Predict for dense panels only, matching the BaseEstimator interface.

predict_index

LatentFactorGLM.predict_index(X, unit_ids=None, time_ids=None, offset=None)

Predict the latent index x’beta + a_i’b_t + offset.

predict_mean

LatentFactorGLM.predict_mean(X, unit_ids=None, time_ids=None, offset=None)

Predict the conditional mean under the configured family.

predict_proba

LatentFactorGLM.predict_proba(X, unit_ids=None, time_ids=None, offset=None)

Predict Bernoulli success probabilities.

summary

LatentFactorGLM.summary()

Print a concise summary of the fitted latent-factor model.

to

LatentFactorGLM.to(device)

Move model parameters and fitted metadata to a new device.