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(sequence_length: int, input_dims: int, latent_dim: int, reconstruction_weight: float = 3.0, learning_rate: float = 0.001, hidden_layer_sizes: tuple[int, ...] | None = None, trend_poly: int = 0, custom_seasonality: tuple[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.

property encoder: TimeVAEEncoder#

Return the TimeVAE encoder.

property decoder: TimeVAEDecoder#

Return the TimeVAE decoder.

class chronocratic.models.generative.timevae.model.TimeVAEDecoder(sequence_length: int, input_dims: int, hidden_layer_sizes: tuple[int, ...], latent_dim: int, trend_poly: int = 0, custom_seasonality: tuple[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(sequence_length: int, input_dims: int, hidden_layer_sizes: tuple[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(*, sequence_length: int, input_dims: int, latent_dim: int, reconstruction_weight: float = 3.0, learning_rate: float = 0.001, hidden_layer_sizes: tuple[int, ...] = (50, 100, 200), trend_poly: int = 0, custom_seasonality: tuple[tuple[int, int], ...] | None = None, use_residual_conn: bool = True)#

Bases: object

Configuration for the TimeVAE model.

Parameters:

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

  • input_dims – Number of input features (channels).

  • latent_dim – Dimensionality of the latent space.

  • reconstruction_weight – 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_seasonality – Optional tuple 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(sequence_length: int, input_dims: int, latent_dim: int, reconstruction_weight: float = 3.0, learning_rate: float = 0.001)#

Bases: LightningModule, ABC

property encoder: Module#

Return the encoder submodule.

property decoder: Module#

Return the decoder submodule.

forward(x: Tensor) → Tensor#

Reconstruct an input batch using the latent mean.

Expects x of shape (batch, sequence_length, input_dims). The encoder transposes to (batch, input_dims, sequence_length) internally.

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