Computer scientists have introduced ACFX, an open-source software toolkit designed to generate actionable counterfactual explanations for machine learning models by incorporating explicit causal relationships and domain constraints. Counterfactual explanations provide human operators with concrete, example-based recommendations detailing how input features must be modified to achieve a desired algorithmic classification. In high-stakes operational environments where artificial intelligence informs critical decisions, such as industrial manufacturing process control, healthcare treatment planning, and cybersecurity monitoring, human decision-makers often need to reverse adverse predictions or remediate suboptimal system states. However, traditional counterfactual generation techniques frequently neglect underlying causal linkages between variables, producing mathematical recommendations that are physically impossible, practically unfeasible, or contradictory to real-world domain mechanics. ACFX addresses this systemic deficiency by embedding dependency graphs and conditional probability distributions directly into the counterfactual search procedure, ensuring that suggested interventions respect known structural dependencies.
The software toolkit serves as the primary implementation of the DANCE optimization framework, translating algorithmic recourse theory into a deployable software platform for both researchers and industry practitioners. By contrast, ACFX constrains the search space using dependency networks derived either from data-driven discovery algorithms or manually encoded expert specifications. The resulting recommendations guide users along realistic intervention paths, though the developers emphasize that the real-world actionability of any generated explanation ultimately depends on the fidelity of the supplied causal graph and requires rigorous validation by qualified domain specialists.
To produce balanced and operationally viable counterfactuals, ACFX implements a composite multi-criterion loss function that simultaneously regulates several competing quality dimensions: plausibility, diversity, sparsity, and proximity. The mathematical formulation balances an outer classification objective with an inner weighted sum of individual penalties, ensuring that the target class achieves the largest margin over competing classes while strictly managing feature perturbations. Specifically, the loss function evaluates instance-level class probabilities, enforcing that the desired label attains the highest probability relative to any alternative label. This objective is combined with a global scaling factor and individual weight parameters assigned to diversity loss, proximity loss, sparsity loss, and plausibility loss. Sparsity ensures that the explanation modifies as few features as possible to minimize intervention effort, proximity bounds the distance between the original instance and the synthetic point, diversity delivers multiple distinct alternative solutions, and plausibility ensures adherence to learned or specified structural constraints.
Managing the trade-offs among these competing criteria presents a complex optimization challenge, which ACFX resolves through integrated hyperparameter tuning. The toolkit embeds the Optuna framework to conduct automated Bayesian hyperparameter searches across the multi-objective loss landscape, identifying parameter configurations tailored to specific user priorities and task requirements. This automated search avoids tedious manual tuning of penalty weights, allowing data scientists to systematically explore the trade-off space between aggressive prediction-flipping confidence and conservative constraint satisfaction. Furthermore, because different industrial applications emphasize distinct operational requirements—such as minimizing the number of altered variables in manual manufacturing adjustments versus maximizing diversity in exploratory customer marketing—the configurable loss formulation allows stakeholders to directly modulate individual penalty weights to reflect domain priorities.
Architecturally, ACFX is organized around a modular, model-agnostic Core API that provides primary methods for model fitting and counterfactual generation through fit and counterfactual execution calls. The software interacts with predictive algorithms through a Custom Machine Learning Model Wrapper, which adapts any scikit-learn-compatible estimator to the internal optimization engine without requiring direct access to internal model parameters, weight tensors, or architectural layers. By abstracting the predictive model behind a standard interface, ACFX allows practitioners to evaluate counterfactual recourse across heterogeneous modeling pipelines without rewriting exploratory scripts or altering upstream production workflows.
To support users with varying levels of computational and technical expertise, the software provides two complementary interaction modalities: a lightweight Python software development kit and a graphical user interface developed in Streamlit. The Python SDK facilitates programmatic execution, batch evaluation, and embedding into larger research pipelines or production automation systems. The web dashboard coordinates the end-to-end analytical workflow across four sequential components: a dataset loader for ingesting and preprocessing tabular records, a model training module for fitting or importing estimators, a dependency structure module for generating and viewing relationship graphs, and a dedicated results panel that visualizes, filters, and exports generated counterfactual recommendations.
A central technical capability of ACFX is its flexible handling of causal and dependency structures, which can be represented either as linear relationship graphs or as probabilistic Bayesian networks. Users can supply predefined domain dependency matrices or infer them directly from observational datasets. For linear causal discovery, the toolkit integrates the DirectLiNGAM algorithm, mapping linear relationships among numerical variables into directed acyclic graphs. In the Streamlit dashboard, users can interactively inspect and modify these linear edges to incorporate specialized expert knowledge that data-driven discovery might have overlooked. In contrast, Bayesian network structures represented through conditional probability distributions must be supplied and modified programmatically via the Python API. The software intentionally restricts Bayesian network editing from the graphical dashboard because conditional probability tables become excessively difficult to manipulate manually when models encompass numerous discrete bins and interdependent graph nodes.
The practical utility of ACFX was demonstrated in an industrial case study conducted in collaboration with FreshMail, Poland’s largest email marketing platform, as part of the European Union-funded SendGuard quality assurance project. Researchers examined a dataset comprising 100,000 commercial email campaigns dispatched between 2019 and 2021, with feature sets capturing dispatch timing, recipient metrics, and subject line characteristics such as promotional percentages and emoji usage. An Explainable Boosting Machine was trained to classify campaigns into low-quality or high-quality performance tiers based on open rates, click-through rates, and recipient spam complaints, achieving an accuracy of 0.67 and a receiver operating characteristic area under the curve of 0.75. Domain specialists constructed a directed acyclic graph capturing marketing best practices, such as scheduling early morning dispatches to maximize reader engagement and minimizing aggressive promotional punctuation in formal sectors.
To quantify the difficulty and structural consequence of modifying individual variables, the research team formalized the concept of Total Intervention Pressure. This metric evaluates the upstream constraints and downstream influence of each node within the causal graph, establishing that variables situated as central network hubs with numerous ancestors and descendants entail substantial intervention friction, whereas peripheral root or leaf nodes represent low-cost intervention candidates. In the email marketing graph, dispatch hour was identified as a prime low-pressure candidate for manipulation. In a representative case study involving a low-quality cosmetics campaign dispatched at 11 AM with emojis and percentage symbols in the title, ACFX generated a sparse counterfactual recommending shifting delivery to 8 AM while eliminating emojis and percentage signs. Evaluated across 5,000 low-quality campaigns, ACFX flipped predictions to high quality in 64.96 percent of instances, with 87 percent of successful counterfactuals requiring only a single feature adjustment.
Beyond single-domain case evaluations, the underlying DANCE methodology implemented in ACFX was systematically benchmarked against alternative counterfactual algorithms across more than 140 public datasets. While established toolkits like DiCE, DCE, CEM, MACE, and CARLA emphasize distinct recourse objectives such as diversity or proximity, they frequently omit structural causal constraints or lack integrated graphical environments. In comparative evaluations, ACFX consistently ranked among the top-performing frameworks across fidelity, sparsity, plausibility, and computational execution speed. Specifically, the method achieved average benchmark ranks between 1.56 and 2.28 for feature sparsity, 2.23 for plausibility, and 2.28 for model fidelity, demonstrating statistically significant advantages over non-causal baselines. These benchmark results establish that integrating structural constraints does not compromise computational feasibility or algorithmic efficiency when processing large-scale tabular databases.
The ACFX software is publicly distributed under the permissive MIT license, ensuring full transparency, code auditability, and ease of commercial or academic integration. Developed for Python versions 3.11 through 3.14 on Windows and Linux platforms, the package is maintained on PyPI and accompanied by online documentation. Furthermore, while the system automates counterfactual discovery under specified constraints, algorithmic recourse cannot serve as an autonomous decision-making engine. Because statistical dependencies do not automatically guarantee physical realizability, generated counterfactual recommendations must be interpreted in light of the underlying assumptions and validated by domain professionals before executing operational changes in real-world systems.
Subject of Research: Causal and dependency-constrained counterfactual explanation software for tabular machine learning models
Article Title: ACFX: Actionable CounterFactual eXplainer
Article References: Bobek, S., Kubacki, P., Bałec, Ł., & Nalepa, G. J. (2026). ACFX: Actionable CounterFactual eXplainer. SoftwareX, 36, Article 103232. https://doi.org/10.1016/j.softx.2026.103232
Image Credits: AI Generated
DOI: 10.1016/j.softx.2026.103232
Keywords: counterfactual explanations, explainable artificial intelligence, causal constraints, ACFX software, DANCE framework, DirectLiNGAM, Bayesian networks, multi-criterion optimization, Optuna hyperparameter tuning, tabular data, model-agnostic explanations, Total Intervention Pressure, email marketing optimization, Explainable Boosting Machine, SendGuard project, Streamlit dashboard, algorithmic recourse, sparsity and plausibility
Cite Scienmag News
Blake Davidson. (November 21, 2026). Software Toolkit Generates Actionable Counterfactual Explanations Under Causal Constraints. Scienmag. https://scienmag.com/software-toolkit-generates-actionable-counterfactual-explanations-under-causal-constraints/
Blake Davidson. "Software Toolkit Generates Actionable Counterfactual Explanations Under Causal Constraints." Scienmag, 21 November 2026, https://scienmag.com/software-toolkit-generates-actionable-counterfactual-explanations-under-causal-constraints/. Accessed 21 November 2026.
Blake Davidson. "Software Toolkit Generates Actionable Counterfactual Explanations Under Causal Constraints." Scienmag. November 21, 2026. https://scienmag.com/software-toolkit-generates-actionable-counterfactual-explanations-under-causal-constraints/








