utils

lingam.utils.print_causal_directions(cdc, n_sampling, labels=None)

Print causal directions of bootstrap result to stdout.

Parameters:

• cdc (dict) – List of causal directions sorted by count in descending order. This can be set the value returned by BootstrapResult.get_causal_direction_counts() method.

• n_sampling (int) – Number of bootstrapping samples.

• labels (array-like, optional (default=None)) – List of feature lables. If set labels, the output feature name will be the specified label.

lingam.utils.print_dagc(dagc, n_sampling, labels=None)

Print DAGs of bootstrap result to stdout.

Parameters:

• dagc (dict) – List of directed acyclic graphs sorted by count in descending order. This can be set the value returned by BootstrapResult.get_directed_acyclic_graph_counts() method.

• n_sampling (int) – Number of bootstrapping samples.

• labels (array-like, optional (default=None)) – List of feature lables. If set labels, the output feature name will be the specified label.

lingam.utils.make_prior_knowledge(n_variables, exogenous_variables=None, sink_variables=None, paths=None, no_paths=None)

Make matrix of prior knowledge.

Parameters:

• n_variables (int) – Number of variables.

• exogenous_variables (array-like, shape (index, ...), optional (default=None)) – List of exogenous variables(index). Prior knowledge is created with the specified variables as exogenous variables.

• sink_variables (array-like, shape (index, ...), optional (default=None)) – List of sink variables(index). Prior knowledge is created with the specified variables as sink variables.

• paths (array-like, shape ((index, index), ...), optional (default=None)) – List of variables(index) pairs with directed path. If (i, j), prior knowledge is created that xi has a directed path to xj.

• no_paths (array-like, shape ((index, index), ...), optional (default=None)) – List of variables(index) pairs without directed path. If (i, j), prior knowledge is created that xi does not have a directed path to xj.

Returns:

prior_knowledge – Return matrix of prior knowledge used for causal discovery.

Return type:

array-like, shape (n_variables, n_variables)

lingam.utils.remove_effect(X, remove_features, return_coefs=False)

Create a dataset that removes the effects of features by linear regression.

Parameters:

• X (array-like, shape (n_samples, n_features)) – Data, where n_samples is the number of samples and n_features is the number of features.

• remove_features (array-like, shape (n_removes,)) – List of features(index) to remove effects.

• return_coefs (bool, optional (default=False)) – Return regression coefficients or not.

Returns:

• X (array-like, shape (n_samples, n_features)) – Data after removing effects of remove_features.

• coefs (dict, optional) – Coefficients estimated by linear regression. The keys are indices of remaining features and the values are lists of coefficients of removed features. The order of the coefficients in the list is the same as in remove_features. Only provided if return_coefs is True.

lingam.utils.make_dot(adjacency_matrix, labels=None, lower_limit=0.01, prediction_feature_indices=None, prediction_target_label='Y(pred)', prediction_line_color='red', prediction_coefs=None, prediction_feature_importance=None, path=None, path_color=None, detect_cycle=False, ignore_shape=False)

Directed graph source code in the DOT language with specified adjacency matrix.

Parameters:

• adjacency_matrix (array-like with shape (n_features, n_features)) – Adjacency matrix to make graph, where n_features is the number of features.

• labels (array-like, optional (default=None)) – Label to use for graph features.

• lower_limit (float, optional (default=0.01)) – Threshold for drawing direction. If float, then directions with absolute values of coefficients less than lower_limit are excluded.

• prediction_feature_indices (array-like, optional (default=None)) – Indices to use as prediction features.

• prediction_target_label (string, optional (default='Y(pred)'))) – Label to use for target variable of prediction.

• prediction_line_color (string, optional (default='red')) – Line color to use for prediction’s graph.

• prediction_coefs (array-like, optional (default=None)) – Coefficients to use for prediction’s graph.

• prediction_feature_importance (array-like, optional (default=None)) – Feature importance to use for prediction’s graph.

• path (tuple, optional (default=None)) – Path to highlight. Tuple of start index and end index.

• path_color (string, optional (default=None)) – Colors to highlight a path.

• detect_cycle (boolean, optional (default=False)) – Highlight simple cycles.

• ignore_shape (boolean, optional (default=False)) – Ignore checking the shape of adjaceny_matrix or not.

Returns:

graph – Directed graph source code in the DOT language. If order is unknown, draw a double-headed arrow.

