Type: Package
Title: Analysis of Partially Ordered Data
Version: 1.0.0
Description: Win ratio approach to partially ordered data, such as multivariate ordinal responses under product (consensus) or prioritized order. Two-sample tests and multiplicative regression models are implemented (Mao, 2024, under revision).
License: CC BY 4.0
URL: https://sites.google.com/view/lmaowisc/, https://lmaowisc.github.io/poset/
Depends: R (≥ 3.10)
Suggests: knitr, rmarkdown
VignetteBuilder: knitr
Config/testthat/edition: 3
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.1
NeedsCompilation: no
Packaged: 2024-06-18 14:23:52 UTC; lmao
Author: Lu Mao ORCID iD [aut, cre]
Maintainer: Lu Mao <lmao@biostat.wisc.edu>
Repository: CRAN
Date/Publication: 2024-06-19 14:50:02 UTC

poset: Analysis of Partially Ordered Data

Description

Win ratio approach to partially ordered data, such as multivariate ordinal responses under product (consensus) or prioritized order. Two-sample tests and multiplicative regression models are implemented (Mao, 2024, under revision).

Author(s)

Maintainer: Lu Mao lmao@biostat.wisc.edu (ORCID)

See Also

Useful links:

A dataset from a non-alcoholic fatty liver disease study

Description

A total of 186 patients with non-alcoholic fatty liver disease were recruited at the University of Wisconsin Hospitals in 2017. The patients underwent computed tomography scan of the liver for the presence of non-alcoholic steato-hepatitis, the most severe form of non-alcoholic fatty liver disease. The image was subsequently assessed by two radiologists using a scale of 1 to 5, with higher values indicating greater likelihood of disease. This is a slightly altered dataset from the one used in Mao (2024).

Usage

liver

Format

A data frame with 186 rows (one per patient) and 7 variables:

R1NASH, R2NASH

Rating scores (1-5) by two readers.

Sex

M: male; F: female.

AF

Advanced fibrosis (TRUE or FALSE).

Steatosis

Percent of steatosis.

SSF2

Liver mean gray level intensity.

LSN

Liver surface nodularity.

References

Mao, L. (2024). Win ratio for partially ordered data. Statistica Sinica, Under revision.

Print method for summary.wreg objects

Description

Print summary results for win ratio regression.

Usage

## S3 method for class 'summary.wreg'
print(x, ...)

Arguments

x

An object returned by summary.wreg.

...

Further arguments passed to or from other methods

Value

No return value, called for side effects.

Print concise model results from wreg

Description

Print concise results for win ratio regression.

Usage

## S3 method for class 'wreg'
print(x, ...)

Arguments

x

An object returned by wreg.

...

Further arguments passed to or from other methods

Value

No return value, called for side effects.

See Also

wreg.

Print results from wrtest

Description

Print the results for two-sample win ratio (net benefit) analysis, including point estimates, 95% confidence intervals, and p-values.

Usage

## S3 method for class 'wrtest'
print(x, ...)

Arguments

x

An object returned by wrtest.

...

Further arguments passed to or from other methods

Value

No return value, called for side effects.

See Also

wrtest.

Summarize model results from wreg

Description

Summarize the inferential results for win ratio regression.

Usage

## S3 method for class 'wreg'
summary(object, ...)

Arguments

object

An object returned by wreg.

...

Additional arguments affecting the summary produced.

Value

An object of class summary.wreg with components:

coefficients

A matrix of coefficients, standard errors, z-values and p-values.

exp_coef

A matrix of win ratios (exp(coef)) and 95% confidence intervals.

wald, wald_pval

Overall wald test statistic on all covariates and p-value.

See Also

wreg.

Examples

#See examples for wreg().

The product-order win function for multivariate ordinal data

Description

A common rule of comparison for the fun argument in wrtest and wreg. A winner has all its components greater than or equal to those of the loser, and strictly so for at least one component.

Usage

