Composable Causality: A Toolkit for Systematic Time-Series Causal Discovery and Treatment-Effect Benchmarking

Muhammad Hasan Ferdous; Md Osman Gani

cs.LGNov 6, 2026

Composable Causality: A Toolkit for Systematic Time-Series Causal Discovery and Treatment-Effect Benchmarking

Authors: Muhammad Hasan Ferdous, Md Osman Gani

Organizations: Causal AI Lab, Department of Information Systems, University of Maryland, Baltimore County

Abstract

Real-world multivariate time series rarely come with verified ground-truth causal structure, so research on time-series causal discovery and treatment-effect estimation depends on synthetic data. Existing tools are either fixed datasets that cannot be modified after release or script-based generators in which each script fixes one combination of mechanism, confounding, and missingness. Neither supports controlled experiments that vary a single property, such as sparsity, noise distribution, or missingness mechanism, while holding the others fixed. Counterfactual evaluation has the same gap, since existing simulators are built per paper with hardcoded mechanisms or produce observational data only. We introduce DTCD (Datasets and Toolkit for Causal Discovery), a data generation library that produces multivariate time series with ground-truth contemporaneous and lagged adjacency matrices. Topology, mechanism, noise, observational mask, and intervention policy are independent components that compose through configuration alone. Paired counterfactual twins, produced by caching the stochastic realization during the factual rollout and re-injecting it during the interventional rollout, recover individual treatment effects to numerical precision. A reference benchmark of eight discovery algorithms on eighty-one configurations and four treatment-effect estimators on eighteen configurations exposes failure modes that aggregate metrics hide. These include the inability of standard discovery methods to handle missing values, regardless of whether the missingness mechanism is informative, and a marginal-variance shortcut (varsortability) that we measure and remove by standardization. Code and data: https://github.com/hferdous/Composable_Causality

Figures & tables

Panel of Figure 1 — Figure 1: Compositional structure of DTCD . Five independent configuration axes feed one structural rollout, which emits the trajectory, the ground-truth adjacencies, the observation mask, and, when an intervention policy is supplied, an exactly paired counterfactual twin via re-injection of the cached noise $\mathbf{N}$ . Varying one axis holds all others fixed by construction.

	Linear			Nonlinear
	SHD	TPR	FDR	SHD	TPR	FDR
DYNOTEARS	0.02 $\pm$ 0.05	1.00 $\pm$ 0.02	0.01 $\pm$ 0.04	0.02 $\pm$ 0.05	0.99 $\pm$ 0.03	0.01 $\pm$ 0.03
PCMCI_GPDC	0.38 $\pm$ 0.17	0.67 $\pm$ 0.12	0.05 $\pm$ 0.11	0.41 $\pm$ 0.15	0.67 $\pm$ 0.12	0.07 $\pm$ 0.13
VARLiNGAM	0.52 $\pm$ 0.40	0.80 $\pm$ 0.17	0.27 $\pm$ 0.20	0.50 $\pm$ 0.41	0.79 $\pm$ 0.22	0.25 $\pm$ 0.20
VARLiNGAM_imp	0.52 $\pm$ 0.40	0.80 $\pm$ 0.17	0.27 $\pm$ 0.20	0.50 $\pm$ 0.41	0.79 $\pm$ 0.22	0.25 $\pm$ 0.20
PCMCI_ParCorr	0.45 $\pm$ 0.14	0.65 $\pm$ 0.07	0.12 $\pm$ 0.13	0.42 $\pm$ 0.12	0.65 $\pm$ 0.07	0.08 $\pm$ 0.10

Table 1: Causal discovery performance on Linear and Nonlinear DGP variants. Mean (

\pm

std) over 90 runs per cell (9 graphs

\times

10 seeds), filtered to status=ok rows. Lower SHD and FDR are better; higher TPR is better. Bold marks the best value in each column. PCMCI-GPDC values reflect

d{=}4

cells only (

n{=}30

versus

n{=}90

for other methods). Performance on Drift is within 0.08 SHD of Linear for every method; full results in Appendix H .

	MNAR			MCAR
	SHD	TPR	FDR	SHD	TPR	FDR
