medil.models.NeuroCausalFactorAnalysis

class medil.models.NeuroCausalFactorAnalysis(seed: int = 0, log_path: str = '', verbose: bool = False, **kwargs)[source]

Bases: _MedilCausalModel

Nonlinear MeDIL causal model represented by a masked variational autoencoder.

Learns a nonlinear MeDIL causal model in two phases: pairwise independence tests identify the causal factor structure (biadj), then a masked VAE whose decoder connectivity encodes that structure is trained to learn nonlinear generative mechanisms [MLAS23].

Requires PyTorch: pip install medil[ncfa].

For continuous data, input should be standardized (zero mean, unit variance per feature) before calling fit(). For categorical data, pass raw class indices (integers 0 to K-1) and set hyperparams["num_classes"] = K.

Parameters:

  • seed (int, optional) – Random seed for reproducibility. Default 0.

  • log_path (str, optional) – Directory for training artifacts (model weights, loss history). Created if it does not exist. No artifacts written if empty (default).

  • verbose (bool, optional) – Print timestamped training log entries to stdout. Default False.

  • biadj (ndarray of shape (num_latent, num_meas), optional) – Boolean biadjacency matrix. If empty (default), estimated from data during fit() using xi correlation.

  • **kwargs – Additional keyword arguments passed to the base class (udg, rng).

biadj

Boolean biadjacency matrix (set after fit() or at init).

Type:

ndarray of shape (num_latent, num_meas)

parameters

Learned VAE, accessible as parameters.vae.

Type:

object

loss

Train/validation ELBO and reconstruction losses after fit(), keyed by "elbo_train", "elbo_valid", "recon_train", "recon_valid".

Type:

dict or None

hyperparams

Training hyperparameters. Modify via model.hyperparams.update({...}) before calling fit(). Keys:

  • "method" : independence test for structure learning ("xicor", "dcov_fast", or "g-test" for integer data; default "xicor")

  • "alpha" : significance level for independence tests (default 0.05)

  • "num_epochs" : maximum training epochs (default 200)

  • "lr" : AdamW learning rate (default 1e-3)

  • "beta" : KL weight in the ELBO (default 1.0)

  • "latent_width" : hidden units per latent variable in the decoder (default 2)

  • "meas_width" : hidden units per measurement variable in the decoder (default 2)

  • "num_hidden_layers" : number of decoder hidden layers (default 1)

  • "encoder_hidden_dim" : hidden dimension of the encoder MLP (default 64)

  • "batch_size" : mini-batch size (default 128)

  • "early_stopping" : stop when validation ELBO stagnates (default True)

  • "patience" : early stopping patience in epochs (default 20)

  • "min_delta" : minimum ELBO improvement to reset patience (default 1e-4)

  • "num_classes" : number of categories per measurement (1 = continuous with MSE reconstruction, K ≥ 2 = categorical with cross-entropy loss; a single K is applied uniformly to all measurements — if some variables have fewer than K categories the model trains correctly but sample() may return out-of-range class indices; default 1)

Type:

dict

Methods

__init__([seed, log_path, verbose])

fit(dataset[, split_idcs])

Fit a NeuroCausalFactorAnalysis model to a dataset using a masked VAE.

sample(sample_size[, include_latent])

Sample observations from a fitted NeuroCausalFactorAnalysis model.