The causal_graph module

The causal_graph module contains the CausalGraph class, which inherits from the DiffImbalance class.

The code can be runned on gpu using the command

jax.config.update(‘jax_platform_name’, ‘gpu’) # set ‘cpu’ or ‘gpu’

class causal_graph.CausalGraph(time_series=None, coords_present=None, coords_future=None, periods=None, standardize=True, seed=0)[source]

Constructs a community causal graph where variables are grouped into single nodes.

time_series

array of shape (N_times,D), where N_times is the length of trajectory and D is the number of dynamical variables. The sampling time is supposed to be constant along the trajectory and for all the variables.

Type:

np.array(float)

coords_present

array of shape (N_samples,D) containing the samples of the D-dimensional trajectory at time t=0; read only when time_series is None.

Type:

np.array(float)

coords_future

array of shape (N_samples,D,n_lags) containing the samples of the D-dimensional trajectory at different future time lags; read only when time_series is None. If you want to test a single time lag, reshape the dataset with coords_future[:,:,np.newaxis].

Type:

np.array(float)

periods

array of shape (D,) containing the periods of the dynamical variables. The default is None, which means that the variables are treated as nonperiodic. If not all variables are periodic, the entries of the nonperiodic ones should be set to 0.

Type:

np.ndarray(float)

standardize

whether to standardize each of the D variables, dividing by its standard deviation along the trajectory or the provided samples. Default is True.

Type:

bool

seed

seed of JAX random generator.

Type:

int

community_graph_visualization(community_dictionary, adj_matrix, type='community', savefig_name=None, **kwargs)[source]

Shows a visual representation of the dynamical communities on a graph.

