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’ 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)[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