melite 0.2.2__tar.gz → 0.2.4__tar.gz

melite-0.2.4/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+.venv/
+.vscode/
+.tmp_stack_smoke/
+.env
+.pytest_tmp
+site/
+dist/
+output/
+
+data/
+!melite/_example_assets/data/
+
+raw/
+!melite/_example_assets/raw/
+
+*.npz
+!melite/_example_assets/data/sample_tabular.npz
+
+*.npy
+!melite/_example_assets/raw/labels.npy
+
+
+*.py[cod]
+*.pkl
+*.joblib
+
+tests_output.txt

{melite-0.2.2 → melite-0.2.4}/CHANGELOG.md

@@ -1,13 +1,117 @@
 # Changelog
 
-All notable changes to MELITE will be documented in this file.
+All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [v0.2.2] - 2026-05-28
+## [0.2.4] - 2026-08-25
+
+### Added
+- Added the packaged `melite example` Quick Start with deterministic synthetic
+  numeric tabular data, available directly from an installed distribution and
+  verified through installed-wheel smoke testing.
+- Added Ruff linting and formatting plus Mypy type checking as permanent CI
+  quality gates.
+- Added README contract tests covering canonical CLI commands, configuration
+  terminology, local links, and version synchronization.
+- Added persistent classifier evaluation evidence through `evaluations.csv`,
+  with one aggregate row per dataset and active classifier.
+- Added `evaluation_folds.csv` with one row per dataset, classifier, and
+  outer-CV split, preserving the raw evidence used for classifier selection.
+- Added one dataset-level F1-macro evidence figure under `output/figures/`,
+  showing the existing outer-CV scores for every evaluated classifier and
+  marking the selected classifier without running additional cross-validation.
+
+### Changed
+- Stabilized the public Python API around `Config`, `load_datasets`,
+  `plot_f1_macro_evidence`, `predict`, and `__version__`; complete evaluation
+  remains available through the `melite run` CLI workflow.
+- Consolidated the public Quick Start around the packaged example and removed
+  the redundant repository-level `examples/` workflow and `environment.yml`;
+  `pyproject.toml` is now the dependency source of truth.
+- Adopted the public product identity
+  **MELITE — Multi-Model Classifier Evaluator**.
+- Classifier selection is now based on mean outer-CV F1-macro from the
+  evaluation evidence retained for every active classifier.
+- Stacking graduated from experimental status to a stable opt-in classifier;
+  it remains disabled by default.
+- Standalone SVC evaluation now avoids probability fitting, while exported SVC
+  artifacts and the SVC base estimator inside stacking retain probability
+  support where required.
+- Evaluation parallelism now avoids nested estimator parallelism: inner grid
+  search or stacking owns parallel execution while contained estimators run
+  single-threaded.
+- Evaluation and smoke-mode terminology was aligned throughout the package,
+  documentation, CLI, and generated reports.
+- Renamed `[models]` / `ACTIVE_MODELS` to `[classifiers]` /
+  `ACTIVE_CLASSIFIERS`; existing configuration users must rename the
+  `[models]` section to `[classifiers]`.
+- Renamed the evaluation CSV field `model_name` to `classifier_name` in
+  `results.csv`, `evaluations.csv`, and `evaluation_folds.csv`; external CSV
+  consumers must update that column name.
+- Narrowed the public `Config` surface: legacy-reduction state, hyperparameter-
+  grid internals, redundant accessors, and runtime setup are no longer public
+  API. `RANDOM_STATE` is now the single public random-seed value, and
+  `CV_CONFIG` contains only `n_splits`, `n_repeats`, and `inner_n_splits`.
+- Explicit `[cv].random_state` and `[cv_smoke].random_state` settings are now
+  rejected with a clear configuration error; the canonical location is
+  `[benchmark].random_state`.
+- Replaced the former three-metric CV distribution plot API with
+  `plot_f1_macro_evidence()`, focused on the outer-CV F1-macro evidence used
+  for classifier selection.
+
+### Fixed
+- Result and evaluation persistence failures now propagate to callers instead
+  of being silently printed and ignored.
+- Corrected tunable-classifier evaluation so hyperparameter search occurs
+  inside each outer cross-validation split, separating hyperparameter tuning
+  from classifier evaluation.
+- Aligned stacking export reconstruction with the configured internal
+  stratified CV strategy used during training.
+- Removed the post-selection cross-validation step from `melite export`.
+  Export now reconstructs the selected model, fits it on all available data,
+  and saves the final `.pkl` artifact without producing a second evaluation.
+- Preserved the role of `results.csv` as the selected-classifier summary while
+  separating full evaluation evidence into dedicated output files.
+
+### Notes
+- The legacy `[benchmark]` configuration section remains supported for backward
+  compatibility.
+- Stacking remains opt-in; the default active classifiers are SVC, Random Forest,
+  and XGBoost.
+- Optuna and MLflow remain outside the scope of v0.2.4.
+
+---
+
+## [0.2.3] - 2026-06-01
+
+### Added
+- Added opt-in experimental stacking via the `stack` model key in
+  `[models].active`.
+- Added sklearn `StackingClassifier` support using `stack_method="predict_proba"`,
+  `passthrough=False`, and `LogisticRegression` as the final estimator.
+- Added export and prediction coverage for saved stacking `.pkl` artifacts.
+
+### Changed
+- Standalone SVC remains a `StandardScaler` -> `SVC` pipeline.
+- The SVC base estimator inside stacking is also scaled and uses
+  `SVC(probability=True)` so stacking combines probability outputs.
+- Random Forest and XGBoost remain unscaled direct estimators because they are
+  tree-based models and do not require feature scaling by default.
+- Stacking-internal CV uses the configured split count and random state with
+  one repeat to satisfy sklearn's out-of-fold prediction requirements.
+
+### Notes
+- Stacking is experimental and disabled by default.
+- Export remains `.pkl` via `joblib`.
+- Optuna and MLflow are intentionally out of scope for v0.2.3.
+
+---
+
+## [0.2.2] - 2026-05-28
 
 ### Changed
 - SVC is now trained as a `StandardScaler` -> `SVC` sklearn `Pipeline`.
