Extract Model Residuals — residuals • PAsso

A generic function to simulate surrogate residuals for cumulative link regression models using the latent method described in Liu and Zhang (2017).

It also support the sign-based residuals (Li and Shepherd, 2010), generalized residuals (Franses and Paap, 2001), and deviance residuals for cumulative link regression models.

Usage

# S3 method for clm
residuals(
  object,
  type = c("surrogate", "sign", "general", "deviance"),
  jitter = c("latent", "uniform"),
  jitter.uniform.scale = c("probability", "response"),
  nsim = 1L,
  ...
)

# S3 method for ord
residuals(
  object,
  type = c("surrogate", "sign", "general", "deviance", "pearson", "working", "response",
    "partial"),
  jitter = c("latent", "uniform"),
  jitter.uniform.scale = c("probability", "response"),
  nsim = 1L,
  ...
)

# S3 method for lrm
residuals(
  object,
  type = c("surrogate", "sign", "general", "deviance"),
  jitter = c("latent", "uniform"),
  jitter.uniform.scale = c("probability", "response"),
  nsim = 1L,
  ...
)

# S3 method for orm
residuals(
  object,
  type = c("surrogate", "sign", "general", "deviance"),
  jitter = c("latent", "uniform"),
  jitter.uniform.scale = c("probability", "response"),
  nsim = 1L,
  ...
)

# S3 method for polr
residuals(
  object,
  type = c("surrogate", "sign", "general", "deviance"),
  jitter = c("latent", "uniform"),
  jitter.uniform.scale = c("probability", "response"),
  nsim = 1L,
  ...
)

# S3 method for glm
residuals(
  object,
  type = c("surrogate", "sign", "general", "deviance", "pearson", "working", "response",
    "partial"),
  jitter = c("latent", "uniform"),
  jitter.uniform.scale = c("probability", "response"),
  nsim = 1L,
  ...
)

# S4 method for vglm
residuals(
  object,
  type = c("surrogate", "sign", "general", "deviance"),
  jitter = c("latent", "uniform"),
  jitter.uniform.scale = c("probability", "response"),
  nsim = 1L,
  ...
)

# S4 method for vgam
residuals(
  object,
  type = c("surrogate", "sign", "general", "deviance"),
  jitter = c("latent", "uniform"),
  jitter.uniform.scale = c("probability", "response"),
  nsim = 1L,
  ...
)

# S3 method for PAsso
residuals(object, draw_id = 1, ...)

Arguments

object

An object of class PAsso.

type

The type of residuals which should be returned. The alternatives are: "surrogate" (default), "sign", "general", and "deviance". Can be abbreviated.

surrogate: surrogate residuals (Liu and Zhang, 2017);
sign: sign-based residuals;
general: generalized residuals (Franses and Paap, 2001);
deviance: deviance residuals (-2*loglik).

jitter

When the type = "surrogate", this argument is a character string specifying which method to use to generate the surrogate response values. Current options are "latent" and "uniform". Default is "latent".

latent: latent approach;
uniform: jittering uniform approach.

jitter.uniform.scale

When the jitter = "uniform", this is a character string specifying the scale on which to perform the jittering whenever jitter = "uniform". Current options are "response" and "probability". Default is "response".

nsim

An integer specifying the number of replicates to use. Default is 1L meaning one simulation only of residuals.

...

Additional optional arguments.

draw_id

A number refers to the i-th draw of residuals.

Value

A numeric vector of class c("numeric", "resids") containing the simulated surrogate residuals. Additionally, if nsim > 1, then the result will contain the attributes:

draws: A matrix with nsim columns, one for each is a replicate of the surrogate residuals. Note, they correspond to the original ordering of the data;
draws_id: A matrix with nsim columns. Each column contains the observation number each surrogate residuals corresponds to in draws. (This is used for plotting purposes.)

A "resid" object with attributes. It contains a vector or a matrix (nsim>1) of residuals for the adjacent categories model.

A matrix of class c("matrix", "resids") containing the simulated surrogate residuals used for the partial association analysis in PAsso. Additionally, if rep_num > 1 in PAsso, then the result will contain the attributes:

draws: An array contains all draws of residuals.

Note

Surrogate response values require sampling from a continuous distribution; consequently, the result will be different with every call to surrogate. The internal functions used for sampling from truncated distributions are based on modified versions of rtrunc and qtrunc.

For "glm" objects, only the binomial() family is supported.

References

Liu, D., Li, S., Yu, Y., & Moustaki, I. (2020). Assessing partial association between ordinal variables: quantification, visualization, and hypothesis testing. Journal of the American Statistical Association, 1-14. doi:10.1080/01621459.2020.1796394

Liu, D., & Zhang, H. (2018). Residuals and diagnostics for ordinal regression models: A surrogate approach. Journal of the American Statistical Association, 113(522), 845-854. doi:10.1080/01621459.2017.1292915

Li, C., & Shepherd, B. E. (2010). Test of association between two ordinal variables while adjusting for covariates. Journal of the American Statistical Association, 105(490), 612-620. doi:10.1198/jasa.2010.tm09386

Franses, P. H., & Paap, R. (2001). Quantitative models in marketing research. Cambridge University Press. doi:10.1017/CBO9780511753794

Examples

# Example 1
# Load data with binary response
data(ANES2016)
# Fit glm model with binomial logit model
fit.prevote <- glm(PreVote.num ~ age + edu.year + income.num,
                   data = ANES2016, family = "binomial")

# Simulate surrogate residuals
res1 <- residuals(fit.prevote,
                  type = "surrogate",
                  jitter="latent",
                  jitter.uniform.scale="response")
attr(res1,"arguments")
#> [1] "surrogate" "latent"    "response" 

# Example 2
# residuals() function can also work for PAsso object
# Load data
data("ANES2016")
PAsso_1 <- PAsso(responses = c("PreVote.num", "PID"),
                 adjustments = c("income.num", "age", "edu.year"),
                 data = ANES2016)

# Extract surrogate residuals from the PAsso object
res1 <- residuals(PAsso_1)