Return type:

graphviz.Digraph

lingam.utils.get_sink_variables(adjacency_matrix)

The sink variables(index) in the adjacency matrix.

Parameters:

adjacency_matrix (array-like, shape (n_variables, n_variables)) – Adjacency matrix, where n_variables is the number of variables.

Returns:

sink_variables – List of sink variables(index).

Return type:

array-like

lingam.utils.get_exo_variables(adjacency_matrix)

The exogenous variables(index) in the adjacency matrix.

Parameters:

adjacency_matrix (array-like, shape (n_variables, n_variables)) – Adjacency matrix, where n_variables is the number of variables.

Returns:

exogenous_variables – List of exogenous variables(index).

Return type:

array-like

lingam.utils.find_all_paths(dag, from_index, to_index, min_causal_effect=0.0)

Find all paths from point to point in DAG.

Parameters:

• dag (array-like, shape (n_features, n_features)) – The adjacency matrix to fine all paths, where n_features is the number of features.

• from_index (int) – Index of the variable at the start of the path.

• to_index (int) – Index of the variable at the end of the path.

• min_causal_effect (float, optional (default=0.0)) – Threshold for detecting causal direction. Causal directions with absolute values of causal effects less than min_causal_effect are excluded.

Returns:

• paths (array-like, shape (n_paths)) – List of found path, where n_paths is the number of paths.

• effects (array-like, shape (n_paths)) – List of causal effect, where n_paths is the number of paths.

lingam.utils.predict_adaptive_lasso(X, predictors, target, gamma=1.0)

Predict with Adaptive Lasso.

Parameters:

• X (array-like, shape (n_samples, n_features)) – Training data, where n_samples is the number of samples and n_features is the number of features.

• predictors (array-like, shape (n_predictors)) – Indices of predictor variable.

• target (int) – Index of target variable.

Returns:

coef – Coefficients of predictor variable.

Return type:

array-like, shape (n_features)

lingam.utils.likelihood_i(x, i, b_i, bi_0)

Compute local log-likelihood of component i.

Parameters:

• x (array-like, shape (n_features, n_samples)) – Data, where n_samples is the number of samples and n_features is the number of features.

• i (array-like) – Variable index.

• b_i (array-like) – The i^th column of adjacency matrix, B[i].

• bi_0 (float) – Constant value for the i^th variable.

Returns:

ll – Local log-likelihood of component i.

Return type:

float

lingam.utils.log_p_super_gaussian(s)

Compute density function of the normalized independent components.

Parameters:

s (array-like, shape (1, n_samples)) – Data, where n_samples is the number of samples.

Returns:

x – Density function of the normalized independent components, whose disturbances are super-Gaussian.

Return type:

float

lingam.utils.variance_i(X, i, b_i)

Compute empirical variance of component i.

Parameters:

• x (array-like, shape (n_features, n_samples)) – Data, where n_samples is the number of samples and n_features is the number of features.

• i (array-like) – Variable index.

• b_i (array-like) – The i^th column of adjacency matrix, B[i].

Returns:

variance – Empirical variance of component i.

Return type:

float

lingam.utils.extract_ancestors(X, max_explanatory_num=2, cor_alpha=0.01, ind_alpha=0.01, shapiro_alpha=0.01, MLHSICR=True, bw_method='mdbs')

Extract a set of ancestors of each variable Implementation of RCD Algorithm1 [1]

References

[1]

T.N.Maeda and S.Shimizu. RCD: Repetitive causal discovery of linear non-Gaussian acyclic models with latent confounders. In Proc. 23rd International Conference on Artificial Intelligence and Statistics (AISTATS2020), Palermo, Sicily, Italy. PMLR 108:735-745, 2020.

Parameters:

• X (array-like, shape (n_samples, n_features)) – Training data, where n_samples is the number of samples and n_features is the number of features.

• max_explanatory_num (int, optional (default=2)) – Maximum number of explanatory variables.

• cor_alpha (float, optional (default=0.01)) – Alpha level for pearson correlation.

• ind_alpha (float, optional (default=0.01)) – Alpha level for HSIC.

• shapiro_alpha (float, optional (default=0.01)) – Alpha level for Shapiro-Wilk test.

• MLHSICR (bool, optional (default=False)) – If True, use MLHSICR for multiple regression, if False, use OLS for multiple regression.

