analyzeSGP: Analyze student data to produce student growth percentiles and student growth projections

Description

Utility function/exemplar used to produce student growth percentiles and student growth projections using long formatted data like that provided by prepareSGP.

Usage

analyzeSGP(sgp_object,
         state=NULL,
         years=NULL,
         content_areas=NULL,
         grades=NULL,
         sgp.percentiles=TRUE,
         sgp.projections=TRUE,
         sgp.projections.lagged=TRUE,
         sgp.percentiles.baseline=TRUE,
         sgp.projections.baseline=TRUE,
         sgp.projections.lagged.baseline=TRUE,
         sgp.percentiles.baseline.max.order=3,
         sgp.projections.baseline.max.order=3,
         sgp.projections.lagged.baseline.max.order=3,
         sgp.use.my.coefficient.matrices=NULL,
         simulate.sgps=TRUE,
         goodness.of.fit.print=TRUE,
         sgp.config=NULL,
         sgp.config.drop.nonsequential.grade.progression.variables=TRUE,
         sgp.baseline.panel.years=NULL,
         sgp.baseline.config=NULL,
         parallel.config=NULL,
         ...)

Arguments

sgp_object

An object of class SGP containing long formatted data in the code (from prepareSGP) slot.

state

Acronym indicating state associated with the data for access to embedded knot and boundaries, cutscores, CSEMs, and other state related assessment data.

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) based upon the assumption of having at least three years of panel da

content_areas

A vector indicating content area(s) in which to produce student growth percentiles and/or student growth projections/trajectories. If left 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 left missing the function will use the data to infer all the grade progressions for student growth percentile and student grow

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

sgp.projections.baseline

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

sgp.projections.lagged.baseline

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

sgp.percentiles.baseline.max.order

Integer indicating the maximum order to calculate baseline student growth percentiles (regardless of maximum coefficient matrix order). Default is 3. To utilize the maximum matrix order, set to NULL.

sgp.projections.baseline.max.order

Integer indicating the maximum order to calculate baseline student growth projections (regardless of maximum coefficient matrix order). Default is 3. To utilize the maximum matrix order, set to NULL.

sgp.projections.lagged.baseline.max.order

Integer indicating the maximum order to calculate lagged baseline student growth projections (regardless of maximum coefficient matrix order). Default is 3. To utilize the maximum matrix order, set to NULL.

sgp.use.my.coefficient.matrices

Arugment, defaults to NULL indicating whether to use coefficient matrices to calcualte student growth percentiles embedded in provided object of same name as those provided by the sgp.labels argument.

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 and included in SGPstateData. This argument mu

goodness.of.fit.print

Boolean variable indicating whether to print out Goodness of Fit figures as pdf into a directory labeled Goodness of Fit. Defaults to TRUE.

sgp.config

If years, content_areas, and grades are missing, user can directly specify a list containing three vectors: baseline.content.areas, baseline.panel.years, and baseline.grade.sequences

sgp.config.drop.nonsequential.grade.progression.variables

