🌿 EcoStackML

Stacked Machine Learning Framework for Environmental and Tabular Data

EcoStackML is a modular and production-ready Python framework that leverages stacked machine learning techniques to deliver robust and explainable models for classification and regression tasks. Designed for environmental researchers, data scientists, and ML engineers.

---

🚀 Features

• ✅ Supports multiple base models (Random Forest, XGBoost, SVM, etc.)
• 🧠 Meta-learner for model stacking (e.g., Logistic Regression, Gradient Boosting)
• 📊 Built-in evaluation: ROC-AUC, PR Curve, SHAP plots, confusion matrix
• 🧽 Preprocessing pipeline with anomaly removal, scaling, imputation
• 📅 Automatic datetime feature extraction
• 💾 Save and load models, predictions, and metrics
• 📓 Includes Jupyter notebooks (01–07) with step-by-step tutorials
• 🔧 YAML-based configuration & logging setup

---

🛠 Installation

pip install .

For development:

pip install .[dev]

---

⚙️ Configuration (config.yaml)

data:
path: "data/raw/sample.csv"target_column: "target"preprocessing:
missing_strategy: "median"scaling: "standard"anomaly_method: "iqr"datetime_cols: []model:
base_models:
- name: "random_forest"
- name: "xgboost"meta_model: "logistic"model_type: "classification"split:
test_size: 0.2stratify: truerandom_state: 42output:
model_dir: "models/"results_dir: "results/"

---

🧪 Quickstart

fromecostackml.data.loaderimportDataLoaderfromecostackml.preprocessing.cleanerimportCleanerfromecostackml.data.splitterimportsplit_datafromecostackml.models.stackerimportModelStackerfromecostackml.models.evaluatorimportevaluate_classificationdf=DataLoader.from_csv("data/raw/sample.csv")
df["target"] = [0, 0, 1, 0, 1]
cleaner=Cleaner(strategy="median", scaling="standard", anomaly_method="iqr")
df_clean=cleaner.fit_transform(df)
X_train, X_test, _, y_train, y_test, _=split_data(df_clean, target_column="target")
stacker=ModelStacker(
base_models_config=[{"name": "random_forest"}, {"name": "xgboost"}],
meta_model_name="logistic",
model_type="classification"
)
stacker.fit(X_train, y_train)
y_pred=stacker.predict(X_test)

---

📈 Evaluation & SHAP

fromecostackml.models.evaluatorimportevaluate_classificationmetrics=evaluate_classification(y_test, y_pred, plot=True)
stacker.explain_base_models(X_test)
stacker.explain_meta_model(X_test)

---

💾 Save / Load

fromecostackml.utils.save_loadimportsave_model, load_model, save_stacker, load_stackersave_model(stacker.meta_model.model, "models/meta_model.pkl")
save_stacker(stacker, "models/full_stacker.pkl")
restored=load_stacker("models/full_stacker.pkl")
restored.predict(X_test)

---

📁 Project Structure

EcoStackML/
├── src/ecostackml/
│ ├── data/
│ ├── preprocessing/
│ ├── models/
│ └── utils/
├── notebooks/
├── main.py
├── config.yaml
├── pyproject.toml
└── README.md

---

📚 Notebooks

• 01_data_loading.ipynb – loading CSV, JSON, Parquet, Hive
• 02_cleaning_and_preprocessing.ipynb – full preprocessing
• 03_model_training.ipynb – base + stacking models
• 04_model_evaluation.ipynb – metrics & visualization
• 05_shap_explainer.ipynb – explainability
• 06_full_pipeline.ipynb – complete pipeline
• 07_save_and_load.ipynb – serialization demo

---

🤝 Contributing

Feel free to fork, contribute, and suggest improvements!

---

📜 License

MIT © 2025 Tymoteusz Miller