Back to guide home

5 Downloading the data

Before you can follow the R or Stata examples in this guide, you need the AMPLab student microdata on your computer in the right place and under the right file names.

This chapter walks you through:

  1. Where to download the official data
  2. Which files you need for this guide
  3. How to organise your folders
  4. How to create ampl-student-v1.dta (the file used in the analysis chapters)
  5. A short checklist before you start analysing

5.1 What you need for this guide

The R and Stata chapters assume you are working inside this guide’s project folder and that the following files exist under data/:

File Purpose
ampl-student-v1.dta Student questionnaire + cognitive data (Stata format)
ampl-student-labels.R Applies English variable/value labels to the student file in R
ampl-student-labels.do Applies English variable/value labels to the student file in Stata
ampl-school-v1.dta School questionnaire data (Stata format; optional for worked examples)
ampl-school-label.R Applies English variable/value labels to the school file in R
ampl-school-label.do Applies English variable/value labels to the school file in Stata

The student and school label scripts are already included in this guide’s data/ folder. You mainly need to download the official student database and save it as data/ampl-student-v1.dta.

The analysis examples use the student file only. The school questionnaire file is useful for other work, but it is not required for the worked examples in this guide.

5.2 Step 1: Download the data from UIS

The official AMPL-ab databases are published by the UNESCO Institute for Statistics (UIS).

  1. Open the AMPL-AB Project page.
  2. Scroll to the Databases and analysis section.
  3. Download these two student resources:
    • Raw Data of AMPL - Student - Database (zipped .csv file)
    • Raw Data of AMPL - Student - Codebook (documentation for variable and value labels)

UIS also publishes school database and codebook files. You can download them if you want them for later work, but you do not need them for this guide. If you do download them, save the school file as data/ampl-school-v1.dta and keep ampl-school-codebook.xlsx with the label scripts already in data/.

After downloading, unzip the student database archive so you can see the .csv file clearly.

5.3 Step 2: Set up your project folders

Work from this guide’s project root (the folder that contains index.Rmd and the chapter .Rmd files). Create a data/ folder there if it does not already exist:

ampl-guide/
├── data/
│   ├── ampl-student-v1.dta         # you create this in Step 3
│   ├── ampl-student-labels.R       # already in the guide
│   ├── ampl-student-labels.do      # already in the guide
│   ├── ampl-school-v1.dta          # optional school file
│   ├── ampl-school-label.R         # already in the guide
│   ├── ampl-school-label.do        # already in the guide
│   ├── ampl-school-codebook.xlsx   # optional school codebook
│   └── AMPL_StQ Data_Codebook.xlsx # optional student codebook
├── 05-downloading-data.Rmd
├── 06-r.Rmd
└── 07-stata.Rmd

Keeping everything under ampl-guide/data/ means the analysis chapters can use short relative paths such as data/ampl-student-v1.dta. You do not need to edit those paths.

If you prefer a different location (for example C:/AMPL/data/), that is fine, but then you must change the file paths in the R and Stata chapters to match.

5.4 Step 3: Create ampl-student-v1.dta

The public student database is released as a .csv file. This guide’s examples use a Stata .dta file named ampl-student-v1.dta, so convert the CSV once and save it in data/.

5.4.1 Option A: Convert in R

library(haven)
library(readr)

# Edit this path to your downloaded CSV
student_csv <- "path/to/downloaded-ampl-student-file.csv"

student <- read_csv(student_csv, show_col_types = FALSE)
write_dta(student, "data/ampl-student-v1.dta")

5.4.2 Option B: Convert in Stata

* Edit this path to your downloaded CSV
import delimited "path/to/downloaded-ampl-student-file.csv", clear
save "data/ampl-student-v1.dta", replace

Use the exact file name ampl-student-v1.dta. The R and Stata chapters look for that name.

5.5 Step 4: Keep the label files with the data

This guide includes scripts that apply English variable and value labels derived from the official codebooks:

  • Student (R): data/ampl-student-labels.R
  • Student (Stata): data/ampl-student-labels.do
  • School (R): data/ampl-school-label.R
  • School (Stata): data/ampl-school-label.do

Leave these files in data/ next to the corresponding .dta files. The analysis chapters call the student label scripts after loading the data.

Optionally, also save the official codebook spreadsheets in data/ (for example as AMPL_StQ Data_Codebook.xlsx and ampl-school-codebook.xlsx). You do not need them to run the examples, but they are useful if you want to look up variables or rebuild the label scripts later.

5.6 Step 5: Confirm everything is ready

Before moving on to the R or Stata chapters, check that:

  1. data/ampl-student-v1.dta exists in the guide project folder.
  2. data/ampl-student-labels.R and data/ampl-student-labels.do are present.
  3. You can open ampl-student-v1.dta in R (haven::read_dta()) or Stata (use).
  4. Your R or Stata working directory is the guide project root when you knit or run the examples.

Quick checks:

# R
file.exists("data/ampl-student-v1.dta")
file.exists("data/ampl-student-labels.R")
* Stata
confirm file "data/ampl-student-v1.dta"
confirm file "data/ampl-student-labels.do"

If both checks succeed, you are ready for the analysis chapters.

5.7 Next steps

Once data/ampl-student-v1.dta is in place:

Both chapters start by loading data/ampl-student-v1.dta and applying the English labels.