Boolean variable (defaults to TRUE) indicating whether non-sequential grade progression variables should be dropped when sgp.config is processed. For example, if a grade progression of c(3,4,6) is provided, the data configuration will assume (default is T

sgp.baseline.panel.years

A vector of years to be used for baseline coefficient matrix calculation. Default is to use most recent five years of data.

sgp.baseline.config

A list containing three vectors: sgp.content.areas, sgp.panel.years, sgp.grade.sequences indicating how baseline student growth percentile analyses
 are to be conducted. In almost all cases this value is calculated b

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 F

...

Arguments to be passed to studentGrowthPercentiles or studentGrowthProjections for finer control over SGP calculations. NOT

`Value`

Function returns a list containing the long data set in the Data slot as a data.table keyed using VALID_CASE, CONTENT_AREA, 
YEAR, ID and the student growth percentile and/or student growth projection/trajectory results in the SGP slot.

`See Also`

prepareSGP, combineSGP

`Examples`

Run this code## analyzeSGP is Step 2 of 5 of abcSGP
Demonstration_SGP <- sgpData_LONG
Demonstration_SGP <- prepareSGP(Demonstration_SGP)
Demonstration_SGP <- analyzeSGP(Demonstration_SGP)

## Or (explicitly pass state argument)

Demonstration_SGP <- prepareSGP(sgpData_LONG)
Demonstration_SGP <- analyzeSGP(Demonstration_SGP, state="DEMO")

###
###  Example uses of the sgp.config argument
###

#  Use only 3 years of Data, for grades 3 to 6
#  and only perform analyses for most recent year (2012)

my.custom.config <- list(
MATHEMATICS.2011_2012 = list(
	sgp.content.areas=rep("MATHEMATICS", 3), # Note, must be same length as sgp.panel.years
	sgp.panel.years=c('2009_2010', '2010_2011', '2011_2012'),
	sgp.grade.sequences=list(3:4, 3:5, 4:6)),
READING.2011_2012 = list(
	sgp.content.areas=rep("READING", 3),
	sgp.panel.years=c('2009_2010', '2010_2011', '2011_2012'),
	sgp.grade.sequences=list(3:4, 3:5, 4:6)))

Demonstration_SGP <- prepareSGP(sgpData_LONG)
Demonstration_SGP <- analyzeSGP(Demonstration_SGP,
	sgp.config=my.custom.config,
	sgp.percentiles.baseline = FALSE,
	sgp.projections.baseline = FALSE,
	sgp.projections.lagged.baseline = FALSE,
	simulate.sgps=FALSE)


##  Another example sgp.config list:

#  Use different CONTENT_AREA priors, and only 1 year of prior data
my.custom.config <- list(
MATHEMATICS.2011_2012.READ_PRIOR = list(
	sgp.content.areas=c("READING", "MATHEMATICS"),
	sgp.panel.years=c('2010_2011', '2011_2012'),
	sgp.grade.sequences=list(3:4, 4:5, 5:6)),
READING.2011_2012.MATH_PRIOR = list(
	sgp.content.areas=c("MATHEMATICS", "READING"),
	sgp.panel.years=c('2010_2011', '2011_2012'),
	sgp.grade.sequences=list(3:4, 4:5, 5:6)))


## An example showing multiple priors within a single year

Demonstration_SGP <- prepareSGP(sgpData_LONG)
 
DEMO.config <- list(
READING.2010_2011 = list(
	sgp.content.areas=c("MATHEMATICS", "READING", "MATHEMATICS", "READING", "READING"),
	sgp.panel.years=c('2008_2009', '2008_2009', '2009_2010', '2009_2010', '2010_2011'),
	sgp.grade.sequences=list(c(3,3,4,4,5), c(4,4,5,5,6), c(5,5,6,6,7), c(6,6,7,7,8))),
MATHEMATICS.2010_2011 = list(
	sgp.content.areas=c("READING", "MATHEMATICS", "READING", "MATHEMATICS", "MATHEMATICS"),
	sgp.panel.years=c('2008_2009', '2008_2009', '2009_2010', '2009_2010', '2010_2011'),
	sgp.grade.sequences=list(c(3,3,4,4,5), c(4,4,5,5,6), c(5,5,6,6,7), c(6,6,7,7,8))))

Demonstration_SGP <- analyzeSGP(Demonstration_SGP,
                                          sgp.config=DEMO.config,
                                          sgp.projections=FALSE,
                                          sgp.projections.lagged=FALSE,
                                          sgp.percentiles.baseline=FALSE,
                                          sgp.projections.baseline=FALSE,
                                          sgp.projections.lagged.baseline=FALSE,
                                          sgp.config.drop.nonsequential.grade.progression.variables=FALSE)


###
###  Example uses of the parallel.config argument
###

##  Windows users must use snow:
#  possibly a quad core machine with low RAM Memory
#  4 workers for percentiles, 2 workers for projections.
#  Note the SOCK type cluster is used for single machines.

Demonstration_SGP <- prepareSGP(sgpData_LONG)
Demonstration_SGP <- analyzeSGP(Demonstration_SGP,
	parallel.config=list(
		BACKEND="SNOW", TYPE="SOCK",
		WORKERS=list(PERCENTILES=4, 
		    PROJECTIONS=2, 
		    LAGGED_PROJECTIONS=2,
		    BASELINE_PERCENTILES=4))

##  Windows users with R version >= 2.14.0  may prefer the parallel package:
#  This example is would be good for a single workstation with 8 cores
#  and enough RAM to use 8 workers for ALL analyses.
	...
	parallel.config=list(
		BACKEND="PARALLEL", TYPE="SOCK"),
		WORKERS=8)
	...

#  A similar specification for R versions pre 2.13 using SNOW:
	...
	parallel.config=list(
		BACKEND="SNOW", TYPE="SOCK"),
		WORKERS=8)
	...

##  Linux/Mac may use the multicore package directly:
	...
	parallel.config=list(
		BACKEND="MULTICORE",
		WORKERS=4)
	...

## FOREACH use cases:
# doMC - only available on Linux or Mac OSX
	...
	parallel.config=list(
		BACKEND="FOREACH", TYPE="doMC",
		WORKERS=3)
	...

#  doMPI package -  the number of workers is 100, 
#  suggesting this example is for a HPC cluster usage.
	...
	parallel.config=list(
		BACKEND="FOREACH", TYPE="doMPI",
		WORKERS=100)
	...


##  New parallel package - only available with R 2.13 or newer
#  Note there are up to 16 workers, and MPI is used, 
#  suggesting this example is for a HPC cluster, possibly Windows OS.
	...
	parallel.config=list(
		BACKEND="PARALLEL", TYPE="MPI",
		WORKERS=list(PERCENTILES=16, 
		    PROJECTIONS=8, 
		    LAGGED_PROJECTIONS=6,
		    BASELINE_PERCENTILES=12))
	...

#  NOTE:  This list of parallel.config specifications is NOT exhaustive.  
#  See examples in analyzeSGP documentation for some others.0

###
###  Advanced Example: restrict years, recalculate baseline SGP
###  coefficient matrices, and use parallel processing
###

#  Remove existing DEMO baseline coefficient matrices from
#  the SGPstateData object so that new ones will be computed.

SGPstateData$DEMO$Baseline_splineMatrix <- NULL

#  set up a customized sgp.config list

	. . .

#  set up a customized sgp.baseline.config list

	. . .

#  to be completed
Run the code above in your browser using DataLab