SGP: visualizeSGP – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

visualizeSGP

Visualize data from SGP analyses

Description

Utility function to produce a variety of graphical displays associated with student growth percentile/percentile growth trajectory results. Function currently includes facility to produce individual student growth and achievement plots, interactive bubble plots depicting summary growth and achievement data, and growth and achievement charts showing system level growth and achievement data as shown on the cover of Educational Measurement: Issues and Practice as part of Betebenner (2009) and Betebenner (2012).

Usage

visualizeSGP(
        sgp_object,
        plot.types=c("bubblePlot", "studentGrowthPlot", "growthAchievementPlot"),
        state,
        bPlot.years=NULL,
        bPlot.content_areas=NULL,
        bPlot.districts=NULL,
        bPlot.schools=NULL,
        bPlot.instructors=NULL,
        bPlot.styles=c(1),
        bPlot.levels=NULL,
        bPlot.level.cuts=NULL,
        bPlot.full.academic.year=TRUE,
        bPlot.minimum.n=10,
        bPlot.anonymize=FALSE,
        bPlot.prior.achievement=TRUE,
        bPlot.draft=FALSE,
        bPlot.demo=FALSE,
        bPlot.output="PDF",
        bPlot.format="print",
        bPlot.folder="Visualizations/bubblePlots",
        sgPlot.save.sgPlot.data=FALSE,
        sgPlot.years=NULL,
        sgPlot.content_areas=NULL,
        sgPlot.districts=NULL,
        sgPlot.schools=NULL,
        sgPlot.reports.by.school=TRUE,
        sgPlot.instructors=NULL,
        sgPlot.reports.by.instructor=FALSE,
        sgPlot.students=NULL,
        sgPlot.reports.by.student=FALSE,
        sgPlot.reports.group.vars=
            list(DISTRICT_NUMBER="DISTRICT_NUMBER", SCHOOL_NUMBER="SCHOOL_NUMBER"),
        sgPlot.header.footer.color="#4CB9CC",
        sgPlot.front.page=NULL,
        sgPlot.folder="Visualizations/studentGrowthPlots",
        sgPlot.folder.names="number",
        sgPlot.fan=TRUE,
        sgPlot.sgp.targets=FALSE,
        sgPlot.sgp.targets.timeframe=3,
        sgPlot.anonymize=FALSE,
        sgPlot.cleanup=TRUE,
        sgPlot.demo.report=FALSE,
        sgPlot.produce.plots=TRUE,
        sgPlot.baseline=NULL,
        sgPlot.zip=TRUE,
        sgPlot.output.format="PDF",
        sgPlot.year.span=5,
        sgPlot.plot.test.transition=TRUE,
        gaPlot.years=NULL,
        gaPlot.content_areas=NULL,
        gaPlot.students=NULL,
        gaPlot.format="print",
        gaPlot.baseline=NULL,
        gaPlot.max.order.for.progression=NULL,
        gaPlot.start.points="Achievement Level Cuts",
        gaPlot.back.extrapolated.cuts=NULL,
        gaPlot.SGPt=NULL,
        gaPlot.folder="Visualizations/growthAchievementPlots",
        parallel.config=NULL)

Arguments

