imbreg 0.1.0__tar.gz

imbreg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Oliveros
+
+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.

imbreg-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+prune examples
+prune tests
+prune Datasets
+prune Output
+prune Results
+prune Plots
+exclude test.csv
+exclude relevant_pct_all_datasets.txt
+exclude generate_chapter4_plots.py

imbreg-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: imbreg
+Version: 0.1.0
+Summary: A Python library for Imbalanced Regression with SMOGN, stratified CV, and utility-based metrics.
+Author: Gabriel Oliveros
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/goliverosj/imbreg
+Project-URL: Issues, https://github.com/goliverosj/imbreg/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: xgboost
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Requires-Dist: plotly
+Dynamic: license-file
+
+# imbreg
+
+![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)
+![Status](https://img.shields.io/badge/status-production_ready-brightgreen.svg)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**imbreg** is a powerful Python library specifically designed to tackle the **Imbalanced Regression** problem. It facilitates the processing of datasets with missing values, applies advanced synthetic over-sampling techniques like SMOGN (Synthetic Minority Over-sampling Technique for Regression with Gaussian Noise), evaluates predictive models using utility-based metrics, and manages stratified cross-validation partitioning.
+
+---
+
+## Key Features
+
+- **SMOGN Resampling (DIBS):** Generates synthetic examples for extreme minority values in continuous domains using the DIBS strategy (a combination of SmoteR interpolation and GaussNoise perturbation).
+- **Stratified Partitioning:** Implements purely stratified cross-validation (CV) algorithms to ensure that extreme values are evenly distributed across folds.
+- **Robust Data Imputation:** Native integration with iterative algorithms (Scikit-Learn IterativeImputer) that prevents data leakage between training and test partitions.
+- **Advanced Utility-based Metrics:** Precise calculation of specialized metrics for imbalanced regression:
+  - **Utility-based F1-Score** ($\beta$-measure).
+  - **SERA** (Squared Error Relevance Area).
+- **Dataset Loading (KEEL/CSV/ARFF):** A smart data loader that infers categorical variables, caps decimals, maps ranges, and cleans noisy values automatically.
+- **Data Visualization:** Built-in 2D and 3D plotting modules (using Plotly, Seaborn) to visually analyze the relevance of the target variable and the impact of noise/distribution.
+
+---
+
+## Requirements and Installation
+
+To use this library, ensure you have Python 3.9 or higher installed. The main dependencies are built around the classic data science ecosystem.
+
+```bash
+pip install imbreg
+```
+
+---
+
+## Quickstart Guide
+
+Here is a quick snippet of how to use the core functions:
+
+### 1. Generate Partitions (Cross-Validation)
+
+The `cv_partitions` function will take care of reading your original dataset, cleaning it, performing missing data imputation, and injecting SMOGN oversampling automatically into each repetition.
+
+```python
+from imbreg import cv_partitions
+
+cv_partitions(
+    ds_name="my_dataset.csv",
+    ds_location="raw_data/",
+    times=1,                 # Number of repetitions
+    folds=10,                # Number of partitions (k-fold)
+    strat=True,              # Enable stratification
+    smogn=True,              # Apply SMOGN during training
+    impute=True,             # Impute missing values (NaNs)
+    out_dir="Output/"        # Output directory for raw data partitions
+)
+```
+
+### 2. Evaluate Predictions
+
+Once the physical folds are generated on your disk, you can automatically train the algorithms and retrieve the results summary containing SERA and F1 metrics.
+
+```python
+from imbreg import evaluate_folds
+
+results = evaluate_folds(
+    output_dir="Output/",    # Directory containing the generated folds
+    dataset="my_dataset",
+    model_type="rf",         # 'rf' (Random Forest), 'et' (Extra Trees), 'xgb' (XGBoost)
+    n_reps=1,
+    n_folds=10,
+    use_imputation=True,
+    use_smogn=True,
+    thr_rel=0.8              # Relevance threshold to define "rare" cases
+)
+
+# You can export these results to a flat structure using the built-in exporter
+from imbreg.validation import export_experiment_summaries
+export_experiment_summaries(results, output_dir="Results/", dataset_name="my_dataset", flat_output=True)
+```
+
+### 3. Visualize the Data
+
+Analyze the relevance curve of your target variable:
+
+```python
+import matplotlib.pyplot as plt
+from imbreg import read_dataset, phi_control, plot_target_distribution
+
+# Load dataset and create relevance control structure
+df = read_dataset("my_dataset.csv", "raw_data/")
+ctrl = phi_control(df["y"].values, method="extremes")
+
+# Visualize distribution vs relevance
+fig = plot_target_distribution(df, target_col="y", phi_ctrl=ctrl, thr_rel=0.8)
+plt.show()
+```
+
+---
+
+## Project Structure
+
+```text
+imbreg/
+│
+├── data_loader.py    # I/O functions (CSV/KEEL) and imputation wrappers
+├── metrics.py        # Mathematical evaluation functions (Utility F1, SERA, Bumps)
+├── models.py         # Training and prediction wrappers (RF, ET, XGBoost)
+├── plots.py          # Advanced visualizations (Histograms, Scatters, Prediction Error)
+├── resampling.py     # Core engine for the DIBS strategy (SMOGN for regression)
+├── stratification.py # Phi function (relevance) and K-Folds generators
+├── utils.py          # Math operations, distance metrics, and internal helpers
+└── validation.py     # Cross-validation evaluation pipeline and result export
+```
+
+### Folder Architecture for Experiments
+
+When running the full validation pipeline, the project enforces a clean separation of concerns:
+
+- **`Output/`**: Stores all heavy, raw data partitions generated by cross-validation and SMOGN.
+- **`Results/`**: A flat, clean directory containing only the final `.txt` and `.csv` summary metrics.
+
+---
+
+**Author: Gabriel Oliveros**

imbreg-0.1.0/README.md

@@ -0,0 +1,123 @@
+# imbreg
+
+![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)
+![Status](https://img.shields.io/badge/status-production_ready-brightgreen.svg)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**imbreg** is a powerful Python library specifically designed to tackle the **Imbalanced Regression** problem. It facilitates the processing of datasets with missing values, applies advanced synthetic over-sampling techniques like SMOGN (Synthetic Minority Over-sampling Technique for Regression with Gaussian Noise), evaluates predictive models using utility-based metrics, and manages stratified cross-validation partitioning.
+
+---
+
+## Key Features
+
+- **SMOGN Resampling (DIBS):** Generates synthetic examples for extreme minority values in continuous domains using the DIBS strategy (a combination of SmoteR interpolation and GaussNoise perturbation).
+- **Stratified Partitioning:** Implements purely stratified cross-validation (CV) algorithms to ensure that extreme values are evenly distributed across folds.
+- **Robust Data Imputation:** Native integration with iterative algorithms (Scikit-Learn IterativeImputer) that prevents data leakage between training and test partitions.
+- **Advanced Utility-based Metrics:** Precise calculation of specialized metrics for imbalanced regression:
+  - **Utility-based F1-Score** ($\beta$-measure).
+  - **SERA** (Squared Error Relevance Area).
+- **Dataset Loading (KEEL/CSV/ARFF):** A smart data loader that infers categorical variables, caps decimals, maps ranges, and cleans noisy values automatically.
+- **Data Visualization:** Built-in 2D and 3D plotting modules (using Plotly, Seaborn) to visually analyze the relevance of the target variable and the impact of noise/distribution.
+
+---
+
+## Requirements and Installation
+
+To use this library, ensure you have Python 3.9 or higher installed. The main dependencies are built around the classic data science ecosystem.
+
+```bash
+pip install imbreg
+```
+
+---
+
+## Quickstart Guide
+
+Here is a quick snippet of how to use the core functions:
+
+### 1. Generate Partitions (Cross-Validation)
+
+The `cv_partitions` function will take care of reading your original dataset, cleaning it, performing missing data imputation, and injecting SMOGN oversampling automatically into each repetition.
+
+```python
+from imbreg import cv_partitions
+
+cv_partitions(
+    ds_name="my_dataset.csv",
+    ds_location="raw_data/",
+    times=1,                 # Number of repetitions
+    folds=10,                # Number of partitions (k-fold)
+    strat=True,              # Enable stratification
+    smogn=True,              # Apply SMOGN during training
+    impute=True,             # Impute missing values (NaNs)
+    out_dir="Output/"        # Output directory for raw data partitions
+)
+```
+
+### 2. Evaluate Predictions
+
+Once the physical folds are generated on your disk, you can automatically train the algorithms and retrieve the results summary containing SERA and F1 metrics.
+
+```python
+from imbreg import evaluate_folds
+
+results = evaluate_folds(
+    output_dir="Output/",    # Directory containing the generated folds
+    dataset="my_dataset",
+    model_type="rf",         # 'rf' (Random Forest), 'et' (Extra Trees), 'xgb' (XGBoost)
+    n_reps=1,
+    n_folds=10,
+    use_imputation=True,
+    use_smogn=True,
+    thr_rel=0.8              # Relevance threshold to define "rare" cases
+)
+
+# You can export these results to a flat structure using the built-in exporter
+from imbreg.validation import export_experiment_summaries
+export_experiment_summaries(results, output_dir="Results/", dataset_name="my_dataset", flat_output=True)
+```
+
+### 3. Visualize the Data
+
+Analyze the relevance curve of your target variable:
+
+```python
+import matplotlib.pyplot as plt
+from imbreg import read_dataset, phi_control, plot_target_distribution
+
+# Load dataset and create relevance control structure
+df = read_dataset("my_dataset.csv", "raw_data/")
+ctrl = phi_control(df["y"].values, method="extremes")
+
+# Visualize distribution vs relevance
+fig = plot_target_distribution(df, target_col="y", phi_ctrl=ctrl, thr_rel=0.8)
+plt.show()
+```
+
+---
+
+## Project Structure
+
+```text
+imbreg/
+│
+├── data_loader.py    # I/O functions (CSV/KEEL) and imputation wrappers
+├── metrics.py        # Mathematical evaluation functions (Utility F1, SERA, Bumps)
+├── models.py         # Training and prediction wrappers (RF, ET, XGBoost)
+├── plots.py          # Advanced visualizations (Histograms, Scatters, Prediction Error)
+├── resampling.py     # Core engine for the DIBS strategy (SMOGN for regression)
+├── stratification.py # Phi function (relevance) and K-Folds generators
+├── utils.py          # Math operations, distance metrics, and internal helpers
+└── validation.py     # Cross-validation evaluation pipeline and result export
+```
+
+### Folder Architecture for Experiments
+
+When running the full validation pipeline, the project enforces a clean separation of concerns:
+
+- **`Output/`**: Stores all heavy, raw data partitions generated by cross-validation and SMOGN.
+- **`Results/`**: A flat, clean directory containing only the final `.txt` and `.csv` summary metrics.
+
+---
+
+**Author: Gabriel Oliveros**

imbreg-0.1.0/imbreg/__init__.py

@@ -0,0 +1,79 @@
+"""
+imbreg - Imbalanced Regression library.
+
+Public API
+----------
+Phi relevance
+    phi_control   - build relevance control structure
+    phi           - evaluate relevance for target values
+
+Resampling
+    dibs_regress  - DIBS strategy resampling (SmoteR + GaussNoise)
+
+Stratification / CV
+    cv_partitions - repeated K-fold CV with optional SMOGN + imputation
+    make_folds    - generate fold indices (stratified or random)
+
+Data I/O
+    read_dataset      - read KEEL-style .dat, csv and arff datasets
+    write_dataset     - write datasets (CSV/KEEL)
+    get_percentages   - compute % of rare cases per dataset
+    split_features_target - convenience X / y split
+"""
+
+from .stratification import phi_control, phi, cv_partitions, make_folds
+from .resampling import dibs_regress, safe_dibs_regress
+from .data_loader import (
+    read_dataset,
+    write_dataset,
+    get_percentages,
+    split_features_target,
+    encode_categoricals,
+    impute_train,
+    impute_test,
+)
+from .plots import (
+    plot_target_distribution,
+    plot_scatter_2d,
+    plot_scatter_3d,
+    plot_prediction_error,
+)
+from .metrics import utility_f1_score, sera_score
+from .validation import evaluate_folds, export_experiment_summaries, evaluate_predictions_from_files
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Phi relevance
+    "phi_control",
+    "phi",
+    # Resampling
+    "dibs_regress",
+    "safe_dibs_regress",
+    # CV partitioning
+    "cv_partitions",
+    "make_folds",
+    # Data I/O
+    "train_extra_trees",
+    "train_xgboost",
+    "predict_model",
+    "read_dataset",
+    "write_dataset",
+    "get_percentages",
+    "split_features_target",
+    "encode_categoricals",
+    # Imputation
+    "impute_train",
+    "impute_test",
+    # Visualization
+    "plot_target_distribution",
+    "plot_scatter_2d",
+    "plot_scatter_3d",
+    "plot_prediction_error",
+    # Metrics / Validation
+    "utility_f1_score",
+    "sera_score",
+    "evaluate_folds",
+    "export_experiment_summaries",
+    "evaluate_predictions_from_files",
+]