VARLiNGAM_imp	0.96 $\pm$ 0.37	0.52 $\pm$ 0.26	0.47 $\pm$ 0.23	0.79 $\pm$ 0.43	0.64 $\pm$ 0.26	0.40 $\pm$ 0.24
CUTS+	0.94 $\pm$ 0.45	0.73 $\pm$ 0.18	0.42 $\pm$ 0.16	0.67 $\pm$ 0.43	0.94 $\pm$ 0.10	0.35 $\pm$ 0.13

Table 2: Causal discovery performance on missingness DGP variants. Only the two methods declaring supports_missing=True are shown; the remaining six methods were skipped on these variants (see Appendix I ). Bold marks the best value in each column.

	CATE Linear		CATE Nonlinear
	PEHE	Runtime (s)	PEHE	Runtime (s)
TARNet	0.491 $\pm$ 0.173	1.639 $\pm$ 0.349	0.427 $\pm$ 0.135	1.639 $\pm$ 0.351
SNet	0.674 $\pm$ 0.220	11.571 $\pm$ 1.436	0.509 $\pm$ 0.129	12.444 $\pm$ 1.988
FlexTENet	0.663 $\pm$ 0.201	6.385 $\pm$ 1.244	0.518 $\pm$ 0.129	6.636 $\pm$ 1.302
X-Learner	0.757 $\pm$ 0.155	1.380 $\pm$ 0.078	0.617 $\pm$ 0.129	1.374 $\pm$ 0.078

Table 3: CATE estimator performance aggregated by DGP variant. Mean (

\pm

std) over 90 runs per cell (9 graphs

\times

10 seeds). PEHE: Precision in Estimation of Heterogeneous Effects; lower is better. Runtime is wall-clock per fit, measured under four parallel processes (Appendix L ); compare ratios only.

Appendix figures & tables18 assets

Supplementary material from the paper’s appendix.

Appendix

Parameter	Value	Variant
Trajectory length $T$	1000	all
Within-graph variables $d$	$\{4,6,8\}$	all
Maximum lag $\tau_{\max}$	$\{2,3,4\}$	all
Edges per graph	$\approx d$ (sparsity calibrated)	all
Innovation distribution	Gaussian, $\mathcal{N}(0,1)$ , homoscedastic	all
Structural weight magnitude	$\sim\mathcal{U}(0.3,0.8)\cdot\pm 1$	all

Appendix

Table 4: DGP parameters fixed across the reference benchmark (referenced from Section 4 ). The "Variant" column lists where each parameter applies; "all" indicates the parameter is shared by every DGP variant. "T+S" abbreviates "Trend+Seasonal"; "N+T+S" abbreviates "Nonlinear+Trend+Seasonal".

Figure 2: Generated trajectories for graph d4_tau2 at seed 42 under four DGP variants (

T{=}400

shown for legibility). Graph, weights and noise realization are identical across panels; only the varied axis differs. Red ticks in the rightmost panel mark entries censored by the MNAR mask on

X_{1}

Figure 3: Ground-truth window graphs for the nine reference templates (rows

d

, columns

\tau_{\max}

). Solid black arrows are contemporaneous edges; dashed arrows are lagged edges, colored and labeled by their lag

\tau

. Green and red outlines mark the treatment and outcome nodes used by the CATE variants. Sparsity is held at

\approx d

edges per graph.

Figure 4: Recovered window graph beside ground truth for d4_tau2 , linear variant, seed 42, identical hyperparameters. Rows are candidate parents across the lag window, columns are targets at time

t

; crosses mark spurious edges and open boxes mark missed edges. DYNOTEARS recovers the graph exactly on raw data and misplaces a majority of edges once the marginal-variance ordering is removed.

Figure 5: Left: contemporaneous varsortability per graph, raw versus standardized. Right: oriented F1 (nine graphs, ten seeds, fixed hyperparameters and DGP); annotations give the F1 lost to standardization.

Condition	$v$	DYNOTEARS	SortnRegress	RandomRegress
Raw (as shipped)	0.93	0.99	0.93	0.79
Standardized	0.50	0.82	0.81	0.79
$\Delta$	$-0.43$	$-0.17$	$-0.12$	$0.00$

Appendix

Table 5: Varsortability audit on the linear reference benchmark; oriented F1 over nine graphs

\times

ten seeds with hyperparameters, weights and noise realizations fixed across conditions. SortnRegress and RandomRegress are controls, not discovery methods. The DYNOTEARS settings come from an earlier tuning run of the same protocol and were not recomputed after the final reference run.

