API

Causal inference

bmlingam.InferParams

class bmlingam.InferParams(seed=0, standardize=True, subtract_mu_reg=False, fix_mu_zero=True, prior_var_mu='auto', max_c=1.0, n_mc_samples=10000, P_M1=0.5, P_M2=0.5, dist_noise='gg', df_indvdl=8.0, prior_scale='log_normal', scale_coeff=1.0, prior_indvdls=['t'], cs=array([ 0. , 0.2, 0.4, 0.6, 0.8, 1. ]), L_cov_21s=[-0.9, -0.7, -0.5, -0.3, 0, 0.3, 0.5, 0.7, 0.9], betas_indvdl=[0.25, 0.5, 0.75, 1.0], betas_noise=[0.25, 0.5, 0.75, 1.0], causalities='x1->x2, x2->x1', sampling_mode='normal')

Parameters for causal inference with the bayesian mixed LiNGAM.

The fields of this class are grouped into two sets. The one is the set of parameters that define the candidates of models, i.e., possible value of hyperparameters.

Parameters:
  • prior_indvdls (list of string) – Distributions of individual specific effects. Possible values are ['t'], ['gauss'], ['gg'], ['t', 'gauss'], or ['t', 'gg']. The default value is ['t']. gg means generalized Gaussian distribution.
  • cs (list of float) – Scales of the standard deviations of the individual specific effects. The default value is [0, 0.2, 0.4, 0.6, 0.8, 1.0].
  • L_cov_21s (list of float) – Correlation coefficients of individual specific effects. The default value is [-.9, -.7, -.5, -.3, 0, .3, .5, .7, .9].
  • betas_indvdl – Beta values of generalized Gaussian distributions for individual specific effects. The default value is [0.25, 0.5, 0.75, 1.].
  • betas_noise – Beta values of generalized Gaussian distributions for noise. The default value is [0.25, 0.5, 0.75, 1.].
  • causalities – Causal directions to be tested. The default value is x1->x2, x2->x1.

The other includes parameters applied to all candidate models.

Parameters:
  • seed (int) – Seed of random number generator. The default value is 0.
  • standardize (bool) – If true (default), samples are standardized.
  • subtract_mu_reg (bool) – Specify regression variable. The default value is False.
  • fix_mu_zero (bool) – If True (default), the common interception is fixed to 0.
  • prior_var_mu ('auto' (str literal) or float) – Set prior variance of common interceptions. The default value is auto.
  • max_c (float) – Scale constant on tau_cmmn. The default value is 1.0.
  • n_mc_samples (int) – Number of Monte Carlo samples. The default value is 10000.
  • P_M1 (float) – Prior probability selecting model M1. The default value is 0.5.
  • P_M2 (float) – Prior probability selecting model M2. The default value is 0.5.
  • dist_noise (str, 'laplace' or 'gg'.) – Noise distribution. The default vaule is gg.
  • df_indvdl (float) – Degrees of freedom of T distibution.
  • prior_scale' – Prior distribution of scale variable.
  • scale_coeff' (float) – Scale of prior std of regression coefficient. The default value is 1.0.
  • sampling_mode (str) – Sampling mode for MC integration. The default value is normal, in which random numbers are generated for each candidate models. If cache[_mp(2, 4, 8)], random numbers are cached and reused for evaluation of each candidate models. This mode is faster than normal. _mp(2, 4, 8) means using multiprocesses (2, 4 or 8 processes) for evaluation of candidate models in parallel.

Attributes

bmlingam.define_hparam_searchspace

bmlingam.define_hparam_searchspace(infer_params)

Returns a list of hyperparameter sets.

Search space is defined by the following fields in infer_params:

  • prior_indvdls
  • cs
  • L_cov_21s
  • betas_indvdl
  • betas_noise

Other fields are treated as constants.

All of the returned values, i.e. hyperparameters, are used to calculate log marginal probabilities and the maximal value is taken.

Parameters:infer_params (InferParams) – Parameters defining hyperparameter set.

Returned value is a list of dicts, each of that is a set of hyperparameters. It is created by the following code:

hparamss = [
    {
        # Fixed hyperparameters
        'seed': seed, 
        'standardize': standardize, 
        'subtract_mu_reg': subtract_mu_reg, 
        'fix_mu_zero': fix_mu_zero, 
        'prior_var_mu': prior_var_mu, 
        'max_c': max_c, 
        'n_mc_samples': n_mc_samples, 
        'P_M1': P_M1, 
        'P_M2': P_M2, 
        'dist_noise': dist_noise, 
        'df_indvdl': df_indvdl, 
        'prior_scale': prior_scale, 

        # Varied hyperparameters
        'causality': causality, 
        'prior_indvdl': prior_indvdl, 
        'v_indvdl_1': v_indvdl_1, 
        'v_indvdl_2': v_indvdl_2, 
        'L_cov': L_cov, 
        'beta_coeff': beta_coeff, 
        'beta_noise': beta_noise
    }
    for prior_indvdl in prior_indvdls
    for v_indvdl_1 in cs
    for v_indvdl_2 in cs
    for L_cov in L_covs
    for causality in causalities
    for beta_coeff in (betas_indvdl if prior_indvdl == 'gg' else [None])
    for beta_noise in (betas_noise if dist_noise == 'gg' else [None])]
