This is the repository for KarmaTS paper, which has been published in ML4H 2025. Full text of the paper can be found here.

Graphical-TS is a Python package for simulating multivariate time series data with an underlying graphical causal structure. Developed by the SCAI Lab, it provides a flexible framework for generating synthetic time series data with full control over causal relationships, edge functions, and temporal dependencies.

pip install graphical-ts

Requirements:

• Python >= 3.6
• NumPy >= 1.21
• SciPy >= 1.7
• NetworkX >= 2.6
• Matplotlib >= 3.4
• Pandas >= 1.3

• Build causal graphs with time-lagged edges
• Support for multiple edge types and lag structures
• NetworkX integration for graph manipulation

• Define how parent nodes affect child nodes
• Pre-defined function gallery (linear, nonlinear, MLP-based)
• Support for custom PyTorch neural networks
• Multiple architectures: MLP, VAE, Transformer, Diffusion models

• Independent signal components for each node
• Pre-defined signals (Bessel processes, discrete signals, etc.)
• Custom signal generation support

• ExpertSim: Integrate domain knowledge into graph structure
• NeuralExpertSim: Learn edge functions from real data using neural networks
• Support for fMRI/neuroimaging data fusion

• Missing Not At Random (MNAR) data generation
• Missing data mechanisms with graphical structure
• MDGCM class for missing data scenarios

• Combine expert knowledge graphs with real-world time series
• Learn functional relationships from observed data
• Generate augmented synthetic data preserving statistical properties

• Graph visualization with temporal structure
• Time series plotting utilities
• Interactive graph editing interface

The examples/ directory contains comprehensive tutorials demonstrating different use cases:

• Purpose: Introduction to building dynamic graphs
• Key Concepts:
  • Creating graph structures with lagged edges
  • Defining parent-child relationships
  • Basic simulation workflow
• Use Case: Learn the fundamental graph structure format

• Purpose: Demonstrate expert-driven graph construction
• Key Concepts:
  • Using ExpertSim for domain knowledge integration
  • Assigning signal functions to nodes
  • Defining edge relationships with expert knowledge
• Use Case: Build graphs when you have domain expertise

• Purpose: Generate synthetic data with random neural network edge functions
• Key Concepts:
  • Using RandomMLPExpertSim for automatic edge function generation
  • Creating complex nonlinear relationships
  • Large-scale graph simulation
• Use Case: Generate diverse synthetic datasets for benchmarking

• Purpose: Interactive workflow for creating and validating graph structures
• Key Concepts:
  • Interactive graph editing and visualization
  • Real-time simulation and validation
  • Graph variation generation (tree, star, cycle structures)
  • Parameter exploration (lag sizes, edge density)
• Use Case: Explore different graph topologies and validate simulation quality

• Purpose: Generate Missing Not At Random (MNAR) data with graphical structure
• Key Concepts:
  • Using MExpertSim for missing data scenarios
  • Defining missingness mechanisms
  • Continuous and discrete variable handling
• Use Case: Simulate realistic missing data patterns for method evaluation

• Purpose: Systematic comparison between real and synthetic time series
• Key Concepts:
  • Evaluating synthetic data quality
  • Downstream task performance (classification)
  • Graph/connectivity similarity metrics
  • Statistical property matching
• Use Case: Validate synthetic data quality for real-world applications

• Purpose: Integrate fMRI data with expert knowledge graphs
• Key Concepts:
  • Loading and preprocessing fMRI data (nilearn integration)
  • Learning edge functions from real fMRI time series
  • Generating synthetic fMRI data preserving connectivity
  • Network metrics comparison
• Use Case: Generate synthetic neuroimaging data for research

• Purpose: Detailed tutorial on MNAR data generation
• Key Concepts:
  • Missing data mechanisms in graphical models
  • Enabling missingness for specific nodes
  • Missing data pattern visualization
• Use Case: Study missing data mechanisms and imputation methods

• Purpose: Free-form experimentation with the package
• Use Case: Custom experiments and method development

• Purpose: Command-line tool for generating multiple datasets
• Features:
  • Configurable graph parameters (nodes, edges, parents)
  • Quality checking and validation
  • Batch processing with parameter sweeps
• Usage:

  python data_generation.py --N_GEN 10 --TRY_MAX 5 --PATH ./output --gen_params_path config.yaml

from graph_ts import DGCM, DynGraph # Define a graph structure graph = { "A": {0: ["B", "C"]}, # A affects B and C at lag 0 "B": {1: ["C"], 6: ["B"]}, # B affects C at lag 1, self-loop at lag 6 "C": {2: ["A"]} # C affects A at lag 2 } # Create dynamic graph dyn_graph = DynGraph(out_graph=graph) # Simulate time series data = dyn_graph.simulate_process(T=1000)

from graph_ts import ExpertSim, SignalFunction # Create expert simulation expert = ExpertSim() # Add nodes expert.add_node('A', type='continuous') expert.add_node('B', type='continuous') # Assign signal function (independent component) expert.assign_node_with_fn('A', SignalFunction.bessel_process_signal()) # Add edge with custom function expert.add_edge('A', 'B', lag=1, input_len=10) # Simulate data = expert.simulate_process(T=1000)

from graph_ts.simulation.expert_augmentation import NeuralExpertSim, TSFDataset from graph_ts.mapping.torch_nets import SimpleFunctionalNet # Load real data dataset = TSFDataset(real_data, graph_structure) # Create neural expert simulator neural_expert = NeuralExpertSim( graph=graph_structure, edge_function_template=SimpleFunctionalNet, in_dim=(10, 5), # (sequence_length, num_parents) out_dim=1 ) # Train on real data neural_expert.fit(dataset) # Generate synthetic data synthetic_data = neural_expert.simulate(T=1000)

• DynGraph: Base dynamic graph structure (NetworkX MultiDiGraph)
• DGCM: Dynamic Graph Causal Model with simulation capabilities
• ExpertSim: Expert knowledge integration framework
• NeuralExpertSim: Neural network-based edge function learning
• MDGCM: Missing data graphical causal model
• EdgeFunction: Base class for edge functional mappings
• SignalFunction: Base class for independent node signals

• SimpleFunctionalNet: Standard MLP for edge functions
• VAEFunctionalNet: Variational autoencoder for statistical matching
• TransformerFunctionalNet: Transformer-based sequence modeling
• DiffusionFunctionalNet: Diffusion model for edge functions

1. Synthetic Data Generation: Create realistic time series with known causal structure
2. Method Evaluation: Benchmark causal discovery and time series analysis methods
3. Data Augmentation: Generate additional training data preserving statistical properties
4. Missing Data Research: Study missing data mechanisms and imputation methods
5. Domain Knowledge Integration: Incorporate expert knowledge into data generation
6. Neuroscience Research: Generate synthetic fMRI/neuroimaging data

⚠️ Warning: Edge functions and signal functions are stored using pickle. Use with caution as stated in Python's pickle documentation.

• Main README: See README.md for detailed usage instructions
• API Documentation: Check docstrings in source code
• Examples: Explore notebooks in examples/ directory

This project is licensed under the MIT License.

For inquiries, please contact:

• Haixin Li: peterlai_0618@outlook.com

• Enable dVariable nodes for storing variable changes and evaluating instant effects
• Enhanced real-world data adaptation with automatic graph learning
• Additional neural network architectures
• Extended visualization capabilities

Version: 0.4
Last Updated: 2024