Encoding Mixins#

Mixins that provide encode() interfaces for inference.

BasicEncodingMixin#

Simple encoding for models that produce single-resolution representations.

Lightweight shared encoding mixin for fixed-length sequence models.

Provides a uniform encode(data, batch_size, num_workers) API for models that process whole sequences in a single forward pass (TST, TimeVAE, TimeNet, MCL, TS-TCC, Series2Vec). Models that need sliding-window inference, multi-scale pooling, or mask-mode handling (the dilated trio: TS2Vec, AutoTCL, CoST) should use the heavier mixins under convolutional/dilated/_mixin/ instead.

Subclasses expose their encoder via BasicEncodingMixin._get_encoder() and customize batch-to-representation logic via _encode_batch(). The mixin itself owns the DataLoader iteration, eval/inference mode handling, device placement, encoder invocation, and result concatenation.

The two-hook contract separates concerns cleanly: - _get_encoder() -> nn.Module identifies the module whose train/eval

state should be toggled during encoding.

  • _encode_batch(encoder, batch_x) -> Tensor defines how one on-device batch becomes a representation tensor.

class chronocratic.models._mixin.encoding.BasicEncodingMixin#

Bases: ABC

Uniform encode() API for fixed-length sequence models.

Designed to be mixed into a lightning.pytorch.LightningModule. The LightningModule is expected to provide self.device so that batches can be moved onto the model’s device.

Subclasses implement exactly two hooks: _get_encoder() (required, returns the nn.Module whose train/eval state to toggle) and _encode_batch() (optional override, maps one on-device batch to a representation tensor).

The mixin manages the training / eval state of the encoder module (not the whole LightningModule) so that encode() does not perturb submodules that are unrelated to inference (e.g. contrastive heads, auxiliary loss modules).

encode(data: Tensor, batch_size: int, num_workers: int = 0, *, gradient_enabled: bool = False) → Tensor#

Extract representations for data in mini-batches.

Iterates data through a DataLoader, moves each batch to self.device, invokes the encoder via the _encode_batch hook, and concatenates the per-batch outputs on dim 0. The model’s prior training-mode state is preserved across the call.

By default the encoding loop runs under torch.inference_mode(), which severs the autograd graph. Set gradient_enabled=True to preserve gradients (e.g. for adversarial attacks or contrastive view comparison); the encoder stays in eval() regardless.

Parameters:

  • data – Input tensor of shape (N, ...) — leading dim is the sample dimension, the rest is whatever the model expects.

  • batch_size – Mini-batch size for inference.

  • num_workers – Number of DataLoader workers.

  • gradient_enabled – When True, keep the autograd graph alive by using nullcontext() instead of inference_mode(). The encoder remains in eval() to ensure deterministic behavior (no dropout, frozen BN stats). Default False.

Returns:

Tensor of shape (N, ...) on the same device as data, concatenation of per-batch representations along dim 0.

PoolingEncodingMixin#

Multi-resolution encoding with sliding window and pooling. Used by dilated convolutional models.

class chronocratic.models.convolutional.dilated._mixin.encoding.BaseEncodingMixin#

Bases: ABC

Base mixin providing shared encoding logic for time series models.

Contains the public encode() entry point, sliding window computation, and default strategy methods. Subclasses override _get_encoder(), _get_eval_method(), and _get_slice() to provide model-specific behavior.

Attributes are intentionally declared here but implemented by subclasses: TS2Vec, AutoTCL (pooling), CoST (decomposition).

encode(data: Tensor, batch_size: int, num_workers: int, mask: MaskMode | None = None, encoding_window: str | int | None = None, *, causal: bool = False, sliding_length: int | None = None, sliding_padding: int = 0, gradient_enabled: bool = False) → Tensor#

Compute representations using the model.

Parameters:

  • data – Shape (n_instance, n_timestamps, n_features). Missing data set to NaN.

  • batch_size – Batch size used for inference.

  • num_workers – Number of workers used for data loading.

  • mask – Mask for the encoder. One of ‘binomial’, ‘continuous’, ‘all_true’, ‘all_false’, or ‘mask_last’.

  • encoding_window – Pooling strategy. ‘full_series’, ‘multiscale’, or an integer for the pooling kernel size.

  • causal – If True, future information is not encoded.

  • sliding_length – Sliding window length. If set, sliding inference is applied.

  • sliding_padding – Contextual data length for each sliding window.

  • gradient_enabled – When True, keep the autograd graph alive by using nullcontext() instead of inference_mode(). The encoder remains in eval() regardless. Default False.

Returns:

The representations for data.

class chronocratic.models.convolutional.dilated._mixin.encoding.DecompositionEncodingMixin#

Bases: BaseEncodingMixin

Mixin for decomposition-based encoding (CoST).

Extends BaseEncodingMixin with trend+seasonality feature concatenation evaluation. Models inheriting this mixin encode decomposed components and concatenate their final-step features rather than using pooling slices.

class chronocratic.models.convolutional.dilated._mixin.encoding.PoolingEncodingMixin#

Bases: BaseEncodingMixin

Mixin for pooling-based encoding (TS2Vec, AutoTCL).

Extends BaseEncodingMixin with slice computation and pooling evaluation strategies. Models inheriting this mixin use multi-scale or integer pooling to produce fixed-length representations.