R/extendr-wrappers.R

In isodistrreg: Isotonic Distributional Regression (IDR)

# Generated by extendr: Do not edit by hand
# nolint start

#' @usage NULL
#' @useDynLib isodistrreg, .registration = TRUE
NULL

#' Compute an isotonic regression of a probability given by Kaplan-Meier estimators (= one
#' threshold of S-IDR).
#'
#' This method is provided for completeness and to make the S-IDR publication easier to reproduce.
#'
#' @param threshold Double of the response value at which to compute the IDR solution.
#' @param X Double vector of totally ordered covariates.
#' @param y Double vector of response values.
#' @param y_observed Integer vector: 1 for observed, 0 for censored.
#' @param weights Double vector of non-negative weights. All vectors must have equal length.
#' @param decreasing Bool indicating direction (decreasing is a CIDR threshold).
#' @returns Numeric vector. The i'th entry gives the fitted CDF at covariate i.
#' @examples
#' survival_isotonic_distributional_regression_threshold(3.5, as.double(1:4), c(2, 1, 4, 3),
#'   as.integer(c(1, 0, 0, 0)), rep(1.0, 4))
#' @export
survival_isotonic_distributional_regression_threshold <- function(threshold, X, y, y_observed, weights, decreasing = FALSE) .Call(wrap__survival_isotonic_distributional_regression_threshold, threshold, X, y, y_observed, weights, decreasing)

#' Compute the plain survival IDR for totally ordered co-variates under the hazard rate order
#' assumption for censored data. Note that the hazard rate order is needed for the method to be
#' consistent, but that the returned solution likely doesn't satisfy this assumption.
#'
#' This method is provided for completeness and to make the S-IDR publication easier to reproduce,
#' but is not recommended for use by practitioners due to prohibitive computational costs and
#' potential inconsistency in case the distributions are not hazard rate ordered.
#'
#' @description
#' Computes the plain survival isotonic distributional regression (plain survival IDR) under the
#' hazard rate order assumption for totally ordered covariates when some responses are right
#' censored. Returns the fitted cumulative distribution evaluated at each response threshold for
#' each unique covariate.
#'
#' @param X Double vector of scalar covariates.
#' @param y Double vector of response values.
#' @param y_observed Integer vector: 1 for observed, 0 for censored.
#' @param weights Double vector of non-negative weights. All vectors must have equal length.
#' @returns Numeric matrix. The (i, j) entry gives the fitted CDF at (unique) response j for
#'   (unique) covariate i.
#' @examples
#' plain_survival_isotonic_distributional_regression(as.double(1:4), c(2, 1, 4, 3),
#'   as.integer(c(0, 1, 0, 1)), c(1, 2, 1, 1))
#' @export
plain_survival_isotonic_distributional_regression <- function(X, y, y_observed, weights) .Call(wrap__plain_survival_isotonic_distributional_regression, X, y, y_observed, weights)

#' Compute an isotonic regression of a probability given by Kaplan-Meier estimators (= one
#' threshold of the plain survival IDR data). Note that this is the non-recursive
#' version that is consistent only under the hazard rate order assumption.
#'
#' @description
#' Computes a single threshold of the plain survival isotonic distributional regression (plain
#' survival IDR) under the hazard rate order assumption for totally ordered covariates when some
#' responses are right-censored. Returns the fitted cumulative distribution evaluated at the
#' threshold for each unique covariate.
#'
#' @param threshold Double of the response value at which to compute the IDR solution.
#' @param X Double vector of totally ordered covariates.
#' @param y Double vector of response values.
#' @param y_observed Integer vector: 1 for observed, 0 for censored.
#' @param weights Double vector of non-negative weights. All vectors must have equal length.
#' @param decreasing Bool indicating direction (decreasing is a CIDR threshold).
#' @param parallel Bool indicating whether to use multiple cores.
#' @returns Numeric vector. The i'th entry gives the fitted CDF at covariate i.
#' @examples
#' plain_survival_isotonic_distributional_regression_threshold(3.5, as.double(1:4), c(2, 1, 4, 3),
#'   as.integer(c(1, 0, 0, 0)), rep(1.0, 4), decreasing = TRUE)
#' @export
plain_survival_isotonic_distributional_regression_threshold <- function(threshold, X, y, y_observed, weights, decreasing = FALSE, parallel = FALSE) .Call(wrap__plain_survival_isotonic_distributional_regression_threshold, threshold, X, y, y_observed, weights, decreasing, parallel)