@@ -25,7 +129,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [v0.2.1] - 2026-05-27
+## [0.2.1] - 2026-05-27
 
 ### Changed
 - `[models].active` / `ACTIVE_MODELS` now controls which model families are
@@ -45,7 +149,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [v0.2.0] - 2026-05-26
+## [0.2.0] - 2026-05-26
 
 ### Added
 - Added canonical `[datasets.<dataset_id>]` TOML registry entries for
@@ -404,3 +508,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - TXT/CSV result export.
 - Final model export as `.pkl`.
 - Three-panel metric plotting for F1, Accuracy and AUC-ROC.
+
+---
+
+[0.2.4]: https://github.com/NanoBiostructuresRG/melite/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/NanoBiostructuresRG/melite/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/NanoBiostructuresRG/melite/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/NanoBiostructuresRG/melite/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.11...v0.2.0
+[0.1.11]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.10...v0.1.11
+[0.1.10]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.9...v0.1.10
+[0.1.9]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.8...v0.1.9
+[0.1.8]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.7...v0.1.8
+[0.1.7]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/NanoBiostructuresRG/melite/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/NanoBiostructuresRG/melite/releases/tag/v0.1.1
+[0.1.0]: https://github.com/NanoBiostructuresRG/melite/releases/tag/v0.1.0

melite-0.2.4/CITATION.cff

@@ -0,0 +1,39 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "MELITE — Multi-Model Classifier Evaluator"
+version: "0.2.4"
+date-released: "2026-08-25"
+authors:
+  - family-names: "Contreras-Torres"
+    given-names: "Flavio F."
+    orcid: "https://orcid.org/0000-0003-2375-131X"
+    affiliation: "Tecnologico de Monterrey"
+  - family-names: "Murrieta"
+    given-names: "Ana C."
+    orcid: "https://orcid.org/0000-0002-7619-8880"
+    affiliation: "Tecnologico de Monterrey"
+repository-code: "https://github.com/NanoBiostructuresRG/melite"
+license: "LGPL-3.0-or-later"
+abstract: >-
+  MELITE is a pre-stable multi-model classifier evaluator for tabular
+  classification, classifier selection with nested cross-validation, final model
+  export, and artifact-based inference.
+
+  It operates at the tabular modeling level by consuming numeric feature
+  matrices and labels. MELITE evaluates SVC, Random Forest, XGBoost, and
+  opt-in Stacking classifiers under an outer repeated-stratified
+  cross-validation framework, with inner hyperparameter search for tunable
+  classifiers. It selects the best active classifier by mean outer-CV F1-macro,
+  persists aggregate and per-fold evaluation evidence, and supports final
+  model retraining, export, and artifact-based inference.
+keywords:
+  - machine learning
+  - tabular classification
+  - classifier evaluation
+  - classifier selection
+  - nested cross-validation
+  - SVC
+  - random forest
+  - XGBoost
+  - stacking

