Package 'xplus'

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.

---

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)

---

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)

---

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.

---