Added SCM example

Signed-off-by: Marvin Hansen <[email protected]>

Author: marvin-hansen

Cargo.lock

@@ -2,6 +2,14 @@
 
 This example demonstrates how to implement a simple Rubin Causal Model (RCM) scenario using the `DeepCausality` library. It showcases the Effect Propagation Process (EPP)'s capability for **Contextual Alternation** to directly compute potential outcomes and determine an individual treatment effect.
 
+## How to Run
+
+To run this example, navigate to the root of the `deep_causality` project and execute:
+
+```bash
+cargo run -p example-rcm
+```
+
 ## Background: The Rubin Causal Model and EPP
 
 The RCM defines a causal effect by comparing two "potential outcomes" for a single unit: the outcome if the unit receives a treatment (Y(1)) versus the outcome if it does not (Y(0)). The fundamental challenge is that only one of these outcomes can be observed in reality.
@@ -42,13 +50,7 @@ By evaluating the *same causal model* against these different contexts, `DeepCau
 *   The Individual Treatment Effect (ITE) is calculated as `Y(1) - Y(0)`.
 *   The result is printed, demonstrating the drug's predicted effect on the patient's blood pressure.
 
-## How to Run
-
-To run this example, navigate to the root of the `deep_causality` project and execute:
 
-```bash
-cargo run -p example-rcm
-```
 
 ## Reference
 

examples/epp_rcm/README.md

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+
+[package]
+name = "example-scm"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.80"
+publish = false
+
+[dependencies]
+deep_causality = { path = "../../deep_causality" }

examples/epp_scm/Cargo.toml

@@ -0,0 +1,65 @@
+# EPP Example: Pearl's Ladder of Causation
+
+This crate demonstrates how the `DeepCausality` library, which implements the Effect Propagation Process (EPP), models the three rungs of Judea Pearl's Ladder of Causation. Each rung represents a different level of causal reasoning, and this example shows how the EPP's unique architecture addresses each one.
+
+The examples are separated into three files, each corresponding to a rung on the ladder:
+
+- `rung1_association.rs`
+- `rung2_intervention.rs`
+- `rung3_counterfactual.rs`
+
+## How to Run
+
+From within the `examples/epp_scm` directory, run:
+
+```bash
+cargo run
+```
+
+---
+
+### Rung 1: Association (Seeing)
+
+- **File:** `rung1_association.rs`
+- **Goal:** Demonstrates simple observational inference. It answers the question: "Given that we observe X, what is the likelihood of Y?" (i.e., `P(Y|X)`).
+
+#### EPP Implementation
+
+Association is modeled as a straightforward evaluation of a `CausaloidGraph`. The graph represents the assumed causal chain (`Smoking -> Tar -> Cancer`). We provide an initial `PropagatingEffect` representing the observation (e.g., high nicotine levels), and the graph's evaluation propagates this effect to determine the associated outcome (cancer risk).
+
+This aligns with **Rung 1** by showing how the system processes passive observations to find statistical associations within the model.
+
+### Rung 2: Intervention (Doing)
+
+- **File:** `rung2_intervention.rs`
+- **Goal:** Demonstrates taking an action based on an observation. It answers the question: "What would Y be if we *do* X?" (i.e., `P(Y|do(X))`).
+
+#### EPP Implementation
+
+Intervention is modeled using the **Causal State Machine (CSM)**. 
+
+1.  A `CausalState` is defined, with its condition for activation being the result of the causal graph (e.g., "High Cancer Risk" is true).
+2.  A `CausalAction` is defined, which represents the real-world intervention (e.g., prescribing therapy).
+3.  The CSM links the state to the action. When the CSM is evaluated with an effect that makes the state true, it automatically fires the action.
+
+This aligns with **Rung 2** by providing a formal mechanism to move from inference to a deterministic, real-world action.
+
+### Rung 3: Counterfactuals (Imagining)
+
+- **File:** `rung3_counterfactual.rs`
+- **Goal:** Demonstrates reasoning about alternate possibilities. It answers the retrospective question: "What would Y have been, had X been different?"
+
+#### EPP Implementation
+
+The EPP models counterfactuals not by surgically altering the causal model itself, but through **Contextual Alternation**.
+
+1.  A **Factual Context** is created to represent the observed reality (e.g., a person who smokes and has high tar).
+2.  A **Counterfactual Context** is created by cloning the factual one and then modifying a specific past condition (e.g., setting the smoking level to low, but leaving the tar level high).
+3.  The *exact same* `Causaloid` (representing the causal laws) is evaluated against both contexts.
+
+This example shows that even if we imagine the person had not smoked, their cancer risk remains high because the direct consequence (tar) is still present in the counterfactual world. This demonstrates the EPP's powerful ability to reason about alternative realities by separating causal logic from the context it operates on.
+
+## Reference
+
+For more information on the EPP, please see chapter 5 in the EPP document:
+https://github.com/deepcausality-rs/papers/blob/main/effect_propagation_process/epp.pdf

examples/epp_scm/README.md

@@ -0,0 +1,14 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+mod rung1_association;
+mod rung2_intervention;
+mod rung3_counterfactual;
+
+fn main() {
+    rung1_association::run_rung1_association();
+    rung2_intervention::run_rung2_intervention();
+    rung3_counterfactual::run_rung3_counterfactual();
+}

examples/epp_scm/src/main.rs

@@ -0,0 +1,57 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use deep_causality::*;
+
+// Define Causaloids
+fn get_smoking_causaloid() -> BaseCausaloid {
+    Causaloid::new(1, |effect| {
+        let nicotine_level = effect.as_numerical().unwrap_or(0.0);
+        Ok(PropagatingEffect::Deterministic(nicotine_level > 0.6))
+    }, "Smoking Status")
+}
+
+fn get_tar_causaloid() -> BaseCausaloid {
+    Causaloid::new(2, |effect| {
+        // Tar is present if the preceding cause (smoking) is active.
+        let is_smoking = effect.as_bool().unwrap_or(false);
+        Ok(PropagatingEffect::Deterministic(is_smoking))
+    }, "Tar in Lungs")
+}
+
+fn get_cancer_risk_causaloid() -> BaseCausaloid {
+    Causaloid::new(3, |effect| {
+        // Cancer risk is high if tar is present.
+        let has_tar = effect.as_bool().unwrap_or(false);
+        Ok(PropagatingEffect::Deterministic(has_tar))
+    }, "Cancer Risk")
+}
+
+pub fn run_rung1_association() {
+    println!("--- Rung 1: Association ---");
+    println!("Demonstrating observational inference: Given smoking, what is the cancer risk?");
+
+    // 1. Build CausaloidGraph
+    let mut graph = CausaloidGraph::new(1);
+    let smoke_idx = graph.add_causaloid(get_smoking_causaloid()).unwrap();
+    let tar_idx = graph.add_causaloid(get_tar_causaloid()).unwrap();
+    let cancer_idx = graph.add_causaloid(get_cancer_risk_causaloid()).unwrap();
+
+    graph.add_edge(smoke_idx, tar_idx).unwrap();
+    graph.add_edge(tar_idx, cancer_idx).unwrap();
+    graph.freeze();
+
+    // 2. Execute and Observe
+    // Represents observing a high nicotine level.
+    let initial_effect = PropagatingEffect::Numerical(0.8);
+    
+    // Evaluate the full chain of events starting from the first cause.
+    let final_effect = graph.evaluate_shortest_path_between_causes(smoke_idx, cancer_idx, &initial_effect).unwrap();
+
+    // 3. Assert and Explain
+    assert_eq!(final_effect, PropagatingEffect::Deterministic(true));
+    println!("Result: Observation of high nicotine level is associated with high cancer risk.");
+    println!("\n");
+}

examples/epp_scm/src/rung1_association.rs

@@ -0,0 +1,78 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use deep_causality::*;
+
+fn get_smoking_causaloid() -> BaseCausaloid {
+    Causaloid::new(1, |effect| {
+        let nicotine_level = effect.as_numerical().unwrap_or(0.0);
+        Ok(PropagatingEffect::Deterministic(nicotine_level > 0.6))
+    }, "Smoking Status")
+}
+
+fn get_tar_causaloid() -> BaseCausaloid {
+    Causaloid::new(2, |effect| {
+        let is_smoking = effect.as_bool().unwrap_or(false);
+        Ok(PropagatingEffect::Deterministic(is_smoking))
+    }, "Tar in Lungs")
+}
+
+fn get_cancer_risk_causaloid() -> BaseCausaloid {
+    Causaloid::new(3, |effect| {
+        let has_tar = effect.as_bool().unwrap_or(false);
+        Ok(PropagatingEffect::Deterministic(has_tar))
+    }, "Cancer Risk")
+}
+
+pub fn run_rung2_intervention() {
+    println!("--- Rung 2: Intervention ---");
+    println!("Demonstrating an intervention: If high cancer risk is detected, prescribe therapy.");
+
+    // 1. Setup Causal Model (same as Rung 1)
+    let mut graph = CausaloidGraph::new(1);
+    let smoke_idx = graph.add_causaloid(get_smoking_causaloid()).unwrap();
+    let tar_idx = graph.add_causaloid(get_tar_causaloid()).unwrap();
+    let cancer_idx = graph.add_causaloid(get_cancer_risk_causaloid()).unwrap();
+    graph.add_edge(smoke_idx, tar_idx).unwrap();
+    graph.add_edge(tar_idx, cancer_idx).unwrap();
+    graph.freeze();
+
+    // The causaloid representing the final effect we want to act upon.
+    let final_risk_causaloid = graph.get_causaloid(cancer_idx).unwrap().clone();
+
+    // 2. Define State and Action
+    let high_cancer_risk_state = CausalState::new(
+        10, // state ID
+        1,  // version
+        PropagatingEffect::Deterministic(true), // The data to evaluate against the causaloid
+        final_risk_causaloid,
+    );
+
+    let prescribe_therapy_action = CausalAction::new(
+        || {
+            println!("Intervention: Cessation therapy prescribed.");
+            Ok(())
+        },
+        "Prescribe Therapy",
+        1,
+    );
+
+    // 3. Build Causal State Machine (CSM)
+    let state_action_pair = &[(&high_cancer_risk_state, &prescribe_therapy_action)];
+    let csm = CSM::new(state_action_pair);
+
+    // 4. Execute and Intervene
+    // We need to evaluate the full causal chain first to get the final effect.
+    let initial_effect = PropagatingEffect::Numerical(0.8);
+    let final_effect = graph.evaluate_shortest_path_between_causes(smoke_idx, cancer_idx, &initial_effect).unwrap();
+
+    // Now, use the final effect as input to the CSM.
+    // The CSM will check if the `high_cancer_risk_state` is met by this effect.
+    let result = csm.eval_single_state(10, &final_effect);
+
+    assert!(result.is_ok());
+    println!("Result: High cancer risk was detected, and the intervention was successfully fired.");
+    println!("\n");
+}

examples/epp_scm/src/rung2_intervention.rs

@@ -0,0 +1,90 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use deep_causality::*;
+use std::sync::Arc;
+
+// Contextoid IDs
+const NICOTINE_ID: IdentificationValue = 1;
+const TAR_ID: IdentificationValue = 2;
+
+/// A contextual causal function that determines cancer risk.
+/// It prioritizes checking for tar, then for smoking.
+fn contextual_cancer_risk_logic(
+    _effect: &PropagatingEffect,
+    context: &Arc<BaseContext>,
+) -> Result<PropagatingEffect, CausalityError> {
+    let mut tar_level = 0.0;
+    let mut nicotine_level = 0.0;
+
+    // Scan the context for relevant data.
+    for i in 0..context.number_of_nodes() {
+        if let Some(node) = context.get_node(i) {
+            if let ContextoidType::Datoid(data_node) = node.vertex_type() {
+                match data_node.id() {
+                    TAR_ID => tar_level = data_node.get_data(),
+                    NICOTINE_ID => nicotine_level = data_node.get_data(),
+                    _ => (),
+                }
+            }
+        }
+    }
+
+    // Causal Logic: High tar is a direct cause of cancer risk, regardless of smoking.
+    if tar_level > 0.6 {
+        return Ok(PropagatingEffect::Deterministic(true));
+    }
+    // If tar is low, then smoking becomes the relevant factor.
+    if nicotine_level > 0.6 {
+        return Ok(PropagatingEffect::Deterministic(true));
+    }
+
+    Ok(PropagatingEffect::Deterministic(false))
+}
+
+pub fn run_rung3_counterfactual() {
+    println!("--- Rung 3: Counterfactual ---");
+    println!("Query: Given a smoker with high tar, what would their cancer risk be if they hadn't smoked?");
+
+    // 1. Define the Causaloid with our contextual logic
+    let cancer_risk_causaloid = Causaloid::new_with_context(
+        1,
+        contextual_cancer_risk_logic,
+        Arc::new(BaseContext::with_capacity(0, "temp", 1)), // Temporary context, will be replaced
+        "Contextual Cancer Risk",
+    );
+
+    // 2. Create Factual Context: A person who smokes and has high tar.
+    let mut factual_context = BaseContext::with_capacity(1, "Factual", 5);
+    factual_context.add_node(Contextoid::new(1, ContextoidType::Datoid(Data::new(NICOTINE_ID, 0.8)))).unwrap();
+    factual_context.add_node(Contextoid::new(2, ContextoidType::Datoid(Data::new(TAR_ID, 0.8)))).unwrap();
+
+    // 3. Create Counterfactual Context: Same person, but we hypothetically set smoking to zero.
+    let mut counterfactual_context = factual_context.clone();
+    // To update, we need to know the index. In this simple case, it's 0.
+    // A real implementation might use a HashMap<ID, Index> for lookup.
+    let new_nicotine_datoid = Contextoid::new(1, ContextoidType::Datoid(Data::new(NICOTINE_ID, 0.1)));
+    counterfactual_context.update_node(1, new_nicotine_datoid).unwrap();
+
+    // 4. Evaluate Both Scenarios
+    let mut factual_causaloid = cancer_risk_causaloid.clone();
+    factual_causaloid.set_context(Some(Arc::new(factual_context)));
+
+    let mut counterfactual_causaloid = cancer_risk_causaloid.clone();
+    counterfactual_causaloid.set_context(Some(Arc::new(counterfactual_context)));
+
+    let factual_risk = factual_causaloid.evaluate(&PropagatingEffect::None).unwrap();
+    let counterfactual_risk = counterfactual_causaloid.evaluate(&PropagatingEffect::None).unwrap();
+
+    // 5. Assert and Explain
+    println!("Factual Result (smoker with high tar): Cancer risk is high -> {}", factual_risk.as_bool().unwrap());
+    println!("Counterfactual Result (non-smoker with high tar): Cancer risk is high -> {}", counterfactual_risk.as_bool().unwrap());
+
+    assert_eq!(factual_risk, PropagatingEffect::Deterministic(true));
+    assert_eq!(counterfactual_risk, PropagatingEffect::Deterministic(true));
+
+    println!("Conclusion: The cancer risk remains high in the counterfactual world because the direct cause (tar) was not undone.");
+    println!("\n");
+}