• bw_method (str, optional (default=``mdbs``)) –

  The method used to calculate the bandwidth of the HSIC.

  • mdbs : Median distance between samples.

  • scott : Scott’s Rule of Thumb.

  • silverman : Silverman’s Rule of Thumb.

lingam.utils.f_correlation(x, y)

Implementation of F-correlation [2]

References

[2]

Bach, Francis R., and Michael I. Jordan. “Kernel independent component analysis.” Journal of machine learning research 3.Jul (2002): 1-48.

Parameters:

• x (array-like, shape (n_samples)) – Data, where n_samples is the number of samples.

• y (array-like, shape (n_samples)) – Data, where n_samples is the number of samples.

Returns:

The valus of F-correlation.

Return type:

float

lingam.utils.visualize_nonlinear_causal_effect(X, cd_result, estimator, cause_name, effect_name, cause_positions=None, percentile=None, fig=None, boxplot=False)

Visualize non-linear causal effect.

Parameters:

• X (pandas.DataFrame, shape (n_samples, n_features)) – Training data used to obtain cd_result.

• cd_result (array-like with shape (n_features, n_features) or BootstrapResult) – Adjacency matrix or BootstrapResult. These are the results of a causal discovery.

• estimator (estimator object) – estimator used for non-linear regression. Regression with estimator using cause_name and covariates as explanatory variables and effect_name as objective variable. Those covariates are searched for in cd_result.

• cause_name (str) – The name of the cause variable.

• effect_name (str) – The name of the effect variable.

• cause_positions (array-like, optional (default=None)) – List of positions from which causal effects are calculated. By default, cause_positions stores the position at which the value range of X is divided into 10 equal parts.

• percentile (array-like, optional (default=None)) – A tuple consisting of three percentile values. Each value must be greater than 0 and less than 100. By default, (95, 50, 5) is set.

• fig (plt.Figure, optional (default=None)) – If fig is given, draw a figure in fig. If not given, plt.fig is prepared internally.

• boxplot (boolean, optional (default=False)) – If True, draw a box plot instead of a scatter plot for each cause_positions.

Returns:

fig – Plotted figure.

Return type:

plt.Figure

lingam.utils.evaluate_model_fit(adjacency_matrix, X, is_ordinal=None)

evaluate the given adjacency matrix and return fit indices

Parameters:

• adjacency_matrix (array-like, shape (n_features, n_features)) – Adjacency matrix representing a causal graph. The i-th column and row correspond to the i-th column of X.

• X (array-like, shape (n_samples, n_features)) – Training data.

• is_ordinal (array-like, shape (n_features,)) – Binary list. The i-th element represents that the i-th column of X is ordinal or not. 0 means not ordinal, otherwise ordinal.

Returns:

fit_indices – Fit indices. This API uses semopy’s calc_stats(). See semopy’s reference for details.

Return type:

pandas.DataFrame

lingam.utils.calculate_distance_from_root_nodes(adjacency_matrix, max_distance=None)

Calculate shortest distances from root nodes.

Parameters:

• adjacency_matrices (array-like) – The adjacency matrix.

• max_distance (int or None, optional (default=None)) – The maximum distance to return nodes from root nodes.

Returns:

shortest_distances –

The dictionary has the following format:

{'distance_from_root_node': [index_of_variables]}

Return type:

dict

lingam.utils.calculate_total_effect(adjacency_matrix, from_index, to_index, is_continuous=None)

Calculate total effect.

Parameters:

• adjacency_matrix (array_like) – The adjacency matrix.

• from_index (int) – The index of the cause variable.

• to_index (int) – The index of the effect variable.

• is_continuous (list) – The list of boolean. is_continuous indicates whether each variable is continuous or discrete.

Returns:

total_effect

Return type:

float

lingam.utils.get_common_edge_probabilities(bootstrap_results, mode='across')

Calculate the probability of common edges across multiple bootstrap results.

This function analyzes adjacency matrices from a list of bootstrap results and computes the probability of common edges (non-zero and not NaN) and hidden common cause edges (NaN) either per sample or across all samples depending on the selected mode.

Parameters:

• bootstrap_results (list) – A list of objects, each containing an attribute adjacency_matrices_, which is a list or array of adjacency matrices (2D numpy arrays) from bootstrap iterations.

