oversampleqa 0.5.1__tar.gz

oversampleqa-0.5.1/AUTHORS.md

@@ -0,0 +1,30 @@
+# Authors and Contributors
+
+## Lead Developer
+- **Diogo Ribeiro** ([@diogoribeiro7](https://github.com/diogoribeiro7))
+  - ESMAD - Instituto Politecnico do Porto
+  - Lead Data Scientist at Mysense.ai
+  - Email: dfr@esmad.ipp.pt
+  - ORCID: https://orcid.org/0009-0001-2022-7072
+
+## Contributors
+
+*Contributors will be listed here as they make contributions to the project.*
+
+### How to be Listed
+
+Contributors are automatically added when they:
+- Submit merged pull requests
+- Report bugs that lead to fixes
+- Contribute to documentation
+- Help with community support
+
+## Acknowledgments
+
+This project implements validation methodology from:
+- Hassanat et al., "Stop Oversampling for Class Imbalance Learning: A Critical Review" (2022)
+
+### Inspiration and References
+- scikit-learn community for API design patterns
+- imbalanced-learn for oversampling integration
+- NumPy and SciPy communities for numerical computing standards

oversampleqa-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OversampleQA contributors
+
+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.

oversampleqa-0.5.1/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: oversampleqa
+Version: 0.5.1
+Summary: A diagnostic toolkit to validate oversampling methods.
+License: MIT
+License-File: AUTHORS.md
+License-File: LICENSE
+Keywords: imbalanced-learning,oversampling,synthetic-data,validation,benchmarking,machine-learning
+Author: Diogo Ribeiro
+Author-email: dfr@esmad.ipp.pt
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Provides-Extra: performance
+Requires-Dist: click (>=8.1.7,<9.0.0)
+Requires-Dist: imbalanced-learn (>=0.14.0,<0.15.0)
+Requires-Dist: jinja2 (>=3.0.0,<4.0.0)
+Requires-Dist: matplotlib (>=3.5.0,<4.0.0)
+Requires-Dist: numpy (>=2.2.6,<3.0.0)
+Requires-Dist: pandas (>=2.3.0,<3.0.0)
+Requires-Dist: platformdirs (>=3.0)
+Requires-Dist: psutil (>=5.9) ; extra == "performance"
+Requires-Dist: pydantic (>=2.9.2,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: rich (>=14.2,<16.0)
+Requires-Dist: scikit-learn (>=1.0.0,<2.0.0)
+Requires-Dist: scipy (>=1.14,<2.0)
+Requires-Dist: seaborn (>=0.13.2,<0.14.0)
+Requires-Dist: tqdm (>=4.66) ; extra == "performance"
+Requires-Dist: umap-learn (>=0.5.0,<0.6.0)
+Project-URL: Bug Tracker, https://github.com/diogoribeiro7/OversampleQA/issues
+Project-URL: Changelog, https://github.com/diogoribeiro7/OversampleQA/blob/main/CHANGELOG.md
+Project-URL: Citation, https://github.com/diogoribeiro7/OversampleQA/blob/main/CITATION.cff
+Project-URL: Documentation, https://github.com/diogoribeiro7/OversampleQA/tree/main/docs
+Project-URL: Homepage, https://github.com/diogoribeiro7/OversampleQA
+Project-URL: Repository, https://github.com/diogoribeiro7/OversampleQA
+Description-Content-Type: text/markdown
+
+# OversampleQA
+
+[![CI](https://img.shields.io/github/actions/workflow/status/diogoribeiro7/OversampleQA/ci.yml?branch=main)](https://github.com/diogoribeiro7/OversampleQA/actions)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/oversampleqa.svg)](https://pypi.org/project/oversampleqa/)
+[![License](https://img.shields.io/github/license/diogoribeiro7/OversampleQA)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21940361.svg)](https://doi.org/10.5281/zenodo.21940361)
+
+A diagnostic toolkit to validate, audit, and benchmark oversampling methods for imbalanced classification.
+
+## What It Does
+
+- Validates oversampling quality with a hidden-majority error rate (binary and multiclass).
+- Offers a broad set of distance metrics (Hassanat, Euclidean, Mahalanobis, etc.).
+- Includes optimized and memory-efficient distance matrix computation.
+- Supports benchmarking across datasets and oversamplers with exportable results.
+- Provides a rich CLI with profiles, templates, shell completion, and diagnostics.
+- Extensible via a plugin system for custom metrics and validators.
+
+## Concepts
+
+OversampleQA validates synthetic samples by hiding a portion of the majority class and asking whether generated points look more like the hidden majority or the real minority. Each synthetic sample is scored by its nearest-neighbor distance to both groups using a chosen metric. If a synthetic sample is closer to the hidden majority than to the minority, it is counted as an error. The resulting error rate is a direct signal of how often oversampling produces majority-like artifacts. Lower error rates suggest better minority fidelity, but the absolute value depends on the dataset, metric, and hidden ratio. For multiclass data, the same idea generalizes to a confusion-style error matrix across classes.
+
+## Install
+
+Python 3.10+ is required. Install the latest release from PyPI:
+
+```bash
+pip install oversampleqa
+```
+
+For the optional performance helpers:
+
+```bash
+pip install "oversampleqa[performance]"
+```
+
+For development or unreleased changes, install from source:
+
+```bash
+git clone https://github.com/diogoribeiro7/OversampleQA.git
+cd OversampleQA
+poetry install
+```
+
+To depend on the current repository state from another project:
+
+```bash
+pip install git+https://github.com/diogoribeiro7/OversampleQA.git
+```
+
+## Quick Start (Python)
+
+```bash
+python - <<'PY'
+from sklearn.datasets import make_classification
+from imblearn.over_sampling import SMOTE
+from oversampleqa import validate_oversampling
+
+X, y = make_classification(
+    n_samples=1000,
+    n_features=20,
+    n_informative=10,
+    n_redundant=10,
+    n_clusters_per_class=1,
+    weights=[0.9, 0.1],
+    random_state=42,
+)
+
+error_rate = validate_oversampling(
+    X=X,
+    y=y,
+    minority_label=1,
+    oversampler=SMOTE(random_state=42),
+    hidden_ratio=0.1,
+    metric="hassanat",
+)
+
+print(f"SMOTE validation error rate: {error_rate:.3f}")
+PY
+```
+
+## CLI
+
+```bash
+oversampleqa --help
+```
+
+```bash
+oversampleqa validate data.csv \
+  --target target \
+  --minority-label 1 \
+  --oversampler SMOTE \
+  --metric hassanat \
+  --hidden-ratio 0.1 \
+  --export json \
+  --output runs
+```
+
+```bash
+oversampleqa profiles
+oversampleqa template --template production -o oversampleqa.yaml
+oversampleqa benchmark --output benchmark_results
+oversampleqa doctor
+```
+
+Legacy minimal CLI (if you prefer a smaller surface):
+
+```bash
+oversampleqa-validate --help
+```
+
+## Configuration
+
+The enhanced CLI loads configuration from `~/.oversampleqa/config.yaml` by default. You can override it with `--config` and select profiles with `--profile`.
+
+## Examples And Docs
+
+- Code samples live in `examples/` and `tutorials/`.
+- Sphinx documentation sources are in `docs/`.
+
+Build docs:
+
+```bash
+make docs
+```
+
+## Development
+
+```bash
+# One-liner
+make setup
+
+# Or run onboarding helper
+poetry run python scripts/onboard.py
+
+# Manual steps
+poetry install
+poetry run pre-commit install
+poetry run pre-commit install --hook-type commit-msg
+```
+
+## Quality Checks
+
+```bash
+# Lint and typecheck -- both pass clean
+make lint typecheck
+# Run tests with coverage
+make coverage
+# Security audit
+make security
+# Build docs the way CI does, with warnings as errors
+make docs
+# Full pre-commit suite
+poetry run pre-commit run --all-files
+```
+
+Linting and formatting are handled by [ruff](https://docs.astral.sh/ruff/) alone;
+the enforced rule set lives in `pyproject.toml`. These commands work on Windows
+and Linux alike.
+
+## Citation
+
+If you use OversampleQA in academic work, please cite it. Machine-readable metadata
+lives in `CITATION.cff`, which GitHub renders as a "Cite this repository" button.
+
+```bibtex
+@software{ribeiro_oversampleqa,
+  author  = {Ribeiro, Diogo},
+  title   = {{OversampleQA: a diagnostic toolkit to validate, audit,
+             and benchmark oversampling methods}},
+  version = {0.5.1},
+  year    = {2026},
+  doi     = {10.5281/zenodo.21940361},
+  url     = {https://doi.org/10.5281/zenodo.21940361}
+}
+```
+
+The DOI above is the concept DOI: it always resolves to the newest archived
+version. To cite an exact archived release, use the version DOI listed in
+`CITATION.cff` after Zenodo has minted it. See
+[Citing OversampleQA](docs/citation.rst) for the release and DOI sequence.
+
+## License
+
+MIT. See `LICENSE`.
+

oversampleqa-0.5.1/README.md

@@ -0,0 +1,186 @@
+# OversampleQA
+
+[![CI](https://img.shields.io/github/actions/workflow/status/diogoribeiro7/OversampleQA/ci.yml?branch=main)](https://github.com/diogoribeiro7/OversampleQA/actions)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/oversampleqa.svg)](https://pypi.org/project/oversampleqa/)
+[![License](https://img.shields.io/github/license/diogoribeiro7/OversampleQA)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21940361.svg)](https://doi.org/10.5281/zenodo.21940361)
+
+A diagnostic toolkit to validate, audit, and benchmark oversampling methods for imbalanced classification.
+
+## What It Does
+
+- Validates oversampling quality with a hidden-majority error rate (binary and multiclass).
+- Offers a broad set of distance metrics (Hassanat, Euclidean, Mahalanobis, etc.).
+- Includes optimized and memory-efficient distance matrix computation.
+- Supports benchmarking across datasets and oversamplers with exportable results.
+- Provides a rich CLI with profiles, templates, shell completion, and diagnostics.
+- Extensible via a plugin system for custom metrics and validators.
+
+## Concepts
+
+OversampleQA validates synthetic samples by hiding a portion of the majority class and asking whether generated points look more like the hidden majority or the real minority. Each synthetic sample is scored by its nearest-neighbor distance to both groups using a chosen metric. If a synthetic sample is closer to the hidden majority than to the minority, it is counted as an error. The resulting error rate is a direct signal of how often oversampling produces majority-like artifacts. Lower error rates suggest better minority fidelity, but the absolute value depends on the dataset, metric, and hidden ratio. For multiclass data, the same idea generalizes to a confusion-style error matrix across classes.
+
+## Install
+
+Python 3.10+ is required. Install the latest release from PyPI:
+
+```bash
+pip install oversampleqa
+```
+
+For the optional performance helpers:
+
+```bash
+pip install "oversampleqa[performance]"
+```
+
+For development or unreleased changes, install from source:
+
+```bash
+git clone https://github.com/diogoribeiro7/OversampleQA.git
+cd OversampleQA
+poetry install
+```
+
+To depend on the current repository state from another project:
+
+```bash
+pip install git+https://github.com/diogoribeiro7/OversampleQA.git
+```
+
+## Quick Start (Python)
+
+```bash
+python - <<'PY'
+from sklearn.datasets import make_classification
+from imblearn.over_sampling import SMOTE
+from oversampleqa import validate_oversampling
+
+X, y = make_classification(
+    n_samples=1000,
+    n_features=20,
+    n_informative=10,
+    n_redundant=10,
+    n_clusters_per_class=1,
+    weights=[0.9, 0.1],
+    random_state=42,
+)
+
+error_rate = validate_oversampling(
+    X=X,
+    y=y,
+    minority_label=1,
+    oversampler=SMOTE(random_state=42),
+    hidden_ratio=0.1,
+    metric="hassanat",
+)
+
+print(f"SMOTE validation error rate: {error_rate:.3f}")
+PY
+```
+
+## CLI
+
+```bash
+oversampleqa --help
+```
+
+```bash
+oversampleqa validate data.csv \
+  --target target \
+  --minority-label 1 \
+  --oversampler SMOTE \
+  --metric hassanat \
+  --hidden-ratio 0.1 \
+  --export json \
+  --output runs
+```
+
+```bash
+oversampleqa profiles
+oversampleqa template --template production -o oversampleqa.yaml
+oversampleqa benchmark --output benchmark_results
+oversampleqa doctor
+```
+
+Legacy minimal CLI (if you prefer a smaller surface):
+
+```bash
+oversampleqa-validate --help
+```
+
+## Configuration
+
+The enhanced CLI loads configuration from `~/.oversampleqa/config.yaml` by default. You can override it with `--config` and select profiles with `--profile`.
+
+## Examples And Docs
+
+- Code samples live in `examples/` and `tutorials/`.
+- Sphinx documentation sources are in `docs/`.
+
+Build docs:
+
+```bash
+make docs
+```
+
+## Development
+
+```bash
+# One-liner
+make setup
+
+# Or run onboarding helper
+poetry run python scripts/onboard.py
+
+# Manual steps
+poetry install
+poetry run pre-commit install
+poetry run pre-commit install --hook-type commit-msg
+```
+
+## Quality Checks
+
+```bash
+# Lint and typecheck -- both pass clean
+make lint typecheck
+# Run tests with coverage
+make coverage
+# Security audit
+make security
+# Build docs the way CI does, with warnings as errors
+make docs
+# Full pre-commit suite
+poetry run pre-commit run --all-files
+```
+
+Linting and formatting are handled by [ruff](https://docs.astral.sh/ruff/) alone;
+the enforced rule set lives in `pyproject.toml`. These commands work on Windows
+and Linux alike.
+
+## Citation
+
+If you use OversampleQA in academic work, please cite it. Machine-readable metadata
+lives in `CITATION.cff`, which GitHub renders as a "Cite this repository" button.
+
+```bibtex
+@software{ribeiro_oversampleqa,
+  author  = {Ribeiro, Diogo},
+  title   = {{OversampleQA: a diagnostic toolkit to validate, audit,
+             and benchmark oversampling methods}},
+  version = {0.5.1},
+  year    = {2026},
+  doi     = {10.5281/zenodo.21940361},
+  url     = {https://doi.org/10.5281/zenodo.21940361}
+}
+```
+
+The DOI above is the concept DOI: it always resolves to the newest archived
+version. To cite an exact archived release, use the version DOI listed in
+`CITATION.cff` after Zenodo has minted it. See
+[Citing OversampleQA](docs/citation.rst) for the release and DOI sequence.
+
+## License
+
+MIT. See `LICENSE`.