Covariance

class torchcast.covariance.Covariance(rank: int, method: str = 'log_cholesky', empty_idx: List[int] = (), predict_variance: Optional[torch.nn.modules.module.Module] = None, expected_kwargs: Optional[Sequence[str]] = None, id: Optional[str] = None, init_diag_multi: float = 0.1)

The Covariance can be used when you’d like more control over the covariance specification of a state- space model. For example, if you’re training on diverse time-serieses that vary in scale/behavior, you could use an torch.nn.Embedding to predict the variance of each series, with the group-ids as predictors:

kf = KalmanFilter(
    measures=measures,
    processes=processes,
    measure_covariance=Covariance.from_measures(
        measures,
        predict_variance=torch.nn.Sequential(
            torch.nn.Embedding(len(group_ids), len(measures), padding_idx=0),
            torch.nn.Softplus()
        ),
        expected_kwargs=['group_ids']
    ),
    process_covariance=Covariance.from_processes(
        processes,
        predict_variance=torch.nn.Sequential(
            torch.nn.Embedding(len(group_ids), Covariance.from_processes(processes).param_rank, padding_idx=0),
            torch.nn.Softplus()
        ),
        expected_kwargs=['group_ids']
    )
)

__init__(rank: int, method: str = 'log_cholesky', empty_idx: List[int] = (), predict_variance: Optional[torch.nn.modules.module.Module] = None, expected_kwargs: Optional[Sequence[str]] = None, id: Optional[str] = None, init_diag_multi: float = 0.1)

You should rarely call this directly. Instead, call Covariance.from_measures() and Covariance.from_processes().

Parameters

rank – The number of elements along the diagonal.
method – The parameterization for the covariance. The default, “log_cholesky”, parameterizes the covariance using the cholesky factorization (which is itself split into two tensors: the log-transformed diagonal elements and the off-diagonal). The other currently supported option is “low_rank”, which parameterizes the covariance with two tensors: (a) the log-transformed std-deviations, and (b) a ‘low rank’ G*K tensor where G is the number of random-effects and K is int(sqrt(G)). Then the covariance is D + V @ V.t() where D is a diagonal-matrix with the std-deviations**2, and V is the low-rank tensor.
empty_idx – In some cases (e.g. process-covariance) we will have some elements with no variance.
predict_variance – For predicting variance, see Covariance.from_measures().
expected_kwargs – If predict_variance is set, this allows you to set the keyword that will be passed at forward().
id – Identifier for this covariance. Typically left None and set when passed to the StateSpaceModel.
init_diag_multi – A float that will be applied as a multiplier to the initial values along the diagonal. This can be useful to provide intelligent starting-values to speed up optimization.

classmethod from_measures(measures: Sequence[str], predict_variance: Optional[Union[bool, torch.nn.modules.module.Module]] = None, **kwargs) → torchcast.covariance.base.Covariance

Parameters

measures – The measures used in your StateSpaceModel.
predict_variance – Will the variance be predicted upon calling forward()? This is implemented as a multiplier on the base variance given from the ‘method’. You can either pass True in which case it is expected you will pass multipliers as ‘measure_var_multi’ when forward() is called; or you can pass a torch.nn.Module that will predict the multipliers, in which case you’ll pass input(s) to this module at forward. Either way please note these should output strictly positive values with shape (num_groups, num_times, len(measures)).
kwargs – Other arguments passed to Covariance.__init__().

Returns

A Covariance object that can be used in your StateSpaceModel.

classmethod from_processes(processes: Sequence[torchcast.process.base.Process], cov_type: str = 'process', predict_variance: Optional[Union[bool, torch.nn.modules.module.Module]] = None, **kwargs) → torchcast.covariance.base.Covariance

Parameters

processes – The processes used in your StateSpaceModel.
cov_type – The type of covariance, either ‘process’ or ‘initial’ (default: ‘process’).
predict_variance – Will the variance be predicted upon calling forward()? This is implemented as a multiplier on the base variance given from the ‘method’. You can either pass True in which case it is expected you will pass multipliers as ‘process_var_multi’ when forward() is called; or you can pass a torch.nn.Module that will predict the multipliers, in which case you’ll pass input(s) to this module at forward. Either way please note these should output strictly positive values with shape (num_groups, num_times, self.param_rank).
kwargs – Other arguments passed to Covariance.__init__().

Returns

A Covariance object that can be used in your StateSpaceModel.