Package 'test2norm'

Neuropsychological test data

Description

A simulated data containing raw test scores and demographic characteristics for 250 persons, 200 in the control group and 50 in the test group. The raw test scores are to be converted to demographically corrected normed scores, adjusting for effects of age and sex. The control group is used to generate the norming formulas, which are then applied to all scores.

Usage

PsychTestData

Format

A data frame with 250 rows and 4 variables:

rawscore

raw test score on a neuropsychological test, ranging 0-36, with higher values indicating better test performance

age

age of the participant, in years

male

sex of the participant, male (1) or female (0)

group

norming group the participant belongs to (control or test)

Examples

data(PsychTestData)
test2norm(data = PsychTestData, test = "rawscore",
          test.min = 0, test.max = 36, test.better = "High",
          group.id = "group", control.id = "control",
          demographics = c("age", "male"))

---

Convert raw neuropsychological test scores to scaled scores.

Description

Convert raw neuropsychological test scores to scaled scores.

Usage

raw2scaled(
  data = NULL,
  test = NULL,
  test.min = NULL,
  test.max = NULL,
  test.better = c("High", "Low"),
  group.id = NULL,
  control.id = NULL,
  all.controls = FALSE,
  rnd.s = TRUE
)

Arguments

data	a data frame containing the test score
test	a character string specifying the name of the variable containing the test score
test.min	a real number indicating the smallest possible test score
test.max	a real number indicating the largest possible test score
test.better	a character string indicating direction of the scores. Use "High" if high test scores imply better performance, use "Low" otherwise.
group.id	a character string specifying the name of the variable containing group identification (i.e. control vs exposed/test/risk). Ignored, if all.controls = TRUE.
control.id	a character string specifying the label of the control group within group.id variable. Ignored, if all.controls = TRUE.
all.controls	a logical indicating whether all observations should be treated as controls. Overwrites group.id and control.id.
rnd.s	a logical indicating whether the scaled scores should be rounded. Default is TRUE.

Details

The raw2scaled() function can be used by neuropsychologists, who wish to convert raw test scores to scaled scores (mean=10, SD=3), using methods described in Heaton et al. (2003 & 2009). The raw test scores that have many decimal digits should be rounded to fewer digits prior to the application of the raw2scaled() function. This will significantly reduce software running time. The recommended number of decimal digits is 4 or fewer. Values below test.min or above test.max will result in NA. Detailed description of the procedure are found in Umlauf et al. (2024).

Note that the function does not guarantee that the calculated scaled scores range from 0 to 20, because it uses normal distribution quantiles. Therefore, scaled scores outside 0-20 range are possible.

Value

A list consisting of 3 objects. The first two are vectors containing the original raw test scores and the calculated scaled scores. The third object in the list, called SS.maps, contains conversions from raw scores to scaled scores in a form of a table with two columns, one representing scaled scores (one per row) and one representing raw scores (a single value or range of raw values corresponding to each scaled score). Note that this table shows rounded scaled scores regardless of the value for rnd.s.

Author(s)

Anya Umlauf

References

Umlauf A et al. (2024) Automated procedure for demographic adjustments on cognitive test scores. <doi:10.1080/23279095.2023.2288231>

Heaton RK, Taylor MJ, & Manly J (2003) Demographic effects and use of demographically corrected norms with the WAIS-III and WMS-III. In: Tulsky D et al. (Eds.) Clinical Interpretation of the WAIS-III and WMS-III. San Diego, CA: Academic Press, 183-210.

Heaton RK, Ryan L, & Grant I (2009) Demographic influences and use of demographically corrected norms in neuropsychological assessment. In Grant I & Adams KM (Eds.) Neuropsychological Assessment of Neuropsychiatric and Neuromedical Disorders. New York, NY: Oxford University Press, 127-155.

Examples

data(PsychTestData)
raw2scaled(data = PsychTestData, test = "rawscore",
           test.min = 0, test.max = 36, test.better = "High",
           group.id = "group", control.id = "control")

---

Convert neuropsychological test scores to demographically adjusted norms.

Description

Convert neuropsychological test scores to demographically adjusted norms.

