In almartin82/mapvizieR: Visualization and Data Analysis tools for NWEA MAP student data

#libraries and functions etc
require(assertthat)
require(dplyr)

big idea

prior to mapvizieR, Chris and I had very different workflows and data structures for storing longitudinal MAP data. As a result our shared R code had a lot of extra cruft built into every plot that would try to adapt it to our different environments As a result there was a lot of code like this which moved stuff around when the plotting functions were called.

As a design pattern this proved to be inefficient (lots of extra parameters for every function) and brittle (we didn't have tests on the old package, and even if we did, they would have been extremely hard to write.)

and thus the mapvizieR object born! rather than write a bunch of defensive logic in each plot (and depend on each end user to write custom pipelines into our canonical formats) we decided that we would put some up-front effort in to defining a data object that, if conforming, would 'just work' with our plots. that object is the mapvizieR object.

raw ingredients

NWEA hands data back in two important files:

• AssessmentResults.csv
• StudentsBySchool.csv

(we are assuming that folks are using web-based MAP here. If you are using client-server MAP, there are a few annoying changes to your CDF that will have to be made, because the data model changed ever-so-slightly between the two platforms. Writing these functions is currently a #todo, but on the whole they're not so complicated. Get in touch if this describes your situation.)

what happens next

well, if you've copied/pasted all the csvs together into two master/combined files, hopefully you can just load your files, and then just call mapvizieR

library(mapvizieR)

mapviz <- mapvizieR(
  cdf = ex_CombinedAssessmentResults,
  roster = ex_CombinedStudentsBySchool
)

mapviz

that's sort of psuedo-code, because I'm not sure how to actually read in the raw data that we've provided in this package in the vignette environment (filesystems are hard, man) but if you run that mapvizier() call as written it should work in your environment, because we've also included those files as .Rda objects.

how to think about the mapvizieR object

The mapvizieR object is a floor, not a ceiling. getting your MAP data into a mapvizieR object ensures that it will work with the plots and reports in the package; however, you can (and should) feel free to modify and add to the mapvizieR object to capture information unique to your region. The roster slot in the object is a good example -- there are certain things that are required by the object, but you can safely add additional demographic columns (regions, houses, etc) and your object will still conform.

what's in the object?

names(mapviz)

howmany <- 4
assertthat::assert_that(length(names(mapviz))==4)

the mapvizieR object is really just a named list; it has a number of data frames that plot functions can access. rather than trying to keep one dataframe to rule them all (which inevitably requires concessions that aren't ideal) we get to keep roster, cdf and growth data on separate objects, and then mix them together when needed to generate reports.

Right now mapvizieR has r howmany objects that live in it.

cdf

the cdf looks a lot like the AssessmentResults file, with a few enhancements. notably, it tags grade level to the CDF observation, and ensures that there aren't multiple assessment records in the same subject/season for a student.

names(mapviz[['cdf']])

mapviz[['cdf']][c(1:2),]

roster

the mapvizieR call above basically returns the StudentsBySchool file here; if you are operating with a data warehouse you have some options here to build your own mapvizieR object with a more extensive roster file that includes other student assignments (courses, homerooms, athletics, etc.) Minimally, the roster object has to have a studentid and the student's grade level for every test season in the CDF.

TODO: describe KIPP NJ's workflow to show how to build a mapvizieR object with a custom roster.

growth_df

The growth df is a transformation of the cdf that has one row per student/subject/growth window. for instance, a 5th grade Math student will have records for 'Fall to Fall', 'Fall to Spring', 'Fall to Winter', 'Winter to Spring', and 'Spring to Spring' growth.
This dataframe is built automatically. Having your data pre-processed in this format makes a variety of otherwise complicated analysis extremely straightforward.

under the hood

If you look at the source on mapvizieR you can see the workflow.

• first calls prep_cdf_long on the raw cdf/AssessmentResults file
• then calls prep_roster on the roster/StudentsBySchool file
• with the roster in hand, it tags the CDF with grade levels by calling grade_levelify_cdf, which triggers a series of post-processing functions that generate labels based on grade level and season.

almartin82/mapvizieR documentation built on June 3, 2023, 10:53 a.m.