timeawarepc package — timeawarepc 2022 documentation

# timeawarepc package

## Submodules

## timeawarepc.find_cfc module

Convenient wrapper for functions in the library.

timeawarepc.find_cfc.find_cfc(data, method_name, alpha=0.05, maxdelay=1, niter=50, thresh=0.25, isgauss=False)
  Estimate Causal Functional Connectivity (CFC) between nodes from time series.

    This is a wrapper for functions cfc_tpc, cfc_pc, cfc_gc in tpc.py. Refer to the individual functions for their details.

  Parameters

    - data – (numpy.array) of shape (n,p) with n time-recordings for p nodes

    - method_name – (string) ‘TPC’: Implements TPC Algorithm, ‘PC’: PC Algorithm, ‘GC’: Granger Causality.

    - alpha – (float) Significance level

    - isgauss – (boolean) Arg used for method_name == ‘PC’ or ‘TPC’. True: Assume Gaussian Noise distribution, False: Distribution free.

    - maxdelay – (int) Maximum time-delay of interactions. Arg used for method_name == ‘GC’ or ‘TPC’.

    - subsampsize – (int) Bootstrap window width in TPC. Arg used for method_name == ‘TPC’.

    - niter – (int) Number of bootstrap iterations in TPC. Arg used for method_name == ‘TPC’.

    - thresh – (float) Bootstrap stability cut-off in TPC. Arg used for method_name == ‘TPC’.

  Returns

    (numpy.array) Adcajency matrix of estimated CFC by chosen method. weights: (numpy.array) Connectivity Weights in the CFC

  Return type

    adjacency

## timeawarepc.tpc module

Implements the Time-Aware PC (TPC) Algorithm for finding Causal Functional Connectivity from Time Series.

timeawarepc.tpc.cfc_pc(data, alpha, isgauss=False)

  Estimate Causal Functional Connectivity using PC Algorithm.

  Parameters

    - data – (numpy.array) of shape (n,p) with n samples for p nodes

    - alpha – (float) Significance level for conditional independence tests

    - isgauss – (boolean) True: Assume Gaussian Noise distribution, False: Distribution free.

  Returns

    (numpy.array) Adcajency matrix of shape (p,p) of estimated CFC by PC Algorithm. weights: (numpy.array) Connectivity Weight matrix of shape (p,p).

  Return type

    adjacency

timeawarepc.tpc.cfc_tpc(data, maxdelay=1, subsampsize=50, niter=25, alpha=0.1, thresh=0.25, isgauss=False)

  Estimate Causal Functional Connectivity using TPC Algorithm.

  Parameters

    - data – (numpy.array) of shape (n,p) with n time-recordings for p nodes .

    - maxdelay – (int) Maximum time-delay of interactions.

    - subsampsize – (int) Bootstrap window width.

    - niter – (int) Number of bootstrap iterations.

    - alpha – (float) Significance level for conditional independence tests.

    - thresh – (float) Bootstrap stability cut-off.

    - isgauss – (boolean) True: Assume Gaussian Noise distribution. False: Distribution-free.

  Returns

    (numpy.array) Adcajency matrix of shape (p,p) for estimated CFC by TPC Algorithm. weights: (numpy.array) Connectivity Weight matrix of shape (p,p).

  Return type

    adjacency

  Biswas, Rahul and Shlizerman, Eli (2022). Statistical perspective on functional and causal neural connectomics: the time-aware pc algorithm. arXiv preprint arXiv:2204.04845.

## timeawarepc.tpc_helpers module

Helper functions for TPC Algorithm

timeawarepc.tpc_helpers.causaleff_ida(g, data)

  Estimate interventional causal effects in the Unrolled DAG in TPC.

  Parameters

    - g – (networkx.DiGraph) Estimated Unrolled Causal DAG outputted by Step 4 (Orient) of TPC.

    - data – (numpy.array) with variables for Unrolled Causal DAG in columns and time-delayed samples in rows

  Returns

    (numpy.array) Interventional Causal Effects among pairs of nodes in the Unrolled Causal DAG.

  Return type

    causaleff

timeawarepc.tpc_helpers.data_transformed(data, maxdelay)

  Implements Step 1 (Time Delay) of TPC, to construct the data with time-delayed samples.

  Parameters

    - data – (numpy.array) of shape (n,p) with n time recordings of p nodes.

    - maxdelay – (int) Maximum time-delay of interactions

  Returns

    (numpy.array) Data with columns as Unrolled DAG nodes (column index v*maxdelay+t = node (v,t)) and rows having time-delayed samples.

  Return type

    data2

timeawarepc.tpc_helpers.orient(g, maxdelay, m)

  Implements Step 4 (Orient) of TPC, to correct future to past edges in Estimated Unrolled DAG

  Parameters

    - g – (networkx.DiGraph) Unrolled Causal DAG estimate outputted by Step 3 (PC) of TPC.

    - maxdelay – (int) Maximum time-delay of interaction

    - m – (int) Number of neurons/nodes in original data

  Returns

    (networkx.DiGraph) Re-Oriented Unrolled Causal DAG estimate.

  Return type

    g1

