Metadata-Version: 2.4
Name: mykrml_25974991
Version: 0.4.0
Summary: Reusable helpers for the 36120 Advanced Machine Learning assignments: dataset splitting, date features, baseline models and rare-event scoring.
License: MIT
License-File: LICENSE
Keywords: machine-learning,scikit-learn,auprc,baseline-models
Author: Dhruv Sharma
Requires-Python: >=3.12
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Science/Research
Provides-Extra: dev
Requires-Dist: jupyterlab (>=4.2) ; extra == "dev"
Requires-Dist: numpy (>=1.26)
Requires-Dist: pandas (>=2.2)
Requires-Dist: pytest (>=8.0) ; extra == "dev"
Requires-Dist: scikit-learn (>=1.5)
Project-URL: Repository, https://github.com/OPSdrag/36120-26SP-group32-25974991-package
Description-Content-Type: text/markdown

# mykrml_25974991

Reusable helpers for the **36120 Advanced Machine Learning Application** assignments:
dataset splitting and persistence, date feature conversion, baseline ("null") models, and
scoring helpers for regression and **rare-event classification**.

Published to TestPyPI as `mykrml_25974991`; the import name is `my_krml_25974991`.

## Install

```bash
# from TestPyPI
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple mykrml_25974991

# or from a clone
pip install -e ".[dev]"
```

Requires Python ≥ 3.12.

## Usage

### Splitting and persisting datasets

```python
import pandas as pd
from my_krml_25974991.data import pop_target, split_sets_random, save_sets, load_sets

df = pd.read_csv("train.csv")
features, target = pop_target(df, target_col="label")

X_train, y_train, X_val, y_val, X_test, y_test = split_sets_random(
    features, target, test_ratio=0.2
)
save_sets(X_train, y_train, X_val, y_val, X_test, y_test, path="data/processed")
X_train, y_train, *_ = load_sets("data/processed")
```

`test_ratio` is the only ratio: validation is sized to match it, so `0.2` gives a 60/20/20
split. `split_sets_random` seeds internally, so the split is reproducible without passing a
seed.

`split_sets_by_time` takes the **whole frame and the target column name** instead, sorts on
the first datetime column it finds and splits chronologically — use it whenever the test
period follows the training period, so validation cannot see the future.

```python
from my_krml_25974991.data import split_sets_by_time

X_train, y_train, X_val, y_val, X_test, y_test = split_sets_by_time(
    df, target_col="label", test_ratio=0.2
)
```

### Date features

```python
from my_krml_25974991.features import convert_to_date

df = convert_to_date(df, cols=["dob", "game_date"])   # raises on unknown or unparseable columns
```

### Baseline models

Every experiment needs a floor. For a rare-event target the floor is **not** accuracy —
always predicting the majority class scores 96.6% on a 3.4%-positive problem while identifying
nobody. It is the positive prevalence, which is the AUPRC of a random ranker.

```python
from my_krml_25974991.models import NullClassifier, NullRegressor

null = NullClassifier().fit(X_train, y_train)
probs = null.predict_proba(X_val)[:, 1]       # constant = training base rate

NullRegressor(strategy="median").fit(X_train, y_train).predict(X_val)
```

### Scoring

```python
from my_krml_25974991.models import print_class_scores, print_regressor_scores

print_class_scores(probs, y_val, "Valid")
# Valid AUPRC:   0.5038  (random = 0.0337, 15.0x)
# Valid ROC AUC: 0.8572

print_regressor_scores(preds, y_val, "Valid")
# Valid RMSE: 0.7071
# Valid MAE: 0.5000
```

`print_class_scores` always reports AUPRC next to the prevalence, because an AUPRC without its
baseline is uninterpretable — 0.50 is excellent at a 3% base rate and poor at a 45% one.

## API

| module | contents |
|---|---|
| `my_krml_25974991.data` | `pop_target`, `save_sets`, `load_sets`, `subset_x_y`, `split_sets_by_time`, `split_sets_random` |
| `my_krml_25974991.features` | `convert_to_date` |
| `my_krml_25974991.models` | `NullRegressor`, `NullClassifier`, `print_regressor_scores`, `print_class_scores` |

## Tests

```bash
pytest tests -q      # 25 tests
```

A root `conftest.py` puts `src/` on the path, so the suite runs on a fresh clone without an
install step.

## Changelog

See [CHANGELOG.md](https://github.com/OPSdrag/36120-26SP-group32-25974991-package/blob/master/CHANGELOG.md), or the Changelog page in the built docs.

