easeai 0.1.0__tar.gz

easeai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

easeai-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: easeai
+Version: 0.1.0
+Summary: Reusable XGBoost + SHAP workflow for tabular regression explainability
+Author: Ria A. Martins
+License: MIT
+Project-URL: Homepage, https://github.com/martinsria7/easeai
+Project-URL: Repository, https://github.com/martinsria7/easeai
+Project-URL: Issues, https://github.com/martinsria7/easeai/issues
+Keywords: xgboost,shap,tabular,xai,regression
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: xgboost>=2.0
+Requires-Dist: shap>=0.45
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: Pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# EASEai
+
+<p align="center">
+  <a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-blue.svg"></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
+  <img alt="Status" src="https://img.shields.io/badge/status-alpha-orange.svg">
+  <img alt="XGBoost" src="https://img.shields.io/badge/model-XGBoost-5C8A3D.svg">
+  <img alt="SHAP" src="https://img.shields.io/badge/explainability-SHAP-7A3E9D.svg">
+</p>
+
+<p align="center"><strong>Explainable AI for epidemiology and public health.</strong></p>
+
+`easeai` is a lightweight Python package for **tabular regression explainability** built around a practical research workflow:
+
+- XGBoost hyperparameter tuning
+- iterative feature elimination based on XGBoost importance
+- cross-validated RMSE and R²
+- SHAP feature ranking
+- partial dependence plots
+- row-level dominant driver extraction
+
+It was extracted from a county-level environmental health workflow, but the package is intentionally general so others can use it on any tabular regression dataset.
+
+## Why use EASEai?
+
+Many research notebooks mix together preprocessing, model tuning, feature selection, evaluation, and explainability in one place. `easeai` turns that into a reusable package for researchers who want:
+
+- a quick XGBoost + SHAP baseline
+- interpretable feature ranking
+- reproducible artifact export
+- a cleaner starting point for GitHub or publication-oriented workflows
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or after publication:
+
+```bash
+pip install easeai
+```
+
+## Minimal example
+
+```python
+import pandas as pd
+import easeai as ea
+
+
+df = pd.read_csv("Alzheimer_merged1.csv", encoding="ISO-8859-1")
+
+workflow = ea.TabularXAIRegressor(
+    target="AD_PREV_MEAN",
+    drop_columns=["Counties", "FIPS"],
+    target_n_features=15,
+)
+
+workflow.fit(df)
+results = workflow.summarize(id_column="FIPS", name_column="Counties")
+
+print(results.selected_features)
+print(results.metrics)
+print(results.shap_importance.head())
+
+results.top_drivers[["id", "name", "top_driver"]].to_csv("county_top_drivers.csv", index=False)
+workflow.export_artifacts("artifacts")
+```
+
+## Package structure
+
+```text
+easeai/
+  data.py        # preprocessing helpers
+  model.py       # tuning, CV, recursive elimination
+  explain.py     # SHAP summaries and top-driver extraction
+  plotting.py    # SHAP and PDP export helpers
+  workflow.py    # end-to-end workflow class
+```
+
+## Suggested GitHub topics
+
+`xgboost`, `shap`, `explainable-ai`, `tabular-data`, `epidemiology`, `public-health`, `machine-learning`, `python`
+
+## Roadmap
+
+- add classification support
+- add permutation importance
+- add bootstrap confidence intervals
+- add optional map-ready exports
+- publish on PyPI
+
+## Development
+
+```bash
+pytest
+```
+
+## License
+
+MIT
+
+## Author
+
+Ria A. Martins

easeai-0.1.0/README.md