Returns:List of hyperparameter sets.
Return type:list of dicts

bmlingam.find_best_model

bmlingam.find_best_model(xs, hparamss, sampling_mode='normal')

Find the optimal and reverse-optimal models.

This function calculates marginal likelihoods for the models specified with hyperparameter sets included in hparamss. The optimal model is the one whose marginal likelihood on data xs is the maximum. Reverse-optimal is the one with the maximum marginal likelihood across models whose causations are opposite to the optimal model.

Parameters:
  • xs (numpy.ndarray, shape=(n_samples, 2)) – Pairs of observed values.
  • hparamss (list of dict) – List of model parameters which defines search space. This is created with bmlingam.define_hparam_searchspace().
  • sampling_mode (str) – Specify the way to perform Monte Carlo sampling.

Estimation of regression coefficient

bmlingam.MCMCParams

class bmlingam.MCMCParams(n_burn=10000, n_mcmc_samples=10000, seed_burn=1, seed=2, verbose=0, nanguard=False)

Parameters for MCMC to estimate regression coefficient.

Parameters:
  • n_burn (int) – Samples in burn-in period. The default value is 10000.
  • n_mcmc_samples (int) – Samples in MCMC (after burn-in). The default value is 10000.
  • seed_burn (int) – Random seed for burn-in period. The default value is 1.
  • seed (int) – Random seed for MCMC. The default value is 2.
  • verbose (int) – Verbose level. The default value is 0 (silent).

Attributes

bmlingam.do_mcmc_samples

bmlingam.do_mcmc_bmlingam(xs, hparams, mcmc_params)

Do MCMC for sampling posterior of bmlingam coefficient.

Example:

mcmc_params = MCMCParams(
    n_burn=10000,     # Samples in burn-in period
    n_mcmc_samples=10000, # Samples in MCMC (after burn-in)
    seed_burn=1, # Random seed for burn-in period
    seed=2 # Random seed for MCMC
) 
trace = do_mcmc_bmlingam(data['xs'], hparams, mcmc_params)
b_post = np.mean(trace['b'])

xs is the numpy.ndarray containing samples.

Parameters:xs (numpy.ndarray, shape=(n_samples, 2)) – Data array.

hparams is a dict including hyperparameters. See bmlingam.hparam.define_hparam_searchspace().

Parameters:hparams (dict) – Set of hyperparameters.

mcmc_params includes parameters for MCMC.

Parameters:mcmc_params (bmlingam.MCMCParams) – Parameters for MCMC.

Artificial data

bmlingam.utils.gendata.GenDataParams

class bmlingam.utils.gendata.GenDataParams(n_samples=100, b21_dist='r2intervals', mu1_dist=5.0, mu2_dist=10.0, f1_scale=1.0, f2_scale=1.0, f1_coef=['r2intervals', 'r2intervals', 'r2intervals'], f2_coef=['r2intervals', 'r2intervals', 'r2intervals'], conf_dist=[['all'], ['all'], ['all']], e1_std=3.0, e2_std=3.0, e1_dist=['laplace'], e2_dist=['laplace'], fix_causality=False, seed=0)

Parameters for generating artificial data.

This parameter object is an argument of function gen_artificial_data(). The number of samples in the data is specified with a parameter.

Parameters:n_samples (int) – Number of samples in the data.

The data generated by this function has two random variables \(x_{1}^{(i)}\) and \(x_{2}^{(i)}\), where \(i\) denotes the sample index. The generative model of data is given as follows:

\[\begin{split}x_{1}^{(i)} &= \mu_{1} + s_{1}\sum_{q=1}^{Q}\lambda_{1}^{q}f_{q}^{(i)} + e_{1}^{(i)} \\ x_{2}^{(i)} &= \mu_{2} + s_{2}\sum_{q=1}^{Q}\lambda_{2}^{q}f_{q}^{(i)} + b_{21}x_{1}^{(i)} + e_{2}^{(i)}. \end{split}\]

All of the above quantities in the RHS are random variables. This equation corresponds to causal direction from \(x_{1}\) to \(x_{2}\). The function randomly flips the causality with 50% probability, i.e., \(x_{2}\) to \(x_{1}\). For testing purpose, however, one might want to fix causal direction. The randomness could be controlled by parameter fix_causality.

