R: Convert a raw score to a percentile rank

Stage.2.NormScore {NormData}

R Documentation

Convert a raw score to a percentile rank

Description

The function Stage.2.NormScore() can be used to convert the raw test score of a tested person Y_0 into a percentile rank \hat{\pi}_0 (taking into account specified values of the independent variables).

Usage

Stage.2.NormScore(Stage.1.Model, Assume.Homoscedasticity, 
Assume.Normality, Score, Rounded=TRUE)

Arguments

`Stage.1.Model`	A fitted object of class `Stage.1` that should be used to conduct the normative conversions.
`Assume.Homoscedasticity`	Logical. Should homoscedasticity be assumed in conducting the normative conversion? By default, homoscedasticity is assumed when the `p`-value of the Levene or Breusch-Pagan test for the fitted Stage 1 model is above the specified `\alpha`-level in the `Stage.1()` function call. When homoscedasticity is assumed, an overall residual standard error is used in the normative conversions. When homoscedasticity is not assumed, prediction-specific residual standard errors used. The default decision procedure can be overruled by means of the arguments argument `Assume.Homoscedasticity=TRUE` or `Assume.Homoscedasticity=FALSE`.
`Assume.Normality`	Logical. Should normality of the standardized errors be assumed in conducting the normative conversion? By default, normality is assumed when the `p`-value of the Shapiro-Wilk test for the fitted Stage 1 model is above the specified `\alpha`-level in the `Stage.1()` function call. When normality is assumed, the `Y_0` to `\hat{\pi}_0` conversion is based on the CDF of the standard normal distribution. When normality is not assumed, this conversion is based on the CDF of the standardized residuals in the normative sample. The default decision procedure can be overruled by means of the arguments argument `Assume.Normality=TRUE` or `Assume.Normality=FALSE`.
`Score`	A `list` that contains the test score `Y_0` to be converted into a percentile rank and the values for the relevant independent variable(s). For example, the argument `Score=list(Science.Exam=30, Gender="F")` specifies that a female student obtained a raw Science Exam score `Y_0`. Observe that quotes are used to refer to a female student (i.e., "F"). This is done because the string `F` (without quotes) is shorthand notation for the logical indicator `FALSE` in R. If no quotes are used, an error will be generated that a logical indicator was provided where a factor level was expected. To avoid such issues, it is recommended to always use quotes to refer to the levels of a factor. In the `Score=...` argument, the test score should always be specified first followed by the independent variable. Notice that both the name of the independent variable and the coding scheme that is specified in the `Score=...` argument should correspond to the name of the independent variable and the original coding scheme that was used in the `Stage.1()` function call. For example, if the variable name `Gender` original coding scheme `F` and `M` was used in the `Stage.1()` function call, the same should be done in the `Stage.2.NormScore()` call. Thus `Score=list(Science.Exam=30, Gender="F")` should be used, and not e.g., `Score=list(Science.Exam=30, GenderM=0)`.
`Rounded`	Logical. Should the percentile rank be rounded to a whole number? Default `Rounded=TRUE`.

Details

For details, see Van der Elst (2023).

Value

An object of class Stage.2.NormScore with components,

`Fitted.Model`	A fitted object of class `Stage.1()` that was used to convert the raw test score `Y_0` into a percentile rank `\hat{\pi}_0`.
`Results`	A data frame that contains the observed test score, residuals, percentile rank, ...
`Assume.Homoscedasticity`	The homoscedasticity assumption that was made in the normative conversion.
`Assume.Normality`	The normality assumption that was made in the normative conversion.
`Score`	The test score and the value(s) of the independent variable(s) that were used in the computations.
`Stage.1.Model`	The `Stage.1.Model` model used in the analysis.

Author(s)

Wim Van der Elst

References

Van der Elst, W. (2024). Regression-based normative data for psychological assessment: A hands-on approach using R. Springer Nature.

Examples

# Replicate the normative conversion that was obtained in 
# Case study 1 of Chapter 3 in Van der Elst (2023)
# (science exam score = 30 obtained by a female)
# -------------------------------------------------------
library(NormData) # load the NormData package
data(GCSE)        # load the GCSE dataset

# Fit the Stage 1 model
Model.1.GCSE <- Stage.1(Dataset=GCSE, 
  Model=Science.Exam~Gender)

# Stage 2: Convert a science exam score = 30 obtained by a 
# female into a percentile rank (point estimate)
Normed_Score <- Stage.2.NormScore(Stage.1.Model=Model.1.GCSE,
  Score=list(Science.Exam=30, Gender="F"))

summary(Normed_Score)
plot(Normed_Score)


# Replicate the normative conversion that was obtained in 
# Case study 1 of Chapter 7 in Van der Elst (2023)
# (LDST score = 40 obtained by a 20-year-old 
# test participant with LE=Low)
# -------------------------------------------------------
library(NormData)   # load the NormData package
data(Substitution)  # load the Substitution dataset

# Make the new variable Age.C (= Age centered) that is 
# needed to fit the final Stage 1 model, 
# and add it to the Substitution dataset
Substitution$Age.C <- Substitution$Age - 50

# Fit the final Stage 1 model
Substitution.Model.9 <- Stage.1(Dataset=Substitution, 
  Alpha=0.005, Model=LDST~Age.C+LE, Order.Poly.Var=1) 
summary(Substitution.Model.9)

# Convert an LDST score = 40 obtained by a 
# 20-year-old test participant with LE=Low 
# into a percentile rank (point estimate)
Normed_Score <- Stage.2.NormScore(
  Stage.1.Model=Substitution.Model.9, 
  Score=list(LDST=40, Age.C=20-50, LE = "Low"))

summary(Normed_Score)
plot(Normed_Score)

[Package NormData version 1.1 Index]