Usage

score2adjust(
  data = NULL,
  test.score = NULL,
  group.id = NULL,
  control.id = NULL,
  all.controls = FALSE,
  demographics = NULL,
  mfp.alpha = 1,
  rnd.a = TRUE,
  mean.a = 50,
  sd.a = 10
)

Arguments

data	a data frame containing the variables needed for the norming process. The current version of the function does not accomodate missing data. For best results, exclude cases with missing test scores or missing demographics before applying this function.
test.score	a character string specifying the name of the test to be normed, usually the output of the raw2scaled() function.
group.id	a character string specifying the name of the variable containing group identification (i.e. control vs exposed/test/risk). Ignored, if all.controls = TRUE.
control.id	a character string specifying the label of the control group within group.id variable. Ignored, if all.controls = TRUE.
all.controls	a logical indicating whether all observations should be treated as controls. Overwrites group.id and control.id.
demographics	a single or multiple character strings (concatenated by c() function) specifying the names of demographic predictors to be included into normative formulas. Demographic variables should be numeric or binary (0/1).
mfp.alpha	a numeric value between 0 and 1 that sets significance level for inclusion of demographic predictors into normative formula. Passed to the mfp2() function (its select argument). Default value is 1 for inclusion of all predictors regardless of their significance.
rnd.a	a logical indicating whether the adjusted scores (T-scores) should be rounded. Default is TRUE.
mean.a	numeric value for the mean of adjusted score (T-score) distribution. Default is 50.
sd.a	numeric value for the standard deviation of adjusted score (T-score) distribution. Default is 10.

Details

The score2adjust() function can be used by neuropsychologists, who wish to construct normative formulas for cognitive tests that adjust for expected effects of demographic characteristics (e.g., age), using methods described in Heaton et al. (2003 & 2009). The adjusted scores are sometimes referred to as T-scores in the literature. The norming procedure makes use of the mfp2() function from the mfp2 package to explore nonlinear associations between cognition and demographic variables. Detailed description of the procedure are found in Umlauf et al. (2024). (Previous versions of the function depended on mfp package.)

Value

A list consisting of 3 objects. The first two are vectors containing the non-adjusted test scores and the calculated demographically adjusted scores. The last item in the output list is also a list called MFP.formulas. It contains the information for calculation of adjusted scores, including variable transformations (if any), multiple fractional polynomial (MFP) model coefficients, the standard deviation of residuals resulting from the MFP modeling, and a matrix with number of rows equal to the number of predictors and 2 columns containing powers (in numeric form) selected for variable transformations.

Author(s)

Anya Umlauf

References

Umlauf A et al. (2024) Automated procedure for demographic adjustments on cognitive test scores. <doi:10.1080/23279095.2023.2288231>

Heaton RK, Taylor MJ, & Manly J (2003) Demographic effects and use of demographically corrected norms with the WAIS-III and WMS-III. In: Tulsky D et al. (Eds.) Clinical Interpretation of the WAIS-III and WMS-III. San Diego, CA: Academic Press, 183-210.

Heaton RK, Ryan L, & Grant I (2009) Demographic influences and use of demographically corrected norms in neuropsychological assessment. In Grant I & Adams KM (Eds.) Neuropsychological Assessment of Neuropsychiatric and Neuromedical Disorders. New York, NY: Oxford University Press, 127-155.

Benner A (2005) mfp: Multivariable fractional polynomials. R News 5(2): 20–23.

Examples

data(PsychTestData)
PsychTestData$scaledscore <- raw2scaled(data=PsychTestData, test="rawscore",
                                        test.min=0, test.max=36,
                                        test.better="High", group.id="group",
                                        control.id="control")[[2]]
score2adjust(data = PsychTestData, test.score = "scaledscore",
             group.id = "group", control.id = "control",
             demographics = c("age", "male"))

---

Convert raw neuropsychological test scores to demographically adjusted norms.

Description

Convert raw neuropsychological test scores to demographically adjusted norms.

Usage

