Data Set Catalog and Codebooks

The book uses 30 real data sets, 14 simulated data sets that are distributed as files, and the data of 35 simulation studies, which are not distributed because their scripts regenerate them. This appendix records where each data set comes from, how it was prepared, which chapters use it, and what its variables mean. Figure C.1 shows at a glance which real data sets each chapter uses: a few data sets carry the core chapters, and the chapters on extensions each bring their own. The first 10 rows of the figure are the core data sets, documented variable by variable in Section C.4.

Note. Rows: data sets, named by their file in Data/ or their R object (Table C.2); the first 10 rows are the core data sets. Columns: Chapters 1 to 32 and Appendices A and B. A filled cell marks a chapter that analyzes the data set or uses it in an exercise.

C.1Files, Formats, and Scripts#

The companion repository keeps the data in three folders. Data/ holds one analysis file per data set in two formats with the same content: an R data file (.rds), which preserves variable types and is the file that the book’s scripts read, and a comma-separated copy (.csv) for other programs; the companion files of the simulated data sets are .csv files only, and the scripts read them in that format. Data/raw/ holds the original files from which some analysis files were built, and Data/export/ holds three zip archives with the same data as SPSS (.sav), Stata (.dta), and Mplus (.dat) files: 58 files in each archive, namely the 44 data sets of Tables C.2 and C.5 and 14 companion files, such as the separate pupil and school files of HSB and the true person parameters of the simulated diary data. Data sets that are read directly from an R package, four of the real data sets, have no file in Data/, but they are included in the archives, and the file export_manifest_V01.csv lists the numbers of rows and columns of every exported file. Data/raw/ also keeps three SAS programs of the course (school10-data.sas, How_to_Simulate_Data.sas, and SAS_MergeData.sas) for reference; no script reads them.

Every analysis file is written by a script, never edited by hand. The files of Chapters 1 to 20 are built by the scripts prepare_*_V01.R in Scripts/Shared/, and those introduced in Chapters 21 to 32 by the script data_chNN_*_V01.R of the chapter that introduces them. Each preparation script states its input and the recoding it performs, and the scripts in Scripts/Shared/ also check the result, for example the numbers of units at each level and the constancy of cluster-level variables within clusters. The export archives are written by Scripts/AppC/appC_export_formats_V01.R, which reads every SPSS and Stata file back and compares its dimensions with the source.

In R, a data set is read either from its file or from its package:

book_root <- "path/to/Textbook"                  # the repository folder
hsb <- readRDS(file.path(book_root, "Data", "hsb.rds"))
hsb <- read.csv(file.path(book_root, "Data", "hsb.csv"))      # same content
data(sleepstudy, package = "lme4")               # package-only data sets

In the .csv and .rds files, missing values are NA; in the SPSS and Stata files, they are system-missing; and in the Mplus files, which have no header, they are coded $-999$. Each Mplus data file comes with an input stub (.inp) that lists the variable names and the missing-value code and documents the codes of variables that are text or factors in R. Mplus names in the stubs have at most eight characters; nine files have names shortened for this purpose, and the stub lists each original name with its short form. Names containing a period, such as hos.cat, are written with an underscore in the SPSS and Stata files. Before export, identifiers and other categorical variables whose categories are numbers are written as those numbers, variables with two categories are coded 0 and 1 with value labels (for example, N = 0 and Y = 1 for contraceptive use), and other factors keep codes from 1 upward with value labels. Text variables with more than two categories, such as the author names of the meta-analytic data, stay text in the SPSS and Stata files and are left out of the Mplus files, whose stubs list them. SAS reads the SPSS and Stata files with PROC IMPORT where the SAS/ACCESS Interface to PC Files is licensed; the .csv files can also be imported, but their missing values, written as NA, must then be recoded. HLM builds its multivariate data matrix from one file per level, sorted by the cluster identifier; the separate pupil and school files of HSB (hsb_pupils, hsb_schools) and TIMSS (timss_pupils, timss_schools) serve this purpose, and the same split can be made for any other data set by keeping the cluster-level variables once per cluster.

