EdSurvey (version 2.2.3)

edsurvey.data.frame.list: EdSurvey Dataset Vectorization

Description

The edsurvey.data.frame.list function creates an edsurvey.data.frame.list object from a series of edsurvey.data.frame objects. append.edsurvey.data.frame.list creates an edsurvey.data.frame.list from two edsurvey.data.frame or edsurvey.data.frame.list objects.

An edsurvey.data.frame.list is useful for looking at data, for example, across time or graphically, and reduces repetition in function calls. The user may specify a variable that varies across the edsurvey.data.frame objects that is then included in further output.

Usage

edsurvey.data.frame.list(datalist, cov = NULL, labels = NULL)
append.edsurvey.data.frame.list(sdfA, sdfB, labelsA = NULL,
  labelsB = NULL)

Arguments

datalist

a list of edsurvey.data.frames to be combined

cov

a character vector that indicates what varies across the edsurvey.data.frame objects. See Examples. Guessed if not supplied. For example, if several edsurvey.data.frames for several different countries are supplied, then cov would be set to the country.

labels

a character vector that specifies labels. Must be the same length as datalist. Not needed if cov exists or can be guessed. See Examples.

sdfA

an edsurvey.data.frame or edsurvey.data.frame.list to be combined

sdfB

an edsurvey.data.frame or edsurvey.data.frame.list to be combined

labelsA

a character vector that specifies labels for sdfA when creating the new edsurvey.data.frame.list. labelsA would be ignored if sdfA is an edsurvey.data.frame.list with labels supplied.

labelsB

a character vector that specifies labels for sdfB when creating the new edsurvey.data.frame.list. labelsB would be ignored if sdfB is an edsurvey.data.frame.list with labels supplied.

Value

edsurvey.data.frame.list returns an edsurvey.data.frame.list with elements

datalist

a list of edsurvey.data.frame objects

covs

a character vector of key variables that vary within the edsurvey.data.frame.list. When labels are included, they will be included in covs. In the unusual circumstance that sdfA or sdfB is an edsurvey.data.frame.list, has covs, and labels are not supplied, the covs are simply pasted together with colons between them.

append.edsurvey.data.frame.list returns an edsurvey.data.frame.list with elements

datalist

a list of edsurvey.data.frame objects

covs

a character vector of key variables that vary within the edsurvey.data.frame.list. When labels are included, they will be included in covs.

Details

The edsurvey.data.frame.list can be used in place of an edsurvey.data.frame in function calls, and results are returned for each of the component edsurvey.data.frames, with the organization of the results varying by the particular method.

An edsurvey.data.frame.list can be created from several edsurvey.data.frame objects that are related; for example, all are NAEP mathematics assessments but have one or more differences (e.g., they are all from different years). Another example could be data from multiple countries for an international assessment.

When cov and labels are both missing, edsurvey.data.frame.list attempts to guess what variables may be varying and uses those. When there are no varying covariates, generic labels are automatically generated.

Examples

# NOT RUN {
# read in the example data (generated, not real student data)
sdf <- readNAEP(system.file("extdata/data", "M36NT2PM.dat", package="NAEPprimer"))

# NOTE: the following code would not normally have to be run but is used here
# to generate demo data.
# Specifically, make subsets of sdf by the scrpsu variable,
# "Scrambled PSU and school code"
sdfA <- subset(sdf, scrpsu %in% c(5,45,56))
sdfB <- subset(sdf, scrpsu %in% c(75,76,78))
sdfC <- subset(sdf, scrpsu %in% 100:200)
sdfD <- subset(sdf, scrpsu %in% 201:300)

# construct an edsurvey.data.frame.list from these four data sets
sdfl <- edsurvey.data.frame.list(list(sdfA, sdfB, sdfC, sdfD),
                                 labels=c("A locations",
                                          "B locations",
                                          "C locations",
                                          "D locations"))


# this shows how these datasets will be described
sdfl$covs 
# }
# NOT RUN {
# get the gaps between Male and Female for each data set
gap1 <- gap("composite", sdfl, dsex=="Male", dsex=="Female")
gap1
# }
# NOT RUN {
# make combine sdfA and sdfB
sdfl1a <- edsurvey.data.frame.list(list(sdfA, sdfB),
                                   labels=c("A locations",
                                            "B locations"))

# combine sdfC and sdfD
sdfl1b <- edsurvey.data.frame.list(list(sdfC, sdfD),
                                   labels=c("C locations",
                                            "D locations"))

# append to make sdf3 the same as sdfl
sdfl3 <- append.edsurvey.data.frame.list(sdfl1a, sdfl1b)
identical(sdfl, sdfl3) #TRUE

# append to make sdf4 the same as sdfl
sdfl4 <- append.edsurvey.data.frame.list(
  append.edsurvey.data.frame.list(sdfl1a, sdfC, labelsB = "C locations"),
  sdfD,
  labelsB = "D locations")
identical(sdfl, sdfl4) #TRUE

# }