Description Usage Arguments Details Value Author(s) References Examples
Returns achievement levels using weights and variance estimates appropriate for the edsurvey.data.frame
.
1 2 3 4 5 
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.
Note that 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 Statistics 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, ∞), i = 1,2...,n1. 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
Statistics
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 for each of the discrete and cumulative achievement levels
as determined by returnDiscrete
and returnCumulative
. The data.frame
contains the following columns:

one row for each level of the specified achievement cutpoints 
Variables in achievementVars 
one column for each variable in 

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

the standard error of the percentage, accounting for the survey sampling methodology. See the vignette titled Statistics. 

the number of observations in the incoming data (the
number of rows when 

the weighted number of observations in the data 

the number of primary sampling units (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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49  ## 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)

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.