Identifiers deserve attention before any model is fitted (Chapter 4). In most files, the identifier of a unit is unique across clusters. The exceptions are the pupil numbers of NELS:88 and the student numbers of the GCSE data, which restart in each school; the class numbers of the Junior School Project, which restart in each school; the school numbers of the school calendar data, which restart in each district; and, among the simulated data, the member numbers of med211_sim, which restart in each team, and the student numbers of did_sim, which restart in each school and year. In these files, a unit is identified by the combination of its own number and the number of its cluster. None of the files carries sampling weights; the weighting examples of Chapter 17 use simulated populations.

C.2Sources, Permissions, and Citation#

Table C.2 gives the source of each real data set. Of the 30 real data sets, 23 are distributed with R packages (Table C.1) or derived from such data, and seven come from files of the course archive on which this book is based or are derived from them. A user of any data set should cite its original source, given in the Source column of Table C.2, and, for packaged data, the package.

The licenses in Table C.1 are software licenses of the packages, and none of the packages states separate terms for its data. They do not settle the terms of use of the underlying studies, which remain with the original investigators and agencies. The NELS:88 subsample of Kreft & de Leeuw (1998) is also distributed with the R package influence.ME, whose documentation states that the data are reproduced with permission from Jan de Leeuw (Nieuwenhuis et al., 2012); the course file used in this book agrees with that version on every variable the two share, for all 519 pupils, and the codes of its categorical variables were matched to the labels in that documentation. The other course files were obtained as follows: the Junior School Project file from the website multilevel.ioe.ac.uk of the Centre for Multilevel Modelling, now at the University of Bristol, as its header states; the Riesby file as distributed by Hedeker & Gibbons (2006); the teacher-turnover file from the data page for Singer & Willett (2003) at the UCLA Office of Advanced Research Computing; and the TIMSS lab files from the course’s computer labs. The header of the TIMSS file dates the data to 1997, whereas pupils in grades 3 and 4 were assessed in the 1995 cycle of TIMSS; the course records do not resolve this discrepancy. The course files are kept in the repository for teaching; permission to redistribute them publicly has not yet been obtained from their original distributors, so a public release of the repository would include the preparation scripts and instructions for obtaining the raw files rather than the files themselves.

C.3Overview of the Real Data Sets#

Table C.2 lists the 30 real data sets with their structure, source, and the chapters that use them. The numbers of units are counted in the distributed files, so they can differ from the numbers analyzed in a chapter when a model excludes cases with missing values. Several analyses use subsets that have no file of their own because their scripts draw them from a distributed file. Chapter 3 uses 260 pupils in 10 of the NELS:88 schools (7472, 7829, 7930, 24725, 25456, 25642, 62821, 68448, 68493, and 72292). Figure 5.3 shows 30 HSB schools drawn with seed 5003. Chapters 9 and 10 use random samples of 50 HSB schools and of 20 of these 50, drawn with seed 20261020; Chapter 13 uses a different random sample of 20 schools, drawn with seed 20261320, and, for Figures 13.2 and 13.4, eight schools with 10 pupils each, drawn with seed 6. Chapters 9 and 10 also read a second course file of the TIMSS data, Data/raw/timss_lab2new.txt, which adds to the same pupils their reported time watching television and playing computer games (hoursTV, hourscomputergames; five ordered categories each, 1 = least, 5 = most) and the type of community in which the school is located (community: 1 = geographically isolated, 2 = village or farm area, 3 = outskirts of a town or city, 4 = close to the center of a town or city). Chapter 17 creates missing values in the TIMSS data by a documented random mechanism, with seed 20261701.

C.4Codebooks of the Core Data Sets#