wprod(y1, y0)

Arguments

y1

A K-dimensional vector y_1.

y0

A K-dimensional vector y_0.

Value

An integer in {1, 0, -1}:

1

If y_1 \ge y_0 component-wise, with strict inequality for at least one component.

-1

If y_0 \ge y_1 component-wise, with strict inequality for at least one component.

0

Otherwise.

See Also

wrtest, wreg.

Win ratio regression analysis

Description

Fit a multiplicative win-ratio regression model to partially ordered response against covariates.

Usage

wreg(Y, Z, fun = NULL, sfun = NULL, ep = 1e-06)

Arguments

Y

An n\times K matrix for K-variate response data on n subjects. The entries must be numeric. For pseudo-efficient estimation (without specifying sfun), the average score across components (row means) should be compatible with the partial order (i.e., preserve the same order for any two comparable and ordered elements).

Z

An n\times p design matrix for covariates.

fun

User-specified win function for pairwise comparison. It takes two arguments y_1 and y_0 (both K-vectors) and returns 1 if y_1 wins, -1 if y_0 wins, and 0 if tied. The default is wprod for the product order of multivariate ordinal data.

sfun

The scoring function used in pseudo-efficient estimation. The default is to take the row means of Y.

ep

Convergence criterion in Newton-Raphson algorithm. The default is 1e-6.

Value

An object of class wreg with the following components:

beta

A vector of estimated regression coefficients.

var

Estimated covariance matrix for beta

l

Number of Newton-Raphson iterations.

beta_nv

Naive (non-pseudo-efficient) estimates of beta.

se_nv

Estimated standard errors for beta_nv.

n

Sample size n of input data with non-missing values.

Nwl

Number of comparable pairs (those with a win and loss) out of the n(n-1)/2 possible ones.

References

Mao, L. (2024). Win ratio for partially ordered data. Statistica Sinica, Under revision.

See Also

wprod, print.wreg, summary.wreg.

Examples

head(liver)
# regress bivariate ratings against covariates
Y <- 5 - liver[, c("R1NASH", "R2NASH")] # lower score is better
Z <- cbind("Female" = liver$Sex == "F",
           liver[, c("AF", "Steatosis",   "SSF2",  "LSN")]) # covariates
obj <- wreg(Y, Z) # fit model
obj
summary(obj)

Two-sample win ratio (net benefit) analysis

Description

Estimate and make inference on win ratio (net benefit) comparing a treatment to a control group.

Usage

wrtest(Y1, Y0, fun = wprod)

Arguments

Y1

K-variate response data on n_1 subjects in treatment (n_1\times K matrix).

Y0

K-variate response data on n_0 subjects in control (n_0\times K matrix).

fun

User-specified win function for pairwise comparison. It takes two arguments y_1 and y_0 (both K-vectors) and returns 1 if y_1 wins, -1 if y_0 wins, and 0 if tied. The default is wprod for the product order of multivariate ordinal data.

Value

An object of class wrtest with the following components:

theta

A bivariate vector of win/loss fractions.

lgwr, lgwr_se, lgwr_pval

Log-win ratio estimate (log(theta[1]/theta[2])), standard error, and p-value.

nb, nb_se, nb_pval

Net benefit estimate (theta[1]-theta[2]), standard error, and p-value.

References

Mao, L. (2024). Win ratio for partially ordered data. Statistica Sinica, Under revision.

Buyse, M. (2010). Generalized pairwise comparisons of prioritized outcomes in the two-sample problem. Statistics in Medicine, 29, 3245-3257.

See Also

wprod, print.wrtest.

Examples

head(liver)
## compare bivariate ratings by fibrosis stage
## lower score is better
Y1 <- liver[liver$AF, c("R1NASH", "R2NASH")] # advanced
Y0 <- liver[!liver$AF, c("R1NASH", "R2NASH")] # not advanced
obj <- wrtest(Y1, Y0)
obj