milia.represent.tensor#

Tucker decomposition of a meter-by-day-by-step tensor (tensorly).

Functions

decompose(tensor, ranks[, random_state])

Tucker core and factor matrices of a 3-D tensor (tensorly).

explained(tensor, core, factors)

Share of the tensor's variance the Tucker reconstruction recovers.

ranks(tensor[, candidates, fixed, tol, ...])

Sweep the meter-mode rank and pick the smallest within tol of the best explained variance.

Classes

Tucker([ranks, normalized, random_state])

Meter embedding from the meter-mode factor of a Tucker decomposition.

milia.represent.tensor.decompose(tensor, ranks, random_state=0)#

Tucker core and factor matrices of a 3-D tensor (tensorly).

Parameters:
  • tensor (ndarray) – Shape (meters, days, steps).

  • ranks (Sequence[int]) – Rank of each mode.

  • random_state (int) – Seed.

Return type:

tuple[ndarray, list[ndarray]]

Returns:

(core, factors); factors[0] is the meter-mode factor.

Examples

>>> core, factors = decompose(np.random.default_rng(0).random((5, 4, 6)), (2, 2, 2))
>>> core.shape, factors[0].shape
((2, 2, 2), (5, 2))
milia.represent.tensor.explained(tensor, core, factors)#

Share of the tensor’s variance the Tucker reconstruction recovers.

Parameters:
Return type:

float

Returns:

1 - var(residual) / var(tensor).

Examples

>>> cube = np.random.default_rng(0).random((5, 4, 6))
>>> 0 < explained(cube, *decompose(cube, (5, 4, 6))) <= 1
True
milia.represent.tensor.ranks(tensor, candidates=(5, 10, 15, 20, 30), fixed=(10, 8), tol=0.01, random_state=0)#

Sweep the meter-mode rank and pick the smallest within tol of the best explained variance.

Parameters:
  • tensor (ndarray) – Shape (meters, days, steps).

  • candidates (Sequence[int]) – Meter-mode ranks to try.

  • fixed (tuple[int, int]) – Day-mode and step-mode ranks, held fixed.

  • tol (float) – Allowed shortfall from the best explained variance.

  • random_state (int) – Seed.

Return type:

tuple[DataFrame, int]

Returns:

(table, rank) – explained variance per candidate, and the chosen rank.

Examples

>>> from milia.data import profiles, synthetic
>>> cube = profiles.tensor(synthetic.generate(meters=6, days=14, steps=24).pivot)
>>> table, rank = ranks(cube, candidates=(2, 3), fixed=(4, 4))
>>> list(table.columns), rank in (2, 3)
(['rank', 'explained'], True)
class milia.represent.tensor.Tucker(ranks=(10, 10, 8), normalized=True, random_state=0)#

Bases: BaseEstimator

Meter embedding from the meter-mode factor of a Tucker decomposition.

Input is a (meters, days, steps) tensor, e.g. from milia.data.profiles.tensor(). Each meter is peak-normalised first when normalized is set, so the embedding reflects shape rather than size.

Parameters:
  • ranks (tuple[int, int, int]) – Meter, day and step ranks.

  • normalized (bool) – Peak-normalise each meter’s slice before decomposing.

  • random_state (int) – Seed.

Variables:
  • factors (core,) – The decomposition.

  • embedding – Meter-mode factor, shape (meters, ranks[0]).

  • explained – Share of variance the reconstruction recovers.

Examples

>>> from milia.data import profiles, synthetic
>>> cube = profiles.tensor(synthetic.generate(meters=6, days=14, steps=24).pivot)
>>> Tucker(ranks=(3, 4, 4)).fit_transform(cube).shape
(6, 3)
fit(X, y=None)#

Decompose the tensor and keep the meter-mode factor as the embedding.

Parameters:
  • X (ndarray) – Tensor of shape (meters, days, steps).

  • y (None) – Ignored; present for API consistency.

Return type:

Tucker

Returns:

The fitted estimator.

Raises:

ValueError – If X is not three-dimensional.

Examples

>>> from milia.data import profiles, synthetic
>>> cube = profiles.tensor(synthetic.generate(meters=6, days=14, steps=24).pivot)
>>> Tucker(ranks=(3, 4, 4)).fit(cube).embedding_.shape
(6, 3)
fit_transform(X, y=None)#

Fit and return the meter embedding.

Parameters:
  • X (ndarray) – Tensor of shape (meters, days, steps).

  • y (None) – Ignored; present for API consistency.

Return type:

ndarray

Returns:

The meter-mode factor, shape (meters, ranks[0]).