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')

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

get_params()

Get model parameters.

set_params(params)

Set model parameters.

_calc_weights(Xs)

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)

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)

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)

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

grid_search(Xs, param_grid, inclusions=None, eval_functions=None, eval_labels=None, kwargs=None)

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)

abstract fit_transform(Xs, inclusions=None)

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)

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)

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)

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)

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)

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)

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