timeawarepc.tpc_helpers.return_finaledges(g, causaleff, maxdelay, m)

  Implements Step 5 (Rolled CFC-DPGM) of TPC, to obtain the Rolled CFC-DPGM and its weights from the Unrolled Causal DAG

  Parameters

    - g – (networkx.DiGraph) Oriented Unrolled Causal DAG estimate outputted by Step 4 (Orient) of TPC.

    - causaleff – (numpy.array) Estimated Interventional Causal Effects in Unrolled DAG

    - maxdelay – (int) Maximum time-delay of interaction

    - m – (int) Number of neurons/nodes in original data

  Returns

    (numpy.array) Adjacency matrix for the Rolled CFC-DPGM estimate. wdir: (numpy.array) Weights for direct connections in the Rolled CFC-DPGM. windir: (numpy.array) Weights for indirect/direct connections in the Rolled CFC-DPGM.

  Return type

    adjacency

## timeawarepc.pcalg module

A graph generator based on the PC algorithm [Kalisch2007] via https://github.com/keiichishima/pcalg

timeawarepc.pcalg.estimate_cpdag(skel_graph, sep_set)

  Estimate a CPDAG from the skeleton graph and separation sets returned by the estimate_skeleton() function.

  Parameters

    - skel_graph – A skeleton graph (an undirected networkx.Graph).

    - sep_set –

      An 2D-array of separation set. The contents look like something like below.

      > sep_set[i][j] = set([k, l, m])

  Returns

    An estimated DAG.

timeawarepc.pcalg.estimate_skeleton(indep_test_func, data_matrix, alpha, **kwargs)

  Estimate a skeleton graph from the statistis information.

  Parameters

    - indep_test_func – the function name for a conditional independency test.

    - data_matrix – data (as a numpy array).

    - alpha – the significance level.

    - kwargs –

      ‘max_reach’: maximum value of l (see the code). The

        value depends on the underlying distribution.

      ’method’: if ‘stable’ given, use stable-PC algorithm

        (see [Colombo2014]).

      ’init_graph’: initial structure of skeleton graph

        (as a networkx.Graph). If not specified, a complete graph is used.

      other parameters may be passed depending on the

        indep_test_func()s.

  Returns

    a skeleton graph (as a networkx.Graph). sep_set: a separation set (as an 2D-array of set()).

  Return type

    g

  [Colombo2014] Diego Colombo and Marloes H Maathuis. Order-independent constraint-based causal structure learning. In The Journal of Machine Learning Research, Vol. 15, pp. 3741-3782, 2014.

## timeawarepc.pcalg_helpers module

Helper functions for PC algorithm.

timeawarepc.pcalg_helpers.ci_test_gauss(data, A, B, S, **kwargs)

  Conduct Conditional Independence Test using Fisher’s Z-transform for node A conditionally independent of node B given set of nodes in S.

  Parameters

    - data – (numpy.array) of shape (n,p) with n samples for p nodes

    - A – (int) node index in data

    - B – (int) node index in data

    - S – (set) set of node indices in data

  Returns

    (float) p-value of the conditional independence test for A and B given S.

  Return type

    pval

timeawarepc.pcalg_helpers.partial_corr(data, A, B, S)

  Find Partial Correlation of var A and var B given set of vars in S.

  Parameters

    - data – (numpy.array) of shape (n,p) with n samples for p nodes

    - A – (int) node index in data

    - B – (int) node index in data

    - S – (set) set of node indices in data

  Returns

    Partial correlation between A and B given S.

  Return type

    p_corr

## timeawarepc.gc module

timeawarepc.gc.cfc_gc(data, maxdelay, alpha)

  Estimate Causal Functional Connectivity using Granger Causality.

  Parameters

    - data – (numpy.array) of shape (n,p) with n samples for p nodes

    - maxdelay – Maximum time-delay of interactions.

    - alpha – (float) Significance level for conditional independence tests

  Returns

    (numpy.array) Adcajency matrix of shape (p,p) of estimated CFC by Granger Causality. weights: (numpy.array) Connectivity Weight matrix of shape (p,p).

  Return type

    adjacency

## timeawarepc.simulate_data module

Create simulated time series dataset from three different paradigms: Linear Gaussian Vector-AutoRegressive (VAR) Model, Non-linear Non-Gaussian VAR Model, and Continuous Time Recurrent Neural Networks (CTRNN).

timeawarepc.simulate_data.simulate_ctrnn(n_ctrnn, p, w, tau, noise=1)

  Simulates a CTRNN.

  Parameters

    - n_ctrnn – Number of time points in the CTRNN

    - p – Number of nodes.

    - w – Weight matrix.

    - tau – Time constant of the CTRNN.

    - noise – Noise level in the CTRNN.

  Returns

    (numpy.array) CTRNN time series of shape (p,n_ctrnn).

  Return type

    u

timeawarepc.simulate_data.simulate_data(model, T=1000, noise=1)

  Simulate time seris data from one of three simulation paradigms with 4 neurons.

  Parameters

    - model – (string) ‘lingauss’: Linear Gaussian VAR model ‘nonlinnongauss’: Non-linear Non-Gaussian VAR model ‘ctrnn’: Continuous Time Recurrent Neural Networks

    - T – (int) Number of time recordings in the time series

    - noise – (float) Noise standard deviation

  Returns

    (numpy.array) Time series data of shape (n,p) with n time recordings for p nodes CFCtruth: (numpy.array) Ground Truth adjacency matrix of shape (p,p).

  Return type

    data