Utility function to perform sequence of 6 steps going from data preparation, prepareSGP, SGP data analysis, analyzeSGP,
data combining, combineSGP, data summary, summarizeSGP, data visualization visualizeSGP and data output
outputSGP.
abcSGP(sgp_object,
state=NULL,
steps=c("prepareSGP", "analyzeSGP", "combineSGP",
"summarizeSGP", "visualizeSGP", "outputSGP"),
years=NULL,
content_areas=NULL,
grades=NULL,
prepareSGP.var.names=NULL,
prepareSGP.create.additional.variables=FALSE,
prepareSGP.create.achievement.level=TRUE,
sgp.percentiles=TRUE,
sgp.projections=TRUE,
sgp.projections.lagged=TRUE,
sgp.percentiles.baseline=TRUE,
sgp.projections.baseline=TRUE,
sgp.projections.lagged.baseline=TRUE,
sgp.use.my.coefficient.matrices=NULL,
sgp.minimum.default.panel.years=NULL,
sgp.target.scale.scores=FALSE,
sgp.target.scale.scores.only=FALSE,
sgp.test.cohort.size=NULL,
return.sgp.test.results=FALSE,
simulate.sgps=TRUE,
calculate.simex=NULL,
calculate.simex.baseline=NULL,
calculate.srs=NULL,
calculate.srs.baseline=NULL,
goodness.of.fit.print=TRUE,
parallel.config=NULL,
save.intermediate.results=FALSE,
save.old.summaries=FALSE,
sgPlot.demo.report=FALSE,
sgp.config=NULL,
sgp.summaries=NULL,
summary.groups=NULL,
data_supplementary=NULL,
confidence.interval.groups=NULL,
plot.types=c("bubblePlot", "studentGrowthPlot", "growthAchievementPlot"),
outputSGP.output.type=c("LONG_Data",
"LONG_FINAL_YEAR_Data",
"WIDE_Data",
"INSTRUCTOR_Data"),
outputSGP.directory="Data",
verbose.output=FALSE,
sgp.sqlite=FALSE,
sgp.percentiles.equated=NULL,
sgp.percentiles.equating.method=NULL,
sgp.percentiles.calculate.sgps=TRUE,
get.cohort.data.info=FALSE,
SGPt=NULL,
fix.duplicates=NULL)Function returns a list containing the input long data set in the @Data slot as a data.table keyed using VALID_CASE, CONTENT_AREA,
YEAR, ID, SGP results including student growth percentile and student growth projections/trajectories in the SGP slot, and summary results in the
@Summary slot.
A list containing LONG formatted data. See sgpData_LONG for an exemplar. By including the name of the state in the object name (e.g., Idaho_SGP), the function
will detect what state is associated with the data and supply that to the 'state' argument of the function so that state meta-data located in the SGPstateData object can be utilized.
NOTE: Data preparation must be meticulous to utilize this enhanced functionality.
Acronym indicating state associated with the data for access to embedded knot and boundaries, cutscores, CSEMs, and other relevant state level data. This can be supplied to the function
automatically by including the full state name (e.g, New_Hampshire_SGP) in the name of the object supplied to sgp_object.
Vector containing all or some subset of prepareSGP, analyzeSGP, combineSGP, summarizeSGP, visualizeSGP
indicating what steps the user wants accomplished. Default is to perform all steps.
A vector indicating year(s) in which to produce student growth percentiles and/or student growth projections/trajectories. If missing the function will use the data to infer the year(s) in which to perform growth percentile analyses based upon the assumption of having at least three years of panel data for analyses.
A vector indicating content area(s) in which to produce student growth percentiles and/or student growth projections/trajectories. If missing the function will use the data to infer the content area(s) available for analyses.
A vector indicating grades for which to calculate student growth percentiles and/or student growth projections/trajectories. If missing the function will use the data to infer all the grade progressions for student growth percentile and student growth projections/trajectories analyses.
list supplied to prepareSGP mapping provided variable names to variable names required as part of the SGP package. See prepareSGP for more details. Defaults to NULL.
Boolean variable indicating whether prepareSGP should create addition variables (e.g., HIGH_NEED_STATUS) if they are missing. Defaults to FALSE.
Boolean variable indicating whether prepareSGP should create ACHIEVEMENT_LEVEL variable if it is missing. Defaults to TRUE.
Boolean variable indicating whether to calculate student growth percentiles. Defaults to TRUE.
Boolean variable indicating whether to calculate student growth projections. Defaults to TRUE.
Boolean variable indicating whether to calculate lagged student growth projections often used for growth to standard analyses. Defaults to TRUE.
Boolean variable indicating whether to calculate baseline student growth percentiles and/or coefficient matrices. Defaults to TRUE.
Boolean variable indicating whether to calculate baseline student growth projections. Defaults to TRUE.
Boolean variable indicating whether to calculate lagged baseline student growth projections. Defaults to TRUE.
Boolean variable indicating whether to use embedded coefficient matrices to calculate SGPs. One should be careful to remove previously calculated SGPs prior to recalculating SGPs.
Integer indicating the minimum number of panel years to begin with in the calculation of student growth percentiles. The default is NULL (converted to 3 years).
Boolean variable passed to combineSGP indicating whether target scale scores associated with SGP_TARGETs should be calculated as
part of the combineSGP run. Defaults to FALSE.
Boolean variable passed to combineSGP indicating whether ONLY target scale scores associated with SGP_TARGETs should be calculated as
part of the combineSGP run. Defaults to FALSE.
Integer indicating the maximum number of students sampled from the full cohort to use in the calculation of student growth percentiles. Intended to be used as a test of the desired analyses to be run. The default, NULL, uses no restrictions (no tests are performed, and analyses use the entire cohort of students).
Boolean variable passed to analyzeSGP and studentGrowthPercentiles indicating whether the results from the cohort sample subset (if specified using the above argument) should be returned for inspection. Defaults to FALSE. If TRUE, only the sample subset of the data used will be returned in the SGP object's @Data slot. Alternatively, user can supply the character "ALL_DATA" to the argument to return the entire original data.
Boolean variable indicating whether to simulate SGP values for students based on test-specific Conditional Standard Errors of Measurement (CSEM).
Test CSEM data must be available for simulation. Must be set to TRUE for confidence interval construction. Defaults to TRUE in abcSGP only.
A character state acronym or list including state/csem variable, csem.data.vnames, csem.loss.hoss, simulation.iterations, lambda and extrapolation method.
Returns both SIMEX adjusted SGP (SGP_SIMEX) as well as the percentile ranked SIMEX SGP (RANK_SIMEX) values as suggested by Castellano and McCaffrey (2017).
Defaults to NULL, no simex calculations performed. Alternatively, setting the argument to TRUE sets the list up with state=state, lambda=seq(0,2,0.5), simulation.iterations=50, simex.sample.size=25000, extrapolation="linear" and save.matrices=TRUE.
A character state acronym or list including state/csem variable, csem.data.vnames, csem.loss.hoss, simulation.iterations, lambda and extrapolation method. Defaults to NULL, no simex calculations performed.
Alternatively, setting the argument to TRUE uses the same defaults as above along with simex.use.my.coefficient.matrices = TRUE. This argument is passed to analyzeSGP.
A character state acronym or list including [FILL IN LATER]. Creates a longitudinal data set based upon a stratified random sample of variables and proportions for the United States (default) or provided by the user. The argument defaults to NULL, Alternatively, setting the argument to TRUE uses the defaults specified above. This argument is passed to analyzeSGP.
A character state acronym or list including [FILL IN LATER]. Calculates SGPs based upon previosly established coefficient matrices derived from a stratified random sample of data. Defaults to NULL, no stratified random sample SGPs are calculated. Alternatively, setting the
argument to TRUE uses the defaults specified above. This argument is passed to analyzeSGP.
Boolean variable passed to analyzeSGP indicating whether to print goodness of fit results.
A named list with, at a minimum, two elements indicating 1) the BACKEND package to be used for parallel computation and 2) the WORKERS list to specify the number of processors to be used in each major analysis. The BACKEND element can be set = to FOREACH or PARALLEL. Please consult the manuals and vignettes for information of these packages! The analyzeSGP help page contains more thorough explanation and examples of the parallel.config setup.
The parallel.config list is passed to analyzeSGP, combineSGP, summarizeSGP and visualizeSGP. The WORKERS list can accordingly contain
elements for PERCENTILES, PROJECTIONS, LAGGED_PROJECTIONS, BASELINE_MATRICES, BASELINE_PERCENTILES for analyzeSGP, SUMMARY for summarizeSGP and GA_PLOTS and SG_PLOTS for
visualizeSGP. See those functions help pages for details.
Should intermediate results of abcSGP be saved after each of prepareSGP, analyzeSGP,
combineSGP, and summarizeSGP. Default is FALSE.
A Boolean argument (defaults to FALSE which will delete the @Summary slot before creating new summaries)
indicating whether the call to summarizeSGP should save existing summaries in the @Summary slot.
A Boolean variable (defaults to FALSE) indicating whether to produce only the demonstration student report catalog. Default is to produce reports for entire current year data.
Configuration passed to analyzeSGP and combineSGP for user specified SGP analyses. See analyzeSGP documentation for details on format of configuration argument.
A list giving the summaries requested for each group analyzed based upon the summary.group argument. Default is NULL allowing the summarizeSGP
function to produce the list of summaries automatically.
A list consisting of 8 types of groups across which all summaries are taken: institution, content, time, institution_type,
institution_level, demographic, and institution_inclusion. Summaries generated in summarizeSGP are for all possible combinations of the 8 types of group. See documentation for
summarizeSGP for more detail.
A list argument (or NULL, the default) providing additional multiple membership lookup tables for summarizeSGP. See sgpData_INSTRUCTOR_NUMBER
for an example. Supplied data is embedded in the @Data_Supplementary slot.
A subset of the groups provided in the summary.groups argument indicating which groups to provide confidence intervals for.
See documentation for summarizeSGP for more detail.
A character vector passed to visualizeSGP indicating the types of plots to produce. Currently supported plots include bubblePlots,
studentGrowthPlots, and growthAchievementPlots.
An argument passed to outputSGP indicating the output types to be produced. Defaults to LONG_Data, LONG_FINAL_YEAR_Data, WIDE_Data,
and INSTRUCTOR_Data.
A a file path indicating where to save output files. Defaults to Data.
A Boolean argument indicating whether the function should output verbose diagnostic messages.
A Boolean argument (defaults to FALSE) indicating whether a SQLite database file of the essential SGP data should be created from the @Data slot and subsequently
used to extract data subsets for analyses conducted in order to reduce the amount of RAM memory required. See full argument description in analyzeSGP.
A Boolean argument (defaults to NULL, which calculates equated results if in the equating year) passed to analyzeSGP
indicating whether equating should be used on the most recent year of test data provided. Equating allows for student growth projections to be calculated in
across assessment transitions where the scale for the assessment changes.
Character vector argument passed to analyzeSGP indicating type(s) of equating method to used if sgp.percentiles.equated=TRUE.
Default is NULL indicating 'equipercentile' equating. Options include 'identity', 'mean', 'linear', and 'equipercentile'.
Boolean argument passed to analyzeSGP indicating whether student growth percentiles are
produced as part of calls to the studentGrowthPercentiles function. Default is TRUE. Setting to FALSE produces only coefficient
matrices.
Boolean argument passd to analyzeSGP indicating whether to create norm group cohort
information based upon sgp configurations provided or calculated in analyzeSGP.
Argument (defaults to NULL) indicating whether to perform time dependent SGP analyses (SGPt).
Argument to control how analyzeSGP and combineSGP deal with duplicate records based upon the key of VALID_CASE, CONTENT_AREA, YEAR, and ID.
The function currently warns of duplicate records and doesn't modify data. If set to 'KEEP.ALL', analyzeSGP tries to fix the duplicate individual records by
adding a '_DUP_***' suffix to the duplicate ID before running studentGrowthPercentiles in order to create unique records based upon the key. If needed, the
@Data slot will be extended as necessary to accomodate additional student records and SGP results in combineSGP.
Damian W. Betebenner dbetebenner@nciea.org and Adam Van Iwaarden avaniwaarden@nciea.org
prepareSGP, analyzeSGP, combineSGP, summarizeSGP,
studentGrowthPercentiles, and studentGrowthProjections
if (FALSE) {
## Runs all 5 steps
Demonstration_SGP <- abcSGP(sgp_object=sgpData_LONG, state="DEMO")
## Or letting the function detect the state.
Demonstration_SGP <- abcSGP(sgpData_LONG)
###
### Example uses of the parallel.config argument
###
Demonstration_SGP <- abcSGP(sgpData_LONG,
parallel.config=list(
BACKEND="PARALLEL", TYPE="PSOCK",
WORKERS=list(
PERCENTILES=8, BASELINE_PERCENTILES=8, PROJECTIONS=7, LAGGED_PROJECTIONS=6,
SUMMARY=8,
GA_PLOTS=8, SG_PLOTS=8)
)
)
}
Run the code above in your browser using DataLab