Creates a 2-column integer matrix that handles left- right- and interval-censored ordinal or continuous values for use in [rmsb::blrm()] and [orm()]. A pair of values `[a, b]` represents an interval-censored value known to be in the interval `[a, b]` inclusive of `a` and `b`. Left censored values are coded as `(-Infinity, b)` and right-censored as `(a, Infinity)`, both of these intervals being open at the finite endpoints. Because all values are converted to an exact integer grid, open intervals are handled with exact integer arithmetic: `(a, Infinity)` contains the same grid points as `[a + 1, Infinity)` after grid conversion, and similarly for left censoring. When right censoring occurs at or beyond the highest uncensored value, a new ordinal category is created to capture the real and unique information in outer censored values, representing P(Y > highest uncensored value). The new category is valued at the smallest such censoring point (moved up by one grid unit only when tied with the highest uncensored value), and is described by the `tail` attribute of the result. For example if the highest uncensored value is 10 and there is a right-censored value in the data at 10, a new category valued just above `10` is created, separate from the category for `10`. So it is assumed that if an exact value of 10 was observed, the pair of values for that observation would not be coded as `(10, Infinity)`.
Ocens2ord(
y,
precision = 7,
maxit = 10,
nponly = FALSE,
cons = c("intervals", "data", "none"),
verbose = FALSE
)a 2-column integer matrix of class `"Ocens"` with an attribute `levels` (ordered), and if there are zero-width intervals arising from censoring, an attribute `upper` with the vector of upper limits. Left-censored values are coded as `-Inf` in the first column of the returned matrix, and right-censored values as `Inf`. When the original variables were `factor`s, these are factor levels, otherwise are numerically or alphabetically sorted distinct (over `a` and `b` combined) values. When the variables are not factors and are numeric, other attributes `median`, `ranges`, `label`, and `npsurv` are also returned. `median` is the median of the uncensored values on the original scale. `ranges` is a 3-element list, each element a 2-vector range. The element named `y` is the range of original data values before adjustments. The `u` element is a 2-vector range of uncensored values before adjustment, and the `c` element contains the lowest left censoring point and highest right-censored point. Getting back to the main returned variables, `label` is the `label` attribute from the first of `a, b` having a label. `npsurv` is the nonparametric estimate of the survival curve (with elements `time` and `surv`) after any interval consolidation. If the argument `nponly=TRUE` was given, this `npsurv` list before consolidation is returned and no other calculations are done. When the variables are factor or character, the median of the integer versions of variables for uncensored observations is returned as attribute `mid`. A final attribute `freq` is the vector of frequencies of occurrences of all values. `freq` aligns with `levels`. A `units` attribute is also included. There are two 3-vectors `Ncens1` and `Ncens2`, the first containing the original number of left, right, and interval-censored observations and the second containing the frequencies after coding. For example, observations that are right-censored at or beyond the highest uncensored value are coded as uncensored at a new highest level to get the correct likelihood component in `orm.fit`. When only right censoring is present and there are censored observations at or beyond the highest uncensored point, an attribute `tail` is included: a list with elements `type` (currently `'right'`), `index` (the position in `levels` of the added category), `value` (the numeric value of the added category, on the original scale), `tied` (`TRUE` if the smallest such censoring value was tied with the highest uncensored value, in which case `value` is one grid unit above the censoring value), and `range` (a 2-vector containing the lowest and highest censored values at or beyond the last uncensored value, on the original scale). For backward compatibility a deprecated attribute `rt_cens_beyond` is also returned in that case, a list with elements `newlevel` (same as `tail$value`) and `range` (same as `tail$range`).
an `Ocens` object, which is a 2-column numeric matrix, or a regular vector representing a `factor`, numeric, integer, or alphabetically ordered character strings. Censoring points have values of `Inf` or `-Inf`.
when `y` columns are numeric, values may need to be rounded to avoid unpredictable behavior with unique() with floating-point numbers. Default is to 7 decimal places. See [this](https://hbiostat.org/r/rms/unique-float/) for more details.
maximum number of iterations allowed in the legacy interval consolidation process when `cons='data'`
set to `TRUE` to return a list containing the survival curve estimates before interval consolidation
set to `'none'` to not consolidate intervals carrying no estimable probability; this will likely cause a lot of trouble with zero cell probabilities during maximum likelihood estimation. The default `'intervals'` consolidates interval definitions and observation mappings without changing the data. `cons='data'` is deprecated: it changes the raw data values to make observed intervals wider, in an iterative manner until no more consecutive tied survival estimates remain, and requires the `icenReg` package.
set to `TRUE` to print information messages. Set `verbose` to a number greater than 1 to get more information printed, such as the estimated survival curve at each stage of consolidation.
Frank Harrell
The intervals that drive the coding of the input data into numeric ordinal levels are the Turnbull intervals (maximal intersections), computed by an internal sweep over sorted interval endpoints. These are defined in the `levels` and `upper` attributes of the object returned by `Ocens2ord`. Sometimes consecutive Turnbull intervals contain the same statistical information likelihood function-wise, leading to the same survival estimates over two or more consecutive intervals. This leads to zero probabilities of involved ordinal values, preventing `orm` from computing a valid log-likelihood. Intervals carrying no estimable probability are detected from the self-consistency (Kuhn-Tucker) condition of the nonparametric maximum likelihood estimate, which is computed internally by Turnbull's self-consistency algorithm, and are consolidated with neighboring intervals. With the default `cons='intervals'` this consolidation only remaps interval definitions and never changes the data. `cons='data'` is deprecated; it uses the legacy approach of iteratively changing the raw data values, and requires the `icenReg` package. If `verbose=TRUE`, information about the actions taken is printed.
When both input variables are `factor`s it is assumed that the one with the higher number of levels is the one that correctly specifies the order of levels, and that the other variable does not contain any additional levels. If the variables are not `factor`s it is assumed their original values provide the orderings. A left-censored point is coded as having `-Inf` as a lower limit, and a right-censored point is coded as having `Inf` as an upper limit. As with most censored-data methods, modeling functions assume that censoring is independent of the response variable values that would have been measured had censoring not occurred. `Ocens` creates a 2-column integer matrix suitable for ordinal regression. Attributes of the returned object give more information.