Added or updated Readmes for all epp examples.

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

Author: marvin-hansen

examples/epp_cate/README.md

@@ -0,0 +1,45 @@
+# EPP Example: Conditional Average Treatment Effect (CATE)
+
+This crate demonstrates how the `DeepCausality` library, which implements the Effect Propagation Process (EPP), can model and calculate the Conditional Average Treatment Effect (CATE). 
+
+Specifically, this example answers the question: **"What is the average effect of a new medication on blood pressure, specifically for the subgroup of patients over the age of 65?"**
+
+This showcases how the EPP's architecture naturally handles concepts from the Rubin Causal Model (RCM), such as potential outcomes, through its powerful contextual reasoning capabilities. This aligns with the principles outlined in Section 5.16 of the EPP documentation.
+
+## How to Run
+
+From within the `examples/epp_cate` directory, run:
+
+```bash
+cargo run --bin example-cate
+```
+
+---
+
+### How It Works: Mapping CATE to EPP Concepts
+
+The core idea behind CATE is to estimate the average effect of a treatment for a specific subset of a population. The EPP achieves this through the following mechanisms:
+
+1.  **Causal Logic (`drug_effect_logic`):**
+    The fundamental effect of the drug is encapsulated in a single, reusable `Causaloid`. This causaloid uses a `ContextualCausalFn`, a function that can inspect the context it's evaluated against. Its logic is simple: if it finds a `drug_administered` flag in its context, it returns a numerical effect (e.g., -10.0 for a 10-point drop in blood pressure); otherwise, it returns zero.
+
+2.  **Population and Subgroup Selection:**
+    The entire patient population is represented as a `Vec<BaseContext>`, where each `Context` is a self-contained representation of an individual, holding their specific attributes (like `age` and `initial_blood_pressure`) as `Datoid`s. We create our subgroup of interest by simply filtering this vector to include only the contexts of patients older than 65.
+
+3.  **Potential Outcomes via Contextual Alternation:**
+    This is the key step. To calculate the Individual Treatment Effect (ITE) for each person in the subgroup, we must simulate two parallel realities: one where they received the drug, and one where they didn't. The EPP models this cleanly using **Contextual Alternation**:
+
+    *   **Treatment Context (`Y(1)`):** For each patient, we clone their original context and *add* a `Datoid` indicating the drug was administered. Evaluating our `Causaloid` against this context yields the *potential outcome under treatment*.
+    *   **Control Context (`Y(0)`):** We clone the patient's context again, this time adding a `Datoid` indicating the drug was *not* administered. Evaluating the *exact same* `Causaloid` against this second context yields the *potential outcome under control*.
+
+4.  **Aggregation to CATE:**
+    By subtracting the control outcome from the treatment outcome (`Y(1) - Y(0)`), we get the ITE for each individual. The CATE for the subgroup is then simply the average of all these ITEs.
+
+### Conclusion
+
+This example highlights a core strength of the Effect Propagation Process: the explicit separation of **causal logic** (the `Causaloid`) from the **state of the world** (the `Context`). This separation makes it trivial to perform powerful counterfactual reasoning by creating alternate contexts and evaluating the same immutable causal laws against them, providing a robust foundation for advanced causal inference.
+
+## 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/csm/Cargo.toml renamed to examples/epp_csm/Cargo.toml