The 10 core data sets carry the running examples of the core chapters. Table C.3 documents every variable in their files, 97 variables in all, with the level at which each variable varies, its meaning, and its codes or range. The paragraphs below add what a table cannot: how each file was prepared and what a reader should know before analyzing it.

NELS:88, 23 schools. The National Education Longitudinal Study of 1988 surveyed eighth-grade pupils in the spring of 1988; the subsample of Kreft & de Leeuw (1998) contains 519 pupils in 23 schools. The outcome is a mathematics test score. The homework variable is an ordered category of weekly time on mathematics homework, not a number of hours: its categories are unequally spaced in time, so a slope for homework is a difference per category. The indicators female, white, and public are derived in the preparation script; school means and school-centered versions of SES and homework are computed in the analysis scripts that use them.

High School and Beyond. The HSB file combines the pupil and school files of Raudenbush & Bryk (2002) as distributed with nlme (Pinheiro & Bates, 2000): 7,185 pupils in 160 U.S. high schools surveyed in 1982, with mathematics achievement as the outcome. The file contains two versions of the school mean SES. The variable meanses is the mean of ses over the sampled pupils, and ses_cwc is SES centered at it; meanses_rb is the value distributed with the data, which exceeds the sample mean by 0.0055 to 0.0065 in every school. Chapters 5 to 7, 18, and 32 use the sample mean; some tables of Chapters 9 to 13 and 15 use the distributed value, as their scripts show. Because the two versions differ by a nearly constant amount, the coefficients of these variables are almost the same under either version, whereas the intercept shifts slightly.

TIMSS lab file. The course file contains the science and mathematics scores, in the metric of the course file, of 7,097 U.S. pupils in grades 3 and 4 in 146 schools, and one school characteristic, the principal’s rating of the shortage of instructional materials. It is distributed as a merged file and, for the merging exercise of Chapter 4, as separate pupil and school files. The file timss3 adds the class, decoded from the pupil identifier, and the class and school means of mathematics used in the three-level models of Chapter 8; it keeps the numeric versions girl and shortages of gender and the shortage rating.

Junior School Project. The long file has one record per pupil and year for 1,192 pupils in 49 inner-London primary schools (Mortimore et al., 1988), with mathematics scores in up to three years; the wide file jsp_wide has one row per pupil, with the scores as math0, math1, and math2. Chapter 1 uses the 1,093 pupils with scores in the first two years. The other variables of the source file are kept as they are and are not used in this book.

Riesby depression data. The file has 66 patients, each scheduled for six weekly ratings on the Hamilton Depression Rating Scale (weeks 0 to 5); 375 of the 396 scheduled ratings are observed, 46 patients have all six, and 37 have endogenous depression (Hedeker & Gibbons, 2006; Reisby et al., 1977). Missing ratings are kept as NA so that the file shows which ratings are missing; the analysis scripts remove them. The plasma drug levels measured in the study are not part of the course file.

Sleep deprivation study, Sustaining Effects Study, and Study of Instructional Improvement. The sleep study data are used as distributed with lme4: reaction times of 18 subjects on 10 consecutive days, perfectly balanced (Belenky et al., 2003). The Sustaining Effects Study file is mlmRev::egsingle with its two-category factors recoded as 0 and 1 and its identifiers stored as text: up to six annual mathematics scores of pupils in 60 schools, with the year of the test centered. The SII file is WWGbook::classroom (West et al., 2014): first-grade pupils in classrooms in schools, with the gain in mathematics as the outcome; the teacher’s mathematics knowledge is missing for 109 pupils.

Bangladesh contraception data. The data are used as distributed with mlmRev: 1,934 married women in 60 districts (Huq & Cleland, 1990). Age is centered at the mean in the distributed file; the analysis scripts rescale it to decades, add its square, reduce the number of living children to an indicator of having any, and code urban residence as 0 and 1.

C.5The Other Real Data Sets#

