Package {xplus}

Title: Positive and Unlabeled Learning from Unbalanced Cases and Sparse Structures
Version: 1.0.2
Description: Provides PLUS-derived extensions for positive and unlabeled (PU) learning from unbalanced cases and sparse structures, based on Zhou et al. (2022) <doi:10.1371/journal.pcbi.1009956>. Iteratively relabels unlabeled observations via penalised logistic regression and pseudo-label updates, then refits a final sparse model. Includes weighted bootstrap sampling, convergence diagnostics, prediction, coefficient extraction, and assessment utilities.
License: GPL (≥ 3)
Encoding: UTF-8
Depends: R (≥ 4.1.0)
LazyData: true
Imports: glmnet (≥ 4.1-8), Matrix, methods, stats, tibble, utils
Suggests: covr, knitr, rmarkdown, survival, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
URL: https://github.com/alrobles/xplus, https://alrobles.github.io/xplus/
BugReports: https://github.com/alrobles/xplus/issues
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-09-15 13:35:09 UTC; alrobles
Author: Angel Robles ORCID iD [aut, cre]
Maintainer: Angel Robles <a.l.robles.fernandez@gmail.com>
Repository: CRAN
Date/Publication: 2026-09-26 16:30:02 UTC

Assess predictive performance

Description

Assess predictive performance

Usage

assess(object, newx = NULL, newy, weights = NULL, ...)

## S3 method for class 'xplus'
assess(object, newx = NULL, newy, weights = NULL, ...)

Arguments

object

A model object.

newx

Optional feature matrix.

newy

Binary 0/1 labels or a two-column finite nonnegative matrix of negative and positive class masses; soft vectors are not accepted.

weights

Optional finite nonnegative numeric row weights without recycling; NULL means unit weights.

...

Additional arguments passed to predict().

Value

A named list with deviance, class, auc, mse, and mae. For class metric, the threshold used is the model's cutoff (from object$cutoff), consistent with predict(type = "class"); MSE and MAE sum both class-column losses (twice the scalar loss). Undefined metrics return NA with a warning.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

See Also

xplus(), get_auc()

Examples

set.seed(1)
x <- matrix(rnorm(100 * 5), ncol = 5)
y <- c(rep(1, 20), rep(0, 80))
fit <- xplus(x, y, max_iter = 5)
assess(fit, newx = x, newy = y)

Compute area under the ROC curve

Description

Compute area under the ROC curve

Usage

auc(y, prob, w = NULL)

Arguments

y

Binary 0/1 vector, including logical, character, or factor encodings.

prob

Finite numeric scores, one per label; values outside ⁠[0, 1]⁠ are allowed.

w

Optional finite nonnegative numeric sample weights; NULL means unit weights.

Value

Numeric rank AUC with half credit for ties; NA with a warning if either effective class mass is zero.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

See Also

auc_matrix(), get_auc()

Examples

y <- c(0, 0, 1, 1)
p <- c(0.1, 0.3, 0.7, 0.9)
auc(y, p)

Compute AUC from matrix labels

Description

Compute AUC from matrix labels

Usage

auc_matrix(y, prob, weights = NULL)

Arguments

y

Two-column finite nonnegative class masses (negative, positive); soft labels, counts, and zero-mass rows are supported.

prob

Finite numeric scores, one per row; values outside ⁠[0, 1]⁠ are allowed.

weights

Optional finite nonnegative numeric row weights without recycling; NULL means unit weights.

Value

Weighted rank AUC with half credit for ties; NA with a warning if either effective class mass is zero.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

See Also

auc(), assess()

Examples

y <- cbind(c(1, 1, 0, 0), c(0, 0, 1, 1))
p <- c(0.2, 0.3, 0.7, 0.8)
auc_matrix(y, p)

Example binary labels dataset

Description

A small binary example dataset used in package examples.

Usage

binexample

Format

A data frame.

Extract coefficients from an xplus model

Description

Extract coefficients from an xplus model

Usage