@@ -0,0 +1,106 @@
+# EASEai
+
+<p align="center">
+  <a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-blue.svg"></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
+  <img alt="Status" src="https://img.shields.io/badge/status-alpha-orange.svg">
+  <img alt="XGBoost" src="https://img.shields.io/badge/model-XGBoost-5C8A3D.svg">
+  <img alt="SHAP" src="https://img.shields.io/badge/explainability-SHAP-7A3E9D.svg">
+</p>
+
+<p align="center"><strong>Explainable AI for epidemiology and public health.</strong></p>
+
+`easeai` is a lightweight Python package for **tabular regression explainability** built around a practical research workflow:
+
+- XGBoost hyperparameter tuning
+- iterative feature elimination based on XGBoost importance
+- cross-validated RMSE and R²
+- SHAP feature ranking
+- partial dependence plots
+- row-level dominant driver extraction
+
+It was extracted from a county-level environmental health workflow, but the package is intentionally general so others can use it on any tabular regression dataset.
+
+## Why use EASEai?
+
+Many research notebooks mix together preprocessing, model tuning, feature selection, evaluation, and explainability in one place. `easeai` turns that into a reusable package for researchers who want:
+
+- a quick XGBoost + SHAP baseline
+- interpretable feature ranking
+- reproducible artifact export
+- a cleaner starting point for GitHub or publication-oriented workflows
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or after publication:
+
+```bash
+pip install easeai
+```
+
+## Minimal example
+
+```python
+import pandas as pd
+import easeai as ea
+
+
+df = pd.read_csv("Alzheimer_merged1.csv", encoding="ISO-8859-1")
+
+workflow = ea.TabularXAIRegressor(
+    target="AD_PREV_MEAN",
+    drop_columns=["Counties", "FIPS"],
+    target_n_features=15,
+)
+
+workflow.fit(df)
+results = workflow.summarize(id_column="FIPS", name_column="Counties")
+
+print(results.selected_features)
+print(results.metrics)
+print(results.shap_importance.head())
+
+results.top_drivers[["id", "name", "top_driver"]].to_csv("county_top_drivers.csv", index=False)
+workflow.export_artifacts("artifacts")
+```
+
+## Package structure
+
+```text
+easeai/
+  data.py        # preprocessing helpers
+  model.py       # tuning, CV, recursive elimination
+  explain.py     # SHAP summaries and top-driver extraction
+  plotting.py    # SHAP and PDP export helpers
+  workflow.py    # end-to-end workflow class
+```
+
+## Suggested GitHub topics
+
+`xgboost`, `shap`, `explainable-ai`, `tabular-data`, `epidemiology`, `public-health`, `machine-learning`, `python`
+
+## Roadmap
+
+- add classification support
+- add permutation importance
+- add bootstrap confidence intervals
+- add optional map-ready exports
+- publish on PyPI
+
+## Development
+
+```bash
+pytest
+```
+
+## License
+
+MIT
+
+## Author
+
+Ria A. Martins

easeai-0.1.0/easeai/__init__.py

@@ -0,0 +1,4 @@
+from .workflow import TabularXAIRegressor
+
+__all__ = ["TabularXAIRegressor"]
+__version__ = "0.1.0"

easeai-0.1.0/easeai/data.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Iterable, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+
+def preprocess_frame(
+    df: pd.DataFrame,
+    target: str,
+    drop_columns: Optional[Iterable[str]] = None,
+    fill_strategy: str = "median",
+    coerce_numeric: bool = True,
+    clean_column_names: bool = True,
+) -> Tuple[pd.DataFrame, pd.Series]:
+    """Prepare a tabular dataframe for XGBoost regression.
+
+    Parameters
+    ----------
+    df:
+        Input dataframe.
+    target:
+        Name of target column.
+    drop_columns:
+        Extra identifier or metadata columns to remove from the feature matrix.
+    fill_strategy:
+        One of {"median", "mean", "zero", "drop"}.
+    coerce_numeric:
+        Convert feature columns to numeric, coercing non-numeric values to NaN.
+    clean_column_names:
+        Replace non-alphanumeric characters with underscores.
+
+    Returns
+    -------
+    X, y
+    """
+    if target not in df.columns:
+        raise KeyError(f"Target column '{target}' not found in dataframe.")
+
+    drop_columns = list(drop_columns or [])
+    y = pd.to_numeric(df[target], errors="raise")
+
+    feature_drop = [target] + [c for c in drop_columns if c in df.columns]
+    X = df.drop(columns=feature_drop).copy()
+
+    if coerce_numeric:
+        X = X.apply(pd.to_numeric, errors="coerce")
+
+    X = X.replace([np.inf, -np.inf], np.nan)
+
+    if fill_strategy == "median":
+        X = X.fillna(X.median(numeric_only=True))
+    elif fill_strategy == "mean":
+        X = X.fillna(X.mean(numeric_only=True))
+    elif fill_strategy == "zero":
+        X = X.fillna(0)
+    elif fill_strategy == "drop":
+        valid_rows = X.notna().all(axis=1)
+        X = X.loc[valid_rows].copy()
+        y = y.loc[valid_rows].copy()
+    else:
+        raise ValueError("fill_strategy must be one of: median, mean, zero, drop")
+
+    if clean_column_names:
+        X.columns = (
+            X.columns.str.replace(r"[^A-Za-z0-9_]+", "_", regex=True)
+            .str.strip("_")
+        )
+
+    return X, y

