Repository Mirror for your Cloud Server and Webhosting

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:

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:

Packaged:

2026-09-15 13:35:09 UTC; alrobles

Author:

Angel Robles

[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

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

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

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.

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.

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

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".

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

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

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

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

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.

Package {xplus}

Assess predictive performance

Description

Usage

Arguments

Value

References

See Also

Examples

Compute area under the ROC curve

Description

Usage

Arguments

Value

References

See Also

Examples

Compute AUC from matrix labels

Description

Usage

Arguments

Value

References

See Also

Examples

Example binary labels dataset

Description

Usage

Format

Extract coefficients from an xplus model

Description

Usage

Arguments

Value

See Also

Examples

Example cutoff values

Description

Usage

Format

Example fitted xplus object

Description

Usage

Format

Compute AUC for predictions from a model

Description

Usage

Arguments

Value

See Also

Examples

Build a tidy prediction table

Description

Usage

Arguments

Value

References

See Also

Examples

LACS dataset

Description

Usage

Format

LACS sample dataset

Description

Usage

Format

Construct a new xplus object

Description

Usage

Arguments

Value

See Also

Predict from an xplus model

Description

Usage

Arguments

Value

References

See Also