## S3 method for class 'xplus'
coef(object, s = "lambda.min", ...)

Arguments

object

An xplus object.

s

Penalty value name or numeric lambda.

...

Additional arguments.

Value

A sparse coefficient matrix.

See Also

summary.xplus(), print.xplus()

Examples

set.seed(1)
x <- matrix(rnorm(100 * 5), ncol = 5)
y <- c(rep(1, 20), rep(0, 80))
fit <- xplus(x, y, max_iter = 5)
coef(fit)

Example cutoff values

Description

Example cutoff values used in demonstrations.

Usage

cutoff_example

Format

A numeric vector.

Example fitted xplus object

Description

Example model fit used in package documentation.

Usage

fit_xplus_example

Format

An object of class xplus.

Compute AUC for predictions from a model

Description

Compute AUC for predictions from a model

Usage

get_auc(object, newx = NULL, newy = NULL, weights = NULL, ...)

## S3 method for class 'xplus'
get_auc(object, newx = NULL, newy = NULL, weights = NULL, ...)

Arguments

object

A model object.

newx

Feature matrix.

newy

True labels.

weights

Optional sample weights.

...

Arguments passed to predict.xplus(), such as s selecting a single lambda.

Value

Numeric AUC value.

See Also

assess(), auc()

Examples

set.seed(1)
x <- matrix(rnorm(100 * 5), ncol = 5)
y <- c(rep(1, 20), rep(0, 80))
fit <- xplus(x, y, max_iter = 5)
get_auc(fit, newx = x, newy = y)

Build a tidy prediction table

Description

Build a tidy prediction table

Usage

get_predictions(object, newx, newy, use_cutoff = TRUE)

Arguments

object

An xplus model object.

newx

Feature matrix.

newy

True labels.

use_cutoff

Logical; if TRUE, classify with the model's cutoff. If FALSE, classify probabilities strictly greater than 0.5 as positive.

Value

A tibble with truth labels, probabilities and predicted classes; Class1 is the positive label 1, classified by probability strictly greater than the cutoff.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

See Also

predict.xplus(), assess()

Examples

set.seed(1)
x <- matrix(rnorm(100 * 5), ncol = 5)
y <- c(rep(1, 20), rep(0, 80))
fit <- xplus(x, y, max_iter = 5)
get_predictions(fit, x, y)

LACS dataset

Description

Example dataset from the original PLUS package.

Usage

lacs

Format

A data frame.

LACS sample dataset

Description

Sample subset of the LACS data.

Usage

lacsSample

Format

A data frame.

Construct a new xplus object

Description

Construct a new xplus object

Usage

new_xplus(
  fit_xplus = list(),
  pred_y = matrix(),
  cutoff = numeric(),
  predicted_coefficients = Matrix::Matrix(),
  n_iter = integer(),
  x = matrix(),
  y = numeric(),
  alpha = numeric(),
  learning_rate = numeric(),
  pseudo_labels = numeric(),
  iterative_path = character(),
  qq = numeric(),
  call = character(),
  max_iter = integer(),
  stop_reason = character(),
  original_y = NULL,
  final_labels = y,
  fallback_used = NULL,
  fallback_reason = NULL,
  history = NULL,
  sampling_counts = NULL,
  draw_counts = NULL,
  final_foldid = NULL,
  cv_measure = NULL,
  sigmoid_scale = NULL,
  sampling = NULL,
  min_iter = NULL,
  stability_window = NULL,
  min_coverage = NULL
)

Arguments

fit_xplus

Fitted glmnet::cv.glmnet() object.

pred_y

Predicted probabilities matrix.

cutoff

Numeric classification cutoff.

predicted_coefficients

Sparse coefficient matrix.

n_iter, history, sampling_counts, draw_counts

Number of completed iterations, per-iteration diagnostics, and per-observation unlabeled inclusion-round and draw counts; optional diagnostics default to NULL.

x

Training feature matrix used to fit the model.

y, final_labels

Identical actual target probabilities used for final fitting; final_labels defaults to y.

alpha

