Metadata-Version: 2.4
Name: coremat
Version: 0.11.0
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: adjusttext>=1.3.0
Requires-Dist: bokeh>=3.7.3
Requires-Dist: catboost>=1.2.8
Requires-Dist: click>=8.0
Requires-Dist: dash>=3.0.4
Requires-Dist: graphviz>=0.21
Requires-Dist: ipykernel>=6.29.5
Requires-Dist: ipywidgets>=8.1.7
Requires-Dist: lightgbm>=4.6.0
Requires-Dist: nbformat>=5.10.4
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: plotly>=6.1.1
Requires-Dist: ptitprince>=0.3.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=14.0.0
Requires-Dist: scikeras>=0.13.0
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: shap>=0.48.0
Requires-Dist: shapiq>=1.4.1
Requires-Dist: skorch>=1.2.0
Requires-Dist: sweetviz>=2.3.1
Requires-Dist: tabpfn>=8.0.3
Requires-Dist: tabpfn-extensions[all]>=0.2.2
Requires-Dist: torch>=2.8.0
Requires-Dist: xgboost>=3.0.1
Requires-Dist: ydata-profiling>=4.16.1
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: jupytext>=1.16.0; extra == "dev"
Requires-Dist: mkdocs-jupyter>=0.24.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: nbmake>=1.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: vulture>=2.14; extra == "dev"
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 70+ algorithm variants (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. Excerpt of what's inside:

| Section | What it shows |
|---|---|
| **Comparison Leaderboard** | All models in a run ranked by weighted Skill Score (OOF, switchable to Hold-out Test) |
| **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 |
| **Round Trajectory** | Feature-selection score and feature count per round |
| **SHAP / Feature Importance** | Per-round SHAP summary plots and contribution bars |
| **Model Parameters** | Curated hyperparameters and preprocessing policy |

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 — available from the first public release):
```bash
pip install coremat
# or with uv:
uv pip install coremat
```

**From the Uni Rostock GitLab Registry** (alternative, requires GitLab account):
```bash
uv pip install git+https://gitlab.uni-rostock.de/cs1302/coremat.git@main
```

**Developers** (editable install):
```bash
git clone https://gitlab.uni-rostock.de/cs1302/coremat.git
cd coremat
uv venv && uv sync
source .venv/bin/activate    # Linux/macOS
.venv\Scripts\activate       # Windows
```

## 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
**[Minimal Run guide](https://coremat.readthedocs.io/en/latest/how-to/01-minimal-run/)**.

---

## 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 70+ 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/metrics.md](https://coremat.readthedocs.io/en/latest/metrics/) | Metric definitions and evaluation methodology |
| [docs/verbose_levels.md](https://coremat.readthedocs.io/en/latest/verbose_levels/) | Logging verbosity levels and output examples |

### Building the docs

```bash
uv add mkdocs mkdocs-material
uv run -m mkdocs serve                          # local preview at http://127.0.0.1:8000, live-reloads on edit
uv run -m mkdocs build --strict --site-dir /tmp/site  # artifact build; --strict turns broken links/nav into errors
```

The `pages` CI job runs the same `--strict` build as a documentation lint — GitLab
Pages is not hosted on this instance, so nothing is deployed automatically.
Publishing the built `site/` output anywhere remains a manual step until a
hosting target is chosen (see the CI/CD section 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.
