Metadata-Version: 2.4
Name: coremat
Version: 0.23.1
Summary: COREMat: Automated ML regression framework for materials science
License-Expression: MIT
Project-URL: Homepage, https://gitlab.uni-rostock.de/cs1302/coremat
Project-URL: Documentation, https://coremat.readthedocs.io
Project-URL: Repository, https://gitlab.uni-rostock.de/cs1302/coremat
Project-URL: Changelog, https://gitlab.uni-rostock.de/cs1302/coremat/-/blob/main/CHANGELOG.md
Project-URL: Issues, https://gitlab.uni-rostock.de/cs1302/coremat/-/issues
Keywords: materials science,automated regression,tabular ML,machine learning,materials property prediction
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bokeh>=3.7.3
Requires-Dist: catboost>=1.2.8
Requires-Dist: click>=8.0
Requires-Dist: cycler>=0.12.1
Requires-Dist: joblib>=1.5.0
Requires-Dist: lightgbm>=4.6.0
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: optuna>=4.4.0
Requires-Dist: optuna-integration>=4.4.0
Requires-Dist: pandas>=2.2.3
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: scipy>=1.15.3
Requires-Dist: seaborn>=0.13.2
Requires-Dist: shap>=0.48.0
Requires-Dist: skorch>=1.2.0
Requires-Dist: tabpfn>=8.0.3
Requires-Dist: threadpoolctl>=3.6.0
Requires-Dist: torch>=2.8.0
Requires-Dist: xgboost>=3.0.1
Dynamic: license-file

# COREMat Framework

COREMat (COmputable REgression for Materials) is a Python framework for automated machine learning on tabular materials-science datasets — alloy research, materials-property prediction, and similar regression workloads. It automates the full workflow behind a single configuration: data ingestion, preprocessing, nested-CV training with hyperparameter optimisation, iterative feature selection, SHAP-based explainability, OOF/Hold-out evaluation, and interactive HTML reporting. The model registry ships 36 models (gradient boosting, kernel methods, linear models, neural nets, foundation models) behind a unified `ModelSpec` interface.

---

## What You Get

Every trained model gets a self-contained, interactive HTML report — open it in a browser, no server or notebook required — and `coremat eval` or `coremat report compare` adds a comparison report over all models of a run. Excerpt of what's inside:

| Section                            | What it shows                                                                         |
|------------------------------------|---------------------------------------------------------------------------------------|
| **Comparison Leaderboard**         | Comparison report: all models in a run ranked by weighted Skill Score (OOF, switchable to Hold-out Test) |
| **Round Performance Comparison**   | Metrics of every round, re-weightable in the browser; the delivered round marked      |
| **Feature Selection**              | Honest OOF curve per round, selection score, hold-out, and the delivered round        |
| **Selection Frequency**            | In how many outer folds each feature survives — how stable the selection is           |
| **Actual vs. Predicted**           | Square scatter with color-by-feature and linear/log axis toggle                       |
| **Residuals & Error Distribution** | Residuals-vs-Predicted scatter, ECDF/histogram error analysis                         |
| **SHAP / Feature Importance**      | Per-round SHAP summary plots and contribution bars                                    |
| **Reproduction**                   | Estimator, features, transforms, split recipe, code snippet and model parameters      |

Every report is built **post-hoc** from persisted per-round predictions — re-opening a report never re-runs a model.

---

## Installation

**Requirements:** Python >= 3.12, < 3.13

**From PyPI** (recommended):

```bash
uv add coremat          # in a uv project
# or:
pip install coremat
```

**From GitLab** (latest `main`):

```bash
uv pip install git+https://gitlab.uni-rostock.de/cs1302/coremat.git@main
```

**Developers** (editable install with the dev tools):

```bash
git clone https://gitlab.uni-rostock.de/cs1302/coremat.git
cd coremat
uv sync                      # creates .venv from uv.lock
uv run coremat build-data    # example datasets into data/
```

## TabPFN Authentication

TabPFN models require a free PriorLabs account. Set up once after installation:

```bash
coremat auth tabpfn
```

## Getting Started

The documentation (mkdocs) is the single source of truth for usage — it covers
the full quick-start walkthrough, sample data generation, and the resulting
artifact layout. Start at [**docs/index.md**](https://coremat.readthedocs.io/) or the
[**Walkthrough**](https://coremat.readthedocs.io/en/latest/how-to/walkthrough/) — the
end-to-end tour in Python, each step with a copy-paste YAML equivalent.

---

## Documentation

| Document                                                                                     | Description                                              |
|----------------------------------------------------------------------------------------------|----------------------------------------------------------|
| [docs/index.md](https://coremat.readthedocs.io/)                                             | Quick-start walkthrough and installation                 |
| [docs/cli_guide.md](https://coremat.readthedocs.io/en/latest/cli_guide/)                     | Full CLI reference — all commands, options, and examples |
| [docs/api.md](https://coremat.readthedocs.io/en/latest/api/)                                 | Public API reference — exported symbols and usage        |
| [docs/reference/models/index.md](https://coremat.readthedocs.io/en/latest/reference/models/) | All 36 registered models with preprocessing policies     |
| [docs/architecture.md](https://coremat.readthedocs.io/en/latest/architecture/)               | Layer model, module responsibilities, dependency graph   |
| [docs/development.md](https://coremat.readthedocs.io/en/latest/development/)                 | Dev setup, reproducibility guide, contribution notes     |
| [docs/reference/metrics/](https://coremat.readthedocs.io/en/latest/reference/metrics/)        | Metric definitions — formula, worked example, and when to use each |
| [docs/verbose_levels.md](https://coremat.readthedocs.io/en/latest/verbose_levels/)           | Logging verbosity levels and output examples             |

The documentation is published on [Read the Docs](https://coremat.readthedocs.io/).
To preview it locally: `uv run mkdocs serve` (details in
[docs/development.md](https://coremat.readthedocs.io/en/latest/development/)).

---

## Citing COREMat

If you use COREMat in your research, please cite it. Machine-readable citation
metadata is provided in [`CITATION.cff`](https://gitlab.uni-rostock.de/cs1302/coremat/-/blob/main/CITATION.cff) at the root of this
repository.

## Acknowledgements

This project was developed using an agentic AI-assisted workflow with [Claude Code](https://code.claude.com/docs/de/overview) by Anthropic.
