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)[source]
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’, ‘TPC’. True: Assume Gaussian Noise distribution, False: Distribution free.

  • maxdelay – (int) Maximum time-delay of interactions. Arg used for method_name = ‘GC’, ‘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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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