oaxaca_blinder 0.2.0

A Rust library for performing Oaxaca-Blinder decomposition on Polars DataFrames, with support for categorical variables and bootstrapped standard errors.
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

use pyo3::prelude::*;
use pyo3::types::PyDict;
use std::collections::HashMap;

#[pyclass]
struct PyOaxacaResults {
    total_gap: f64,
    explained: f64,
    unexplained: f64,
    detailed_explained: HashMap<String, f64>,
    detailed_unexplained: HashMap<String, f64>,
}

#[pymethods]
impl PyOaxacaResults {
    #[getter]
    fn total_gap(&self) -> f64 {
        self.total_gap
    }

    #[getter]
    fn explained(&self) -> f64 {
        self.explained
    }

    #[getter]
    fn unexplained(&self) -> f64 {
        self.unexplained
    }

    #[getter]
    fn detailed_explained(&self) -> HashMap<String, f64> {
        self.detailed_explained.clone()
    }

    #[getter]
    fn detailed_unexplained(&self) -> HashMap<String, f64> {
        self.detailed_unexplained.clone()
    }

    fn to_dict(&self, py: Python) -> PyResult<PyObject> {
        let dict = PyDict::new_bound(py);
        dict.set_item("total_gap", self.total_gap)?;
        dict.set_item("explained", self.explained)?;
        dict.set_item("unexplained", self.unexplained)?;
        dict.set_item("detailed_explained", self.detailed_explained.clone())?;
        dict.set_item("detailed_unexplained", self.detailed_unexplained.clone())?;
        Ok(dict.into())
    }
}

/// Performs Oaxaca-Blinder decomposition from a CSV file.
///
/// # Arguments
///
/// * `csv_path` - Path to the CSV file
/// * `outcome` - Name of the outcome variable
/// * `predictors` - List of predictor variable names
/// * `categorical_predictors` - List of categorical predictor names
/// * `group` - Name of the group variable
/// * `reference_group` - Value representing the reference group
/// * `bootstrap_reps` - Number of bootstrap replications (default: 100)
#[pyfunction]
#[pyo3(signature = (csv_path, outcome, predictors, categorical_predictors, group, reference_group, bootstrap_reps=100))]
fn decompose_from_csv(
    csv_path: &str,
    outcome: &str,
    predictors: Vec<String>,
    categorical_predictors: Vec<String>,
    group: &str,
    reference_group: &str,
    bootstrap_reps: usize,
) -> PyResult<PyOaxacaResults> {
    use polars::prelude::*;
    use crate::OaxacaBuilder;

    let df = LazyCsvReader::new(csv_path)
        .finish()
        .map_err(|e| PyErr::new::<pyo3::exceptions::PyIOError, _>(format!("Failed to read CSV: {}", e)))?
        .collect()
        .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(format!("Failed to parse CSV: {}", e)))?;

    let pred_refs: Vec<&str> = predictors.iter().map(|s| s.as_str()).collect();
    let cat_refs: Vec<&str> = categorical_predictors.iter().map(|s| s.as_str()).collect();

    let mut builder = OaxacaBuilder::new(df, outcome, group, reference_group);
    builder.predictors(&pred_refs)
           .categorical_predictors(&cat_refs)
           .bootstrap_reps(bootstrap_reps);

    let results = builder.run()
        .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(format!("Decomposition failed: {:?}", e)))?;

    let explained = results.two_fold().aggregate().iter()
        .find(|c| c.name() == "explained")
        .map(|c| *c.estimate())
        .unwrap_or(0.0);

    let unexplained = results.two_fold().aggregate().iter()
        .find(|c| c.name() == "unexplained")
        .map(|c| *c.estimate())
        .unwrap_or(0.0);

    let mut detailed_explained = HashMap::new();
    for comp in results.two_fold().detailed_explained() {
        detailed_explained.insert(comp.name().to_string(), *comp.estimate());
    }

    let mut detailed_unexplained = HashMap::new();
    for comp in results.two_fold().detailed_unexplained() {
        detailed_unexplained.insert(comp.name().to_string(), *comp.estimate());
    }

    Ok(PyOaxacaResults {
        total_gap: *results.total_gap(),
        explained,
        unexplained,
        detailed_explained,
        detailed_unexplained,
    })
}

/// Python module for oaxaca_blinder
#[pymodule]
fn oaxaca_blinder(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(decompose_from_csv, m)?)?;
    m.add_class::<PyOaxacaResults>()?;
    Ok(())
}