@@ -0,0 +1,46 @@
+# EPP Example: Causal State Machine (CSM)
+
+This crate demonstrates how the `DeepCausality` library, which implements the Effect Propagation Process (EPP), can be used to build a Causal State Machine (CSM). 
+
+Specifically, this example models a simple industrial monitoring system with three sensors: smoke, fire, and explosion. Each sensor is represented by a `CausalState` that, when its conditions are met, triggers a corresponding `CausalAction` (e.g., raising an alert).
+
+This showcases how the EPP's architecture provides a formal bridge between causal reasoning and deterministic intervention, a concept that aligns with Rung 2 (Intervention) of Pearl's Ladder of Causation.
+
+## How to Run
+
+From within the `examples/csm` directory, run:
+
+```bash
+cargo run --bin example-csm
+```
+
+---
+
+### How It Works: Mapping CSM Concepts to EPP
+
+The CSM provides a mechanism to link causal inferences to real-world actions. It is a collection of state-action pairs, where each state's activation is determined by a causal model.
+
+1.  **Causal Logic as `Causaloid`s:**
+    The trigger condition for each sensor is encapsulated in a `Causaloid`. For example, the `smoke_sensor_causaloid` contains a simple `causal_fn` that checks if an incoming numerical value (the sensor reading) exceeds a predefined threshold (e.g., 65.0).
+
+2.  **States as `CausalState`s:**
+    Each sensor in the system is represented by a `CausalState`. The `CausalState` struct holds a reference to the `Causaloid` that defines its logic. For instance, the `smoke_cs` holds the `smoke_sensor_causaloid`. When the CSM evaluates this state, it uses the causaloid to determine if the state is active.
+
+3.  **Actions as `CausalAction`s:**
+    Each potential intervention is defined as a `CausalAction`. This struct wraps a function that will be executed when the action is fired. In this example, the actions (`get_smoke_alert_action`, `get_fire_alert_action`, etc.) simply print a message to the console, but they could just as easily trigger an API call, send an email, or control a physical device.
+
+4.  **The `CSM` as an Orchestrator:**
+    The `CSM` is initialized with a collection of state-action pairs. Its primary role is to orchestrate the evaluation process. The `main` loop simulates a stream of sensor data. In each iteration:
+    - A `PropagatingEffect::Numerical` is created from the raw sensor data.
+    - `csm.eval_single_state()` is called for each sensor.
+    - The CSM finds the corresponding `CausalState`, evaluates its `Causaloid` against the provided data, and if the result is `Deterministic(true)`, it automatically calls the `fire()` method on the associated `CausalAction`.
+
+### Conclusion
+
+This example demonstrates how the CSM acts as a powerful bridge between the abstract world of causal reasoning and the concrete world of action and intervention. By formally linking `CausalState`s (defined by `Causaloid`s) to `CausalAction`s, the EPP provides a robust, auditable, and deterministic way to build systems that not only understand cause and effect but can also act on that understanding.
+
+
+## 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_csm/README.md

@@ -0,0 +1,48 @@
+# EPP Example: Dynamic Bayesian Network (DBN)
+
+This crate demonstrates how the `DeepCausality` library, which implements the Effect Propagation Process (EPP), can model a simple Dynamic Bayesian Network (DBN). 
+
+Specifically, this example models the classic "Umbrella World" scenario, where the decision to take an umbrella today depends on whether it is raining, and the probability of rain today depends on whether it rained yesterday.
+
+This showcases how the EPP's architecture, with its first-class treatment of time and context, provides a natural and powerful framework for modeling temporal causal processes. This aligns with the principles outlined in Section 5.13 of the EPP documentation.
+
+## How to Run
+
+From within the `examples/epp_dbn` directory, run:
+
+```bash
+cargo run --bin example-dbn
+```
+
+---
+
+### How It Works: Mapping DBN Concepts to EPP
+
+A DBN models a temporal process by "unrolling" a causal graph over discrete time slices. The EPP achieves the same result by evaluating a single, static causal model over a dynamic, temporal context.
+
+1.  **Time Slices as a Dynamic Context:**
+    Instead of creating new nodes for each time step (e.g., `Rain_t-1`, `Rain_t`), the EPP represents the entire timeline as a single, dynamic `Context`. This context holds `Datoid` nodes representing the state of variables (like `Rain`) at different points in time. As the simulation progresses, this context is updated, representing the forward flow of time.
+
+2.  **State Variables as Causaloids:**
+    The state variables in the DBN (e.g., `Rain` and `Umbrella`) are represented as `Causaloid`s. Each `Causaloid` encapsulates the conditional probability table (CPT) for that variable as its `causal_fn`.
+    -   The `rain_causaloid` implements `P(Rain_t | Rain_t-1)`. It queries the context to find the state of rain on the previous day to determine the probability of rain today.
+    -   The `umbrella_causaloid` implements `P(Umbrella_t | Rain_t)`. It takes the probability of rain today as input and decides whether to take an umbrella.
+
+3.  **Dependencies as a CausaloidGraph:**
+    The directed edges in the DBN, representing causal dependencies, are modeled as a `CausaloidGraph`. In this case, the graph represents the simple chain: `Rain -> Umbrella`.
+
+4.  **Inference as Evaluation over Time (Filtering):**
+    The DBN's "filtering" process—updating the belief state as new evidence arrives—is modeled as a loop that simulates the passing of days. In each iteration:
+    - The `rain_causaloid` is evaluated to determine the probability of rain for the current day.
+    - A random sample is drawn to determine if it actually rained (simulating real-world observation).
+    - The `umbrella_causaloid` is evaluated based on the probability of rain.
+    - The `Context` is updated with the new state of rain, making it available for the next day's calculation.
+
+### Conclusion
+
+This example demonstrates that the EPP provides a flexible alternative to traditional DBNs. By externalizing time into a dynamic `Context`, the EPP allows for the modeling of complex temporal dependencies with a static and reusable causal graph. This separation of concerns simplifies the model and provides a clear and intuitive way to reason about causality in dynamic systems.
+
+## 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/csm/src/main.rs renamed to examples/epp_csm/src/main.rs

