abcSGP {SGP}

Perform 6 step sequence: prepareSGP, analyzeSGP, combineSGP, summarizeSGP, visualizeSGP, and outputSGP

Description

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.

Usage

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,
	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)

Arguments

sgp_object

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.

state

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.

steps

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.

years

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.

content_areas

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.

grades

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.

prepareSGP.var.names

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.

prepareSGP.create.additional.variables

Boolean variable indicating whether prepareSGP should create addition variables (e.g., ACHIEVEMENT_LEVEL) if they are missing.

sgp.percentiles

Boolean variable indicating whether to calculate student growth percentiles. Defaults to TRUE.

sgp.projections

Boolean variable indicating whether to calculate student growth projections. Defaults to TRUE.

sgp.projections.lagged

Boolean variable indicating whether to calculate lagged student growth projections often used for growth to standard analyses. Defaults to TRUE.

sgp.percentiles.baseline

Boolean variable indicating whether to calculate baseline student growth percentiles and/or coefficient matrices. Defaults to TRUE.

sgp.projections.baseline

Boolean variable indicating whether to calculate baseline student growth projections. Defaults to TRUE.

sgp.projections.lagged.baseline

Boolean variable indicating whether to calculate lagged baseline student growth projections. Defaults to TRUE.

sgp.use.my.coefficient.matrices

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.

sgp.minimum.default.panel.years

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).

sgp.target.scale.scores

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.

sgp.target.scale.scores.only

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.

sgp.test.cohort.size

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).

return.sgp.test.results

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.

simulate.sgps

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.

calculate.simex

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.

calculate.simex.baseline

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.

calculate.srs

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.

calculate.srs.baseline

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.

goodness.of.fit.print

Boolean variable passed to analyzeSGP indicating whether to print goodness of fit results.

parallel.config

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.

save.intermediate.results

Should intermediate results of abcSGP be saved after each of prepareSGP, analyzeSGP, combineSGP, and summarizeSGP. Default is FALSE.

save.old.summaries

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.

sgPlot.demo.report

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.

sgp.config

Configuration passed to analyzeSGP and combineSGP for user specified SGP analyses. See analyzeSGP documentation for details on format of configuration argument.

sgp.summaries

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.

summary.groups

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.

data_supplementary

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.

confidence.interval.groups

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.

plot.types

A character vector passed to visualizeSGP indicating the types of plots to produce. Currently supported plots include bubblePlots, studentGrowthPlots, and growthAchievementPlots.

outputSGP.output.type

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.

outputSGP.directory

A a file path indicating where to save output files. Defaults to Data.

verbose.output

A Boolean argument indicating whether the function should output verbose diagnostic messages.

sgp.sqlite

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.

sgp.percentiles.equated

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.

sgp.percentiles.equating.method

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'.

sgp.percentiles.calculate.sgps

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.

get.cohort.data.info

Boolean argument passd to analyzeSGP indicating whether to create norm group cohort information based upon sgp configurations provided or calculated in analyzeSGP.

SGPt

Argument (defaults to NULL) indicating whether to perform time dependent SGP analyses (SGPt).

fix.duplicates

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.

Value

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.

Author(s)

Damian W. Betebenner [e-mail] and Adam Van Iwaarden [e-mail]

See Also

prepareSGP, analyzeSGP, combineSGP, summarizeSGP,
studentGrowthPercentiles, and studentGrowthProjections

Examples

## Not run: 
## 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)
	)
)


## End(Not run)