evomap.mapping.evomap._core#

Core functions shared by all implementations.

Module Contents#

Classes#

EvoMap

EvoMap Interface. Implements default functions shared by all

Functions#

_evomap_cost_function(Y_all_periods, Ds, ...[, ...])

EvoMap's cost function for a given static cost function.

_get_positions_for_period(Y_all_periods, n_samples, period)

Extract map coordinates for period t from the array of all coordinates.

_calc_kth_order_dist(Y_all_periods, n_periods, p)

Calculate all kth-order distances (up to order p).

_shift_elements(vector)

Shift all elements in a vector by one (first element becomes zero).

_calc_kth_order_dist_grad(n_periods, p)

Calculate the gradients of all kth-order distances, up to order p.

_evomap_temporal_cost_function(Y_all_periods, ...[, ...])

Calculate temporal component of EvoMap's cost function.
class evomap.mapping.evomap._core.EvoMap(alpha=0, p=1, weighting='exponential')[source]#

EvoMap Interface. Implements default functions shared by all implementation in its child classes.

get_params()[source]#

Get model parameters.

set_params(params)[source]#

Set model parameters.

_calc_weights(Xs)[source]#

Calculate object-specific weights, applied to the temporal penalties in EvoMap’s cost function.

Parameters

Xs (list of ndarrays, each of shape (n_samples, n_samples)) – Input data (typically, distances matrices).

Returns

Object specific weights, stacked on top of each other for all periods

Return type

ndarray of shape (n_samples * n_periods, 1)

_initialize(Xs)[source]#

Create initialized positions for EvoMap.

Parameters

Xs (list of ndarrays) – Input data

Returns

Initialized starting positions.

Return type

ndarray of shape(n_samples * n_periods, n_dims)

_validate_input(Xs, inclusions=None)[source]#

Validate input data vis-a-vis model parameters.

Parameters

Xs (list of ndarrays) – Input data.

static _calc_static_cost(Xs, Y_all_periods, static_cost_function, inclusions=None, args=None, kwargs=None, static_cost_kwargs=None)[source]#

Calculate total static cost, i.e. sum over all static cost values across all periods.

Parameters

  • Xs (list of ndarrays, containing the input data) – Sequence of input data (typically, distance matrices)

  • Y_all_periods (ndarray of shape (n_samples * n_periods, n_dims)) – Map positions estimated by EvoMap

  • static_cost_function (callable) – Static cost function

  • inclusions (list of np.arrays of shape (n_samples)) – Sequence of 0/1 arrays indicating if an object is included in the estimation

  • args (list, optional) – Additional arguments passed to the static cost function, by default None

  • kwargs (dict, optional) – Additional keyword arguments passed to the static cost function, by default None

Returns

Total static cost

Return type

float

Fit model once for each parameter combination within the grid and evaluate each run accordings to various metrics.

Parameters

  • Xs (list of ndarrays) – Sequence of input data (typically, distance matrices)

  • param_grid (dict) – Parameter grid

  • eval_functions (list of callables, optional) – Evaluation functions. Should take a sequence of map layouts ‘Ys’ as first argument, by default None

  • eval_labels (list of strings, optional) – Labels for each evaluation function, by default None

  • kwargs (dict, optional) – Additional keyword arguments passed to the evaluation functions, by default None

Returns

Results for each parameter combination

Return type

DataFrame

abstract fit(Xs, inclusions=None)[source]#
abstract fit_transform(Xs, inclusions=None)[source]#
evomap.mapping.evomap._core._evomap_cost_function(Y_all_periods, Ds, static_cost_function, weights, alpha, p, inclusions=None, compute_error=True, compute_grad=True, static_cost_kwargs=None, args=None, kwargs=None)[source]#

EvoMap’s cost function for a given static cost function.

