scirs2-stats 0.4.2

Statistical functions module for SciRS2 (scirs2-stats)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

//! Causal Graph Methods
//!
//! This module provides a comprehensive suite of causal inference tools
//! based on Directed Acyclic Graphs (DAGs) and structural causal models.
//!
//! # Sub-modules
//!
//! | Module | Contents |
//! |--------|----------|
//! | [`dag`] | [`CausalDAG`] — DAG structure with d-separation (Bayes Ball), Markov blanket, topological sort |
//! | [`identification`] | Do-calculus rules, backdoor/frontdoor criteria, ID algorithm, Tian-Pearl factorisation |
//! | [`estimation`] | IPW, AIPW (doubly robust), nearest-neighbour matching, regression discontinuity, synthetic control, DiD |
//! | [`structure_learning`] | PC algorithm, FCI algorithm, BIC greedy search, LiNGAM, NOTEARS |
//!
//! # Quick Start
//!
//! ## Build and query a DAG
//!
//! ```rust
//! use scirs2_stats::causal_graph::dag::CausalDAG;
//!
//! let mut dag = CausalDAG::new();
//! dag.add_edge("X", "Y").unwrap();
//! dag.add_edge("Y", "Z").unwrap();
//!
//! // D-separation: X ⊥ Z | Y in a chain
//! assert!(dag.is_d_separated("X", "Z", &["Y"]));
//! assert!(!dag.is_d_separated("X", "Z", &[]));
//!
//! let order = dag.topological_sort();
//! assert_eq!(order[0], "X");
//! ```
//!
//! ## Identify P(y | do(x)) using the backdoor criterion
//!
//! ```rust
//! use scirs2_stats::causal_graph::dag::CausalDAG;
//! use scirs2_stats::causal_graph::identification::find_backdoor_sets;
//!
//! // Z → X → Y, Z → Y  (Z is a confounder)
//! let mut dag = CausalDAG::new();
//! dag.add_edge("Z", "X").unwrap();
//! dag.add_edge("Z", "Y").unwrap();
//! dag.add_edge("X", "Y").unwrap();
//!
//! let bd = find_backdoor_sets(&dag, "X", "Y", 3);
//! assert!(bd.is_admissible);
//! assert!(bd.adjustment_set.contains(&"Z".to_string()));
//! ```
//!
//! ## Estimate ATE with IPW
//!
//! ```rust
//! use scirs2_stats::causal_graph::estimation::IPWEstimator;
//! use scirs2_core::ndarray::{Array1, Array2};
//!
//! let n = 20;
//! let cov = Array2::<f64>::from_shape_fn((n, 1), |(i, _)| i as f64 / n as f64);
//! let treat = Array1::from_iter((0..n).map(|i| if i < n/2 { 1.0 } else { 0.0 }));
//! let outcome = Array1::from_iter((0..n).map(|i| if i < n/2 { 2.0 } else { 0.0 }));
//!
//! let est = IPWEstimator::default();
//! let result = est.estimate(cov.view(), treat.view(), outcome.view()).unwrap();
//! assert!(result.estimate.is_finite());
//! ```
//!
//! ## Learn causal structure from data
//!
//! ```rust
//! use scirs2_stats::causal_graph::structure_learning::PcAlgorithm;
//! use scirs2_core::ndarray::Array2;
//!
//! let n = 50;
//! let data = Array2::<f64>::from_shape_fn((n, 3), |(i, j)| {
//!     (i as f64 * 0.1 + j as f64).sin()
//! });
//! let pc = PcAlgorithm::default();
//! let result = pc.fit(data.view(), &["A", "B", "C"]).unwrap();
//! assert_eq!(result.dag.n_nodes(), 3);
//! ```
//!
//! # References
//!
//! - Pearl, J. (2000). *Causality: Models, Reasoning, and Inference*.
//!   Cambridge University Press.
//! - Spirtes, P., Glymour, C. & Scheines, R. (2000). *Causation, Prediction,
//!   and Search* (2nd ed.). MIT Press.
//! - Imbens, G.W. & Rubin, D.B. (2015). *Causal Inference for Statistics,
//!   Social, and Biomedical Sciences*. Cambridge University Press.
//! - Shpitser, I. & Pearl, J. (2006). Identification of Joint Interventional
//!   Distributions in Recursive Semi-Markovian Causal Models. AAAI 2006.
//! - Zheng, X. et al. (2018). DAGs with NO TEARS. NeurIPS 2018.
//! - Shimizu, S. et al. (2006). A Linear Non-Gaussian Acyclic Model for
//!   Causal Discovery. JMLR.

pub mod dag;
pub mod estimation;
pub mod identification;
pub mod structure_learning;

// ---------------------------------------------------------------------------
// Re-exports — DAG
// ---------------------------------------------------------------------------

pub use dag::CausalDAG;

// ---------------------------------------------------------------------------
// Re-exports — Identification
// ---------------------------------------------------------------------------

pub use identification::{
    c_components_with_hidden, check_do_calculus_rule, find_backdoor_sets, find_frontdoor_set,
    id_algorithm, satisfies_backdoor, satisfies_frontdoor, tian_pearl_id, BackdoorResult,
    CComponent, DoCalculusRule, FrontdoorResult, IdResult,
};

// ---------------------------------------------------------------------------
// Re-exports — Estimation
// ---------------------------------------------------------------------------

pub use estimation::{
    DiDResult, DifferenceInDifferences, DoublyRobustEstimator, EstimationResult, IPWEstimator,
    NearestNeighborMatching, RegressionDiscontinuity, SyntheticControlEstimator,
    SyntheticControlResult,
};

// ---------------------------------------------------------------------------
// Re-exports — Structure Learning
// ---------------------------------------------------------------------------

pub use structure_learning::{
    BicGreedySearch, EdgeType, FciAlgorithm, LiNGAM, LiNGAMResult, Notears, PcAlgorithm,
    StructureLearningResult,
};