Metadata-Version: 2.4
Name: poseigen_compass
Version: 1.0.1
Summary: Hyperparameter optimization and model evaluation utilities for the Poseigen family
Author-email: Husam Abdulnabi <husam.abdulnabi@gmail.com>
Maintainer-email: Husam Abdulnabi <husam.abdulnabi@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/husam94/poseigen_compass
Project-URL: Repository, https://github.com/husam94/poseigen_compass
Project-URL: Issues, https://github.com/husam94/poseigen_compass/issues
Keywords: poseigen,bioinformatics,machine-learning,hyperparameter-optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: poseigen_seaside
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Compass

[![PyPI version](https://img.shields.io/pypi/v/poseigen_compass)](https://pypi.org/project/poseigen_compass/)
[![Python versions](https://img.shields.io/pypi/pyversions/poseigen_compass)](https://pypi.org/project/poseigen_compass/)
[![License](https://img.shields.io/pypi/l/poseigen_compass)](https://pypi.org/project/poseigen_compass/)

`poseigen_compass` is the hyperparameter search and model-evaluation package in the [Poseigen ecosystem](https://github.com/Husam94/poseigen). It generates candidate configurations, evaluates models across data splits and repeats, and supports ensembling and statistical assessment.

## Installation

Requires Python 3.12 or newer. Install from PyPI:

```bash
python -m pip install poseigen_compass
```

## Package

Compass's public helpers are re-exported from the `poseigen_compass` package:

- **Candidate generation** — `RandomCanGen` samples continuous, integer, and categorical hyperparameter spaces.
- **Model evaluation** — `StandardCanScorer` scores a model with a selected metric, while `CanEvaluator` and `RandomOpt` evaluate candidates across splits and repeats, with optional parallel execution.
- **Candidate selection** — `TopCan` ranks candidates by their evaluation scores, and `TopCanDict` returns the selected configurations.
- **Ensembling and uncertainty** — `EnsembleScorer` combines model predictions; `Bootstrapper`, `BootstrapConfidenceInterval`, and `BootstrapStandardError` support bootstrap-based assessment.

Compass uses [poseigen_seaside](https://github.com/Husam94/poseigen_seaside) for shared utilities and metrics. [poseigen_oyster](https://github.com/Husam94/poseigen_oyster) provides `Oyster_BaseDict` and `Dual_Oyster_BaseDict` search spaces for Compass.

## Usage

`RandomCanGen` accepts a dictionary that defines the range or choices for each parameter:

```python
import poseigen_compass as co

search_space = {
    "learning_rate": [[1e-4, 1e-2], "float"],
    "batch_size": [[16, 32, 64], "cat"],
    "max_depth": [[2, 12], "int"],
}

candidates = co.RandomCanGen(search_space, num_can=20)
```

Pass the resulting candidates to `RandomOpt` to evaluate them with a model, data, and an optional set of splits.