Parameters:fix_causality (bool) – Randomness of causal direction. If this parameter is set to True, the causal direction of the generative model is determined with 50% probability. Otherwise, the causal direction isfixed to \(x_{1}\) to \(x_{2}\). Default is False.

\(b_{21}\) is the regression coefficient, corresponding to strength of the causal effect. \(\mu_{r} (r=1,2)\) is the bias term. These random variables are drawn only once for a dataset. Probability distributions for these random variables are specified with the following parameters.

Parameters:
  • b21_dist (str or float) – Distribution of \(b_{21}\). If b21_dist is 'r2interval', \(b21\) is drawn from a mixture of two uniform distributions \([-1.5, -0.5]\) and \([0.5, 1.5]\), as appeared in the paper. If a float value is given, \(b_{21}\) is set to that value.
  • mu1_dist (str or float) – Distribution of \(\mu_{1}\). If randn, \(mu_{1}\) is drawn from the standard normal distribution. If a float value is given, \(\mu_{1}\) is set to that value.
  • mu2_dist (str or float) – Same with mu1_dist.

\(s_{r}\sum_{q=1}^{Q}\lambda_{r,q}f_{q}^{(i)} (r=1,2)\) is a weighted sum of confounders. \(s_{r}\) is just a scaling constant. The weights \(\lambda_{r,q}\) (\(q=1,\cdots, Q\)) are dependent on confounders and could be random variables or constants. Random variables \(f_{q}^{(i)}\) are dependent on both of confounders and samples. The parameters related to the confounders are as below.

Parameters:
  • f1_scale (float) – Scaling constant for the confound term in x_{1}. f1_coef=[1, 1, 1], f1_scale=1/3.0 is equivalent to f1_coef=[1/3.0, 1/3.0, 1/3.0], f1_scale=1.
  • f1_coef (list of (str or float)) – List of distributions or constants of weights of confounders. The length of the list is the number of confounders in the weighted sum. If f1_coef[q] is r2intervals, the uniform mixture distribution, used for \(b_{21}\), is also used to draw a value of the \(q\)-th weight. If a float value is given, the weight is set to that value.
  • conf_dist (list of (list of strs)) – List of possible distributions for confound factors. The length of the list, len(conf_dist), is equal to the number of confounders. For example, if conf_dist = [['laplace'], ['exp', 'uniform]]`, the 1st confounder is distributed according to the standard Laplace distribution and the 2nd confounder is drawn from either the exponential or uniform distributions with 50% probability. 'all' denotes that all distributions in usr_distrib() are possible.
  • f2_scale (float) – Same with f1_scale.
  • f2_coef (list of (str or float)) – Same with f1_coef.

\(e_{r}^{(i)}\) is a noise term. Its distribution and standard deviation are specified by the following parameters.

Parameters:
  • e1_dist (List of strs) – Possible distributions of noise.
  • e1_std (float) – Standard deviation of the noise.
  • e2_dist (List of strs) – Same with e1_dist.
  • e2_std (float) – Same with e1_std.

The seed of random number generator needs to be set.

Parameters:seed – Seed of random number generator.

Here is the list of distributions in usr_distrib().

  • ‘gmm4_symm_mul’: mixture of 4 Gaussians, symmetric and multimodal
  • ‘gmm4_symm_trn’: mixture of 4 Gaussians, symmetric and transitional
  • ‘gmm4_symm_uni’: mixture of 4 Gaussians, symmetric and unimodal
  • ‘gmm4_asym_mul’: mixture of 4 Gaussians, nonsymmetric and multimodal
  • ‘gmm4_asym_trn’: mixture of 4 Gaussians, nonsymmetric and transitional
  • ‘gmm4_asym_uni’: mixture of 4 Gaussians, nonsymmetric and unimodal
  • ‘t5df’: Student T with 3 degrees of freedom
  • ‘t5df’: Student T with 5 degrees of freedom
  • ‘exp’: Simple exponential
  • ‘laplace’: Double exponential (Laplace)
  • ‘uniform’: Uniform
  • ‘dexp2’: mixtures of 2 double exponential
  • ‘gmm2_symm_mul’: mixture of 2 Gaussians, symmetric and multimodal
  • ‘gmm2_symm_trn’: mixture of 2 Gaussians, symmetric and transitional
  • ‘gmm2_symm_uni’: mixture of 2 Gaussians, symmetric and unimodal
  • ‘gmm2_asym_mul’: mixture of 2 Gaussians, nonsymmetric and multimodal
  • ‘gmm2_asym_trn’: mixture of 2 Gaussians, nonsymmetric and transitional
  • ‘gmm2_asym_uni’: mixture of 2 Gaussians, nonsymmetric and unimodal
  • ‘all’: All distributions above

Attributes