Skip to contents

Assert probability matrix

assert_prob_matrix.Rd

Validates that the input is a proper probability matrix representing either a survival function ("surv"), cumulative distribution function ("cdf"), or cumulative incidence function ("cif"). Uses the internal Rcpp function c_assert_prob_matrix().

Usage

assert_prob_matrix(x, times = NULL, type = "surv")

Arguments

x

(matrix())
A probability matrix. Rows correspond to observations and columns correspond to time points.

times

(numeric()|NULL)
Optional numeric vector of time points corresponding to the columns of x. If numeric(), these will be returned after the checks are performed. If NULL (default), the time points are extracted from colnames(x).

type

(character(1))
Type of probability function: "surv" (default), "cdf", or "cif".

Value

Invisibly returns the validated numeric vector of time points. Throws an error if validation fails.

Details

The following conditions must hold:

  1. The input x is a numeric matrix with no missing values.

  2. Time points (times) are numeric, non-negative, unique, and sorted. If not supplied, they are derived from colnames(x) (coerced to numeric).

  3. The number of time points equals the number of columns of x.

  4. All values are valid probabilities, i.e. lie in \([0,1]\).

  5. Each row is monotone:

    • "surv": non-increasing survival curves, i.e. \(S(t_i) \ge S(t_{i+1})\).

    • "cdf" / "cif": non-decreasing functions, i.e. \(F(t_i) \le F(t_{i+1})\).

  6. Boundary condition at t = 0:

    • "surv": \(S(0) = 1\).

    • "cdf" / "cif": \(F(0) = 0\).

Examples

x = matrix(data = c(1, 0.6, 0.4,
                    0.8, 0.8, 0.7),
           nrow = 2, ncol = 3, byrow = TRUE)

# Explicitly provide time points
assert_prob_matrix(x, times = c(12, 34, 42), type = "surv")

# Or use column names as time points
colnames(x) = c(12, 34, 42)
assert_prob_matrix(x)

# check CDF
assert_prob_matrix(1 - x, type = "cdf")