extendedmosaicperm.tilings module

build_adaptive_tiling(outcomes, exposures, batch_size=10, D=None, seed=0)[source]

Build an adaptive tiling of the sample based on residual covariance.

The time dimension is split into batches of size batch_size. For the first batch, groups are assigned using a random even partition. For subsequent batches, residuals from previous tiles are used to estimate a covariance matrix, and the grouping is updated via greedy_grouping().

Parameters:

  • outcomes (ndarray) – Outcome matrix of shape (T, p).

  • exposures (ndarray) – Factor loadings, either constant of shape (p, K) or time-varying of shape (T, p, K).

  • batch_size (int) – Number of observations per batch.

  • D (Optional[int]) – Number of groups. If None, defaults to max(2, p // (2 * K)), where K is the number of factors.

  • seed (int) – Random seed used for initial grouping and subsequent updates.

Returns:

A tiling object containing all (batch, group) pairs.

Return type:

Tiling

Raises:

ValueError – If outcomes or exposures is None, or if the exposure slices cannot be reshaped to (p, K).

Examples

>>> import numpy as np
>>> from mosaicperm.tilings import Tiling
>>> from extendedmosaicperm.tilings import build_adaptive_tiling
>>> rng = np.random.default_rng(0)
>>> T, p, K = 12, 6, 2
>>> Y = rng.normal(size=(T, p))
>>> L = rng.normal(size=(p, K))
>>> til = build_adaptive_tiling(Y, L, batch_size=4, D=3, seed=7)
>>> isinstance(til, Tiling)
True
>>> len(til)  
9
estimate_covariance(residuals, prev_batches, prev_groups)[source]

Estimate residual covariance from previous tiles.

For each previously observed (batch, group) pair, the function computes a local covariance matrix and aggregates these estimates into a global covariance estimate.

Parameters:

  • residuals (ndarray) – Residual matrix of shape (T, p).

  • prev_batches (Sequence[Sequence[int]]) – Sequence of time-index arrays used so far.

  • prev_groups (Sequence[Sequence[int]]) – Sequence of asset-index arrays corresponding to the groups used so far.

Returns:

Estimated covariance matrix of shape (p, p).

Return type:

np.ndarray

Notes

Entries not covered by any previous (batch, group) pair remain zero. Division by zero is avoided by replacing empty counts with one.

greedy_grouping(cov, D, seed=0)[source]

Greedily group variables to weaken within-group correlations.

The algorithm starts from D randomly selected variables and then iteratively assigns remaining variables to the group with which they have the weakest (maximum absolute) correlation.

Parameters:

  • cov (ndarray) – Covariance (or correlation) matrix of shape (p, p).

  • D (int) – Number of groups.

  • seed (int) – Random seed used to initialize the starting variables.

Returns:

List of D index arrays forming a partition of {0, ..., p-1}.

Return type:

list[np.ndarray]

Examples

>>> import numpy as np
>>> from extendedmosaicperm.tilings import greedy_grouping
>>> cov = np.eye(6)
>>> groups = greedy_grouping(cov, D=3, seed=42)
>>> len(groups), sum(len(g) for g in groups)
(3, 6)
>>> all(len(set(g1).intersection(set(g2))) == 0
...     for i, g1 in enumerate(groups) for j, g2 in enumerate(groups) if i < j)
True
>>> set(np.concatenate(groups)) == set(range(6))
True