melite-0.2.4/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in MELITE
+and our community a harassment-free experience for everyone, regardless of age,
+body size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported privately by email to Flavio F. Contreras-Torres, the project
+maintainer, at <contreras.flavio@tec.mx>. Please do not use public GitHub
+issues for sensitive conduct reports.
+
+Conduct reports are received by the project maintainer and will be reviewed and
+investigated promptly, fairly, and with appropriate confidentiality.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. For the full text, see [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

melite-0.2.4/CONTRIBUTING.md

@@ -0,0 +1,157 @@
+# Contributing to MELITE
+
+Thank you for your interest in contributing to MELITE.
+
+MELITE is maintained by the
+[NanoBiostructures Research Group](https://nanobiostructuresrg.github.io)
+at Tecnológico de Monterrey. Contributions that improve correctness,
+reproducibility, usability, documentation, testing, or supported workflows are
+welcome.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Open an issue on
+[GitHub Issues](https://github.com/NanoBiostructuresRG/melite/issues)
+and include, when relevant:
+
+- a clear description of the problem;
+- the expected and observed behavior;
+- a minimal reproducible example;
+- the MELITE and Python versions;
+- the operating system and installation method;
+- the command, API call, or configuration involved;
+- the relevant traceback or error output.
+
+Do not include confidential, proprietary, or sensitive datasets in public
+issues.
+
+### Suggesting Features
+
+Open an issue describing:
+
+- the problem or use case;
+- the proposed behavior;
+- why it would be useful beyond a single workflow;
+- any expected effect on the public API, CLI, configuration, outputs, or
+  evaluation contract.
+
+### Submitting a Pull Request
+
+1. Fork the repository.
+2. Create a descriptive branch from `main`.
+3. Make a focused set of changes.
+4. Add or update tests when behavior changes.
+5. Run the relevant validation locally.
+6. Push your branch and open a pull request against `main`.
+
+Pull requests should pass CI before merge. User-facing changes should include
+appropriate documentation and changelog updates.
+
+## Development Setup
+
+Create an environment with a supported Python version using the environment
+manager you prefer, then install MELITE in editable mode with its development
+dependencies:
+
+```bash
+git clone https://github.com/NanoBiostructuresRG/melite.git
+cd melite
+python -m pip install -e ".[dev]"
+```
+
+To work on the documentation:
+
+```bash
+python -m pip install -e ".[dev,docs]"
+mkdocs serve
+```
+
+## Testing
+
+Run the complete test suite before opening a pull request:
+
+```bash
+python -m pytest tests -q
+```
+
+Changes should include tests when they modify behavior, fix a bug, add or
+modify a classifier, change configuration handling, alter generated outputs,
+or affect a public interface.
+
+For documentation changes, also run:
+
+```bash
+mkdocs build --strict
+```
+
+## Code Style
+
+Keep changes focused and consistent with the existing codebase. Use clear
+names, type hints where appropriate, and NumPy-style docstrings consistent with
+the surrounding modules.
+
+Avoid unrelated refactoring or formatting changes in the same pull request.
+
+## Scientific and Evaluation Changes
+
+Changes that affect classifier tuning, cross-validation, scoring, classifier
+construction, classifier selection, evaluation evidence, or final model fitting
+require particular care.
+
+Such contributions should:
+
+- explain the scientific or methodological rationale;
+- preserve the separation between hyperparameter tuning and outer evaluation;
+- avoid information leakage between tuning and evaluation;
+- identify any change to the classifier-selection criterion or evaluation contract;
+- add or update tests that exercise the changed behavior;
+- preserve reproducibility through explicit configuration and random-state
+  handling where applicable;
+- update documentation and the changelog when user-visible behavior changes.
+
+## Documentation and Changelog
+
+Update the relevant documentation when a change affects:
+
+- public behavior;
+- the CLI or Python API;
+- configuration;
+- supported classifiers;
+- input requirements;
+- generated outputs;
+- examples or documented workflows.
+
+Add an entry to `CHANGELOG.md` for user-visible changes. Purely internal
+refactoring normally does not require a changelog entry unless it changes
+observable behavior.
+
+## Compatibility
+
+MELITE is pre-stable, so public interfaces may evolve before version 1.0.
+Compatibility changes should nevertheless be intentional, documented, tested,
+and explained in the pull request.
+
+Avoid changing public API symbols, CLI behavior, configuration keys, output
+schemas, or serialized-artifact behavior without explicit justification.
+
+## Pull Request Scope
+
+Keep pull requests focused on one coherent change. Avoid combining feature
+work, broad refactoring, formatting changes, and unrelated cleanup in the same
+pull request.
+
+Small, reviewable changes are easier to validate scientifically and
+technically.
+
+## Code of Conduct
+
+Participation in MELITE is governed by the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Questions
+
+For questions about contributing, open a GitHub issue. Sensitive
+conduct-related matters should follow the private reporting process described
+in the [Code of Conduct](CODE_OF_CONDUCT.md).