Method	Hyperparameter	Search Space	Notes
VARLiNGAM	none	—	Nothing tuned
VARLiNGAM_imp	none	—	Mean imputation pre-fit; not tuned
PCMCI-ParCorr	pc_alpha	{0.001, 0.01, 0.05}
PCMCI-GPDC	pc_alpha	{0.001, 0.01, 0.05}	5 trials per cell; $d=4$ only
DYNOTEARS	lambda_w	log-uniform $[10^{-3},1]$	5 trials per cell
	lambda_a	log-uniform $[10^{-3},1]$

Appendix

Table 6: Hyperparameter search spaces per method.

	Precision	Recall	F1
DYNOTEARS	0.99	1.00	0.99
PCMCI_GPDC	0.95	0.67	0.78
VARLiNGAM	0.73	0.80	0.76
VARLiNGAM_imp	0.73	0.80	0.76
PCMCI_ParCorr	0.88	0.65	0.74
CUTS+	0.64	0.87	0.74

Appendix

Table 7: Precision and recall decomposition on Linear DGP. Mean over 90 runs per method.

	SHD			Runtime (s)
d	4	6	8	4	6	8
CDNOD	1.00	1.03	1.06	0.01	0.01	0.02
CUTS+	0.67	0.36	0.40	0.06	0.06	0.06
DYNOTEARS	0.00	0.02	0.03	0.15	0.41	0.59
GrangerF	1.75	1.78	1.97	0.02	0.04	0.07
PCMCI_GPDC	0.38	-	-	41.78	-	-

Appendix

Table 8: Performance breakdown by graph dimension on Linear DGP. Mean (

\pm

std) over 30 runs per cell (3

\tau

configurations

\times

10 seeds), filtered to status=ok . PCMCI-GPDC at

d\in\{6,8\}

was excluded by the compute-budget skip.

	PEHE
	d=4	d=6	d=8
TARNet	0.440 $\pm$ 0.222	0.594 $\pm$ 0.127	0.438 $\pm$ 0.097
SNet	0.458 $\pm$ 0.218	0.750 $\pm$ 0.143	0.814 $\pm$ 0.076
FlexTENet	0.478 $\pm$ 0.215	0.753 $\pm$ 0.132	0.756 $\pm$ 0.091
X-Learner	0.841 $\pm$ 0.155	0.820 $\pm$ 0.112	0.611 $\pm$ 0.060

Appendix

Table 9: CATE performance by dimension on Linear DGP. Mean (

\pm

std) over 30 runs per cell (3

\tau

configurations

\times

10 seeds).

Mechanism	Property	SHD ( $\downarrow$ )	F1 ( $\uparrow$ )
Linear ( $x$ )	identity	$0.10\pm 0.30$	$0.99\pm 0.02$
Nonlinear ( $\text{sign}(x)\|x\|^{0.5}$ )	monotonic, saturating	$0.11\pm 0.38$	$0.99\pm 0.03$
Non-monotonic ( $\sin x$ )	non-monotonic, bounded	$1.14\pm 1.32$	$0.88\pm 0.15$

Appendix

Table 10: DYNOTEARS performance under different recursive nonlinear mechanisms. Mean (

\pm

std) over 90 cells per mechanism (nine graphs

\times

ten seeds). Hyperparameters held fixed at each graph’s Nonlinear-cell tuning.

	Drift
	SHD	TPR	FDR
DYNOTEARS	0.04 $\pm$ 0.07	0.98 $\pm$ 0.05	0.01 $\pm$ 0.04
PCMCI_GPDC	0.38 $\pm$ 0.17	0.67 $\pm$ 0.12	0.06 $\pm$ 0.12
VARLiNGAM	0.51 $\pm$ 0.36	0.81 $\pm$ 0.14	0.27 $\pm$ 0.17
VARLiNGAM_imp	0.51 $\pm$ 0.36	0.81 $\pm$ 0.14	0.26 $\pm$ 0.17
PCMCI_ParCorr	0.45 $\pm$ 0.16	0.65 $\pm$ 0.07	0.12 $\pm$ 0.13

Appendix

Table 11: Causal discovery performance on Drift DGP. Mean (

\pm

std) over 90 runs per cell.

	Completed	Skipped (no missing support)	Skipped (compute budget)