`sgp_object`	An object of class SGP containing long formatted data in the `@Data` slot that will be used for the production of student growth and achievement plots and system growth and achievement plots, summary data from `summarizeSGP` in the `Summary` slot for bubble plots. Alternatively, a properly formatted WIDE data set can be provided for production of student growth plots. Such data sets are produced from an SGP object when the sgPlot.save.sgPlot.data argument is set to TRUE.
`plot.types`	A character vector indicating what types of plots to construct. Currently available plots include `bubblePlot`, `studentGrowthPlot`, and `growthAchievementPlot`.
`state`	Acronym indicating state associated with the summaries for access to assessment program information embedded in `SGPstateData`.
`bPlot.years`	A vector indicating year(s) in which to produce `bubblePlot`s using data available in `sgp_object`. If missing the function will use the last year available in the data to produce `bubblePlot`s.
`bPlot.content_areas`	A vector indicating content area(s) to produce `bubblePlot`s using data available in `sgp_object`. If missing the function will produce plots for all available content areas provided in the data.
`bPlot.districts`	A vector indicating districts to produce `bubblePlot`s using data available in `sgp_object`. Consult `bubblePlot` styles to determine which `bubblePlot`s styles accept specification for districts. Default is to produce plots for all available districts in the data.
`bPlot.schools`	A vector indicating schools to produce `bubblePlot`s using data available in `sgp_object`. Consult `bubblePlot` styles to determine which `bubblePlot` styles accept specification for schools. Default is to produce plots for all available schools in the data.
`bPlot.instructors`	A vector indicating instructors to produce `bubblePlot`s using data available in `sgp_object`. If missing the function will produce plots for all available instructors provided in the data where schools and districts represent relevant units to be represented by the specific `bubblePlot` style.
`bPlot.styles`	A vector of positive integers indicating the types of `bubblePlot`s to produce using data available in `sgp_object`. See associated documentation for example plots.
`bPlot.levels`	A character vector of levels to be used to color bubbles in the `bubblePlot`. See associated documentation for example plots.
`bPlot.level.cuts`	A vector of cuts to be used to distinguish levels used to color bubbles in the `bubblePlot`. See associated documentation for example plots.
`bPlot.full.academic.year`	A Boolean argument (defaults to TRUE) indicating whether `bubblePlot`s should use full academic year results if available.
`bPlot.minimum.n`	A positive integer (defaults to 10) indicating the minimum size for summary values to be displayed in the `bubblePlot`s.
`bPlot.anonymize`	A Boolean argument (defaults to FALSE) indicating whether to anonymize `bubblePlot`s school and district names that appear in the plots and data tips of the plots. For student level anonymization, the function utilizes the randomNames package to produce gender and ethnic correct names based upon gender and ethnicity codes available in `sgp_object@Data`.
`bPlot.prior.achievement`	A Boolean argument (defaults to TRUE) indicating whether to produce `bubblePlot`s using prior achievement as well as current achievement as the vertical dimension of the `bubblePlot`.
`bPlot.draft`	A Boolean argument (defaults to FALSE) indicating whether to put an indicator on the chart noting that the results are draft and to not distribute.
`bPlot.demo`	A Boolean argument (defaults to FALSE) indicating whether to produce demo student level plots (styles 150 and/or 153) for instructors.
`bPlot.output`	Argument indicating the desired type of output format for bubble plots. Either 'PDF' (default) or 'PNG'.
`bPlot.format`	Either "print" or "presentation" indicating whether to optimize the plot for print form (light background) or presentation form (dark background).
`bPlot.folder`	Character vector indicating where `bubblePlot`s should be placed. Default folder is "Visualizations/bubblePlots".
`sgPlot.save.sgPlot.data`	A Boolean argument indicating whether wide formatted data should be save as part of individual student report production. For operational student report production construction, using a wide formatted file for a large state can save in having to reshape the same long file multiple times.
`sgPlot.years`	A vector indicating year for which to produce `studentGrowthPlot`s. The supplied year indicates the final year associated with each student's `studentGrowthPlot`. If missing the function will use the last year available in the data to produce `studentGrowthPlot`s.
`sgPlot.content_areas`	A vector indicating the content areas for which to produce `studentGrowthPlot`s. If missing, the function will utilize all available content areas.
`sgPlot.districts`	A vector indicating which districts to produce `studentGrowthPlot`s for. If missing the function will use all available districts in the data to produce `studentGrowthPlot`s.
`sgPlot.schools`	A vector indicating which schools to produce `studentGrowthPlot`s for. If missing the function will use all available schools in the data to produce `studentGrowthPlot`s. If both `sgPlot.districts` and `sgPlot.schools` are provided the function produces `studentGrowthPlot`s for ALL students in the districts and schools provided.
`sgPlot.reports.by.school`	A Boolean variable indicating whether the reports should be collated as single reports in a single folder by school and deposited into a `district/school/grade folder` hierarchy. The default is TRUE which puts the reports into their appropriate `district/school/grade` folder.
`sgPlot.instructors`	A vector indicating which instructors to produce `studentGrowthPlot`s for. If NULL and the argument `sgPlot.reports.by.instructor` is TRUE, the argument function will use all available instructors in the data to produce `studentGrowthPlot`s. If `sgPlot.districts` and/or `sgPlot.schools` are provided the function produces `studentGrowthPlot`s for ALL students in the districts and/or schools provided.
`sgPlot.reports.by.instructor`	A Boolean variable indicating whether the reports should be collated as single reports in a single folder by school and deposited into a `district/school/grade folder` hierarchy. The default is TRUE which puts the reports into their appropriate `district/school/grade` folder.
`sgPlot.students`	A vector of student `ID`s indicating which students to produce `studentGrowthPlot`s for. If missing the function will use all available students in the data to produce `studentGrowthPlot`s.
`sgPlot.reports.group.vars`	A list of variables used to group student reports. Default is `list(DISTRICT_NUMBER='DISTRICT_NUMBER', SCHOOL_NUMBER='SCHOOL_NUMBER')`
`sgPlot.reports.by.student`	A Boolean variable indicating whether the reports should be collated as single reports in a single folder or deposited into a `district/school/grade folder` hierarchy. The default is FALSE which puts the reports into their appropriate `district/school/grade` slot.
`sgPlot.header.footer.color`	Character vector (default is blue) indicating the color of the header/footer associated with the `studentGrowthPlot`. Another good color is `goldenrod2`.
`sgPlot.front.page`	A path to a PDF to be used as the front page to the `studentGrowthPlot`. The default is missing so that no front page is attached to the `studentGrowthPlot`.
`sgPlot.folder`	Character vector indicating where `studentGrowthPlot`s should be placed. Note that `studentGrowthPlot`s are placed within nested folders within this folder. Default folder is "Visualizations/studentGrowthPlots".
`sgPlot.folder.names`	Either "name" or "number" (the default) indicating how the nested folder structure will be labeled that holds the `studentGrowthPlot`s.
`sgPlot.fan`	A Boolean argument (defaults to TRUE) indicating whether to produce projection fan on `studentGrowthPlot`s.
`sgPlot.sgp.targets`	A Boolean argument (defaults to TRUE) indicating whether to indicate SGP growth targets on `studentGrowthPlot`s.
`sgPlot.sgp.targets.timeframe`	An integer argument specifying the number of years forward associated with targets to be added to the student growth plots.
`sgPlot.anonymize`	A Boolean argument (defaults to FALSE) indicating whether to anonymize `studentGrowthPlot`s student, school and district names. For student level anonymization, the function utilizes the `randomNames` package to produce gender and ethnicity based names based upon gender and ethnicity codes available in `sgp_object@Data`.
`sgPlot.cleanup`	A Boolean argument (defaults to TRUE) indicating whether to remove files produced by pdfLaTeX to produce `studentGrowthPlot` catalogs.
`sgPlot.demo.report`	A Boolean argument (defaults to TRUE) indicating whether to just produce a sample `studentGrowthPlot` catalogs. Note: When producing `studentGrowthPlot`s for an entire state, considerable resources are required to produce this many reports. We are actively working on parallelizing this functionality to reduce report production time by two orders of magnitude.
`sgPlot.produce.plots`	A Boolean argument (defaults to TRUE) indicating whether to produce `studentGrowthPlot`s. Useful when one just wants to produce wide formatted data without the actual student growth plots.
`sgPlot.baseline`	Argument (defaults to NULL) indicating whether to use baseline referenced SGPs for student growth plot construction. If not set by user, argument will be set using `SGPstateData` which contains information on whether state is a cohort or baseline referenced system.
`sgPlot.zip`	A Boolean argument (defaults to TRUE) indicating whether to zip school folders containing `studentGrowthPlot`s.
`sgPlot.output.format`	Argument indicating the desired type of output format for student growth plots. Either 'PDF' (default), 'PNG', 'PDF_PIECES', or 'JSON'.
`sgPlot.year.span`	Integer argument (defaults to 5) indicating the number of years to display for the pdf student growth plot.
`sgPlot.plot.test.transition`	Boolean argument (defaults to TRUE) indicating whether test transition data will be used IF it's available. Setting to FALSE ignore previous test transition data, which would indicate a desire to 'forget the past'.
`gaPlot.years`	A vector indicating the year(s) for which to produce `growthAchievementPlot`s. If missing the function will use the last year available in the data to produce the `growthAchievementPlot`s.
`gaPlot.content_areas`	A vector indicating content area(s) to produce `growthAchievementPlot`s using data available in `sgp_object`. If missing the function will produce plots for all available content areas provided in the data.
`gaPlot.students`	A vector of student `ID`s indicating which students to produce `growthAchievementPlot`s for. If missing the function will use all available students in the data to produce `growthAchievementPlot`s.
`gaPlot.format`	Either 'print' or 'presentation' indicating whether to optimize the plot for print form (light background) or presentation form (dark background).
`gaPlot.baseline`	Argument (defaults to NULL) indicating whether to calculate growth and achievement plots using percentile trajectories derived from baseline referenced coefficient matrices. If not set by user, argument will be set using `SGPstateData` which contains information on whether state is a cohort or baseline referenced system.
`gaPlot.max.order.for.progression`	The maximum coefficient matrix order to use for each progression. Default is NULL which utilizes the maximum order available with the coefficient matrices.
`gaPlot.start.points`	Either 'Achievement Level Cuts' or 'Achievement Percentiles' defining where the percentile trajectories of the growth achievement plot will start from.
`gaPlot.folder`	Character vector indicating where `growthAchievementPlot`s should be placed. The default folder is 'Visualizations/growthAchievementPlots'.
`gaPlot.back.extrapolated.cuts`	A numeric value or Boolean vector indicating whether to create back extrapolated cutscores based upon nth percentile growth.
`gaPlot.SGPt`	Boolean indicator for growth achievement plot indicating whether time dependent SGPs are to be used for student growth projections `SGPt`
`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. TYPE is a third element of the `parallel.config` list that provides necessary information when using FOREACH or PARALLEL packages as the backend. With BACKEND="FOREACH", the TYPE element specifies the flavor of 'foreach' backend. As of version 1.0-1.0, only "doParallel" is supported. TYPE=NA (default) produces summaries sequentially. If BACKEND = "PARALLEL", the `parallel` package will be used. This package combines deprecated parallel packages `snow` and `multicore`. Using the "snow" implementation of `parallel` the function will create a cluster object based on the TYPE element specified and the number of workers requested (see WORKERS list description below). The TYPE element indicates the users preferred cluster type (either "PSOCK" for socket cluster of "MPI" for an OpenMPI cluster). If Windows is the operating system, this "snow" implementation must be used and the TYPE element must = "PSOCK". Defaults are assigned based on operating system if TYPE is missing based on system OS. Unix/Mac OS defaults to the "multicore" to avoid worker node pre-scheduling and appears to be more efficient in these operating systems. The WORKERS element is a list with GA_PLOTS (growth achievement plots) and SG_PLOTS (student growth plots) specifying the number of processors to be used. NOTE: choice of the number of cores is a balance between the number of processors available and the amount of RAM a system has; each system will be different and may require some adjustment. Default is FOREACH as the back end, TYPE=NA and both plot WORKERS=1, which produces plots sequentially: 'list(BACKEND="FOREACH", TYPE=NA, WORKERS=list(GA_PLOTS=1, SG_PLOTS=1))' Examples of various parallel configurations can be found in the examples for `analyzeSGP` and `summarizeSGP`.

Value

Function produces numerous (potentially hundreds of thousands) of pdf files in a folder structure specified by the user and supplied through arguments to the function.

Author(s)

Damian W. Betebenner dbetebenner@nciea.org and Adam Van Iwaarden vaniwaarden@colorado.edu

References

Betebenner, D. W. (2012). Growth, standards, and accountability. In G. J. Cizek, Setting Performance Standards: Foundations, Methods & Innovations. 2nd Edition (pp. 439-450). New York: Routledge.

Betebenner, D. W. (2009). Norm- and criterion-referenced student growth. Educational Measurement: Issues and Practice, 28(4):42-51.

Examples

## Not run: 
## visualizeSGP is Step 5 of 5 of abcSGP
Demonstration_SGP <- sgpData_LONG
Demonstration_SGP <- prepareSGP(Demonstration_SGP)
Demonstration_SGP <- analyzeSGP(Demonstration_SGP)
Demonstration_SGP <- combineSGP(Demonstration_SGP)
Demonstration_SGP <- summarizeSGP(Demonstration_SGP)
visualizeSGP(Demonstration_SGP)

## Produce a DEMO catalog of student growth plots

visualizeSGP(
	sgp_object=Demonstration_SGP,
	plot.types="studentGrowthPlot",
	state="DEMO",
	sgPlot.demo.report=TRUE)

## Production of sample student growth and achievement plots

visualizeSGP(
	sgp_object=Demonstration_SGP,
	plot.types="studentGrowthPlot",
	state="DEMO",
	sgPlot.districts=470,
	sgPlot.schools=c(6418, 8008),
	sgPlot.header.footer.color="#4CB9CC")

## End(Not run)

SGP

Student Growth Percentiles & Percentile Growth Trajectories

v1.9-5.0

GPL-3

Authors

Damian W. Betebenner [aut, cre], Adam R. Van Iwaarden [aut], Ben Domingue [aut], Yi Shang [aut], Jonathan Weeks [ctb], John Stewart [ctb], Jinnie Choi [ctb], Xin Wei [ctb], Hi Shin Shim [ctb], Xiaoyuan Tan [ctb] (Arizona Department of Education), Carrie Giovannini [ctb] (Arizona Department of Education), Sarah Polasky [ctb] (Arizona State University), Rebecca Gau [ctb] (Arizona Charter School Association), Jeffrey Dean [ctb] (University of Arkansas), William Bonk [ctb] (Colorado Department of Education), Marie Huchton [ctb] (Colorado Department of Education), Allison Timberlake [ctb] (Georgia Department of Education), Qi Qin [ctb] (Georgia Department of Education), Melissa Fincher [ctb] (Georgia Department of Education), Kiran Athota [ctb] (Georgia Department of Education), Travis Allen [ctb] (Georgia Department of Education), Glenn Hirata [ctb] (Hawaii Department of Education), Glenn Nochi [ctb] (Hawaii Department of Education), Joshua Lee [ctb] (Hawaii Department of Education), Ayaka Nukui [ctb] (Idaho Department of Education), Carissa Miller [ctb] (Idaho Department of Education), Matthew Raimondi [ctb] (Elgin Area School District U46 (Illinois)), Wes Bruce [ctb] (Indiana Department of Education), Robert Hochsegang [ctb] (Indiana Department of Education), Tony Moss [ctb] (Kansas State Department of Education), Xuewen Sheng [ctb] (Kansas State Department of Education), Kathy Flanagan [ctb] (Massachusetts Department of Elementary and Secondary Education), Robert Lee [ctb] (Massachusetts Department of Elementary and Secondary Education), Ji Zeng [ctb] (Michigan Department of Education), Steve Viger [ctb] (Michigan Department of Education), Joe DeCastra [ctb] (Mississippi Department of Education), Ken Thompson [ctb] (Mississippi Department of Education), Soo Yeon Cho [ctb] (Missouri Department of Education), Jeff Halsell [ctb] (Clark County School District, Nevada), Selcuk Ozdemir [ctb] (Washoe County School District, Nevada), Roger Silva [ctb] (Nevada Department of Education), Deb Wiswell [ctb] (New Hampshire Department of Education), Katya Levitan-Reiner [ctb] (New Haven Public Schools), Catherine McCaslin [ctb] (New Haven Public Schools), Joshua Marland [ctb] (New York Education Department), W Joshua Rew [ctb] (Oregon Department of Education), Jason Becker [ctb] (Rhode Island Department of Education), Jessica Bailey [ctb] (Rhode Island Department of Education), Ana Karantonis [ctb] (Rhode Island Department of Education), Deborah Jonas [ctb] (Virginia Department of Education), Juan D'Brot [ctb] (West Virginia Department of Education), Nate Hixson [ctb] (West Virginia Department of Education), Deb Came [ctb] (Washington Office of Superintendent of Public Instruction), Ashley Colburn [ctb] (Washington Office of Superintendent of Public Instruction), Nick Hassell [ctb] (Washington Office of Superintendent of Public Instruction), Krissy Johnson [ctb] (Washington Office of Superintendent of Public Instruction), Daniel Bush [ctb] (Wisconsin Department of Education), Justin Meyer [ctb] (Wisconsin Department of Education), Joseph Newton [ctb] (Wisconsin Department of Education), Nick Stroud [ctb] (Wisconsin Department of Education), John Paul [ctb] (Wyoming Department of Education), Michael Flicek [ctb] (Michael Flicek Projects LLC working with Wyoming Department of Education), Phyllis Clay [ctb] (Albuquerque Public Schools), Peter Kinyua [ctb] (Albuquerque Public Schools), Brendan Houng [ctb] (University of Melbourne, Australia, NAPLAN), Leslie Rosale [ctb] (Ministry of Education, Guatemala), Nathan Wall [ctb] (eMetric working with Nevada Department of Education and South Dakota Department of Education), Narek Sahakyan [ctb] (World Class Instruction and Design (WIDA))

Initial release

2020-1-30