achievementLevels {EdSurvey} | R Documentation |

Returns achievement levels using weights and variance estimates appropriate for the `edsurvey.data.frame`

.

```
achievementLevels(
achievementVars = NULL,
aggregateBy = NULL,
data,
cutpoints = NULL,
returnDiscrete = TRUE,
returnCumulative = FALSE,
weightVar = NULL,
jrrIMax = 1,
omittedLevels = TRUE,
defaultConditions = TRUE,
recode = NULL,
returnNumberOfPSU = FALSE,
returnVarEstInputs = FALSE
)
```

`achievementVars` |
character vector indicating variables to be included in the achievement
levels table, potentially with a subject scale or subscale. When the subject
scale or subscale is omitted, the default subject scale or subscale is
used. You can find the default composite scale and all subscales using the
function |

`aggregateBy` |
character vector specifying variables by which to aggregate achievement levels. The percentage
column sums up to 100 for all levels of all variables specified here. When set to the
default of |

`data` |
an |

`cutpoints` |
numeric vector indicating cutpoints. Set to standard NAEP cutpoints for Basic, Proficient, and Advanced by default. |

`returnDiscrete` |
logical indicating if discrete achievement levels should be returned. Defaults
to |

`returnCumulative` |
logical indicating if cumulative achievement levels should be returned. Defaults
to |

`weightVar` |
character string indicating the weight variable to use.
Only the name of the
weight variable needs to be included here, and any
replicate weights will be automatically included.
When this argument is |

`jrrIMax` |
a numeric value. When using the jackknife variance estimation method, the default estimation option, |

`omittedLevels` |
a logical value. When set to the default value ( |

`defaultConditions` |
a logical value. When set to the default value of |

`recode` |
a list of lists to recode variables. Defaults to |

`returnNumberOfPSU` |
a logical value set to |

`returnVarEstInputs` |
a logical value set to |

The `achievementLevels`

function applies appropriate weights
and the variance estimation method for each
`edsurvey.data.frame`

, with several arguments for customizing
the aggregation and output of the analysis
results. Namely, by using these optional arguments, users can choose
to generate the percentage of students
performing at each achievement level (discrete), generate the
percentage of students performing at or above each achievement level
(cumulative),
calculate the percentage distribution of students by achievement
level (discrete or cumulative) and
selected characteristics (specified in `aggregateBy`

), and
compute the percentage distribution of students
by selected characteristics within a specific achievement level.

The details of the methods are shown in the vignette titled Statistical Methods Used in EdSurvey in “Estimation of Weighted Percentages When Plausible Values Are Present” and are used to calculate all cumulative and discrete probabilities.

When the requested achievement levels are discrete (`returnDiscrete = TRUE`

),
the percentage `\mathcal{A}`

is the percentage of students (within the categories specified in `aggregateBy`

)
whose scores lie in the range `[cutPoints_i, cutPoints_{i+1}), i = 0,1,...,n`

.
`cutPoints`

is the score thresholds provided by the user with `cutPoints_0`

taken
to be 0. `cutPoints`

are set to NAEP standard cutpoints for achievement levels by default.
To aggregate by a specific variable, for example, `dsex`

, specify `dsex`

in `aggregateBy`

and all other variables in `achievementVars`

. To aggregate by subscale, specify
the name of the subscale (e.g., `num_oper`

) in `aggregateBy`

and all other variables in
`achievementVars`

.

When the requested achievement levels are cumulative (`returnCumulative = TRUE`

),
the percentage `\mathcal{A}`

is the percentage of students (within the categories specified in `aggregateBy`

)
whose scores lie in the range [`cutPoints_i`

, `\infty`

), `i = 1, 2, ..., n-1`

. The
first and last categories are the same as defined for discrete levels.

The method used to calculate the standard error of the percentages is described in the vignette titled
Statistical Methods Used in EdSurvey
in the sections “Estimation of the Standard Error of Weighted Percentages When Plausible Values Are Present, Using the Jackknife Method”
and “Estimation of the Standard Error of Weighted Percentages When Plausible Values Are Not Present, Using the Taylor Series Method.”
For “Estimation of the Standard Error of Weighted Percentages When Plausible Values Are Present, Using the Jackknife Method,”
the value of `jrrIMax`

sets the value of `m^*`

.

A `list`

containing up to two data frames, one discrete achievement levels (when `returnDiscrete`

is `TRUE`

)
and one for cumulative achievement levels (when `returnCumulative`

is `TRUE`

). The `data.frame`

contains the following columns:

`Level` |
one row for each level of the specified achievement cutpoints |

`Variables in achievementVars` |
one column for each variable in |

`Percent` |
the percentage of students at or above each achievement level aggregated as specified by |

`StandardError` |
the standard error of the percentage, accounting for the survey sampling methodology. See the vignette titled Statistical Methods Used in EdSurvey. |

`N` |
the number of observations in the incoming data (the
number of rows when |

`wtdN` |
the weighted number of observations in the data |

`nPSU` |
the number of PSUs at or above each achievement level aggregated as specified by |

Huade Huo, Ahmad Emad, and Trang Nguyen

Rubin, D. B. (1987). *Multiple imputation for nonresponse in surveys*. New York, NY: Wiley.

```
## Not run:
# read in the example data (generated, not real student data)
sdf <- readNAEP(system.file("extdata/data", "M36NT2PM.dat", package="NAEPprimer"))
# discrete achievement levels
achievementLevels(achievementVars=c("composite"), aggregateBy=NULL, data=sdf)
# discrete achievement levels with a different subscale
achievementLevels(achievementVars=c("num_oper"), aggregateBy=NULL, data=sdf)
# cumulative achievement levels
achievementLevels(achievementVars=c("composite"), aggregateBy=NULL, data=sdf,
returnCumulative=TRUE)
# cumulative achievement levels with a different subscale
achievementLevels(achievementVars=c("num_oper"), aggregateBy=NULL, data=sdf,
returnCumulative=TRUE)
# achievement levels as independent variables, by sex aggregated by composite
achievementLevels(achievementVars=c("composite", "dsex"), aggregateBy="composite",
data=sdf, returnCumulative=TRUE)
# achievement levels as independent variables, by sex aggregated by sex
achievementLevels(achievementVars=c("composite", "dsex"), aggregateBy="dsex",
data=sdf, returnCumulative=TRUE)
# achievement levels as independent variables, by race aggregated by race
achievementLevels(achievementVars=c("composite", "sdracem"),
aggregateBy="sdracem", data=sdf, returnCumulative=TRUE)
# use customized cutpoints
achievementLevels(achievementVars=c("composite"), aggregateBy=NULL, data=sdf,
cutpoints = c("Customized Basic" = 200,
"Customized Proficient" = 300,
"Customized Advanced" = 400))
# use recode to change values for specified variables:
achievementLevels(achievementVars=c("composite", "dsex", "b017451"),
aggregateBy = "dsex", sdf,
recode=list(b017451=list(from=c("Never or hardly ever",
"Once every few weeks",
"About once a week"),
to="Infrequently"),
b017451=list(from=c("2 or 3 times a week",
"Every day"),
to="Frequently")))
## End(Not run)
```

[Package *EdSurvey* version 2.7.1 Index]