@@ -0,0 +1,49 @@
+# EPP Example: Granger Causality
+
+This crate demonstrates how the `DeepCausality` library, which implements the Effect Propagation Process (EPP), can model a Granger Causality test. 
+
+Specifically, this example answers the question: **"Do past changes in oil prices Granger-cause future changes in shipping activity?"**
+
+This showcases how the EPP's architecture naturally handles the counterfactual reasoning inherent in a Granger test. This aligns with the principles outlined in Section 5.14 of the EPP documentation.
+
+## How to Run
+
+From within the `examples/epp_granger` directory, run:
+
+```bash
+cargo run --bin example-granger
+```
+
+---
+
+### How It Works: Mapping Granger Causality to EPP Concepts
+
+The core idea behind Granger Causality is to determine if one time series is useful in forecasting another. The EPP models this by comparing the predictive accuracy of a causal model under two different contexts: one with the complete history (factual) and one where the history of the potential causal variable has been removed (counterfactual).
+
+1.  **Causal Logic (`shipping_predictor_logic`):**
+    The predictive model is encapsulated in a single, reusable `Causaloid`. This causaloid uses a `ContextualCausalFn`, a function that can inspect the context it's evaluated against. Its logic is to predict the next value of shipping activity based on the historical data it finds in its context. It will use both shipping and oil price data if available, but will gracefully fall back to using only shipping data if oil price data is missing.
+
+2.  **Factual vs. Counterfactual Contexts:**
+    This is the key to the Granger test. We create two distinct realities:
+
+    *   **Factual Context:** A `BaseContext` is created containing the complete, observed history of *both* oil prices and shipping activity.
+    *   **Counterfactual Context:** A second `BaseContext` is created that contains the history of shipping activity but is *missing* the history of oil prices.
+
+3.  **Evaluating Potential Outcomes:**
+    We instantiate two separate `Causaloid`s, each with the same predictive logic but associated with a different context:
+
+    *   The **factual causaloid** is evaluated against the factual context. Its prediction will be informed by the history of oil prices.
+    *   The **counterfactual causaloid** is evaluated against the counterfactual context. Its prediction will *not* be informed by the history of oil prices.
+
+4.  **Comparing Prediction Errors:**
+    We compare the prediction error from both evaluations against a known, actual outcome. If the error from the factual evaluation (which included oil prices) is significantly lower than the error from the counterfactual evaluation, we can conclude that the oil price time series provides valuable information for predicting the shipping activity time series. In other words, oil prices Granger-cause shipping activity.
+
+### Conclusion
+
+This example highlights a core strength of the Effect Propagation Process: the explicit separation of **causal logic** (the `Causaloid`) from the **state of the world** (the `Context`). This separation makes it trivial to perform the powerful counterfactual reasoning required for a Granger Causality test by simply creating alternate contexts and evaluating the same immutable causal laws against them.
+
+
+## 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