Table C.4 lists the variables that the book uses from the other 20 real data sets; the documentation of each package describes the remaining variables. Most files are the package data with at most a few derived variables, but four were restructured. The epilepsy data, which have one row per patient and follow-up visit with the baseline count as a column, received the eight-week baseline count as an additional row (period 0), with the length of each period as the exposure. The LSAT data were expanded from a table of response patterns and their frequencies to one row per examinee. The GCSE data were stacked into one row per student and outcome, without the missing scores. The teacher data are distributed both with one row per teacher and in the person-period format of Chapter 25. The schizophrenia and smoking prevention data were extracted from the source archive of mixor 1.0.4 (Hedeker & Gibbons, 1996), because the current version, 1.0.7, requires R 4.6 or later (Table C.1); the data of the two versions are identical. The smoking prevention file is used only in an exercise.

C.6Simulated Data Sets#

Where no suitable public data set was available, or where the true values of the parameters had to be known, chapters use simulated data. The 14 simulated data sets in Table C.5 are distributed as files, so that an exercise can use them without running the generating script, and each is reproduced exactly by its script with the stated seed. Several files come with a companion file of true values or of the higher-level units: diary_sim_persons, mood_sim_persons, and esm_sim_persons contain each person’s true parameters; mlirt_sim_schools and mm_sim_schools contain the schools; mm_sim_membership contains the membership weights; dyads_sim_dyad has one row per couple; and dropout_sim_students has one row per student. A few figures and tables use small illustrative data generated inside their own scripts; these are reproduced by rerunning the script and are not distributed separately.

C.7Simulation Studies#

The 35 simulation studies of 31 chapters (Table C.6) follow the simulation template introduced in Chapter 4, except for two supplementary runs, sim_ch28_design_V02.R and sim_ch29_mediation_J_V02.R, which write their own summaries and have no analysis script. Each of the other studies has a simulation script, sim_chNN_*_V01.R or _V02.R, and an analysis script with the corresponding name, analysis_chNN_*; a _V02 simulation script regenerates data sets of the _V01 script from the same seeds and refits them with several optimizers or starting values, and in Chapter 19 it also adds replications with new seeds. The simulation script saves the results of each condition as soon as the condition is finished, skips finished conditions when it is restarted, and writes the results of every replication as .rds and .csv files in Results/ChNN/; the analysis script reads these files and produces the tables and figures. The replication-level results are therefore available without rerunning a study, and the seeds in Table C.6 reproduce the generated data exactly under the same versions of R and the packages. The number of replications per condition ranges from 100 to 5,000, and differences between conditions are judged against their Monte Carlo standard errors; differences within about two Monte Carlo standard errors are not read as trends. The parametric bootstrap of Chapter 10, with 5,000 samples drawn from a model fitted to the HSB data, is part of a data analysis and is not counted as a simulation study.

C.8Data Described but Not Analyzed#

Some data sets appear in the book without being analyzed. The Taiwan Case boxes use Taiwanese surveys, among them the Taiwan Education Panel Survey (TEPS), the Taiwan Assessment of Student Achievement (TASA), the Taiwanese samples of PISA, TIMSS, and PIRLS, the Comprehensive Assessment Program for Junior High School Students, and the Taiwan Youth Project, as designs to think with: they show how the levels, sampling, and measurement of a real study shape the analysis, but no data from these studies are analyzed in this book, and their access conditions must be checked with the archives or agencies that distribute them. A few exercises point to data that are not in the repository: the Taiwanese PISA sample (Chapter 17), the adolescent mood data distributed with MIXREGLS (Hedeker & Nordgren, 2013) (Chapter 28), and the reading scores and first-grade records of the STAR experiment (Chapters 31 and 32), which are part of mlmRev::star and can be prepared like star_k and star_tree. Chapter 18 describes the data of past final examinations of the course only in words; their provenance and permission for redistribution have not been confirmed.