test2norm(
  data = NULL,
  test = NULL,
  test.min = NULL,
  test.max = NULL,
  test.better = c("High", "Low"),
  group.id = NULL,
  control.id = NULL,
  all.controls = FALSE,
  demographics = NULL,
  mfp.alpha = 1,
  rnd.s = TRUE,
  rnd.a = TRUE,
  mean.a = 50,
  sd.a = 10
)

Arguments

data	a data frame containing the variables needed for the norming process. The current version of the function does not accomodate missing data. For best results, exclude cases with missing test scores or missing demographics before applying this function.
test	a character string specifying the name of the test to be normed
test.min	a real number indicating the smallest possible test score
test.max	a real number indicating the largest possible test score
test.better	a character string indicating direction of the scores. Use "High" if high test scores imply better performance, use "Low" otherwise.
group.id	a character string specifying the name of the variable containing group identification (i.e. control vs exposed/test/risk). Ignored, if all.controls = TRUE.
control.id	a character string specifying the label of the control group within group.id variable. Ignored, if all.controls = TRUE.
all.controls	a logical indicating whether all observations should be treated as controls. Overwrites group.id and control.id.
demographics	a single or multiple character strings (concatenated by c() function) specifying the names of demographic predictors to be included into normative formulas. Demographic variables should be numeric or binary (0/1).
mfp.alpha	a numeric value between 0 and 1 that sets significance level for inclusion of demographic predictors into normative formula. Passed to the mfp2() function. Default value is 1 for inclusion of all predictors regardless of their significance.
rnd.s	a logical indicating whether the scaled scores should be rounded. Default is TRUE.
rnd.a	a logical indicating whether the adjusted scores (T-scores) should be rounded. Default is TRUE.
mean.a	numeric value for the mean of adjusted score (T-score) distribution. Default is 50.
sd.a	numeric value for the standard deviation of adjusted score (T-score) distribution. Default is 10.

Details

The test2norm() function can be used by neuropsychologists, who wish to construct normative formulas for cognitive tests that adjust for expected effects of demographic characteristics (e.g., age), using methods described in Heaton et al. (2003 & 2009). The norming procedure makes use of the mfp2() function from the mfp2 package to explore nonlinear associations between cognition and demographic variables. The raw test scores that have many decimal digits should be rounded to fewer digits prior to the application of the test2norm() function. This will significantly reduce software running time. The recommended number of decimal digits is 4 or fewer. Detailed description of the procedure are found in Umlauf et al. (2024). (Previous versions of the function depended on mfp package.)

Value

A list consisting of 6 objects. The first four are vectors containing the original raw test scores and the calculated scaled scores, demographically adjusted scores, and deficit scores. The fifth object in the list, called SS.maps, contains conversions from raw scores to scaled scores in a form of a table with two columns, one representing scaled scores (one per row) and one representing raw scores (range of raw values corresponding to each scaled score). The last item in the output list is also a list called MFP.formulas and contains the information for calculation of adjusted scores, including variable transformations (if any), multiple fractional polynomial (MFP) model coefficients, and the standard deviation of residuals resulting from the MFP modeling.

Author(s)

Anya Umlauf

References

Umlauf A et al. (2024) Automated procedure for demographic adjustments on cognitive test scores. <doi:10.1080/23279095.2023.2288231>

Heaton RK, Taylor MJ, & Manly J (2003) Demographic effects and use of demographically corrected norms with the WAIS-III and WMS-III. In: Tulsky D et al. (Eds.) Clinical Interpretation of the WAIS-III and WMS-III. San Diego, CA: Academic Press, 183-210.

Heaton RK, Ryan L, & Grant I (2009) Demographic influences and use of demographically corrected norms in neuropsychological assessment. In Grant I & Adams KM (Eds.) Neuropsychological Assessment of Neuropsychiatric and Neuromedical Disorders. New York, NY: Oxford University Press, 127-155.

Benner A (2005) mfp: Multivariable fractional polynomials. R News 5(2): 20–23.

Examples

data(PsychTestData)
test2norm(data = PsychTestData, test = "rawscore",
          test.min = 0, test.max = 36, test.better = "High",
          group.id = "group", control.id = "control",
          demographics = c("age", "male"))

---