Generative Models#

Generative architectures for time-series representation learning.

TimeVAE#

Variational autoencoder for time-series, with KL divergence + reconstruction loss. Uses BasicEncodingMixin for inference.

class chronocratic.models.generative.timevae.model.TimeVAE(seq_len: int, feat_dim: int, latent_dim: int, reconstruction_wt: float = 3.0, learning_rate: float = 0.001, hidden_layer_sizes: list[int] | None = None, trend_poly: int = 0, custom_seas: list[tuple[int, int]] | None = None, *, use_residual_conn: bool = True)#

Bases: BaseVariationalAutoencoder, BasicEncodingMixin

TimeVAE Model.

This model was implemented based on the code available on this GitHub repo abudesai/timeVAE under MIT License.

class chronocratic.models.generative.timevae.model.TimeVAEDecoder(seq_len: int, feat_dim: int, hidden_layer_sizes: list[int], latent_dim: int, trend_poly: int = 0, custom_seas: list[tuple[int, int]] | None = None, *, use_residual_conn: bool = True, encoder_last_dense_dim: int | None = None)#

Bases: Module

forward(z: Tensor) → Tensor#

Decode latent samples into reconstructed time-series batches.

class chronocratic.models.generative.timevae.model.TimeVAEEncoder(seq_len: int, feat_dim: int, hidden_layer_sizes: list[int], latent_dim: int)#

Bases: Module

forward(x: Tensor) → tuple[Tensor, Tensor, Tensor]#

Encode an input batch into latent mean, log-variance, and sample.

Configuration for the TimeVAE model.

Provides TimeVAEModelParameters with all settings for the variational autoencoder, including the optional trend, seasonal, and residual decoder branches.

class chronocratic.models.generative.timevae.config.TimeVAEModelParameters(*, seq_len: int, feat_dim: int, latent_dim: int, reconstruction_wt: float = 3.0, learning_rate: float = 0.001, hidden_layer_sizes: list[int] = <factory>, trend_poly: int = 0, custom_seas: list[tuple[int, int]] | None=None, use_residual_conn: bool = True)#

Bases: object

Configuration for the TimeVAE model.

Parameters:

  • seq_len – Length of each input time-series sample.

  • feat_dim – Number of input features (channels).

  • latent_dim – Dimensionality of the latent space.

  • reconstruction_wt – Weight applied to the reconstruction term of the VAE loss (the KL term is unweighted).

  • learning_rate – Base learning rate for the optimizer.

  • hidden_layer_sizes – Output channel sizes of the successive Conv1d / ConvTranspose1d blocks in the encoder and residual decoder.

  • trend_poly – Degree of the polynomial trend basis used by the trend decoder branch. 0 disables the trend branch.

  • custom_seas – Optional list of (num_seasons, len_per_season) tuples describing additive seasonal components. None disables the seasonal branch.

  • use_residual_conn – Whether to include the residual ConvTranspose branch in the decoder.

class chronocratic.models.generative.timevae.vae_base.BaseVariationalAutoencoder(seq_len: int, feat_dim: int, latent_dim: int, reconstruction_wt: float = 3.0, learning_rate: float = 0.001)#

Bases: LightningModule, ABC

forward(x: Tensor) → Tensor#

Reconstruct an input batch using the latent mean.

training_step(batch: Tensor, _batch_idx: int) → Tensor#

Compute, log, and return the training loss for one batch.

validation_step(batch: Tensor, _batch_idx: int) → Tensor#

Compute, log, and return the validation loss for one batch.

configure_optimizers() → Optimizer#

Return the Adam optimizer used to train the VAE.

predict(x: ndarray) → ndarray#

Return reconstructions for a NumPy input batch.

get_num_trainable_variables() → int#

Return the number of trainable parameters.

get_prior_samples(num_samples: int) → ndarray#

Sample from the standard normal prior and decode the samples.

get_prior_samples_given_z(z: ndarray) → ndarray#

Decode the provided latent vectors.

loss_function(x: Tensor, x_recons: Tensor, z_mean: Tensor, z_log_var: Tensor) → tuple[Tensor, Tensor, Tensor]#

Return total, reconstruction, and KL losses for a batch.

class chronocratic.models.generative.timevae.vae_base.Sampling(*args: Any, **kwargs: Any)#

Bases: Module

Reparameterization layer for VAE latent sampling.

forward(inputs: tuple[Tensor, Tensor]) → Tensor#

Sample a latent vector from (z_mean, z_log_var).