| Title: | Interpreting Differences Between Mean ACT Scores |
|---|---|
| Description: | Interpreting the differences between mean scale scores across various forms of an assessment can be challenging. This difficulty arises from different mappings between raw scores and scale scores, complex mathematical relationships, adjustments based on judgmental procedures, and diverse equating functions applied to different assessment forms. An alternative method involves running simulations to explore the effect of incrementing raw scores on mean scale scores. The 'idmact' package provides an implementation of this approach based on the algorithm detailed in Schiel (1998) <https://www.act.org/content/dam/act/unsecured/documents/ACT_RR98-01.pdf> which was developed to help interpret differences between mean scale scores on the American College Testing (ACT) assessment. The function idmact_subj() within the package offers a framework for running simulations on subject-level scores. In contrast, the idmact_comp() function provides a framework for conducting simulations on composite scores. |
| Authors: | Mackson Ncube [aut, cre, cph] |
| Maintainer: | Mackson Ncube <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.1.9000 |
| Built: | 2025-02-07 03:11:31 UTC |
| Source: | https://github.com/mncube/idmact |
This function adjusts raw scores either by a fixed increment or according to a specified function. It can adjust scores stored in a list or within a specific column of a data frame.
adjust_raw_scores(df = NULL, raw, inc = 1)adjust_raw_scores(df = NULL, raw, inc = 1)
df |
An optional data frame containing a column for raw scores. If 'df' is provided, 'raw' should be the name of the column in 'df' that contains the raw scores. If 'df' is NULL, 'raw' should be a list of raw scores. Default is NULL. |
raw |
Either a string representing the name of the column in 'df' that contains the raw scores, or a list of raw scores if 'df' is NULL. |
inc |
Either a numeric value that will be added to each raw score to calculate the adjusted raw score, or a function that will be applied to each raw score to calculate the adjusted score. The function should take a single numeric argument and return a single numeric value. |
If 'df' is NULL, the function returns a list containing the the adjusted raw scores. If 'df' is provided, the function returns a vector containing the adjusted raw scores.
# Create raw data df <- data.frame(Id = 1:20, RawScore = rep(11:15, 4)) # Increment scores by 2 df$AdjScore <- adjust_raw_scores(df, "RawScore", inc = 2) # Adjust scores using a function adjust_raw_scores(df = NULL, raw = list(11:15), inc = function(x) {x^2})# Create raw data df <- data.frame(Id = 1:20, RawScore = rep(11:15, 4)) # Increment scores by 2 df$AdjScore <- adjust_raw_scores(df, "RawScore", inc = 2) # Adjust scores using a function adjust_raw_scores(df = NULL, raw = list(11:15), inc = function(x) {x^2})
The idmact_comp() function calculates and interprets differences in ACT composite scores. The function operates in the following steps:
Increment raw scores for one or more subjects for each student to obtain adjusted raw scores.
Map adjusted raw scores to adjusted scale scores using the form's raw score to scale score map.
Obtain each examinee's adjusted composite scale score by averaging the adjusted scale scores across subjects.
Calculate the adjusted and unadjusted mean composite scale scores across all observations.
Compute the difference between the adjusted and unadjusted mean composite scale scores.
idmact_comp( df = NULL, df_map = NULL, raw, inc, map_raw, map_scale, mcent_subj = function(x) mean(x, na.rm = TRUE), mcent_obs = function(x) round(sum(x)/length(x)), mcent_comp = function(x) mean(x, na.rm = TRUE), na.rm.max = TRUE )idmact_comp( df = NULL, df_map = NULL, raw, inc, map_raw, map_scale, mcent_subj = function(x) mean(x, na.rm = TRUE), mcent_obs = function(x) round(sum(x)/length(x)), mcent_comp = function(x) mean(x, na.rm = TRUE), na.rm.max = TRUE )
df |
A data frame containing raw scores (optional). If provided, the 'raw' parameter should contain column names from this data frame. |
df_map |
A data frame mapping raw scores to scale scores. |
raw |
A list of raw scores for each subject, or column names from 'df' where raw scores are stored. |
inc |
A value or function used to increment raw scores for adjusted score calculation. This can be a single value or a list of values for each subject. |
map_raw |
Column names from 'df' or 'df_map' representing the domain of raw scores, or a list of such domains. |
map_scale |
Column names from 'df' or 'df_map' representing the range of scale scores, or a list of such ranges. |
mcent_subj |
A function summarizing scale scores at the subject level (default is mean with NA removal). |
mcent_obs |
A function summarizing scale scores at the examinee level (default is round(mean)). |
mcent_comp |
A function summarizing composite level scale scores (default is mean with NA removal). |
na.rm.max |
A boolean indicating whether to remove NA values when computing maximum raw and scale values in the mapping. |
By default, the function parameters align with the method presented in Schiel (1998). However, you can specify arbitrary anonymous functions for different implementations.
A list containing composite and subject level results. "composite_results" includes the difference between the adjusted and unadjusted mean composite scale scores (deltac), the mean adjusted and unadjusted composite scale scores (mscale), and a list of individual adjusted and unadjusted composite scale scores (scale). "subject_results" includes the outcomes from idmact_subj for each subject.
Schiel, J. C. (1998). Interpreting differences in ACT composite scores (ACT Research Report Series 98-1). ACT, Inc. URL: https://www.act.org/content/dam/act/unsecured/documents/ACT_RR98-01.pdf
# Example 1: Using df and df_map df <- data.frame(raw1 = c(1, 2, 3), raw2 = c(1, 1, 1)) df_map <- data.frame(map_raw1 = c(1, 2, 3), map_scale1 = c(20, 21, 22), map_raw2 = c(1, 1, 1), map_scale2 = c(20, 20, 20)) comp_mean <- idmact_comp(df = df, df_map = df_map, raw = c("raw1", "raw2"), inc = 1, map_raw = c("map_raw1", "map_raw2"), map_scale = c("map_scale1", "map_scale2")) # Example 2: Using lists raw = list(list(1, 2, 3, 4, 5), list(1, 1, 1, 1, 1)) inc = list(1 , 1) map_raw = list(list(1, 2, 3, 4, 5)) map_scale = list(list(20, 21, 22, 23, 24)) comp_mean <- idmact_comp(raw = raw, inc = inc, map_raw = map_raw, map_scale = map_scale)# Example 1: Using df and df_map df <- data.frame(raw1 = c(1, 2, 3), raw2 = c(1, 1, 1)) df_map <- data.frame(map_raw1 = c(1, 2, 3), map_scale1 = c(20, 21, 22), map_raw2 = c(1, 1, 1), map_scale2 = c(20, 20, 20)) comp_mean <- idmact_comp(df = df, df_map = df_map, raw = c("raw1", "raw2"), inc = 1, map_raw = c("map_raw1", "map_raw2"), map_scale = c("map_scale1", "map_scale2")) # Example 2: Using lists raw = list(list(1, 2, 3, 4, 5), list(1, 1, 1, 1, 1)) inc = list(1 , 1) map_raw = list(list(1, 2, 3, 4, 5)) map_scale = list(list(20, 21, 22, 23, 24)) comp_mean <- idmact_comp(raw = raw, inc = inc, map_raw = map_raw, map_scale = map_scale)
This function implements an algorithm to analyze differences in subject level scores.It first adjusts raw scores for each student, maps these adjusted raw scores to scale scores using the provided raw-to-scale score mapping (note: perfect raw scores are always converted to the maximum allowable scale score despite the adjustment in the previous step), then calculates the mean adjusted and unadjusted scale scores across all observations. The difference (delta) between these two mean scores is then computed. The adjustment and calculation method follows Schiel's (1998) methodology, but can also be customized with user-defined parameters and functions.
idmact_subj( df = NULL, df_map = NULL, raw, inc = 1, map_raw, map_scale, mcent_subj = function(x) mean(x, na.rm = TRUE), na.rm.max = TRUE )idmact_subj( df = NULL, df_map = NULL, raw, inc = 1, map_raw, map_scale, mcent_subj = function(x) mean(x, na.rm = TRUE), na.rm.max = TRUE )
df |
An optional data frame containing the variable for raw scores. |
df_map |
A data frame that maps raw scores to their corresponding scale scores. |
raw |
A list of raw scores, or a string representing the column name in 'df' containing raw scores. |
inc |
A numeric value used to increment raw scores to calculate adjusted scores, or a function to perform this incrementing operation. |
map_raw |
A list containing the domain of raw scores for the raw-to-scale score mapping, or a string representing the column name in 'df' or 'df_map' that contains this domain. |
map_scale |
A list containing the range of scale scores for the raw-to-scale score mapping, or a string representing the column name in 'df' or 'df_map' that contains this range. |
mcent_subj |
A function that defines the measure of central tendency to be used. The default is 'mean'. |
na.rm.max |
A logical value. If TRUE, missing values are removed before calculating the maximum raw and scale values in the mapping. If FALSE, missing values are not removed. |
A list containing the following elements:
'deltas': the difference between the mean adjusted and unadjusted scale scores,
'm_scale': a list with the mean adjusted ('adj') and unadjusted ('unadj') scale scores,
'scale': a list with the individual adjusted ('adj') and unadjusted ('unadj') scale scores,
'raw': a list with the individual adjusted ('adj') and unadjusted ('unadj') raw scores.
Schiel, J. C. (1998). Interpreting differences in ACT composite scores (ACT Research Report Series 98-1). ACT, Inc. URL: https://www.act.org/content/dam/act/unsecured/documents/ACT_RR98-01.pdf
raw_scores = list(1, 2, 3, 4, 5) map_raw_scores = list(1, 2, 3, 4, 5) map_scale_scores = list(20, 21, 22, 23, 24) idmact_subj(raw = raw_scores, map_raw = map_raw_scores, map_scale = map_scale_scores)raw_scores = list(1, 2, 3, 4, 5) map_raw_scores = list(1, 2, 3, 4, 5) map_scale_scores = list(20, 21, 22, 23, 24) idmact_subj(raw = raw_scores, map_raw = map_raw_scores, map_scale = map_scale_scores)
This function elongates the mapping of raw scores to scale scores. Each element in 'map_raw' and 'map_scale' is repeated according to the length of the corresponding 'map_raw' element, resulting in equal-length lists of map_raw' and 'map_scale' scores.
map_elongate(map_raw, map_scale)map_elongate(map_raw, map_scale)
map_raw |
A list where each element is a number or a numeric vector representing a set of raw scores. Each vector in 'map_raw' should have a corresponding element in 'map_scale'. |
map_scale |
A list where each element represents a scale score corresponding to the raw scores in 'map_raw'. Each element in 'map_scale' is repeated times the length of the corresponding element in 'map_raw'. |
A named list with two components: 'map_raw' and 'map_scale'. Each component is a list representing the elongated mapping of raw scores to scale scores.
# Elongate the mapping of raw scores (1:5 and 6:10) to scale scores (20 and 21) map_elongate(map_raw = list(1:5, 6:10), map_scale = list(20, 21))# Elongate the mapping of raw scores (1:5 and 6:10) to scale scores (20 and 21) map_elongate(map_raw = list(1:5, 6:10), map_scale = list(20, 21))
This function takes a data frame that maps raw scores to scale scores, and elongates it. Each raw score range in the 'map_raw' column is split into individual scores, and each corresponding scale score in the 'map_scale' column is repeated for each individual raw score. The function returns a new data frame with each raw score paired with its corresponding scale score.
map_elongate_df(df_map, map_raw, map_scale)map_elongate_df(df_map, map_raw, map_scale)
df_map |
A data frame that maps raw scores to their corresponding scale scores. The 'map_raw' column should contain ranges of raw scores as strings (in the form, "1-5"), and the 'map_scale' column should contain the corresponding scale scores. |
map_raw |
A string representing the column name in 'df_map' that contains the raw score ranges. |
map_scale |
A string representing the column name in 'df_map' that contains the scale scores. |
An elongated data frame where each row represents a raw score and its corresponding scale score.
# Create a data frame mapping raw score ranges to scale scores df_map <- data.frame( raw = c("1-5", "6-10"), scale = c(10, 11) ) # Elongate the data frame elongated_df <- map_elongate_df(df_map, "raw", "scale") print(elongated_df)# Create a data frame mapping raw score ranges to scale scores df_map <- data.frame( raw = c("1-5", "6-10"), scale = c(10, 11) ) # Elongate the data frame elongated_df <- map_elongate_df(df_map, "raw", "scale") print(elongated_df)
This function converts raw scores into scale scores using a provided mapping. The mapping can be provided directly as lists through 'map_raw' and 'map_scale', or indirectly via columns within either 'df' or 'df_map' data frames.
map_scores( df = NULL, df_map = NULL, conv, map_raw, map_scale, na.rm.max = TRUE )map_scores( df = NULL, df_map = NULL, conv, map_raw, map_scale, na.rm.max = TRUE )
df |
An optional data frame containing a column for raw scores. If 'df' is provided and 'conv' is a character, 'conv' should represent the name of the column in 'df' containing the raw scores. |
df_map |
An optional data frame that maps raw scores to their corresponding scale scores. If 'df_map' is provided, map_raw' and 'map_scale' should represent the names of the columns in 'df_map' that describe how raw scores map to scale scores. |
conv |
Either a list of raw scores to be converted or a string representing the name of a column in 'df' containing the raw scores. |
map_raw |
Either a list containing the domain of raw scores for the raw-to-scale score mapping, or a string representing the name of a column in either 'df' or 'df_map' containing these values. |
map_scale |
Either a list containing the range of scale scores for the raw-to-scale score mapping, or a string representing the name of a column in either 'df' or 'df_map' containing these values. |
na.rm.max |
Logical. Should missing values be removed when computing the maximum raw and scale values in the mapping? Default is TRUE. |
A list of scale scores.
# Convert raw scores to scale scores using lists map_scores(conv = list(1, 2, 3, 4, 5), map_raw = list(1, 2, 3, 4, 5), map_scale = list(20, 21, 22, 23, 24)) # Convert raw scores to scale scores using a data frame df <- data.frame(Id = 1:5, RawScore = 1:5) df_map <- data.frame(Raw = 1:5, Scale = 20:24) df$ScaleScore <- map_scores(df, df_map, conv = "RawScore", map_raw = "Raw", map_scale = "Scale")# Convert raw scores to scale scores using lists map_scores(conv = list(1, 2, 3, 4, 5), map_raw = list(1, 2, 3, 4, 5), map_scale = list(20, 21, 22, 23, 24)) # Convert raw scores to scale scores using a data frame df <- data.frame(Id = 1:5, RawScore = 1:5) df_map <- data.frame(Raw = 1:5, Scale = 20:24) df$ScaleScore <- map_scores(df, df_map, conv = "RawScore", map_raw = "Raw", map_scale = "Scale")