This function makes use of the library networkx (https://networkx.org/documentation/stable/index.html)

Parameters:

  • community_dictionary (dict) – dictionary with pairs (comm_id, level) as keys and lists containing the indices of the variables in each dynamical community as values.

  • adj_matrix (np.array(float)) – matrix of shape (D,D) defining the links between the variables after thresholding the matrix of the optimized weights.

  • type (str) – type of graph where the dynamical communities are represented, possible options are “community” (default) and “all-variable”. If “community”, a community causal graph where each node represents a community is shown. If “all-variable”, communities are represented with different colors in a graph with all the original D variables in the time series.

  • savefig_name (str) – path at which the picture of the final graph is saved in pdf format. If None (default), the figure is not saved.

  • **kwargs – customizable arguments used by the networkx library. If type=”all-variable”, these include: ‘scale’,’k1’ and ‘k2’, ‘cmap’, ‘width’ and ‘arrowsize’. If type=”community”, the possible arguments are: ‘node_color’, ‘node_size’, ‘width’, ‘arrowstyle’, ‘arrowsize’.

Returns:

G (nx.diGraph object) – final causal graph.

compute_adj_matrix(weights, threshold=0.1)[source]

Computes the adjacency matrix from the optimal weights returned by optimize_present_to_future.

As a preliminary step before applying the threshold, the maximum weight over the tested time lags is taken for each pair X_i(0) -> X_j(tau) (i,j=1,…,D). If the weights are referred to time-delay embeddings, the maximum is also taken along the embedding dimension.

Parameters:

  • weights (np.ndarray(float)) – array of shape (D, n_time_lags, D) containing the optimal scaling weights produced by optimize_present_to_future with the option target_variables=”all”. If the optimization was carried out with embedding_dim_present > 1, the array should have an additional dimension, i.e. shape (D, n_time_lags, D, embedding_dim_present).

  • threshold (float) – value of the threshold used to construct the adjacency matrix. If a weight is smaller than the threshold the corresponding entry in the adjacency matrix is set to 0, otherwise it is set to 1.

Returns:

adj_matrix (np.ndarray(float)) – array of shape (D,D) defining the adjacency matrix of a directed graph, where each arrow defines a direct or indirect link. Also accessible as attribute of the CausalGraph object.

find_communities(adj_matrix)[source]

Finds dynamical communities, i.e. groups of variables defining single nodes in the community causal graph.

Parameters:

adj_matrix (np.ndarray(float)) – binary matrix of shape (D,D) defining the links of a directed graph with D nodes.

Returns:

community_dictionary (dict) – dictionary with pairs (comm_id, level) as keys and lists containing the indices of the variables in each community as values. ‘comm_id’ is an integer number identifying the dynamical community, while ‘level’ is an integer identifying the step of the algorithm at which the community is identified, namely its level of autonomy. The keys are sorted from the smallest to the largest level. Both ‘comm_id’ and ‘level’ start from 0.

optimize_present_to_future(num_samples, time_lags, embedding_dim_present=1, embedding_dim_future=1, embedding_time=1, target_variables='all', save_weights=False, num_epochs=200, batches_per_epoch=1, l1_strength=0.0, point_adapt_lambda=False, k_init=1, k_final=1, lambda_factor=0.1, params_init=None, optimizer_name='sgd', learning_rate=0.01, learning_rate_decay=None, num_points_rows=None, compute_imb_final=False, compute_error=False, ratio_rows_columns=1, discard_close_ind=None)[source]

Iteratively optimizes the DII from the full space in the present to a target space in the future.

Arguments ‘num_samples’, ‘time_lags’, ‘embedding_dim_present’, ‘embedding_dim_future’ and ‘embedding_time’ are read only when data are provided to the CausalGraph object through the argument ‘time_series’. Arguments ‘compute_error’, ‘ratio_rows_columns’ and ‘discard_close_ind’ are only read when ‘compute_imb_final’ is set to True.

Parameters:

  • num_samples (int) – number of samples harvested from the full time series, interpreted as independent initial conditions of the same dynamical process.

  • time_lags (list(int), np.ndarray(int)) – tested time lags between ‘present’ and ‘future’.

  • embedding_dim_present (int) – dimension of the time-delay embedding vectors built in the present space (t=0, t=-1, …). Default is 1, which means the time-delay embeddings are not employed.

  • embedding_dim_future (int) – dimension of the time-delay embedding vectors built in the space of the target variable (t=tau, t=tau-1, …). Default is 1.

  • embedding_time (int) – lag between consecutive samples in the time-delay embedding vectors of each variable. Default is 1.

  • target_variables (str or list(int), np.array(int)) – list or np.array of the target variables defining the distance space in the future. Default is “all”, for which the optimization is iterated over all variables as target.

  • save_weights (bool) – whether to save or not the weights during training, rather than only the final weights. If True, weights are saved in the attribute ‘weights_training’ of the CausalGraph object, which is an array of shape (n_target_variables, n_time_lags, num_epochs+1, num_variables). Default is False.

  • num_epochs (int) – number of training epochs. Default is 200.

  • batches_per_epoch (int) – number of minibatches; must be a divisor of n_points. Each weight update is carried out by computing the DII gradient over n_points / batches_per_epoch points. Default is 1, which means that the gradient is computed over all the available points (batch GD).

  • seed (int) – seed of JAX random generator, default is 0. Different seeds determine different mini-batch partitions.

  • l1_strength (float) – strength of the L1 regularization (LASSO) term. Default is 0.

  • point_adapt_lambda (bool) – whether to use a global smoothing parameter lambda for the c_ij coefficients in the DII (if False), or a different parameter for each point (if True). Default is True.

  • k_init (int) – initial rank of neighbors used to set lambda. Ranks are defined starting from 1. If batches_per_epoch > 1, neighbors are recomputed within each mini-batch. Default is 1.

  • k_final (int) – final rank of neighbors used to set lambda. If batches_per_epoch > 1, neighbors are recomputed within each mini-batch. Default is 1.

  • lambda_factor (float) – factor defining the scale of lambda. Default is 0.1.

  • params_init (np.array(float), jnp.array(float)) – array of shape (n_features_A,) containing the initial values of the scaling weights to be optimized. If None, params_init is set to [0.1, 0.1, …, 0.1].

  • optimizer_name (str) – name of the optimizer, calling the Optax library. Possible choices are ‘sgd’ (default), ‘adam’ and ‘adamw’. See https://optax.readthedocs.io/en/latest/api/optimizers.html for additional details.

  • learning_rate (float) – value of the learning rate. Default is 1e-2.

  • learning_rate_decay (str) – schedule to damp the learning rate to zero starting from the value provided with the attribute learning_rate. The available schedules are: cosine decay (“cos”), exponential decay (“exp”; the initial learning rate is halved every 10 steps), or constant learning rate (None). Default is None (constant learning rate).

  • num_points_rows (int) – number of points sampled from the rows of rank and distance matrices. In case of large datasets, choosing num_points_rows < n_points can significantly speed up the training. The default is None, for which num_points_rows == n_points.

  • compute_imb_final (bool) – whether to compute the final DII over the full data set, using the options specified by ‘compute_error’, ‘ratio_rows_columns’ and ‘discard_close_ind’. Default is False, for which those arguments are ignored.

  • compute_error (bool) – whether to compute the final DII and its error by sampling different points along rows and columns of the distance matrix. If False, the final DII is computed using the same points along rows and columns, which does not allow for an error estimation. Default is True.

  • ratio_rows_columns (float) –

    only read when compute_error is True; defines the ratio between the number of points along rows (nrows) and along columns (ncolumns) of distance and rank matrices, in two groups randomly sampled. In general, nrows and ncolumns are determined by solving the equations

    nrows / ncolumns = ratio_rows_columns, nrows + ncolumns = n_total_points.

    Default is 1, which means that both groups have n_points / 2 elements.

  • discard_close_ind (int) – given any point i, defines the “close” points (following the time ordering along axis=0 of ‘time_series’ or ‘coords_present’) that are known to be significantly correlated with i. If compute_error is True, “time-correlated” points are excluded by subsampling the data along axis=0 with stride discard_close_ind + 1. If compute_error is False, distances between each point i and points within the time window [i-discard_close_ind, i+discard_close_ind] are discarded. Default is 0, for which no distances between points close in the time are discarded.

Returns:

  • weights_final (np.array(float)) – array of shape (n_target_variables, n_time_lags, D) containing the D final scaling weights for each optimization, where D is the number of variables in the time series. If embedding_dim_present > 1, the shape is (n_target_variables, n_time_lags, D, embedding_dim_present). Also accessible as attribute of the CausalGraph object.

  • imbs_training (np.array(float)) – array of shape (n_target_variables, n_time_lags, num_epochs+1) containing the DII during the trainings. Also accessible as attribute of the CausalGraph object.

  • imbs_final (np.array(float)) – array of shape (n_target_variables, n_time_lags) containing the DII at the end of each training computed over the full data set. If ‘compute_imb_final’ is False, imbs_final is set to None. Also accessible as attribute of the CausalGraph object.

  • errors_final (np.array(float)) – array of shape (n_target_variables, n_time_lags) containing the errors of the DII at the end of each training, computed over the full data set. If ‘compute_imb_final’ is False, or if ‘compute_imb_final’ is True and ‘compute_error’ is False, errors_final is set to None. Also accessible as attribute of the CausalGraph object.

return_nn_indices(variables, num_samples, time_lags, embedding_dim=1, embedding_time=1, discard_close_ind=None)[source]

Returns the indices of the nearest neighbor of each point.

Parameters:

  • variables (list, jnp.array(int)) – array of the coordinates used to build the distance space (with weights 1).

  • num_samples (int) – number of samples harvested from the full time series.

  • time_lags (list(int), np.array(int)) – tested time lags between ‘present’ and ‘future’.

  • embedding_dim (int) – dimension of the time-delay embedding vector built on each variable. Default is 1, which means the time-delay embeddings are not employed.

  • embedding_time (int) – lag between consecutive samples in the time-delay embedding vectors of each variable. Default is 1.

  • discard_close_ind (int) – defines the “close points” for which distances and ranks are not computed: for each point i, distances between i and points within [i-discard_close_ind, i+discard_close_ind] are discarded.

Returns:

nn_indices (np.array(float)) – array of the nearest neighbors indices: nn_indices[i] is the index of the column with value 1 in the rank matrix.