#' Compute the isotonic regression for the mean for totally ordered covariates.
#'
#' Internal wrapper; user-facing input validation happens in the R function
#' `isotonic_regression()` (R/modeling.R). The asserts here are backstops with clear
#' messages for anyone calling the wrapper directly.
#'
#' @description Internal method that is used by R code to pass into Rust code.
#' @param y Double vector of response values.
#' @param X Double vector of covariate values, or NULL if responses are pre-sorted.
#' @param weights Double vector of non-negative weights, or NULL for equal weights.
#' @param decreasing Bool indicating direction (default FALSE is increasing, TRUE is decreasing).
#' @returns Numeric vector of isotonic fitted means.
isotonic_regression_impl <- function(y, X = NULL, weights = NULL, decreasing = FALSE) .Call(wrap__isotonic_regression_impl, y, X, weights, decreasing)

#'
#' @section Methods:
#'\subsection{Method `fit`}{
#'Wrapper around the Rust function. No careful input parsing here, we expect that to have
#'happened on the R side.
#'
#' \subsection{Arguments}{
#'\describe{
#'\item{`y`}{Outcome / response values (might be observed or censored)}
#'\item{`X`}{Flattened array of covariate values.}
#'\item{`y_observed`}{Nullable array of the same length as the responses indicating censoring (TRUE represents observed, FALSE represents right-censored), default is all observed}
#'\item{`sample_weight`}{Nullable array of the same length as the responses with nonnegative weights.}
#'\item{`x_order`}{List of covariate group descriptions.}
#'\item{`y_order`}{String representing the kind of stochastic order of the response.}
#'\item{`decreasing`}{Whether the responses are decreasing with the covariate (not is increasing).}
#'\item{`settings`}{List of solver settings for partially ordered covariates.}
#'\item{`seed`}{Integer seed for the random number generator. Only relevant when (su)bagging is active (i.e. when `subsamples` is set).}
#'\item{`n_jobs`}{Number of worker threads used to fit the individual subsamples in parallel. Only relevant when (su)bagging is active. Default is 1 (serial execution).}
#'\item{`show_progress`}{Whether to display a progress bar while fitting. Default is false.}
#'}}
#' \subsection{description}{
#'Internal method that is used by R code to pass into Rust code.
#'}
#'}
#'
#'\subsection{Method `cdf`}{
#'Predict a conditional CDF for the covariates provided in `data`.
#'
#' \subsection{Arguments}{
#'\describe{
#'\item{`data`}{Covariate array (flattened) for which to predict CDFs, (covariate-major) layout is inferred using this fit's covariate dimension.}
#'}}
#'}
#'
IDR <- new.env(parent = emptyenv())

IDR$fit <- function(y, X, y_observed, sample_weight, x_order, y_order, decreasing, subsamples, subsample_size, replace, settings, seed, n_jobs, show_progress) .Call(wrap__IDR__fit, y, X, y_observed, sample_weight, x_order, y_order, decreasing, subsamples, subsample_size, replace, settings, seed, n_jobs, show_progress)

IDR$cdf <- function(X) .Call(wrap__IDR__cdf, self, X)

IDR$cdf_at <- function(X, y) .Call(wrap__IDR__cdf_at, self, X, y)

IDR$quantile <- function(X, probability) .Call(wrap__IDR__quantile, self, X, probability)

IDR$dimension <- function() .Call(wrap__IDR__dimension, self)

IDR$thresholds <- function() .Call(wrap__IDR__thresholds, self)

IDR$diagnostic <- function() .Call(wrap__IDR__diagnostic, self)

#' @export
`$.IDR` <- function (self, name) { func <- IDR[[name]]; environment(func) <- environment(); func }

#' @export
`[[.IDR` <- `$.IDR`

# nolint end