Struct CausalInferenceEngine 

pub struct CausalInferenceEngine {
    pub graph: CausalGraph,
    pub max_path_length: usize,
}

Production-grade causal inference engine.

Example

use ipfrs_tensorlogic::{
    CausalInferenceEngine, CausalNode, CausalEdge, Intervention,
};

let mut engine = CausalInferenceEngine::new(10);
engine.add_node(CausalNode::new("X", 0.0, 1.0)).expect("example: should succeed in docs");
engine.add_node(CausalNode::new("Y", 0.0, 1.0)).expect("example: should succeed in docs");
engine.add_edge(CausalEdge::direct("X", "Y", 0.8)).expect("example: should succeed in docs");

let result = engine.do_calculus(
    &Intervention::new("X", 1.0),
    &ipfrs_tensorlogic::CausalNodeId::new("Y"),
);
assert!((result.mean - 0.8).abs() < 1e-9);

Fields

graph: CausalGraph

The underlying causal graph.

max_path_length: usize

Maximum number of hops considered when enumerating paths.

Implementations

impl CausalInferenceEngine

pub fn new(max_path_length: usize) -> Self

Create a new engine with an empty graph and the given path-length limit.

pub fn add_node(&mut self, node: CausalNode) -> Result<(), CausalError>

Add a node to the graph.

Returns CausalError::NodeAlreadyExists if the identifier is taken.

pub fn add_edge(&mut self, edge: CausalEdge) -> Result<(), CausalError>

Add a directed edge to the graph.

Both endpoints must already exist, and the edge must not introduce a directed cycle. On success the parent/child lists of both endpoints are updated in-place.

pub fn remove_node(&mut self, id: &CausalNodeId) -> bool

Remove a node and all edges that touch it.

Returns true if the node existed and was removed, false otherwise.

pub fn has_path(&self, from: &CausalNodeId, to: &CausalNodeId) -> bool

Return true if there is at least one directed path from from to to (depth-first search, respects max_path_length).

pub fn is_ancestor( &self, ancestor: &CausalNodeId, descendant: &CausalNodeId, ) -> bool

Return true if ancestor is a strict ancestor of descendant (i.e. there is a directed path from ancestor to descendant).

pub fn ancestors(&self, id: &CausalNodeId) -> Vec<CausalNodeId>

Return all strict ancestors of id via BFS through parent pointers.

pub fn descendants(&self, id: &CausalNodeId) -> Vec<CausalNodeId>

Return all strict descendants of id via BFS through child pointers.

pub fn all_directed_paths( &self, from: &CausalNodeId, to: &CausalNodeId, ) -> Vec<Vec<CausalNodeId>>

Enumerate all directed paths from from to to up to max_path_length hops (DFS with backtracking).

pub fn backdoor_paths( &self, from: &CausalNodeId, to: &CausalNodeId, ) -> Vec<Vec<CausalNodeId>>

Enumerate backdoor paths from from to to.

A backdoor path is any path that arrives at from via an incoming edge (i.e. starts from a parent of from and eventually reaches to). Paths are limited to max_path_length hops.

pub fn do_calculus( &self, intervention: &Intervention, target: &CausalNodeId, ) -> InferenceResult

Compute the interventional distribution P(target | do(intervention)).

Uses a linear causal model: the mean of target under the intervention is the intervention value times the sum of all path effects from the intervened node to target. The posterior variance shrinks by the total explained fraction (capped at 0.99 to avoid degenerate zero variance), and the confidence is the explained fraction clamped to [0, 1].

pub fn counterfactual(&self, query: &CounterfactualQuery) -> InferenceResult

Estimate the counterfactual distribution of query.target had query.intervention been applied, conditioned on query.evidence.

The implementation uses do-calculus as a base and adds an evidence correction: for each observed variable in evidence we sum the product of its observed value and the direct edge strength to the target.

pub fn average_causal_effect( &self, from: &CausalNodeId, to: &CausalNodeId, value1: f64, value2: f64, ) -> f64

Compute the Average Causal Effect (ACE) of from on to.

ACE = E[to | do(from = value2)] - E[to | do(from = value1)]

pub fn confounders( &self, x: &CausalNodeId, y: &CausalNodeId, ) -> Vec<CausalNodeId>

Return the common ancestors of x and y (i.e. potential confounders).

pub fn is_d_separated( &self, x: &CausalNodeId, y: &CausalNodeId, given: &[CausalNodeId], ) -> bool

Simplified d-separation check.

Returns true if x and y are d-separated given the conditioning set given.

The implementation tests:

1. No direct edge from x to y (after removing given nodes).
2. No directed path from x to y that does not pass through a given node.
3. No backdoor path from x to y that is not blocked by a given node.

pub fn stats(&self) -> CausalStats

Compute summary statistics for the current graph.

Trait Implementations

impl Debug for CausalInferenceEngine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.