• mode (str, optional) –

  The mode of calculation. Must be either:

  • ’per’: Computes common edge probabilities by extracting common edges at each bootstrap iteration.

  • ’across’: Computes common edge probabilities across all samples within each bootstrap result.

Returns:

common_edge_probabilities – A stacked array of shape (2, n, n), where:

• common_edge_probabilities[0]: The probabilities of common edges.

• common_edge_probabilities[1]: The nan probabilities of hidden common cause.

Return type:

np.ndarray

lingam.utils.print_common_edge_directions(common_edge_probabilities, confidence_level=0.01, labels=None)

Print statistically significant causal directions based on common edge probabilities.

Parameters:

• common_edge_probabilities (ndarray) – A 2D NumPy array where each element [i, j] represents the probability that variable j causes variable i. The matrix is expected to be square and contain non-negative values.

• confidence_level (float, optional) – A threshold between 0 and 1 (inclusive) used to determine whether a causal direction is considered statistically significant. Only edges with probabilities strictly greater than this value will be displayed.

• labels (list of str, optional) – A list of variable names corresponding to the indices in the matrix. If provided, these labels will be used in the output instead of generic variable names (e.g., x0, x1, …).

lingam.utils.make_dot_for_nan_probability_matrix(adjacency_matrix, labels=None, lower_limit=0.01, path=None, path_color=None, ignore_shape=False)

Directed graph source code in the DOT language with specified nan probability matrix of hidden common cause.

Parameters:

• adjacency_matrix (array-like with shape (n_features, n_features)) – Nan probability matrix of hidden common cause to make graph, where n_features is the number of features.

• labels (array-like, optional (default=None)) – Label to use for graph features.

• lower_limit (float, optional (default=0.01)) – Threshold for drawing direction. If float, then directions with absolute values of coefficients less than lower_limit are excluded.

• path (tuple, optional (default=None)) – Path to highlight. Tuple of start index and end index.

• path_color (string, optional (default=None)) – Colors to highlight a path.

• ignore_shape (boolean, optional (default=False)) – Ignore checking the shape of adjaceny_matrix or not.

Returns:

graph – Directed graph source code in the DOT language. If order is unknown, draw a double-headed arrow.

Return type:

graphviz.Digraph

lingam.utils.bic_select_logistic_l1(X, y, Cs=50, max_iter=1000)

Select the best L1-regularized logistic regression model using BIC.

Parameters:

• X (array-like, shape (n_samples, n_features)) – Feature matrix.

• y (array-like, shape (n_samples, ...)) – Binary target vector.

• Cs (int or array, optional (default=50)) – If an integer, defines the number of regularization strengths to test, logarithmically spaced between strong and weak regularization. If an array, provides explicit values of inverse regularization strengths to evaluate.

• max_iter (int, optional (default=1000)) – Maximum number of iterations

Returns:

• best_coef (array-like, shape (n_features, …)) – Best coefficients according to BIC score.

• best_intercept (float) – Best intercept according to BIC score.

• best_C (float) – Regularization strength selected

• bic_scores (list) – BIC for each C

• Cs (array-like) – The Cs tested

class lingam.utils.MGGD(mean, cov, beta=1, tolerance=1e-06)

Multivariate Generalized Gaussian Distribution (MGGD)

__init__(mean, cov, beta=1, tolerance=1e-06)

Initializes the MGGD with given parameters.

Parameters:

• mean (array-like, shape (n_features,)) – Mean vector of the distribution.

• cov (array-like, shape (n_features, n_features)) – Covariance matrix of the distribution.

• beta (float, optional (default=1)) – Shape parameter of the distribution.

• tolerance (float, optional (default=1e-6)) – Tolerance for convergence in parameter estimation.

rvs(size)

Generates random samples from the MGGD.

Parameters:

size (int) – Number of samples to generate.

Returns:

samples – Generated samples.

Return type:

array-like, shape (size, n_features)

class lingam.utils.MGGDEstimator

Estimator for Multivariate Generalized Gaussian Distribution (MGGD) parameters

__init__()

fit(X, eps=1e-06)

Estimates the parameters of the MGGD from data.

Parameters:

• X (array-like, shape (n_samples, n_features)) – Input data.

• eps (float, optional (default=1e-6)) – Small value to avoid division by zero.

Returns:

mggd – Estimated MGGD object.

Return type:

MGGD