:py:mod:`evomap.mapping.evomap._core` ===================================== .. py:module:: evomap.mapping.evomap._core .. autoapi-nested-parse:: Core functions shared by all implementations. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: evomap.mapping.evomap._core.EvoMap Functions ~~~~~~~~~ .. autoapisummary:: evomap.mapping.evomap._core._evomap_cost_function evomap.mapping.evomap._core._get_positions_for_period evomap.mapping.evomap._core._calc_kth_order_dist evomap.mapping.evomap._core._shift_elements evomap.mapping.evomap._core._calc_kth_order_dist_grad evomap.mapping.evomap._core._evomap_temporal_cost_function .. py:class:: EvoMap(alpha=0, p=1, weighting='exponential') EvoMap Interface. Implements default functions shared by all implementation in its child classes. .. py:method:: get_params() Get model parameters. .. py:method:: set_params(params) Set model parameters. .. py:method:: _calc_weights(Xs) Calculate object-specific weights, applied to the temporal penalties in EvoMap's cost function. :param Xs: Input data (typically, distances matrices). :type Xs: list of ndarrays, each of shape (n_samples, n_samples) :returns: Object specific weights, stacked on top of each other for all periods :rtype: ndarray of shape (n_samples * n_periods, 1) .. py:method:: _initialize(Xs) Create initialized positions for EvoMap. :param Xs: Input data :type Xs: list of ndarrays :returns: Initialized starting positions. :rtype: ndarray of shape(n_samples * n_periods, n_dims) .. py:method:: _validate_input(Xs, inclusions=None) Validate input data vis-a-vis model parameters. :param Xs: Input data. :type Xs: list of ndarrays .. py:method:: _calc_static_cost(Xs, Y_all_periods, static_cost_function, inclusions=None, args=None, kwargs=None, static_cost_kwargs=None) :staticmethod: Calculate total static cost, i.e. sum over all static cost values across all periods. :param Xs: Sequence of input data (typically, distance matrices) :type Xs: list of ndarrays, containing the input data :param Y_all_periods: Map positions estimated by EvoMap :type Y_all_periods: ndarray of shape (n_samples * n_periods, n_dims) :param static_cost_function: Static cost function :type static_cost_function: callable :param inclusions: Sequence of 0/1 arrays indicating if an object is included in the estimation :type inclusions: list of np.arrays of shape (n_samples) :param args: Additional arguments passed to the static cost function, by default None :type args: list, optional :param kwargs: Additional keyword arguments passed to the static cost function, by default None :type kwargs: dict, optional :returns: Total static cost :rtype: float .. py:method:: 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. :param Xs: Sequence of input data (typically, distance matrices) :type Xs: list of ndarrays :param param_grid: Parameter grid :type param_grid: dict :param eval_functions: Evaluation functions. Should take a sequence of map layouts 'Ys' as first argument, by default None :type eval_functions: list of callables, optional :param eval_labels: Labels for each evaluation function, by default None :type eval_labels: list of strings, optional :param kwargs: Additional keyword arguments passed to the evaluation functions, by default None :type kwargs: dict, optional :returns: Results for each parameter combination :rtype: DataFrame .. py:method:: fit(Xs, inclusions=None) :abstractmethod: .. py:method:: fit_transform(Xs, inclusions=None) :abstractmethod: .. py:function:: _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. :param Y_all_periods: Map coordinates for all periods, stacked on top of each other. :type Y_all_periods: ndarray of shape (n_samples * n_periods, n_dims) :param Ds: Sequence of input data (typically, distances matrices). :type Ds: list of ndarrays, each of shape (n_samples,n_samples) :param static_cost_function: 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. :type static_cost_function: callable :param weights: Object specific weights. :type weights: ndarray of shape (n_samples * n_periods, 1) :param alpha: Hyperparamter alpha, controlling the strength of alignment. :type alpha: float :param p: Hyperparameter p, controlling the degree of smoothing. :type p: int :param inclusions: Sequence of inclusion arrays, each containing (n_samples) 0/1 entries indicating if an object should be included in the estimation :type inclusions: list of n_period np.arrays of shape (n_samples) :param compute_error: True if cost function value should be computed, by default True :type compute_error: bool, optional :param compute_grad: True if gradient should be computed, by default True :type compute_grad: bool, optional :param args: Additional arguments passed to the static cost function, by default None :type args: list, optional :param kwargs: Additional keyword arguments passed to the static cost function, by default None :type kwargs: dict, optional :returns: * *float* -- Cost function value * *ndarray of shape (n_samples * n_periods, n_dims)* -- Gradient .. py:function:: _get_positions_for_period(Y_all_periods, n_samples, period) Extract map coordinates for period t from the array of all coordinates. :param Y_all_periods: All map coordinates, stacked on top of each other. :type Y_all_periods: ndarray of shape (n_samples*n_periods, n_dims) :param n_samples: Number of objects :type n_samples: int :param period: Period for which coordinates should be extracted. :type period: int :returns: Map coordinates at focal period :rtype: ndarray of shape (n_samples, n_dims) .. py:function:: _calc_kth_order_dist(Y_all_periods, n_periods, p) Calculate all kth-order distances (up to order p). :param Y_all_periods: All map corrdinates, stacked on top of each other. :type Y_all_periods: ndarray of shape (n_samples*n_periods, n_dims) :param n_periods: Number of periods :type n_periods: int :param p: Highest order of distances that should be computed. :type p: int :returns: List of ndarrays, each of shape (n_samples * n_periods, n_dims), containing the kth order distances at index k. :rtype: list .. py:function:: _shift_elements(vector) Shift all elements in a vector by one (first element becomes zero). :param vector: Input vector :type vector: ndarray :returns: Vector with all elements shifted by one index (row) :rtype: ndarray .. py:function:: _calc_kth_order_dist_grad(n_periods, p) Calculate the gradients of all kth-order distances, up to order p. :param n_periods: Number of periods. :type n_periods: int :param p: Highest order of distances. :type p: int :returns: Gradients of kth-order distances at index k. :rtype: list of ndarrays, each of shape (n_periods, n_dims) .. py:function:: _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. :param Y_all_periods: Map coordinates for all periods, stacked on top of each other. :type Y_all_periods: ndarray of shape (n_samples*n_periods, n_dims) :param n_periods: Number of periods. :type n_periods: int :param weights: Object-specific weights. :type weights: ndarray of shape (n_samples, 1) :param alpha: Hyperparameter alpha, controlling the strength of alignment. :type alpha: float :param p: Hyperparameter p, controlling the degree of smoothing. :type p: int :param inclusions: Sequence of arrays with 0/1 entries indicating if an object should be included in the estimation :type inclusions: list of n_periods np.arrays of shape (n_samples) :param compute_error: True, if cost function value should be computed, by default True :type compute_error: bool, optional :param compute_grad: Ture, if gradient should be computed, by default True :type compute_grad: bool, optional :returns: * *float* -- Cost function value * *ndarray of shape (n_samples * n_periods, n_dims)* -- Gradient