Skip to contents

Connect to TIMSS Data

Source: R/readTIMSS.R
readTIMSS.Rd

Opens a connection to a TIMSS data file and returns an edsurvey.data.frame with information about the file and data.

Usage

readTIMSS(
  path,
  countries,
  gradeLvl = c("4", "8", "4b", "8b"),
  forceReread = FALSE,
  verbose = TRUE
)

Arguments

path

a character vector to the full directory path(s) to the TIMSS extracted SPSS (.sav) set of data

countries

a character vector of the country/countries to include using the three-digit ISO country code. A list of country codes can be found on Wikipedia at https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes or other online sources. Consult the TIMSS User Guide documentation to help determine what countries are included within a specific testing year of TIMSS and for country code definitions. To select all countries available, use a wildcard value of *.

gradeLvl

a character value to indicate the specific grade level you wish to return

  • 4 = fourth grade (the default if not specified)

  • 8 = eighth grade

  • 4B = fourth grade bridge study (TIMSS 2019 only)

  • 8B = eight grade bridge study (TIMSS 2019 only)

forceReread

a logical value to force rereading of all processed data. The default value of FALSE will speed up the readTIMSS function by using existing read-in data already processed.

verbose

a logical value to either print or suppress status message output. The default value is TRUE.

Value

an edsurvey.data.frame for a single specified country or an edsurvey.data.frame.list if multiple countries specified

Details

Reads in the unzipped files downloaded from the TIMSS international database(s) using the IEA Study Data Repository. Data files require the SPSS data file (.sav) format using the default filenames.

A TIMSS edsurvey.data.frame includes three distinct data levels:

  • student

  • school

  • teacher

When the getData function is called using a TIMSS edsurvey.data.frame, the requested data variables are inspected, and it handles any necessary data merges automatically. The school data always will be returned merged to the student data, even if only school variables are requested. If teacher variables are requested by the getData call, it will cause teacher data to be merged. Many students can be linked to many teachers, which varies widely between countries.

Please note that calling the dim function for a TIMSS edsurvey.data.frame will result in the row count as if the teacher dataset was merged. This row count will be considered the full data N of the edsurvey.data.frame, even if no teacher data were included in an analysis. The column count returned by dim will be the count of unique column variables across all three data levels.

Beginning with TIMSS 2015, a numeracy dataset was designed to assess mathematics at the end of the primary school cycle for countries where most children are still developing fundamental mathematics skills. The numeracy dataset is handled automatically for the user and is included within the fourth-grade dataset gradeLvl=4. Most numeracy countries have a 4th grade dataset in addition to their numeracy dataset, but some do not. For countries that have both a numeracy and a 4th grade dataset, the two datasets are combined into one edsurvey.data.frame for that country. Data variables missing from either dataset are kept, with NA values inserted for the dataset records where that variable did not exist. Data variables common to both datasets are kept as a single data variable, with records retaining their original values from the source dataset. Consult the TIMSS User Guide for further information.

For the TIMSS 2019 study, a bridge study was conducted to help compute adjustment factors between the electronic test format and the paper/pencil format. The bridge study is considered separate from the normal TIMSS 2019 study. The gradeLvl parameter now includes a "4B" option for the Grade 4 bridge study, and the "8B" option for the Grade 8 bridge study files.

See also

readNAEP, getData, and downloadTIMSS

Author

Tom Fink

Examples

if (FALSE) { # \dontrun{
# single country specified
fin <- readTIMSS(path="~/TIMSS/2015", countries = c("fin"), gradeLvl = 4)
gg <- getData(data=fin, varnames=c("asbg01", "totwgt", "srea"))
head(gg)
edsurveyTable(formula=srea ~ asbg01, fin)

# multiple countries returned as edsurvey.data.frame.list, specify all countries with '*' argument
timss2011 <- readTIMSS(path="~/TIMSS/2011", countries="*", gradeLvl = 8, verbose = TRUE)
# print out edsurvey.data.frame.list covariates
timss2011$covs
} # }