lepidoptera: A Domain-Agnostic Engine for Causal Simulation with Mixed Variable Types, Vine Copula Dependence, and Individual-Level Counterfactual Propagation
Abstract
lepidoptera is an open-source R and Python package for simulation from structural causal models with heterogeneous variable types. The package is built around a typed mechanism architecture, which separates the causal graph from the generating rule at each node and exposes each rule as an inspectable, serialisable object. A pre-built mechanism library covers all nine combinations of continuous, categorical, and ordinal parent and child types, removing the need for users to implement type-specific sampling from scratch. A vine copula mechanism estimates the full joint dependence structure from observed data using pair-copula constructions and the Rosenblatt conditional-simulation algorithm, supporting over twenty copula families. Individual-level counterfactual queries are supported through partial propagation, which freezes the random draws of unaffected nodes and replays only the downstream consequences of an intervention, thereby separating the individual treatment effect (ITE) estimand from the population-level average treatment effect (ATE) without additional model assumptions. An extension layer allows any pre-fitted predictive model to serve as a generative mechanism via a unified callable interface. Three worked illustrations spanning clinical trial planning, emergency-ward capacity analysis, and epidemiological mediation analysis demonstrate the package's scope.
Related
- Distributional Counterfactual Dependence in the Special Sciences
- From Average Effects to Proportions Benefiting: A Tutorial on ETZ-Powered Counterfactual Individual Benefit Analysis
- Where Is the Truth When AI Agents Disagree? Dependence-Aware Belief Propagation for Unsupervised Truth Discovery (Extended Version)
- Q-Edge: Symmetry-Reduced Quantum Simulation of Structured Extreme Dependence
- Multivariate conformal uncertainty propagation in multitask atomistic simulation: Successes and pitfalls
BibTeX
@misc{sarti2026lepidoptera,
title = {{lepidoptera: A Domain-Agnostic Engine for Causal Simulation with Mixed Variable Types, Vine Copula Dependence, and Individual-Level Counterfactual Propagation}},
author = {Danilo Augusto Sarti},
howpublished = {arXiv},
year = {2026},
month = oct,
doi = {10.48550/arxiv.2610.24147},
eprint = {2610.24147},
archivePrefix = {arXiv},
url = {https://arxiv.org/abs/2610.24147},
note = {CC BY 4.0},
}
RIS
TY - UNPB
TI - lepidoptera: A Domain-Agnostic Engine for Causal Simulation with Mixed Variable Types, Vine Copula Dependence, and Individual-Level Counterfactual Propagation
AU - Danilo Augusto Sarti
PY - 2026
DA - 2026/10/16
PB - arXiv
DO - 10.48550/arxiv.2610.24147
UR - https://arxiv.org/abs/2610.24147
AB - lepidoptera is an open-source R and Python package for simulation from structural causal models with heterogeneous variable types. The package is built around a typed mechanism architecture, which separates the causal graph from the generating rule at each node and exposes each rule as an inspectable, serialisable object. A pre-built mechanism library covers all nine combinations of continuous, categorical, and ordinal parent and child types, removing the need for users to implement type-specific sampling from scratch. A vine copula mechanism estimates the full joint dependence structure from observed data using pair-copula constructions and the Rosenblatt conditional-simulation algorithm, supporting over twenty copula families. Individual-level counterfactual queries are supported through partial propagation, which freezes the random draws of unaffected nodes and replays only the downstream consequences of an intervention, thereby separating the individual treatment effect (ITE) estimand from the population-level average treatment effect (ATE) without additional model assumptions. An extension layer allows any pre-fitted predictive model to serve as a generative mechanism via a unified callable interface. Three worked illustrations spanning clinical trial planning, emergency-ward capacity analysis, and epidemiological mediation analysis demonstrate the package's scope.
ER -