CDNOD	630	180	0
CUTS+	810	0	0
DYNOTEARS	630	180	0
GrangerF	630	180	0
PCMCI_GPDC	210	60	540
PCMCI_ParCorr	630	180	0

Appendix

Table 12: Aggregate failure mode counts by method, summed across all nine DGP variants.

status	Completed	Total attempted
Linear	90	90
Nonlinear	90	90
Drift	90	90
Trend	90	90
Seasonal	90	90
Trend+Seasonal	90	90

Appendix

Table 13: VARLiNGAM_imp completion vs. error counts by DGP variant, after the wrapper fix. Each variant has 90 attempted runs (9 graphs

\times

10 seeds).

		DYNOTEARS F1		SortnRegress F1		DYNOTEARS
$d$	$T$	raw	std.	raw	std.	runtime (s)
4	1000	1.00	1.00	0.70	0.85	0.2
4	5000	1.00	1.00	0.70	0.55	0.3
4	10000	1.00	1.00	0.55	0.85	0.4
8	1000	1.00	0.82	0.70	0.75	0.3
8	5000	1.00	0.82	0.74	0.71	0.6

Appendix

Table 14: Scalability sweep at

\tau_{\max}{=}3

, three seeds per cell (one seed at

d{=}32,T{=}10000

). “std.” is the variance-standardized condition of Section 4.3 . Runtime is single-core wall clock for the raw condition.

DYNOTEARS $F_{1}$ (std.)	$d{=}4$	$d{=}8$	$d{=}16$	$d{=}32$
$\tau_{\max}{=}3$	1.00	0.94	0.92	0.98
$\tau_{\max}{=}6$	1.00	0.96	0.95	0.91
$\tau_{\max}{=}12$	1.00	1.00	0.97	0.98

Appendix

Table 15: Standardized-condition

F_{1}

of the leading method across the full grid, mean over

T

and three seeds. The minimum over all twelve

(d,\tau_{\max})

cells is

0.91

: once the variance shortcut is removed, accuracy does not degrade with dimension, trajectory length, or lag order.

Seconds per fit, $d{=}32$	$\tau_{\max}{=}3$	$\tau_{\max}{=}6$	$\tau_{\max}{=}12$
DYNOTEARS	5	9	16
VARLiNGAM	25	24	21
PCMCI-ParCorr	22	47	118
GrangerF	14	45	187

Appendix

Table 16: Mean seconds per fit at the largest dimension (

d{=}32

, raw condition; standardized is comparable). The binding runtime constraint shifts with lag order: VARLiNGAM is flat in

\tau_{\max}

and binds at

\tau_{\max}{=}3

, PCMCI-ParCorr grows roughly linearly in the window and binds at

\tau_{\max}{=}6

, and GrangerF grows fastest and binds at

\tau_{\max}{=}12

	full ( $v{=}1.00$ )		seasonal ( $v{=}0.56$ )		mechanism ( $v{=}0.25$ )
Method	raw	std.	raw	std.	raw	std.
DYNOTEARS †	0.13	0.19	0.21	0.24	0.00	0.49
SortnRegress	0.14	0.11	0.11	0.09	0.51	0.48
RandomRegress	0.11	0.11	0.10	0.10	0.44	0.44
VARLiNGAM	0.11	0.11	0.09	0.09	0.44	0.44
GrangerF	0.06	0.06	0.09	0.09	0.30	0.30

Appendix

Table 17: Mean oriented

F_{1}

on the TimeGraph C1 family (nine configurations, two seeds), with contemporaneous varsortability

v

per variant. † DYNOTEARS is oracle-tuned on a held-out seed in the full and seasonal variants and runs at library defaults in the mechanism variant; all other methods run at library defaults throughout. For reference, tuned DYNOTEARS reaches

0.99

(raw) on the linear reference family of Section 4.3 .

Time-Series Causal Discovery

Time-series causal discovery seeks to infer which variables influence others over time and when those effects occur.

See all 70 papers

Jul 27, 2026

Causal-TS: A Python Library for Causal Discovery in High-Dimensional and Nonstationary Time Series