easeai-0.1.0/easeai/explain.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+import shap
+
+
+def compute_shap_values(model, X: pd.DataFrame):
+    explainer = shap.TreeExplainer(model)
+    shap_values = explainer.shap_values(X)
+    return explainer, shap_values
+
+
+
+def shap_importance_table(shap_values, X: pd.DataFrame) -> pd.DataFrame:
+    return (
+        pd.DataFrame(
+            {
+                "feature": X.columns,
+                "mean_abs_shap": np.abs(shap_values).mean(axis=0),
+            }
+        )
+        .sort_values("mean_abs_shap", ascending=False)
+        .reset_index(drop=True)
+    )
+
+
+
+def county_top_drivers(
+    shap_values,
+    X: pd.DataFrame,
+    id_col: Optional[pd.Series] = None,
+    name_col: Optional[pd.Series] = None,
+) -> pd.DataFrame:
+    shap_df = pd.DataFrame(shap_values, columns=X.columns)
+    if id_col is not None:
+        shap_df["id"] = list(id_col)
+    if name_col is not None:
+        shap_df["name"] = list(name_col)
+    shap_df["top_driver"] = shap_df[X.columns].abs().idxmax(axis=1)
+    return shap_df

easeai-0.1.0/easeai/model.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Optional, Tuple
+
+import pandas as pd
+from sklearn.model_selection import KFold, RandomizedSearchCV, cross_val_score
+from xgboost import XGBRegressor
+
+
+DEFAULT_PARAM_DIST: Dict[str, Iterable] = {
+    "n_estimators": [300, 500, 700, 900],
+    "max_depth": [3, 4, 5, 6, 7],
+    "learning_rate": [0.01, 0.03, 0.05, 0.1, 0.2],
+    "subsample": [0.5, 0.7, 0.85, 1.0],
+    "colsample_bytree": [0.7, 0.8, 0.9, 1.0],
+    "min_child_weight": [1, 3, 5, 7, 10],
+    "gamma": [0, 1, 2, 3, 5],
+    "reg_alpha": [0, 0.1, 0.5, 1.0],
+    "reg_lambda": [1, 3, 5, 10],
+}
+
+
+def make_cv(n_splits: int = 5, shuffle: bool = True, random_state: int = 42) -> KFold:
+    return KFold(n_splits=n_splits, shuffle=shuffle, random_state=random_state)
+
+
+def tune_xgb_regressor(
+    X: pd.DataFrame,
+    y: pd.Series,
+    param_distributions: Optional[Dict[str, Iterable]] = None,
+    n_iter: int = 30,
+    cv: Optional[KFold] = None,
+    scoring: str = "neg_root_mean_squared_error",
+    random_state: int = 42,
+    n_jobs: int = -1,
+    tree_method: str = "hist",
+    verbose: int = 0,
+) -> Tuple[XGBRegressor, RandomizedSearchCV]:
+    """Tune an XGBRegressor using randomized search."""
+    cv = cv or make_cv(random_state=random_state)
+    base_model = XGBRegressor(
+        objective="reg:squarederror",
+        random_state=random_state,
+        n_jobs=n_jobs,
+        tree_method=tree_method,
+    )
+
+    search = RandomizedSearchCV(
+        estimator=base_model,
+        param_distributions=param_distributions or DEFAULT_PARAM_DIST,
+        n_iter=n_iter,
+        scoring=scoring,
+        cv=cv,
+        random_state=random_state,
+        n_jobs=n_jobs,
+        verbose=verbose,
+        refit=True,
+    )
+    search.fit(X, y)
+    return search.best_estimator_, search
+
+
+def rfe_xgb(
+    model: XGBRegressor,
+    X: pd.DataFrame,
+    y: pd.Series,
+    target_n: int = 15,
+    drop_frac: float = 0.10,
+) -> List[str]:
+    """Iteratively drop the least important features until target_n remain."""
+    if target_n < 1:
+        raise ValueError("target_n must be >= 1")
+    if not 0 < drop_frac < 1:
+        raise ValueError("drop_frac must be between 0 and 1")
+    if target_n > X.shape[1]:
+        raise ValueError("target_n cannot exceed number of features")
+
+    features = list(X.columns)
+    while len(features) > target_n:
+        model.fit(X[features], y)
+        imp = pd.Series(model.feature_importances_, index=features).sort_values()
+        drop_n = max(1, int(len(features) * drop_frac))
+        drop_feats = imp.index[:drop_n].tolist()
+        features = [f for f in features if f not in drop_feats]
+    return features
+
+
+def evaluate_regression_cv(
+    model: XGBRegressor,
+    X: pd.DataFrame,
+    y: pd.Series,
+    cv: Optional[KFold] = None,
+    n_jobs: int = -1,
+) -> Dict[str, float]:
+    """Return mean and SD for RMSE and R^2 across CV folds."""
+    cv = cv or make_cv()
+    rmse_scores = -cross_val_score(
+        model,
+        X,
+        y,
+        scoring="neg_root_mean_squared_error",
+        cv=cv,
+        n_jobs=n_jobs,
+    )
+    r2_scores = cross_val_score(
+        model,
+        X,
+        y,
+        scoring="r2",
+        cv=cv,
+        n_jobs=n_jobs,
+    )
+    return {
+        "rmse_mean": float(rmse_scores.mean()),
+        "rmse_sd": float(rmse_scores.std()),
+        "r2_mean": float(r2_scores.mean()),
+        "r2_sd": float(r2_scores.std()),
+    }

