Metadata-Version: 2.4
Name: mini-causal
Version: 0.4.2
Summary: A machine learning decision intelligence framework that helps practitioners understand how feature changes influence model behavior, performance and business decisions
Author-email: Masemene Matlakana Benny <bennymasemene46@gmail.com>
Project-URL: Homepage, https://github.com/MasemeneMatlakanaBenny/Mini_Causal
Project-URL: Issues, https://github.com/MasemeneMatlakana/Mini_Causal/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: scipy>=1.11.3
Requires-Dist: pandas>=2.1.1
Requires-Dist: scikit-learn>=1.3.0
Dynamic: license-file

# Mini-Causal

![logo](images/cropped_logo.jpeg)

Mini-Causal is  machine learning decision intelligence framework that helps practitioners understand how feature changes influence model behavior, performance, and business decisions.

**Key features**
- **Causality tools:** compare models using causal metrics and tests.
- **Counterfactuals:** generate and evaluate counterfactual explanations.
- **Partial counterfactuals:** run targeted counterfactual analyses on subsets of features.
- **Batteries of examples:** runnable Jupyter notebooks demonstrating common workflows.

## Getting Started with mini-causal in a notebook

- Create and activate a virtual environment (PowerShell example):

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```





- Install the package:

```powershell
pip install mini-causal
```

**Quick after you loaded the data with X and y sets:
```python

import pandas as pd
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.linear_model import LogisticRegression
from mini_causal.partial_counter import PartialCounterfactualClassifier

X_train,X_test,y_train,y_test=train_test_split(X,y,test_size=0.2,random_state=42)

model=LogisticRegression(solver="liblinear")
model.fit(X_train,y_train)

counter_classifier=PartialCounterfactualClassifier(model=model,X=X_train,y=y_train)

## get the individual causal effects:
ind_causal_effect_age=counter_classifier.individual_causal_effects(X=X_train,feature="age")

##accuracy effect by the exclusion of the feature
age_acc_effect=counter_classifier.causal_effect_metric(X=X_train,
                                                       y=y_train,
                                                       metric="accuracy",
                                                       feature="age")

## recall effect
age_recall_effect=counter_classifier.causal_effect_metric(X=X_train,
                                                          y=y_train,
                                                          metric="recall",
                                                           feature="age")

##log-loss effect
age_log_loss_eff=counter_classifier.causal_effect_probs_metric(X=X_train,
                                                               y=y_train,
                                                               metric="log-loss",
                                                               feature="age")

## hamming-loss effect
age_hamming_loss_eff=counter_classifier.causal_effect_loss_metricX_train,y_train,metric="hamming-loss",feature="age")


## true negative effect
age_tn_effect=counter_classifier.causal_effect_confusion(X_train,y_train,metric="tn",
                                                                feature="age")

##true positive effect
age_tp_effect=counter_classifier.causal_effect_confusion(X_train,y_train,metric="tp",
                                                                feature="age")

##summarized tabular dataframe
tab_metrics_df=counter_classifier.causal_effect_metric_tab(X_train,
                                                           y_train,
                                                           feature="age"
)
```

**Examples**

This folder contains runnable Jupyter notebooks demonstrating `mini_causal` features.

Notebooks included

- ![mini_causal_partial_regression](examples/mini_causal_partial_regression_example.ipynb) — demonstrates the library in a regression workflow.
- ![mini_causal_partial_classification](examples/mini_causal_prostate_with_partial_counterfactual.ipynb) — demonstrates the library in a classification workflow.

## Citing mini-causal

If you use mini-causal in your research, please cite it:

```bibtex
@software{mini-causal,
  title = {mini-causal: A Decision Intelligence Framework for machine learning},
  author = {Masemene Matlakana Benny},
  year = {2026},
  url = {https://github.com/MasemeneMatlakanaBenny/Mini-Causal},
  doi = {10.5281/zenodo.19646175},
  license = {MIT},
}
```
See [`CITATION.cff`](https://github.com/MasemeneMatlakanaBenny/Mini-Causal/blob/main/CITATION.cff) for the full citation metadata.

## Contributing

See CONTRIBUTING.md for guidelines on reporting issues, opening pull requests, code style, and testing.

## License

This project is released under the terms of the MIT License.