We describe Causal-TS, an open-source Python library for causal discovery in high-dimensional and nonstationary multivariate time series. Causal-TS provides four specialized algorithms-CDNOTS, CDNOTS+, CEDAR, and GRACE-along with wrappers for GES, Granger, LASSO-VAR, and LGES, all sharing a unified conditional independence (CI) test layer with GPU acceleration via PyTorch. A regime discovery pipeline detects structural breaks via pluggable changepoint detectors and runs discovery per regime with regime-specific parameters. A command-line interface, synthetic data generators, and optional DoWhy integration provide an end-to-end pipeline from raw time series to causal effect estimates. The library is pip-installable, tested on Python 3.10--3.12, and available at https://github.com/bloomberg/causal-ts.

Mohammad Fesanghary

Bloomberg LP, New York, NY, USA

Time-Series Causal Discovery Causal Discovery Causal Inference Conditional Independence Testing

Ask PDF

Jul 29, 2026

DoTime: A Synthetic Benchmark Generator for Interventional and Counterfactual Time Series

Most benchmarks for causal inference over time series are observational, small, or domain-specific, leaving interventional and counterfactual estimation under-served exactly where it matters most, such as in healthcare, policy evaluation, and climate science. We introduce DoTime, an open, scalable, and theoretically grounded generator of multivariate temporal structural causal models (TSCMs) with interventions, released as the \code{dotime} PyPI package together with four frozen evaluation suites. Beyond existing work, it adds capabilities absent from prior generators: continuous-time intervention windows, counterfactual sampling modes with a positivity guard, regime-switching SCMs as a strict generalization of interrupted time series, non-stationary dynamics by construction with switching SCM parameters, and deterministic ramp and sinusoidal intervention profiles that place trends and structural breaks inside the evaluation window. Moreover, it demonstrates the suitability of the generator as a prior for a causal foundation model reference implementation. The released suites span a training-scale snapshot of

100{,}000

trajectories and eight named identification structures, each with exact ground truth: paired interventional trajectories from the same SCM throughout, and shared-noise counterfactuals in the continuous-time suite. We ship reference baseline implementations with an evaluation harness, and pose a falsifiable claim: interventional training buys a measurable direction-accuracy advantage over an observational model of identical capacity. It is tested across three training seeds per arm. Under structure-matched evaluation on held-out episodes, the interventional prior-fitted network's (PFN) gap is positive in every structure, trajectory length, and seed tested.

Dennis Thumm, Billy Tim Anthony, Ying Chen

National University of Singapore, Singapore, Singapore

Counterfactual Evaluation Structural Causal Models Time-Series Causal Discovery Causal Counterfactual Generation Synthetic Benchmark Generation Causal Intervention

Ask PDF

Oct 9, 2026

One Thing Leads to Another: The Essentials of Time Series Causal Discovery

Time series causal discovery --- the process of detecting causation between time series --- has its roots in signal processing research from over a half century ago. It has since received active and widespread interest, evolving into different forms across domains such as statistics, dynamical systems and machine learning. Entering this fragmented and constantly evolving research landscape can be daunting. This tutorial provides a unified overview of time series causal discovery across research communities. We introduce the key principles invoked by modern discovery methods, and we discuss their limitations and assumptions. We also discuss how discovery methods are evaluated, benchmarked and fine-tuned. We further discuss how causal discovery for time series is becoming crucial for downstream tasks in agriculture and Earth science, in healthcare, and in artificial intelligence systems. We believe that this tutorial will serve as a valuable resource in navigating the deluge of recent causality research, as well as an invitation to signal processing audiences to contribute to causal problems. To further help readers, we host a companion repository to link to useful code packages and resources at https://github.com/CHAI-UK/Awesome-Time-Series-Causal-Discovery.

Kurt Butler, Damian Machlanski, Michael P. J. Camilleri +5

School of Engineering, The University of Edinburgh, and the Causality in Healthcare AI Hub (CHAI) · School of Informatics, The University of Edinburgh and CHAI · Department of Statistical Science, University College London, and CHAI

Time-Series Causal Discovery Causal Discovery Causal Inference Causal Structure Learning

Ask PDF

Abstract

Time-Series Causal Discovery

Explore similar work

Causal-TS: A Python Library for Causal Discovery in High-Dimensional and Nonstationary Time Series

DoTime: A Synthetic Benchmark Generator for Interventional and Counterfactual Time Series

One Thing Leads to Another: The Essentials of Time Series Causal Discovery