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.