Elastic-net alpha used during fitting.

learning_rate

Learning rate used during pseudo-label updates.

pseudo_labels, original_y, fallback_used, fallback_reason

Proposed probabilities before fallback, original numeric binary labels, fallback flag and reason (empty if unused); optional metadata default to NULL for legacy bundles.

iterative_path, final_foldid, cv_measure, sigmoid_scale, sampling

Iterative path and optional final cross-validation folds, measure (deviance or auc), positive sigmoid scale, and sampling mode (bootstrap or unique); optional controls default to NULL.

qq

Quantile parameter used for cutoff calibration.

call

Original function call.

max_iter, min_iter, stability_window, min_coverage

Maximum iterations and optional minimum iterations, consecutive stability rounds, and unlabeled coverage required for stopping; optional controls default to NULL.

stop_reason

Reason fitting stopped: "max_iter", "label_stability", "budget_exhausted", or "degenerate_labels" (the pseudo-labels of the iterative training subset collapsed to a single class).

Value

An object of class "xplus".

See Also

validate_xplus()

Predict from an xplus model

Description

Predict from an xplus model

Usage

## S3 method for class 'xplus'
predict(object, newx = NULL, s = "lambda.min", type = "response", ...)

Arguments

object

An xplus object.

newx

Optional finite numeric feature matrix; defaults to training data. Named training features must match and are reordered automatically.

s

Exact penalty name ("lambda.min", "lambda.1se") or finite nonnegative numeric lambda vector. Cache-only objects support only "lambda.min".

type

Prediction type: "response", "link", or "class".

...

Additional arguments are not supported and cause an error.

Value

Probabilities (type = "response") or log-odds (type = "link"); cached probabilities of 0 and 1 give infinite log-odds. Classes use a factor with fixed levels "0", "1" for one lambda, or a dimension-preserving 0/1 matrix for multiple lambdas.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

See Also

xplus(), print.xplus()

Examples

set.seed(1)
x <- matrix(rnorm(100 * 5), ncol = 5)
y <- c(rep(1, 20), rep(0, 80))
fit <- xplus(x, y, max_iter = 5)
predict(fit, newx = x, type = "response")
predict(fit, newx = x, type = "link")

Example predicted coefficients

Description

Sparse coefficients extracted from an xplus model.

Usage

predicted_coefficients_example

Format

A sparse matrix.

Example predicted probabilities

Description

Predicted probabilities from an xplus model.

Usage

predicted_y_example

Format

A numeric matrix.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

Print method for summary.xplus objects

Description

Print method for summary.xplus objects

Usage

## S3 method for class 'summary.xplus'
print(x, ...)

Arguments

x

A summary.xplus object.

...

Additional arguments.

Value

The input object x is returned invisibly (called for side effects).

Print an xplus model

Description

Print an xplus model

Usage

## S3 method for class 'xplus'
print(x, digits = max(3, getOption("digits") - 3), ...)

Arguments

x

An xplus object.

digits

Number of significant digits.

...

Additional arguments.

Value

Invisibly returns x.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

See Also

summary.xplus(), coef.xplus()

Examples

set.seed(1)
x <- matrix(rnorm(100 * 5), ncol = 5)
y <- c(rep(1, 20), rep(0, 80))
fit <- xplus(x, y, max_iter = 5)
print(fit)

Build class-stratified cross-validation fold assignments

Description

Assigns each observation to one of nfolds folds so that both classes are spread as evenly as possible across folds. This prevents a small class from being concentrated in a single fold, which would leave a cross-validation training split with fewer than the two observations per class that glmnet::glmnet() requires for binomial fits.

Usage

stratified_foldid(y, nfolds)

Arguments

y

Binary (0/1) vector of class labels.

nfolds

Number of folds.

Value

Integer vector of fold assignments in 1:nfolds, the same length as y, suitable for the foldid argument of glmnet::cv.glmnet().

Summarize an xplus model

Description

Summarize an xplus model

Usage

## S3 method for class 'xplus'
summary(object, ...)

Arguments

