---
title: "Introduction to xplus"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to xplus}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

## What is PU learning?

Positive and Unlabeled (PU) learning addresses settings where only positives are labeled,
and the remaining data are unlabeled (not guaranteed negatives).

## When to use xplus

`xplus` provides PLUS-derived extensions for confirmed-positive/unlabeled data
and sparse feature models. The 1.0.0 development candidate does not guarantee
calibrated probabilities or establish predictive superiority. Fitting requires
finite numeric features (at least two columns) and at least three known positives
and three unlabeled observations. `learning_rate` must be in `(0, 1]`.

## Basic workflow

```{r basic-workflow}
library(xplus)
set.seed(1)
x <- matrix(rnorm(200 * 10), ncol = 10)
y <- c(rep(1, 40), rep(0, 160))

fit <- xplus(x, y, max_iter = 20, seed = 42)
summary(fit)
fit$stop_reason
fit$fallback_used
head(predict(fit, x, type = "response"))
levels(predict(fit, x, type = "class"))
```

The default uses weighted bootstrap multiplicities on unique CV rows and
`cv_measure = "deviance"` in both fitting stages. `sampling = "unique"` opts into
legacy deduplication. An explicit `seed` restores the caller's RNG state.
`max_iter` is a limit, not a convergence claim: stability requires a full
consecutive window and sampling coverage. Inspect stopping and fallback metadata.

## Model assessment

These are training PU-label diagnostics on random features, not held-out
true-class performance. Use independently established test labels for the latter.
`get_auc()` forwards a single penalty selection to prediction.

```{r assessment}
metrics <- assess(fit, newx = x, newy = y, s = "lambda.1se")
metrics$auc
get_auc(fit, newx = x, newy = y, s = "lambda.1se")
```

Assessment accepts finite binary truth or two-column negative/positive masses
for soft truth; soft vectors are not binary truth. Weights must be finite,
nonnegative and exactly row-aligned. Invalid rows are errors, not silently
dropped data. Undefined AUC warns and returns `NA`. MSE and MAE sum both class
columns (twice scalar binary loss); deviance clips probabilities to
`[1e-5, 1 - 1e-5]`.