easeai-0.1.0/easeai/plotting.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, Optional
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import shap
+from sklearn.inspection import PartialDependenceDisplay
+from PIL import Image
+
+
+
+def save_shap_summary(X: pd.DataFrame, shap_values, outpath: str, plot_type: Optional[str] = None, dpi: int = 300):
+    plt.figure()
+    shap.summary_plot(shap_values, X, plot_type=plot_type, show=False)
+    plt.tight_layout()
+    plt.savefig(outpath, dpi=dpi, bbox_inches="tight")
+    plt.close()
+
+
+
+def save_pdp_plots(model, X: pd.DataFrame, features: Iterable[str], outdir: str, grid_resolution: int = 60):
+    outdir = Path(outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+    saved = []
+    for feature in features:
+        fig, ax = plt.subplots(figsize=(5.5, 4.0))
+        PartialDependenceDisplay.from_estimator(
+            model,
+            X,
+            features=[feature],
+            kind="average",
+            grid_resolution=grid_resolution,
+            percentiles=(0.01, 0.99),
+            ax=ax,
+        )
+        ax.set_title(f"PDP: {feature}")
+        outpath = outdir / f"pdp_{str(feature)[:40].replace(' ', '_')}.png"
+        plt.tight_layout()
+        plt.savefig(outpath, dpi=300, bbox_inches="tight")
+        plt.close()
+        saved.append(str(outpath))
+    return saved
+
+
+
+def save_dependence_panel(X: pd.DataFrame, shap_values, top_vars: Iterable[str], outpath: str):
+    fig, axes = plt.subplots(2, 3, figsize=(12, 9))
+    axes = axes.ravel()
+    for i, var in enumerate(top_vars):
+        plt.sca(axes[i])
+        shap.dependence_plot(
+            ind=var,
+            shap_values=shap_values,
+            features=X,
+            interaction_index="auto",
+            show=False,
+            ax=axes[i],
+        )
+        axes[i].set_title(str(var))
+    plt.tight_layout()
+    plt.savefig(outpath, dpi=300, bbox_inches="tight")
+    plt.close()
+
+
+
+def combine_images_side_by_side(left_path: str, right_path: str, outpath: str):
+    left = Image.open(left_path)
+    right = Image.open(right_path)
+    target_h = max(left.height, right.height)
+    left = left.resize((int(left.width * target_h / left.height), target_h), Image.Resampling.LANCZOS)
+    right = right.resize((int(right.width * target_h / right.height), target_h), Image.Resampling.LANCZOS)
+    combined = Image.new("RGB", (left.width + right.width, target_h), (255, 255, 255))
+    combined.paste(left, (0, 0))
+    combined.paste(right, (left.width, 0))
+    combined.save(outpath)

easeai-0.1.0/easeai/workflow.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+import pandas as pd
+from xgboost import XGBRegressor
+
+from .data import preprocess_frame
+from .explain import compute_shap_values, county_top_drivers, shap_importance_table
+from .model import evaluate_regression_cv, make_cv, rfe_xgb, tune_xgb_regressor
+from .plotting import save_pdp_plots, save_shap_summary
+
+
+@dataclass
+class WorkflowResults:
+    selected_features: List[str]
+    metrics: dict
+    shap_importance: pd.DataFrame
+    top_drivers: pd.DataFrame
+
+
+class TabularXAIRegressor:
+    """End-to-end workflow for tabular regression with XGBoost + SHAP."""
+
+    def __init__(
+        self,
+        target: str,
+        drop_columns: Optional[Iterable[str]] = None,
+        target_n_features: int = 15,
+        random_state: int = 42,
+        n_iter_search: int = 15,
+    ):
+        self.target = target
+        self.drop_columns = list(drop_columns or [])
+        self.target_n_features = target_n_features
+        self.random_state = random_state
+        self.n_iter_search = n_iter_search
+        self.search_ = None
+        self.best_model_: Optional[XGBRegressor] = None
+        self.final_model_: Optional[XGBRegressor] = None
+        self.selected_features_: Optional[List[str]] = None
+        self.explainer_ = None
+        self.shap_values_ = None
+        self.X_selected_: Optional[pd.DataFrame] = None
+
+    def fit(self, df: pd.DataFrame) -> "TabularXAIRegressor":
+        X, y = preprocess_frame(
+            df,
+            target=self.target,
+            drop_columns=self.drop_columns,
+        )
+        cv = make_cv(random_state=self.random_state)
+        self.best_model_, self.search_ = tune_xgb_regressor(
+            X,
+            y,
+            cv=cv,
+            random_state=self.random_state,
+            n_iter=self.n_iter_search,
+        )
+        self.selected_features_ = rfe_xgb(
+            self.best_model_,
+            X,
+            y,
+            target_n=self.target_n_features,
+        )
+        self.final_model_ = XGBRegressor(
+            **self.search_.best_params_,
+            objective="reg:squarederror",
+            random_state=self.random_state,
+            n_jobs=-1,
+            tree_method="hist",
+        )
+        self.X_selected_ = X[self.selected_features_].copy()
+        self.final_model_.fit(self.X_selected_, y)
+        self.explainer_, self.shap_values_ = compute_shap_values(self.final_model_, self.X_selected_)
+        self.y_ = y
+        self.original_df_ = df.copy()
+        return self
+
+    def summarize(self, id_column: Optional[str] = None, name_column: Optional[str] = None) -> WorkflowResults:
+        if self.final_model_ is None or self.X_selected_ is None or self.selected_features_ is None:
+            raise RuntimeError("Call fit() before summarize().")
+        metrics = evaluate_regression_cv(self.final_model_, self.X_selected_, self.y_)
+        shap_rank = shap_importance_table(self.shap_values_, self.X_selected_)
+        top_drivers = county_top_drivers(
+            self.shap_values_,
+            self.X_selected_,
+            id_col=self.original_df_[id_column] if id_column and id_column in self.original_df_.columns else None,
+            name_col=self.original_df_[name_column] if name_column and name_column in self.original_df_.columns else None,
+        )
+        return WorkflowResults(
+            selected_features=self.selected_features_,
+            metrics=metrics,
+            shap_importance=shap_rank,
+            top_drivers=top_drivers,
+        )
+
+    def export_artifacts(self, outdir: str, top_k_pdp: int = 6) -> None:
+        if self.X_selected_ is None:
+            raise RuntimeError("Call fit() before export_artifacts().")
+        outdir = Path(outdir)
+        outdir.mkdir(parents=True, exist_ok=True)
+        save_shap_summary(self.X_selected_, self.shap_values_, str(outdir / "shap_beeswarm.png"))
+        save_shap_summary(self.X_selected_, self.shap_values_, str(outdir / "shap_bar.png"), plot_type="bar")
+        top_vars = list(self.X_selected_.columns[:top_k_pdp])
+        save_pdp_plots(self.final_model_, self.X_selected_, top_vars, str(outdir / "pdp_plots"))

easeai-0.1.0/easeai.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: easeai
+Version: 0.1.0
+Summary: Reusable XGBoost + SHAP workflow for tabular regression explainability
+Author: Ria A. Martins
+License: MIT
+Project-URL: Homepage, https://github.com/martinsria7/easeai
+Project-URL: Repository, https://github.com/martinsria7/easeai
+Project-URL: Issues, https://github.com/martinsria7/easeai/issues
+Keywords: xgboost,shap,tabular,xai,regression
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: xgboost>=2.0
+Requires-Dist: shap>=0.45
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: Pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# EASEai
+
+<p align="center">
+  <a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-blue.svg"></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
+  <img alt="Status" src="https://img.shields.io/badge/status-alpha-orange.svg">
+  <img alt="XGBoost" src="https://img.shields.io/badge/model-XGBoost-5C8A3D.svg">
+  <img alt="SHAP" src="https://img.shields.io/badge/explainability-SHAP-7A3E9D.svg">
+</p>
+
+<p align="center"><strong>Explainable AI for epidemiology and public health.</strong></p>
+
+`easeai` is a lightweight Python package for **tabular regression explainability** built around a practical research workflow:
+
+- XGBoost hyperparameter tuning
+- iterative feature elimination based on XGBoost importance
+- cross-validated RMSE and R²
+- SHAP feature ranking
+- partial dependence plots
+- row-level dominant driver extraction
+
+It was extracted from a county-level environmental health workflow, but the package is intentionally general so others can use it on any tabular regression dataset.
+
+## Why use EASEai?
+
+Many research notebooks mix together preprocessing, model tuning, feature selection, evaluation, and explainability in one place. `easeai` turns that into a reusable package for researchers who want:
+
+- a quick XGBoost + SHAP baseline
+- interpretable feature ranking
+- reproducible artifact export
+- a cleaner starting point for GitHub or publication-oriented workflows
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or after publication:
+
+```bash
+pip install easeai
+```
+
+## Minimal example
+
+```python
+import pandas as pd
+import easeai as ea
+
+
+df = pd.read_csv("Alzheimer_merged1.csv", encoding="ISO-8859-1")
+
+workflow = ea.TabularXAIRegressor(
+    target="AD_PREV_MEAN",
+    drop_columns=["Counties", "FIPS"],
+    target_n_features=15,
+)
+
+workflow.fit(df)
+results = workflow.summarize(id_column="FIPS", name_column="Counties")
+
+print(results.selected_features)
+print(results.metrics)
+print(results.shap_importance.head())
+
+results.top_drivers[["id", "name", "top_driver"]].to_csv("county_top_drivers.csv", index=False)
+workflow.export_artifacts("artifacts")
+```
+
+## Package structure
+
+```text
+easeai/
+  data.py        # preprocessing helpers
+  model.py       # tuning, CV, recursive elimination
+  explain.py     # SHAP summaries and top-driver extraction
+  plotting.py    # SHAP and PDP export helpers
+  workflow.py    # end-to-end workflow class
+```
+
+## Suggested GitHub topics
+
+`xgboost`, `shap`, `explainable-ai`, `tabular-data`, `epidemiology`, `public-health`, `machine-learning`, `python`
+
+## Roadmap
+
+- add classification support
+- add permutation importance
+- add bootstrap confidence intervals
+- add optional map-ready exports
+- publish on PyPI
+
+## Development
+
+```bash
+pytest
+```
+
+## License
+
+MIT
+
+## Author
+
+Ria A. Martins

easeai-0.1.0/easeai.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+easeai/__init__.py
+easeai/data.py
+easeai/explain.py
+easeai/model.py
+easeai/plotting.py
+easeai/workflow.py
+easeai.egg-info/PKG-INFO
+easeai.egg-info/SOURCES.txt
+easeai.egg-info/dependency_links.txt
+easeai.egg-info/requires.txt
+easeai.egg-info/top_level.txt
+tests/test_basic.py
+tests/test_import.py

easeai-0.1.0/easeai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

easeai-0.1.0/easeai.egg-info/requires.txt

@@ -0,0 +1,10 @@
+numpy>=1.24
+pandas>=2.0
+scikit-learn>=1.3
+xgboost>=2.0
+shap>=0.45
+matplotlib>=3.8
+Pillow>=10.0
+
+[dev]
+pytest>=8.0

easeai-0.1.0/easeai.egg-info/top_level.txt

@@ -0,0 +1 @@
+easeai

easeai-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "easeai"
+version = "0.1.0"
+description = "Reusable XGBoost + SHAP workflow for tabular regression explainability"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+  {name = "Ria A. Martins"}
+]
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "scikit-learn>=1.3",
+  "xgboost>=2.0",
+  "shap>=0.45",
+  "matplotlib>=3.8",
+  "Pillow>=10.0",
+]
+keywords = ["xgboost", "shap", "tabular", "xai", "regression"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+[project.urls]
+Homepage = "https://github.com/martinsria7/easeai"
+Repository = "https://github.com/martinsria7/easeai"
+Issues = "https://github.com/martinsria7/easeai/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["easeai*"]

easeai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

easeai-0.1.0/tests/test_basic.py

@@ -0,0 +1,26 @@
+import pandas as pd
+import numpy as np
+import easeai as ea
+
+
+def test_basic_fit():
+    rng = np.random.default_rng(42)
+    df = pd.DataFrame({
+        "x1": rng.normal(size=100),
+        "x2": rng.normal(size=100),
+        "FIPS": range(100),
+        "Counties": [f"c{i}" for i in range(100)],
+    })
+    df["y"] = 2 * df["x1"] - 0.5 * df["x2"] + rng.normal(scale=0.1, size=100)
+
+    workflow = ea.TabularXAIRegressor(
+        target="y",
+        drop_columns=["FIPS", "Counties"],
+        target_n_features=2,
+    )
+
+    workflow.fit(df)
+    results = workflow.summarize(id_column="FIPS", name_column="Counties")
+
+    assert len(results.selected_features) > 0
+    assert results.metrics is not None

easeai-0.1.0/tests/test_import.py

@@ -0,0 +1,5 @@
+import easeai
+
+
+def test_import():
+    assert hasattr(easeai, "TabularXAIRegressor")