object

An xplus object.

...

Additional arguments.

Value

A list of class summary.xplus with model details.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

See Also

print.xplus(), coef.xplus()

Examples

set.seed(1)
x <- matrix(rnorm(100 * 5), ncol = 5)
y <- c(rep(1, 20), rep(0, 80))
fit <- xplus(x, y, max_iter = 5)
summary(fit)

Validate an xplus object

Description

Validate an xplus object

Usage

validate_xplus(xplus_object)

Arguments

xplus_object

An object of class "xplus".

Value

The validated xplus object.

Fit an xplus model

Description

Fit a PLUS-derived model for positive-unlabeled learning.

Usage

xplus(
  x,
  y,
  alpha = 1,
  sample_use_time = 30,
  learning_rate = 1,
  qq = 0.1,
  verbose = FALSE,
  nfolds = 4,
  max_iter = 10000,
  convergence_threshold = 0.9,
  seed = NULL,
  sigmoid_scale = 10,
  min_iter = 5,
  stability_window = 5,
  min_coverage = 0.9,
  sampling = c("bootstrap", "unique"),
  cv_measure = c("deviance", "auc"),
  degenerate_threshold = 1e-06
)

Arguments

x

Finite numeric feature matrix with at least two columns.

y

Binary vector where 1 indicates known positives and 0 indicates unlabeled samples; factors are interpreted by their labels.

alpha

Elastic-net mixing parameter in ⁠[0, 1]⁠, not the sigmoid scale in the PLUS paper.

sample_use_time

Unlabeled-sampling budget inherited from the reference implementation: maximum number of completed sampling rounds containing each unlabeled case, not the number of bootstrap copies within a round.

learning_rate

Pseudo-label smoothing rate in ⁠(0, 1]⁠; values below one retain the package's global-update, hard-thresholded enhancement path.

qq

Quantile used to define the positive-reference cutoff.

verbose

Logical; print iterative progress messages.

nfolds

Requested CV folds, an integer at least three; reduced for small classes.

max_iter

Maximum number of pseudo-labeling iterations.

convergence_threshold

Required stability score in ⁠(0, 1]⁠, evaluated before learning-rate damping.

seed

Integer or NULL. Random seed for reproducibility, applied via set.seed(). Default NULL (no seed).

sigmoid_scale, degenerate_threshold

Positive sigmoid scale and nonnegative residual-clamping tolerance.

min_iter, stability_window

Minimum iterations and consecutive stable iterations required before declaring convergence. xplus retains two iterative paths, distinct from the paper's pseudocode: "current" (learning_rate = 1) uses sampled Bernoulli labels, while "continuous_enhancement" (learning_rate < 1) smooths probabilities and updates all unlabeled hard labels. Both use soft final fitting targets. Stability compares the undamped mapped scores with the current pseudo-labels across all unlabeled cases and requires a full window and sampling coverage.

min_coverage

Minimum fraction of unlabeled cases sampled before convergence, in ⁠[0, 1]⁠. Bootstrap multiplicities are represented as case weights, keeping duplicate copies together in CV. sampling = "unique" retains legacy deduplication. Final-fit fallback is based on effective class mass, not thresholded labels, and is recorded with the actual fitting targets and the iteration history.

sampling, cv_measure

Sampling convention ("bootstrap" or "unique") and CV criterion ("deviance" or "auc"); deviance is the default for both fitting stages.

Details

Core PLUS behavior alternates between fitting penalized logistic models on known positives plus sampled unlabeled cases, anchoring predictions to a positive quantile cutoff, and iteratively relabeling unlabeled samples.

Value

An object of class "xplus" containing predictions, original and final labels, pseudo-labels, fallback metadata, sampling counts, and history.

References

Zhou et al. (2022). doi:10.1371/journal.pcbi.1009956

See Also

predict.xplus(), summary.xplus(), assess.xplus()

Examples

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)

Example xplus object

Description

Saved xplus object for examples and tests.

Usage

xplus_object_example

Format

An object of class xplus.