timeawarepc 1.2.4__tar.gz → 2.0.1__tar.gz

{timeawarepc-1.2.4/timeawarepc.egg-info → timeawarepc-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timeawarepc
-Version: 1.2.4
+Version: 2.0.1
 Summary: Time-Aware PC Python Package
 Home-page: https://github.com/biswasr/TimeAwarePC
 Author: Rahul Biswas
@@ -15,7 +15,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: pandas
-Requires-Dist: rpy2==3.5.11
+Requires-Dist: rpy2>=3.5.11
 Requires-Dist: networkx
 Requires-Dist: scipy
 Dynamic: author
@@ -39,17 +39,25 @@ Dynamic: summary
 
 ## Installation
 
-You can get the latest version of TimeAwarePC as follows.
+### Recommended: conda environment (handles R + kpcalg automatically)
 
 ```
-$ pip install timeawarepc
+$ git clone https://github.com/shlizee/TimeAwarePC.git
+$ cd TimeAwarePC
+$ conda env create -f environment.yml
+$ conda activate timeawarepc
+$ Rscript install_r_deps.R   # installs kpcalg from CRAN archive
 ```
 
-## Requirements
-- Python == 3.10
-- Python packages automatically checked and installed as part of the setup. To use Granger Causality, additional dependency of ```nitime``` which can be installed by ```pip install nitime```.
-- R == 4.4.2
-- R package ```kpcalg``` and its dependencies. They can be installed in R or RStudio as follows:
+This installs Python, R, rpy2, all required R packages (graph, RBGL, pcalg), and TimeAwarePC v2.0.0 in a single isolated environment.
+
+### Manual install (alternative)
+
+If you prefer to install without conda:
+
+- Python >=3.9, <3.11
+- R >= 4.0
+- R package ```kpcalg``` and its dependencies, installed via R or RStudio:
 ```
 > install.packages("BiocManager")
 > BiocManager::install("graph")
@@ -57,10 +65,12 @@ $ pip install timeawarepc
 > install.packages("pcalg")
 > install.packages("https://cran.r-project.org/src/contrib/Archive/kpcalg/kpcalg_1.0.1.tar.gz")
 ```
-<!-- - In addition, if you like to use Granger Causality functions in this package, please separately install nitime as follows:
+- Then:
 ```
-pip install nitime
-``` -->
+$ pip install timeawarepc
+```
+
+To use Granger Causality, also install `nitime` (`pip install nitime`).
 
 ## Documentation
 
@@ -68,7 +78,15 @@ pip install nitime
 
 ## Tutorial
 
-See the [Quick Start Guide](https://timeawarepc.readthedocs.io/en/latest/gettingstarted.html) for a quick tutorial of the main functionalities of this library and check if it is installed properly. 
+See the [Quick Start Guide](https://timeawarepc.readthedocs.io/en/latest/gettingstarted.html) for a quick tutorial of the main functionalities of this library and check if it is installed properly.
+
+## What's new in v2.0.0
+
+- `cfc_tpc` now defaults to **no bootstrap subsampling**: a single PC run is performed on the full time-delayed data.
+  - To use bootstrap stability scoring, pass `subsampsize` and `niter` together (e.g., `subsampsize=50, niter=25`).
+  - Both arguments must be specified together (or both left as the default `None`).
+- `partial_corr` now fits an intercept and is shift-invariant. Previously the regression was forced through the origin, biasing residuals when the data was not mean-centered.
+- See [CHANGELOG.md](CHANGELOG.md) for the full list of changes and migration notes.
 <!-- 
 ## Documentation
 
@@ -80,7 +98,7 @@ Your help is absolutely welcome! Please do reach out or create a feature branch!
 
 ## Citation
 
-Biswas, R., & Shlizerman, E. (2022). Statistical Perspective on Functional and Causal Neural Connectomics: The Time-Aware PC Algorithm. https://arxiv.org/abs/2204.04845
+Biswas, R., & Shlizerman, E. (2022). Statistical Perspective on Functional and Causal Neural Connectomics: The Time-Aware PC Algorithm. https://doi.org/10.1371/journal.pcbi.1010653
 
 Biswas, R., & Shlizerman, E. (2021). Statistical Perspective on Functional and Causal Neural Connectomics: A Comparative Study. Frontiers in Systems Neuroscience. https://doi.org/10.3389/fnsys.2022.817962
 

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/README.md

@@ -7,17 +7,25 @@
 
 ## Installation
 
-You can get the latest version of TimeAwarePC as follows.
+### Recommended: conda environment (handles R + kpcalg automatically)
 
 ```
-$ pip install timeawarepc
+$ git clone https://github.com/shlizee/TimeAwarePC.git
+$ cd TimeAwarePC
+$ conda env create -f environment.yml
+$ conda activate timeawarepc
+$ Rscript install_r_deps.R   # installs kpcalg from CRAN archive
 ```
 
-## Requirements
-- Python == 3.10
-- Python packages automatically checked and installed as part of the setup. To use Granger Causality, additional dependency of ```nitime``` which can be installed by ```pip install nitime```.
-- R == 4.4.2
-- R package ```kpcalg``` and its dependencies. They can be installed in R or RStudio as follows:
+This installs Python, R, rpy2, all required R packages (graph, RBGL, pcalg), and TimeAwarePC v2.0.0 in a single isolated environment.
+
+### Manual install (alternative)
+
+If you prefer to install without conda:
+
+- Python >=3.9, <3.11
+- R >= 4.0
+- R package ```kpcalg``` and its dependencies, installed via R or RStudio:
 ```
 > install.packages("BiocManager")
 > BiocManager::install("graph")
@@ -25,10 +33,12 @@ $ pip install timeawarepc
 > install.packages("pcalg")
 > install.packages("https://cran.r-project.org/src/contrib/Archive/kpcalg/kpcalg_1.0.1.tar.gz")
 ```
-<!-- - In addition, if you like to use Granger Causality functions in this package, please separately install nitime as follows:
+- Then:
 ```
-pip install nitime
-``` -->
+$ pip install timeawarepc
+```
+
+To use Granger Causality, also install `nitime` (`pip install nitime`).
 
 ## Documentation
 
@@ -36,7 +46,15 @@ pip install nitime
 
 ## Tutorial
 
-See the [Quick Start Guide](https://timeawarepc.readthedocs.io/en/latest/gettingstarted.html) for a quick tutorial of the main functionalities of this library and check if it is installed properly. 
+See the [Quick Start Guide](https://timeawarepc.readthedocs.io/en/latest/gettingstarted.html) for a quick tutorial of the main functionalities of this library and check if it is installed properly.
+
+## What's new in v2.0.0
+
+- `cfc_tpc` now defaults to **no bootstrap subsampling**: a single PC run is performed on the full time-delayed data.
+  - To use bootstrap stability scoring, pass `subsampsize` and `niter` together (e.g., `subsampsize=50, niter=25`).
+  - Both arguments must be specified together (or both left as the default `None`).
+- `partial_corr` now fits an intercept and is shift-invariant. Previously the regression was forced through the origin, biasing residuals when the data was not mean-centered.
+- See [CHANGELOG.md](CHANGELOG.md) for the full list of changes and migration notes.
 <!-- 
 ## Documentation
 
@@ -48,7 +66,7 @@ Your help is absolutely welcome! Please do reach out or create a feature branch!
 
 ## Citation
 
-Biswas, R., & Shlizerman, E. (2022). Statistical Perspective on Functional and Causal Neural Connectomics: The Time-Aware PC Algorithm. https://arxiv.org/abs/2204.04845
+Biswas, R., & Shlizerman, E. (2022). Statistical Perspective on Functional and Causal Neural Connectomics: The Time-Aware PC Algorithm. https://doi.org/10.1371/journal.pcbi.1010653
 
 Biswas, R., & Shlizerman, E. (2021). Statistical Perspective on Functional and Causal Neural Connectomics: A Comparative Study. Frontiers in Systems Neuroscience. https://doi.org/10.3389/fnsys.2022.817962
 

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = timeawarepc
-version = 1.2.4
+version = 2.0.1
 author = Rahul Biswas
 author_email = rahul.biswas@ucsf.edu
 description = Time-Aware PC Python Package
@@ -24,7 +24,7 @@ python_requires = >=3.7, <3.11
 install_requires = 
 	numpy
 	pandas
-	rpy2==3.5.11
+	rpy2>=3.5.11
 	networkx
 	scipy
 

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/setup.py

@@ -3,7 +3,7 @@ import setuptools
 with open('README.md','r') as fh:
     README = fh.read()
 
-VERSION = "1.2.4"
+VERSION = "2.0.1"
 
 setuptools.setup(
     name = 'timeawarepc',
@@ -19,7 +19,7 @@ setuptools.setup(
     install_requires=[
         'numpy',
         'pandas',
-        'rpy2==3.5.11',
+        'rpy2>=3.5.11',
         'networkx',
         'scipy'
     ],

timeawarepc-2.0.1/test/test_optional_bootstrap.py

@@ -0,0 +1,107 @@
+"""Tests for the optional bootstrap behavior of cfc_tpc.
+
+By default (subsampsize=None, niter=None), cfc_tpc should run PC once on the
+full time-delayed data without bootstrap subsampling. When both subsampsize
+and niter are specified, it should run bootstrap subsampling as before.
+"""
+import os
+import sys
+
+# Insert project root before any installed timeawarepc so tests run against
+# the in-repo source, not any pre-installed package version.
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+import numpy as np
+
+
+# All cfc_tpc paths import rpy2. If R/rpy2 isn't available on this system, we
+# fall back to testing the no-bootstrap signature directly via _run_pc_inner.
+try:
+    from timeawarepc.tpc import cfc_tpc
+    HAS_RPY2 = True
+except OSError:
+    HAS_RPY2 = False
+
+
+def _make_test_data(seed: int = 0, T: int = 400, p: int = 4):
+    rng = np.random.default_rng(seed)
+    data = rng.standard_normal((T, p))
+    # Inject lagged causal structure on the first 4 vars when available.
+    for t in range(1, T):
+        if p >= 2:
+            data[t, 1] = 0.7 * data[t - 1, 0] + 0.3 * rng.standard_normal()
+        if p >= 3:
+            data[t, 2] = 0.6 * data[t - 1, 1] + 0.3 * rng.standard_normal()
+        if p >= 4:
+            data[t, 3] = 0.5 * data[t - 1, 2] + 0.3 * rng.standard_normal()
+    return data
+
+
+def test_cfc_tpc_default_no_bootstrap():
+    """Default call (no subsampsize / niter) should succeed without bootstrap."""
+    if not HAS_RPY2:
+        print("SKIP test_cfc_tpc_default_no_bootstrap: rpy2/R not available")
+        return
+    data = _make_test_data()
+    adjacency, weights = cfc_tpc(data, maxdelay=1, alpha=0.1, isgauss=True)
+    assert adjacency.shape == (4, 4)
+    assert weights.shape == (4, 4)
+
+
+def test_cfc_tpc_bootstrap_path():
+    """Explicit bootstrap (subsampsize + niter specified) should still work."""
+    if not HAS_RPY2:
+        print("SKIP test_cfc_tpc_bootstrap_path: rpy2/R not available")
+        return
+    data = _make_test_data()
+    adjacency, weights = cfc_tpc(
+        data, maxdelay=1, alpha=0.1, isgauss=True,
+        subsampsize=50, niter=5,
+    )
+    assert adjacency.shape == (4, 4)
+    assert weights.shape == (4, 4)
+
+
+def test_cfc_tpc_partial_bootstrap_args_raises():
+    """Specifying only one of subsampsize/niter should raise ValueError."""
+    if not HAS_RPY2:
+        print("SKIP test_cfc_tpc_partial_bootstrap_args_raises: rpy2/R not available")
+        return
+    data = _make_test_data()
+    try:
+        cfc_tpc(data, isgauss=True, subsampsize=50)
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("Expected ValueError when only subsampsize is given")
+
+    try:
+        cfc_tpc(data, isgauss=True, niter=5)
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("Expected ValueError when only niter is given")
+
+
+def test_cfc_tpc_subsampsize_too_large_raises():
+    """subsampsize >= number of time-delayed samples should raise ValueError."""
+    if not HAS_RPY2:
+        print("SKIP test_cfc_tpc_subsampsize_too_large_raises: rpy2/R not available")
+        return
+    data = _make_test_data(T=20, p=3)
+    try:
+        cfc_tpc(data, isgauss=True, subsampsize=1000, niter=1)
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("Expected ValueError when subsampsize too large")
+
+
+if __name__ == "__main__":
+    test_cfc_tpc_default_no_bootstrap()
+    test_cfc_tpc_bootstrap_path()
+    test_cfc_tpc_partial_bootstrap_args_raises()
+    test_cfc_tpc_subsampsize_too_large_raises()
+    print("All tests passed.")

timeawarepc-2.0.1/test/test_partial_corr_shift_invariance.py

@@ -0,0 +1,61 @@
+"""Regression test: partial_corr should be shift-invariant.
+
+Adding a constant to the input data should not change the partial correlation,
+because the underlying linear regression now includes an intercept term.
+"""
+import os
+import sys
+
+# Insert project root before any installed timeawarepc so the tests run
+# against the in-repo source, not any pre-installed package version.
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+import numpy as np
+
+from timeawarepc.pcalg import partial_corr as partial_corr_pcalg
+from timeawarepc.pcalg_helpers import partial_corr as partial_corr_helpers
+
+
+def _make_test_data(seed: int = 0, n: int = 200):
+    rng = np.random.default_rng(seed)
+    # 3 variables; var 2 is a linear combination of vars 0 and 1 plus noise
+    data = rng.standard_normal((n, 3))
+    data[:, 2] = data[:, 0] + 0.5 * data[:, 1] + 0.1 * rng.standard_normal(n)
+    return data
+
+
+def test_partial_corr_pcalg_shift_invariant():
+    data = _make_test_data()
+    r_orig = partial_corr_pcalg(0, 2, {1}, data)
+    r_shift = partial_corr_pcalg(0, 2, {1}, data + 10.0)
+    assert np.isclose(r_orig, r_shift, atol=1e-8), (
+        f"partial_corr (pcalg) not shift-invariant: {r_orig} vs {r_shift}"
+    )
+
+
+def test_partial_corr_helpers_shift_invariant():
+    data = _make_test_data()
+    r_orig = partial_corr_helpers(data, 0, 2, {1})
+    r_shift = partial_corr_helpers(data + 10.0, 0, 2, {1})
+    assert np.isclose(r_orig, r_shift, atol=1e-8), (
+        f"partial_corr (helpers) not shift-invariant: {r_orig} vs {r_shift}"
+    )
+
+
+def test_partial_corr_pcalg_matches_helpers():
+    """Both partial_corr implementations should agree."""
+    data = _make_test_data()
+    r1 = partial_corr_pcalg(0, 2, {1}, data)
+    r2 = partial_corr_helpers(data, 0, 2, {1})
+    assert np.isclose(r1, r2, atol=1e-8), (
+        f"partial_corr disagreement between pcalg and helpers: {r1} vs {r2}"
+    )
+
+
+if __name__ == "__main__":
+    test_partial_corr_pcalg_shift_invariant()
+    test_partial_corr_helpers_shift_invariant()
+    test_partial_corr_pcalg_matches_helpers()
+    print("All tests passed.")

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/timeawarepc/__init__.py

@@ -2,5 +2,5 @@
 Time-Aware PC Algorithm for estimating Causal Functional Connectivity from Time Series
 """
 
-__version__ = "0.0.1"
+__version__ = "2.0.1"
 __all__ = ["tpc_helpers","tpc","find_cfc","pcalg","pcalg_helpers","simulate_data"]

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/timeawarepc/find_cfc.py

@@ -2,7 +2,8 @@
 """
 __all__ = ["find_cfc"]
 from timeawarepc.tpc import *
-def find_cfc(data,method_name,alpha=0.05,maxdelay=1,niter=50,thresh=0.25,isgauss=False):
+def find_cfc(data, method_name, alpha=0.05, maxdelay=1, isgauss=False,
+             subsampsize=None, niter=None, thresh=0.25):
     """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.
@@ -15,12 +16,16 @@ def find_cfc(data,method_name,alpha=0.05,maxdelay=1,niter=50,thresh=0.25,isgauss
             'GC': Granger Causality.
         alpha: (float) Significance level
         isgauss: (boolean) Arg used for method_name == 'PC' or 'TPC'.
-            True: Assume Gaussian Noise distribution, 
+            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'.
+        subsampsize: (int, optional) Bootstrap window width in TPC. If None
+            (default), no bootstrap is performed and the full time-delayed
+            data is used. Must be specified together with niter.
+        niter: (int, optional) Number of bootstrap iterations in TPC. Must be
+            specified together with subsampsize.
+        thresh: (float) Bootstrap stability cut-off in TPC. Only used when
+            bootstrap is active.
 
     Returns:
         adjacency: (numpy.array) Adcajency matrix of estimated CFC by chosen method.
@@ -29,10 +34,13 @@ def find_cfc(data,method_name,alpha=0.05,maxdelay=1,niter=50,thresh=0.25,isgauss
     """
 
     if method_name == 'TPC':
-        adjacency, weights = cfc_tpc(data,maxdelay=maxdelay,alpha=alpha,niter=niter,thresh=thresh,isgauss=isgauss)
+        adjacency, weights = cfc_tpc(
+            data, maxdelay=maxdelay, alpha=alpha, isgauss=isgauss,
+            subsampsize=subsampsize, niter=niter, thresh=thresh,
+        )
     elif method_name == 'PC':
         adjacency, weights = cfc_pc(data,alpha,isgauss=isgauss)
     elif method_name == 'GC':
-        from timeawarepc.gc import cfc_gc 
+        from timeawarepc.gc import cfc_gc
         adjacency, weights = cfc_gc(data,maxdelay,alpha)
     return adjacency,weights

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/timeawarepc/pcalg.py

@@ -419,16 +419,20 @@ def partial_corr(A,B,S,data):
     for i in range(p):
         if i in S:
             idx[i]=True
-    C=data
-    beta_A = linalg.lstsq(C[:,idx], C[:,A])[0]
-    beta_B = linalg.lstsq(C[:,idx], C[:,B])[0]
+    C = data
 
-    res_A = C[:,A] - C[:, idx].dot(beta_A)
-    res_B = C[:,B] - C[:, idx].dot(beta_B)
-    
-    p_corr = stats.pearsonr(res_A, res_B)[0]  
-    
-    return p_corr
+    # conditioning matrix: (n_samples, n_conditioning_vars)
+    # prepend a column of ones so lstsq fits an intercept -> shift-invariant
+    Z = C[:, idx]
+    Z = np.column_stack([np.ones(Z.shape[0]), Z])
+
+    beta_A = linalg.lstsq(Z, C[:, A])[0]
+    beta_B = linalg.lstsq(Z, C[:, B])[0]
+
+    res_A = C[:, A] - Z.dot(beta_A)
+    res_B = C[:, B] - Z.dot(beta_B)
+
+    return stats.pearsonr(res_A, res_B)[0]
 if __name__ == '__main__':
     import networkx as nx
     import numpy as np

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/timeawarepc/pcalg_helpers.py

@@ -43,13 +43,17 @@ def partial_corr(data,A,B,S):
     for i in range(p):
         if i in S:
             idx[i]=True
-    C=data
-    beta_A = linalg.lstsq(C[:,idx], C[:,A])[0]
-    beta_B = linalg.lstsq(C[:,idx], C[:,B])[0]
+    C = data
 
-    res_A = C[:,A] - C[:, idx].dot(beta_A)
-    res_B = C[:,B] - C[:, idx].dot(beta_B)
-    
-    p_corr = stats.pearsonr(res_A, res_B)[0]  
-    
-    return p_corr
+    # conditioning matrix: (n_samples, n_conditioning_vars)
+    # prepend a column of ones so lstsq fits an intercept -> shift-invariant
+    Z = C[:, idx]
+    Z = np.column_stack([np.ones(Z.shape[0]), Z])
+
+    beta_A = linalg.lstsq(Z, C[:, A])[0]
+    beta_B = linalg.lstsq(Z, C[:, B])[0]
+
+    res_A = C[:, A] - Z.dot(beta_A)
+    res_B = C[:, B] - Z.dot(beta_B)
+
+    return stats.pearsonr(res_A, res_B)[0]

timeawarepc-2.0.1/timeawarepc/tpc.py

@@ -0,0 +1,194 @@
+"""Implements the Time-Aware PC (TPC) Algorithm for finding Causal Functional Connectivity from Time Series.
+"""
+import time
+import numpy as np
+import pandas as pd
+from timeawarepc.tpc_helpers import *
+from timeawarepc.pcalg import estimate_skeleton, estimate_cpdag, ci_test_gauss
+import rpy2.robjects as robjects
+from rpy2.robjects.packages import importr
+import rpy2.rlike.container as rlc
+from rpy2.robjects import pandas2ri
+import random
+import networkx as nx
+import re
+import numpy as np
+import warnings
+import logging
+_logger = logging.getLogger(__name__)
+#%%
+def _run_pc_inner(sample, alpha, isgauss):
+    """Run PC on a single (sub)sample of time-delayed data, return CPDAG as nx.DiGraph."""
+    if not isgauss:
+        d = {'print.me': 'print_dot_me', 'print_me': 'print_uscore_me'}
+        kpcalg = importr('kpcalg', robject_translations=d)
+        sample_pd = pd.DataFrame(sample)
+        pandas2ri.activate()
+        df = robjects.conversion.py2rpy(sample_pd)
+        base = importr("base")
+        out = kpcalg.kpc(**{
+            'suffStat': rlc.TaggedList((df, "hsic.perm"), tags=('data', 'ic.method')),
+            'indepTest': kpcalg.kernelCItest,
+            'alpha': alpha,
+            'labels': sample_pd.columns.astype(str),
+            'u2pd': "relaxed",
+            'skel.method': "stable",
+            'verbose': robjects.r('F'),
+        })
+        dollar = base.__dict__["@"]
+        graphobj = dollar(out, "graph")
+        graph = importr("graph")
+        graphedges = graph.edges(graphobj)
+        graphedgespy = {int(key): np.array(re.findall(r'-?\d+\.?\d*', str(graphedges.rx2(str(key))))).astype(int)
+                        for key in graphedges.names}
+        g = nx.DiGraph(graphedgespy)
+    else:
+        (g, sep_set) = estimate_skeleton(indep_test_func=ci_test_gauss,
+                                         data_matrix=sample,
+                                         alpha=alpha, method='stable')
+        g = estimate_cpdag(skel_graph=g, sep_set=sep_set)
+    return g
+
+
+def cfc_tpc(data, maxdelay=1, alpha=0.1, isgauss=False,
+            subsampsize=None, niter=None, thresh=0.25):
+    """Estimate Causal Functional Connectivity using TPC Algorithm.
+
+    By default (subsampsize=None, niter=None), TPC runs PC once on the full
+    time-delayed data — no bootstrap subsampling. To enable bootstrap
+    subsampling for stability scoring, pass both `subsampsize` and `niter`.
+
+    Args:
+        data: (numpy.array) of shape (n,p) with n time-recordings for p nodes.
+        maxdelay: (int) Maximum time-delay of interactions.
+        alpha: (float) Significance level for conditional independence tests.
+        isgauss: (boolean)
+            True: Assume Gaussian Noise distribution.
+            False: Distribution-free.
+        subsampsize: (int, optional) Bootstrap window width. If None (default),
+            no bootstrap is performed and the full time-delayed data is used.
+            Must be specified together with `niter`.
+        niter: (int, optional) Number of bootstrap iterations. Must be specified
+            together with `subsampsize`. Ignored when subsampsize is None.
+        thresh: (float) Bootstrap stability cut-off. Only used when bootstrap
+            is active (both subsampsize and niter specified).
+
+    Returns:
+        adjacency: (numpy.array) Adjacency matrix of shape (p,p) for estimated CFC by TPC Algorithm.
+        weights: (numpy.array) Connectivity Weight matrix of shape (p,p).
+
+    Biswas, Rahul and Shlizerman, Eli (2022). Statistical perspective on functional and causal neural connectomics: the time-aware pc algorithm. arXiv preprint arXiv:2204.04845.
+    """
+    if (subsampsize is None) != (niter is None):
+        raise ValueError(
+            "subsampsize and niter must both be specified (for bootstrap) "
+            "or both be None (for no bootstrap)."
+        )
+    use_bootstrap = subsampsize is not None
+
+    start_time = time.time()
+    data_trans = data_transformed(data, maxdelay)  # Step 1: Time-Delayed Samples
+    _logger.debug("Data transformed in " + str(time.time() - start_time))
+
+    if not use_bootstrap:
+        # No-bootstrap path: run PC once on the full time-delayed data.
+        g = _run_pc_inner(data_trans, alpha, isgauss)
+        causaleff = causaleff_ida(g, data_trans)
+        G, causaleffin, _ = return_finaledges(g, causaleff, maxdelay, data.shape[1])
+        adjacency = np.asarray(G).copy()
+        weights = np.asarray(causaleffin, dtype=float)
+        # Step 8: Pruning (keep same magnitude-based pruning as bootstrap path)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=RuntimeWarning)
+            cutoff = np.nanmax(np.abs(weights)) / 10
+        adjacency[np.abs(weights) <= cutoff] = 0
+        return adjacency, weights
+
+    # Bootstrap path (legacy / stability-scored).
+    C_iter, C_cf_iter, C_cf2_iter = [], [], []
+    n = data_trans.shape[0]
+    if n - subsampsize <= 0:
+        raise ValueError(
+            f"subsampsize ({subsampsize}) must be smaller than the "
+            f"number of time-delayed samples ({n})."
+        )
+
+    for inneriter in range(niter):
+        start_btrstrp = time.time()
+        _logger.debug("Starting bootstrap " + str(inneriter))
+
+        # Step 2: Select random Bootstrap window
+        r_idx = random.sample(range(n - subsampsize), 1)[0]
+        sample = data_trans[r_idx:(r_idx + subsampsize), :]
+
+        # Step 3: PC
+        g = _run_pc_inner(sample, alpha, isgauss)
+
+        # Step 5: Rolled CFC-DPGM
+        causaleff = causaleff_ida(g, data_trans)
+        G, causaleffin, causaleffin2 = return_finaledges(g, causaleff, maxdelay, data.shape[1])
+
+        C_iter.append(G)
+        C_cf_iter.append(causaleffin)
+        C_cf2_iter.append(causaleffin2)
+        _logger.debug("Bootstrap done in " + str(time.time() - start_btrstrp))
+
+    # Step 6b-c: Robust Edges and Connectivity Weights
+    adjacency = (np.mean(np.asarray(C_iter), axis=0) >= thresh).astype(int)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", category=RuntimeWarning)
+        weights = np.nanmean(np.where(np.asarray(C_cf_iter) != 0,
+                                       np.asarray(C_cf_iter), np.nan), axis=0)
+    _logger.debug("CE shape " + str(weights.shape))
+
+    # Step 8: Pruning
+    adjacency[np.abs(weights) <= np.nanmax(np.abs(weights)) / 10] = 0
+
+    return adjacency, weights
+
+def cfc_pc(data,alpha,isgauss=False):
+    """Estimate Causal Functional Connectivity using PC Algorithm.
+
+    Args:
+        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:
+        adjacency: (numpy.array) Adcajency matrix of shape (p,p) of estimated CFC by PC Algorithm.
+        weights: (numpy.array) Connectivity Weight matrix of shape (p,p).
+
+    """
+    if not isgauss:
+        d = {'print.me': 'print_dot_me', 'print_me': 'print_uscore_me'}
+        kpcalg = importr('kpcalg', robject_translations = d)
+        data_trans_pd = pd.DataFrame(data)
+        pandas2ri.activate()
+        df = robjects.conversion.py2rpy(data_trans_pd)
+        out=kpcalg.kpc(**{'suffStat' : rlc.TaggedList((df,"hsic.perm"),tags=('data','ic.method')),#robjects.r('list(data=data_trans, ic.method="hsic.perm")'),#list(data=data_trans, ic.method="hsic.perm"),
+        'indepTest' : kpcalg.kernelCItest,
+        'alpha' : alpha,
+        'labels' : data_trans_pd.columns.astype(str),
+        'u2pd' : "relaxed",
+        'skel.method' : "stable",
+        'verbose' : robjects.r('F')})
+        base=importr("base")
+        dollar = base.__dict__["@"]
+        graphobj=dollar(out, "graph")
+        graph=importr("graph")
+        graphedges=graph.edges(graphobj)#, "matrix")
+        import re
+        graphedgespy={int(key): np.array(re.findall(r'-?\d+\.?\d*', str(graphedges.rx2(key)))[1:]).astype(int) for key in graphedges.names}
+        g=nx.DiGraph(graphedgespy)
+    else:
+        (g, sep_set) = estimate_skeleton(indep_test_func=ci_test_gauss,
+                                            data_matrix=data,
+                                            alpha=alpha,method='stable')
+        g = estimate_cpdag(skel_graph=g, sep_set=sep_set)
+
+    weights = causaleff_ida(g,data)
+    adjacency=nx.adjacency_matrix(g).toarray()
+    return adjacency, weights*adjacency
+# %%

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/timeawarepc/tutorial.py

@@ -44,9 +44,9 @@ alpha = 0.05
 isgauss = (model == 'lingauss')
 if method_name == 'TPC':
     maxdelay=1
-    niter = 50
-    thresh = 0.25
-    adjmat, causaleffmat = cfc_tpc(data,maxdelay=maxdelay,alpha=alpha,niter=niter,thresh=thresh,isgauss=isgauss)
+    # Default: no bootstrap, use full time-delayed data.
+    # To enable bootstrap stability scoring, pass subsampsize and niter together.
+    adjmat, causaleffmat = cfc_tpc(data, maxdelay=maxdelay, alpha=alpha, isgauss=isgauss)
 elif method_name == 'PC':
     adjmat, causaleffmat = cfc_pc(data,alpha,isgauss=isgauss)
 elif method_name == 'GC':

{timeawarepc-1.2.4 → timeawarepc-2.0.1/timeawarepc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timeawarepc
-Version: 1.2.4
+Version: 2.0.1
 Summary: Time-Aware PC Python Package
 Home-page: https://github.com/biswasr/TimeAwarePC
 Author: Rahul Biswas
@@ -15,7 +15,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: pandas
-Requires-Dist: rpy2==3.5.11
+Requires-Dist: rpy2>=3.5.11
 Requires-Dist: networkx
 Requires-Dist: scipy
 Dynamic: author
@@ -39,17 +39,25 @@ Dynamic: summary
 
 ## Installation
 
-You can get the latest version of TimeAwarePC as follows.
+### Recommended: conda environment (handles R + kpcalg automatically)
 
 ```
-$ pip install timeawarepc
+$ git clone https://github.com/shlizee/TimeAwarePC.git
+$ cd TimeAwarePC
+$ conda env create -f environment.yml
+$ conda activate timeawarepc
+$ Rscript install_r_deps.R   # installs kpcalg from CRAN archive
 ```
 
-## Requirements
-- Python == 3.10
-- Python packages automatically checked and installed as part of the setup. To use Granger Causality, additional dependency of ```nitime``` which can be installed by ```pip install nitime```.
-- R == 4.4.2
-- R package ```kpcalg``` and its dependencies. They can be installed in R or RStudio as follows:
+This installs Python, R, rpy2, all required R packages (graph, RBGL, pcalg), and TimeAwarePC v2.0.0 in a single isolated environment.
+
+### Manual install (alternative)
+
+If you prefer to install without conda:
+
+- Python >=3.9, <3.11
+- R >= 4.0
+- R package ```kpcalg``` and its dependencies, installed via R or RStudio:
 ```
 > install.packages("BiocManager")
 > BiocManager::install("graph")
@@ -57,10 +65,12 @@ $ pip install timeawarepc
 > install.packages("pcalg")
 > install.packages("https://cran.r-project.org/src/contrib/Archive/kpcalg/kpcalg_1.0.1.tar.gz")
 ```
-<!-- - In addition, if you like to use Granger Causality functions in this package, please separately install nitime as follows:
+- Then:
 ```
-pip install nitime
-``` -->
+$ pip install timeawarepc
+```
+
+To use Granger Causality, also install `nitime` (`pip install nitime`).
 
 ## Documentation
 
@@ -68,7 +78,15 @@ pip install nitime
 
 ## Tutorial
 
-See the [Quick Start Guide](https://timeawarepc.readthedocs.io/en/latest/gettingstarted.html) for a quick tutorial of the main functionalities of this library and check if it is installed properly. 
+See the [Quick Start Guide](https://timeawarepc.readthedocs.io/en/latest/gettingstarted.html) for a quick tutorial of the main functionalities of this library and check if it is installed properly.
+
+## What's new in v2.0.0
+
+- `cfc_tpc` now defaults to **no bootstrap subsampling**: a single PC run is performed on the full time-delayed data.
+  - To use bootstrap stability scoring, pass `subsampsize` and `niter` together (e.g., `subsampsize=50, niter=25`).
+  - Both arguments must be specified together (or both left as the default `None`).
+- `partial_corr` now fits an intercept and is shift-invariant. Previously the regression was forced through the origin, biasing residuals when the data was not mean-centered.
+- See [CHANGELOG.md](CHANGELOG.md) for the full list of changes and migration notes.
 <!-- 
 ## Documentation
 
@@ -80,7 +98,7 @@ Your help is absolutely welcome! Please do reach out or create a feature branch!
 
 ## Citation
 
-Biswas, R., & Shlizerman, E. (2022). Statistical Perspective on Functional and Causal Neural Connectomics: The Time-Aware PC Algorithm. https://arxiv.org/abs/2204.04845
+Biswas, R., & Shlizerman, E. (2022). Statistical Perspective on Functional and Causal Neural Connectomics: The Time-Aware PC Algorithm. https://doi.org/10.1371/journal.pcbi.1010653
 
 Biswas, R., & Shlizerman, E. (2021). Statistical Perspective on Functional and Causal Neural Connectomics: A Comparative Study. Frontiers in Systems Neuroscience. https://doi.org/10.3389/fnsys.2022.817962
 

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/timeawarepc.egg-info/SOURCES.txt

@@ -3,6 +3,8 @@ README.md
 pyproject.toml
 setup.cfg
 setup.py
+test/test_optional_bootstrap.py
+test/test_partial_corr_shift_invariance.py
 timeawarepc/__init__.py
 timeawarepc/find_cfc.py
 timeawarepc/gc.py

{timeawarepc-1.2.4 → timeawarepc-2.0.1}/timeawarepc.egg-info/requires.txt

@@ -1,5 +1,5 @@
 numpy
 pandas
-rpy2==3.5.11
+rpy2>=3.5.11
 networkx
 scipy

timeawarepc-1.2.4/timeawarepc/tpc.py

@@ -1,155 +0,0 @@
-"""Implements the Time-Aware PC (TPC) Algorithm for finding Causal Functional Connectivity from Time Series.
-"""
-import time
-import numpy as np
-import pandas as pd
-from timeawarepc.tpc_helpers import *
-from timeawarepc.pcalg import estimate_skeleton, estimate_cpdag, ci_test_gauss
-import rpy2.robjects as robjects
-from rpy2.robjects.packages import importr
-import rpy2.rlike.container as rlc
-from rpy2.robjects import pandas2ri
-import random
-import networkx as nx
-import re
-import numpy as np
-import warnings
-import logging
-_logger = logging.getLogger(__name__)
-#%%
-def cfc_tpc(data,maxdelay=1,subsampsize=50,niter=25,alpha=0.1,thresh=0.25,isgauss=False):
-    """Estimate Causal Functional Connectivity using TPC Algorithm.
-
-    Args:
-        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:
-        adjacency: (numpy.array) Adcajency matrix of shape (p,p) for estimated CFC by TPC Algorithm.
-        weights: (numpy.array) Connectivity Weight matrix of shape (p,p).
-
-    Biswas, Rahul and Shlizerman, Eli (2022). Statistical perspective on functional and causal neural connectomics: the time-aware pc algorithm. arXiv preprint arXiv:2204.04845.
-    """
-    C_iter=[]
-    C_cf_iter=[]
-    C_cf2_iter=[]
-    start_time = time.time()
-    data_trans = data_transformed(data, maxdelay)#Step 1: Time-Delayed Samples
-    _logger.debug("Data transformed in "+str(time.time()-start_time))
-
-    #Steps 2-6a:
-    for inneriter in range(niter):
-        start_btrstrp = time.time()
-        _logger.debug("Starting bootstrap "+str(inneriter))
-        n=data_trans.shape[0]
-
-        #Step 2: Select random Bootstrap window
-        r_idx = random.sample(range(n-subsampsize),1)[0]
-        
-        #Step 3: PC
-        if not isgauss:
-            d = {'print.me': 'print_dot_me', 'print_me': 'print_uscore_me'}
-            kpcalg = importr('kpcalg', robject_translations = d)
-            data_trans_pd=pd.DataFrame(data_trans[r_idx:(r_idx+subsampsize),:])
-            pandas2ri.activate()
-            df = robjects.conversion.py2rpy(data_trans_pd)
-            base=importr("base")
-            out=kpcalg.kpc(**{'suffStat' : rlc.TaggedList((df,"hsic.perm"),tags=('data','ic.method')),
-            'indepTest' : kpcalg.kernelCItest,
-            'alpha' : alpha,
-            'labels' : data_trans_pd.columns.astype(str),
-            'u2pd' : "relaxed",
-            'skel.method' : "stable",
-            'verbose' : robjects.r('F')})
-            dollar = base.__dict__["@"]
-            graphobj=dollar(out, "graph")
-            graph=importr("graph")
-            graphedges=graph.edges(graphobj)#, "matrix")
-            graphedgespy={int(key): np.array(re.findall(r'-?\d+\.?\d*', str(graphedges.rx2(str(key))))).astype(int) for key in graphedges.names}
-            g=nx.DiGraph(graphedgespy)
-        else:
-            data_trans_pd=data_trans[r_idx:(r_idx+subsampsize),:]
-            (g, sep_set) = estimate_skeleton(indep_test_func=ci_test_gauss,
-                                                data_matrix=data_trans_pd,
-                                                alpha=alpha,method='stable')
-            g = estimate_cpdag(skel_graph=g, sep_set=sep_set)
-        
-        #Step 4: Orient - update: not needed
-        #g=orient(g,maxdelay,data.shape[1])
-
-        #Step 5: Rolled CFC-DPGM
-        causaleff = causaleff_ida(g,data_trans)#Interventional Causal Effects in Unrolled DAG
-        G,causaleffin, causaleffin2=return_finaledges(g,causaleff,maxdelay,data.shape[1])#Rolled CFC-DPGM
-        
-        A_rr=G
-        C_iter.append(A_rr)
-        C_cf_iter.append(causaleffin)
-        C_cf2_iter.append(causaleffin2)
-        _logger.debug("Bootstrap done in "+str(time.time()-start_btrstrp))
-        #Step 6a: Repeat Steps 2-5    
-
-    #Step 6b-c: Robust Edges and Connectivity Weights
-    adjacency=(np.mean(np.asarray(C_iter),axis=0)>=thresh).astype(int)#Robust Edges
-    with warnings.catch_warnings():
-        warnings.simplefilter("ignore", category=RuntimeWarning)
-        weights=np.nanmean(np.where(np.asarray(C_cf_iter)!=0,np.asarray(C_cf_iter),np.nan),axis=0)#Robust Connectivity Weights
-    _logger.debug("CE shape "+str(weights.shape))
-
-    #Step 8: Pruning
-    adjacency[np.abs(weights) <= np.nanmax(np.abs(weights))/10]=0
-
-    return adjacency, weights
-
-def cfc_pc(data,alpha,isgauss=False):
-    """Estimate Causal Functional Connectivity using PC Algorithm.
-
-    Args:
-        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:
-        adjacency: (numpy.array) Adcajency matrix of shape (p,p) of estimated CFC by PC Algorithm.
-        weights: (numpy.array) Connectivity Weight matrix of shape (p,p).
-
-    """
-    if not isgauss:
-        d = {'print.me': 'print_dot_me', 'print_me': 'print_uscore_me'}
-        kpcalg = importr('kpcalg', robject_translations = d)
-        data_trans_pd = pd.DataFrame(data)
-        pandas2ri.activate()
-        df = robjects.conversion.py2rpy(data_trans_pd)
-        out=kpcalg.kpc(**{'suffStat' : rlc.TaggedList((df,"hsic.perm"),tags=('data','ic.method')),#robjects.r('list(data=data_trans, ic.method="hsic.perm")'),#list(data=data_trans, ic.method="hsic.perm"),
-        'indepTest' : kpcalg.kernelCItest,
-        'alpha' : alpha,
-        'labels' : data_trans_pd.columns.astype(str),
-        'u2pd' : "relaxed",
-        'skel.method' : "stable",
-        'verbose' : robjects.r('F')})
-        base=importr("base")
-        dollar = base.__dict__["@"]
-        graphobj=dollar(out, "graph")
-        graph=importr("graph")
-        graphedges=graph.edges(graphobj)#, "matrix")
-        import re
-        graphedgespy={int(key): np.array(re.findall(r'-?\d+\.?\d*', str(graphedges.rx2(key)))[1:]).astype(int) for key in graphedges.names}
-        g=nx.DiGraph(graphedgespy)
-    else:
-        (g, sep_set) = estimate_skeleton(indep_test_func=ci_test_gauss,
-                                            data_matrix=data,
-                                            alpha=alpha,method='stable')
-        g = estimate_cpdag(skel_graph=g, sep_set=sep_set)
-
-    weights = causaleff_ida(g,data)
-    adjacency=nx.adjacency_matrix(g).toarray()
-    return adjacency, weights*adjacency
-# %%