Welcome to ProRCA’s Documentation!

ProRCA is an end-to-end framework for diagnosing anomalies in complex operational environments by uncovering multi-hop causal pathways. Unlike traditional anomaly detection methods that focus on correlations or feature importance (e.g., via SHAP), our approach leverages structural causal modeling to trace the full causal chain—from hidden root causes to observed anomalies.

Inspired by the paper:

Beyond Traditional Problem-Solving: A Causal Pathway Approach for Complex Operational Environments Ahmed Dawoud & Shravan Talupula, February 9, 2025 [📄 Download PDF]

This work introduces a methodology that combines conditional anomaly scoring with causal path discovery and ranking. By extending the DoWhy library, the framework provides decision-makers with actionable insights into the true source of complex operational disruptions.

Key Capabilities

ProRCA empowers you to move from simply detecting anomalies to truly understanding their origins. Here’s how:

• Pinpoint Critical Anomalies: Don’t just find outliers; identify the significant operational hiccups in your time series data that truly matter. ProRCA uses robust detection methods to flag the starting points for your investigation.

• Map Your System’s Causal DNA: Go beyond black boxes. Explicitly define and model the cause-and-effect relationships within your operations using Structural Causal Models (SCMs). This captures the real logic of how different parts of your system influence each other.

• Uncover the *Real* Root Causes: This is where ProRCA shines. Move past simple correlations and discover the actual causal pathways leading to anomalies. Our analysis traces disruptions back through multiple steps (multi-hop paths) in your system, uniquely combining structural knowledge with noise pattern analysis to pinpoint the true origins.

• Visualize Causal Stories: Complex findings become clear insights. ProRCA generates intuitive diagrams of the discovered causal pathways, making it easy to see the chain of events, understand the flow of influence, and communicate exactly where the problem started.

Contents

outline:

• Installation
  • Install from PyPI
  • For Development
• Usage Guide
  • Step 1: Prepare Your Data (Real or Synthetic)
  • Step 2: Detect Anomalies
  • Step 3: Define Causal Structure (DAG)
  • Step 4: Build the Structural Causal Model (SCM)
  • Step 5: Perform Causal Root Cause Analysis
  • Step 6: Visualize Causal Pathways
• Synthetic Data Generation
  • Why Use Synthetic Data?
  • Realism and Quality
  • Current Capabilities: Retail Data
  • Injecting Controlled Anomalies
  • Future Directions
• End-to-End Example: Retail Anomaly Root Cause Analysis
  • Step 1: Data Preparation (from Data_Generation.ipynb)
  • Step 2: Anomaly Detection (from RCA.ipynb)
  • Step 3: Define Causal Structure (DAG) (from RCA.ipynb)
  • Step 4: Build the Structural Causal Model (SCM) (from RCA.ipynb)
  • Step 5: Perform Causal Root Cause Analysis (from RCA.ipynb)
  • Step 6: Visualize Causal Pathways (from RCA.ipynb)
  • Step 7: Conclusion (Summary from RCA.ipynb)
• API Reference
  • prorca.pathway
  • prorca.dag_builder
  • anomaly.adtk
  • data_generators.synthetic_sales_data