Parameters

  • Y_all_periods (ndarray of shape (n_samples * n_periods, n_dims)) – Map coordinates for all periods, stacked on top of each other.

  • Ds (list of ndarrays, each of shape (n_samples,n_samples)) – Sequence of input data (typically, distances matrices).

  • static_cost_function (callable) – Static cost function. Needs to return the cost function value and the gradient. Can take additional args / kwargs. The first two arguments should be the map coordinates Y and the input data D.

  • weights (ndarray of shape (n_samples * n_periods, 1)) – Object specific weights.

  • alpha (float) – Hyperparamter alpha, controlling the strength of alignment.

  • p (int) – Hyperparameter p, controlling the degree of smoothing.

  • inclusions (list of n_period np.arrays of shape (n_samples)) – Sequence of inclusion arrays, each containing (n_samples) 0/1 entries indicating if an object should be included in the estimation

  • compute_error (bool, optional) – True if cost function value should be computed, by default True

  • compute_grad (bool, optional) – True if gradient should be computed, by default True

  • args (list, optional) – Additional arguments passed to the static cost function, by default None

  • kwargs (dict, optional) – Additional keyword arguments passed to the static cost function, by default None

Returns

  • float – Cost function value

  • ndarray of shape (n_samples * n_periods, n_dims) – Gradient

evomap.mapping.evomap._core._get_positions_for_period(Y_all_periods, n_samples, period)[source]#

Extract map coordinates for period t from the array of all coordinates.

Parameters

  • Y_all_periods (ndarray of shape (n_samples*n_periods, n_dims)) – All map coordinates, stacked on top of each other.

  • n_samples (int) – Number of objects

  • period (int) – Period for which coordinates should be extracted.

Returns

Map coordinates at focal period

Return type

ndarray of shape (n_samples, n_dims)

evomap.mapping.evomap._core._calc_kth_order_dist(Y_all_periods, n_periods, p)[source]#

Calculate all kth-order distances (up to order p).

Parameters

  • Y_all_periods (ndarray of shape (n_samples*n_periods, n_dims)) – All map corrdinates, stacked on top of each other.

  • n_periods (int) – Number of periods

  • p (int) – Highest order of distances that should be computed.

Returns

List of ndarrays, each of shape (n_samples * n_periods, n_dims), containing the kth order distances at index k.

Return type

list

evomap.mapping.evomap._core._shift_elements(vector)[source]#

Shift all elements in a vector by one (first element becomes zero).

Parameters

vector (ndarray) – Input vector

Returns

Vector with all elements shifted by one index (row)

Return type

ndarray

evomap.mapping.evomap._core._calc_kth_order_dist_grad(n_periods, p)[source]#

Calculate the gradients of all kth-order distances, up to order p.

Parameters

  • n_periods (int) – Number of periods.

  • p (int) – Highest order of distances.

Returns

Gradients of kth-order distances at index k.

Return type

list of ndarrays, each of shape (n_periods, n_dims)

evomap.mapping.evomap._core._evomap_temporal_cost_function(Y_all_periods, n_periods, weights, alpha, p, inclusions=None, compute_error=True, compute_grad=True)[source]#

Calculate temporal component of EvoMap’s cost function.

Parameters

  • Y_all_periods (ndarray of shape (n_samples*n_periods, n_dims)) – Map coordinates for all periods, stacked on top of each other.

  • n_periods (int) – Number of periods.

  • weights (ndarray of shape (n_samples, 1)) – Object-specific weights.

  • alpha (float) – Hyperparameter alpha, controlling the strength of alignment.

  • p (int) – Hyperparameter p, controlling the degree of smoothing.

  • inclusions (list of n_periods np.arrays of shape (n_samples)) – Sequence of arrays with 0/1 entries indicating if an object should be included in the estimation

  • compute_error (bool, optional) – True, if cost function value should be computed, by default True

  • compute_grad (bool, optional) – Ture, if gradient should be computed, by default True

Returns

  • float – Cost function value

  • ndarray of shape (n_samples * n_periods, n_dims) – Gradient