lsa.download.data: Download large-scale assessment and survey data

View source: R/lsa.download.data.r

lsa.download.dataR Documentation

Download large-scale assessment and survey data

Description

Downloads data files from large-scale assessments' and surveys' data repositories on the web and, if desired, converts them to lsa.data format and stores them in .RData files.

Usage

lsa.download.data(
  study,
  cycle,
  POP,
  ISO,
  out.folder,
  append = TRUE,
  convert = TRUE,
  missing.to.NA = FALSE
)

Arguments

study

String, large-scale assessment or study name. See details.

cycle

Numeric, study year of administration (cycle). See details.

POP

String, population of interest. If none is provide, default is taken. See details.

ISO

Vector containing character ISO codes of the countries' data files to include in the merged file. See details.

out.folder

Path to the folder where the downloaded (and optionally converted) files will be stored. If the final folder in the path does not exist, it will be created.

append

If some files for the study, cycle, populations and countries have already been downloaded, download only the new ones. (default is TRUE). See details.

convert

Logical, shall the data be converted to lsa.data and stored in .RData files (default) after being downloaded. See details.

missing.to.NA

Logical, should the user-defined missing values be converted to NA when converting the downloaded data (default is FALSE)? See lsa.convert.data.

Details

The lsa.download.data function downloads large-scale assessments' and surveys' data files from data repositories on the web. This is a convenience function that saves time and efforts for the user. IEA studies, as well as OECD TALIS and TALIS 3S, provide their data in SPSS .sav format with same or very similar structure: one file per country and type of respondent (e.g. school principal, student, teacher, etc.) per population. For IEA studies and OECD TALIS and TALIS 3S use the ISO argument to specify the countries' three-letter ISO codes whose data is to be downloaded. The three-letter ISO codes for each country can be found in the user guide for the study in scope. For example, the ISO codes of the countries participating in PIRLS 2016 can be found in its user guide on pages 52-54. To download the files from all countries for an IEA study and OECD TALIS and TALIS 3S, simply omit the ISO argument, this will download files for all countries for the population in POP in the study and cycle. The ISO argument will not work for PISA files, as all data for all countries is provided within a single file per respondent type. If ISO is provided anyway, it will be ignored. Note that as of now, the function downloads PISA databases only from its latest cycles - 2015, 2018 and 2022.

When all desired SPSS data files are downloaded, the function converts them to lsa.data objects and stores them as .RData files on the disk, removing the data files downloaded in their original (SPSS) format. This is the default behavior which can be overridden by setting convert = FALSE.

The study argument defines the study for which data shall be downloaded. The acceptable strings are as follows:

  • CivED - IEA Civic and Citizenship Education study (CivED)

  • ICCS - IEA International Civic and Citizenship Education Study (ICCS)

  • ICILS - IEA International Computer and Information Literacy Study (ICILS)

  • PIRLS - IEA Progress in International Reading Literacy Study (PIRLS)

  • prePIRLS - IEA PIRLS Literacy (prePIRLS)

  • REDS - IEA Responses to Educational Disruption Survey (REDS)

  • RLII - IEA Reading Literacy Study (RL), second round

  • SITES - IEA Second Information Technology in Education Study (SITES)

  • TIMSS - IEA Trends in International Mathematics and Science Study (TIMSS)

  • preTIMSS - IEA TIMSS Numeracy (TIMSS)

  • eTIMSS PSI - IEA TIMSS with PSI items (TIMSS)

  • TIMSS Advanced Mathematics/TIMSS Advanced Physics - IEA Trends in International Mathematics and Science Study in Mathematics and Physics (TIMSS Advanced)

  • TiPi - IEA joint TIMSS and PIRLS 2011 study

  • PISA - OECD Programme for International Student Assessment (PISA)

  • PISA D - OECD Programme for International Student Assessment for low- and middle-income countries (PISA for Development)

  • TALIS - OECD Teaching and Learning International Survey (TALIS) and

  • TALIS 3S - OECD Starting Strong Teaching and Learning International Survey (TALIS Starting Strong Survey)

The cycle argument provides information about the year of administration of a particular study for which SPSS data files can be downloaded. A numeric value for a specific year of administration needs to be provided. Here is the list from all released cycles for all studies RALSA supports till now:

  • For CivED - 1999

  • For ICCS - 2009, 2016, or 2022

  • For ICILS - 2013, 2018, or 2023

  • For PIRLS - 2001, 2006, 2011, 2016, or 2021

  • For prePIRLS - 2016

  • For ePIRLS - 2016

  • For REDS - 2021

  • For RLII - 1991 or 2001

  • For SITES - 1998 or 2006

  • For TIMSS - 1995, 1998, 2003, 2007, 2011, 2015, 2019 or 2023

  • For preTIMSS - 2015

  • For eTIMSS PSI - 2019

  • For TIMSS Advanced Mathematics/TIMSS Advanced Physics - 1995, 2008, or 2015

  • For TiPi - 2011

  • For PISA - 2015, 2018 or 2022

  • For PISA D - 2019

  • For TALIS - 2008, 2013, or 2018

  • For TALIS 3S - 2018

Note that the data from the IEA Teacher Education and Development Study in Mathematics (TEDS-M) is not freely available from the IEA website due to data confidentiality issues and is available only on request from the IEA.

Some studies (e.g. TIMSS and TALIS) have more than one population (i.e. students in grades 4 and 8 in TIMSS and teachers in different ISCED levels in TALIS). The POP argument is required for these studies, as the lsa.download.data needs to know data from which population is needed. The population strings for the POP argument for the pertinent studies are as follows:

  • CivED:

    • G8 (grade 8)

    • G12 (grade 12)

  • ICCS:

    • G8 (grade 8)

    • G9 (grade 9, ICCS 2009 only)

  • ICILS:

    • G8 (grade 8)

  • PIRLS:

    • G4 (grade 4)

  • prePIRLS:

    • G4 (grade 4)

  • ePIRLS:

    • G4 (grade 4)

  • REDS:

    • G8 (grade 8)

  • RLII:

    • G4 (grade 4)

  • SITES:

    • M1 POP A (Module 1, 1998, population A)

    • M1 POP B (Module 1, 1998, population B)

    • M1 POP C (Module 1, 1998, population C)

    • M2 (Module 2, 2006)

  • TIMSS:

    • G4 (grade 4)

    • G8 (grade 8)

  • preTIMSS:

    • G4 (grade 4)

  • eTIMSS PSI:

    • G4 (grade 4)

    • G8 (grade 8)

  • TIMSS Advanced Mathematics / TIMSS Advanced Physics:

    • G12 (grade 12)

  • TiPi:

    • G4 (grade 4)

  • PISA:

    • Y15 (15-year-old)

  • PISA for Development

    • IS (in school)

    • OS (out of school)

  • TALIS:

    • I1 (ISCED 1)

    • I2 (ISCED 2)

    • I3 (ISCED 3)

    • P (PISA schools)

  • TALIS 3S:

    • I0.2 (ISCED 0.2)

    • IU3 (ISCED U3)

For the exact meaning of the population names, see the respective study documentation. Note that if POP is not provided, a default (first population for a study and/or a cycle) is applied.

The out.folder argument controls where the files shall be stored. Note that the files will not download the files directly in the folder path provided to the argument. Instead, it will create a folder named as the study name, cycle and population and place the downloaded files there. Note that for IEA studies, OECD TALIS and TALIS 3S, if the download folder already exists and it contains data files for a given study, cycle and population for some of the countries, the function will only append the new files in it, keeping the ones that already exist there, if the append argument equals TRUE (default). This can save a lot of time if the user needs to download just the additional files instead of download everything again. If append argument equals TRUE, the existing files will be overwritten. For OECD PISA and PISA for Development the append argument will be ignored and, if the study folder in out.folder exists and contains any SPSS .sav or .RData files, the function will stop its execution and ask for moving the existing files.

Value

If convert = FALSE, the function will return the originally downloaded data files (SPSS or ASCII textt with .sps control files) for the study, cycle, countries and population defined in the respective arguments, stored in the directory specified in out.folder. If convert = TRUE (default), converted .RData data files, containing an object with class lsa.data, an extension of the data.table class, will be saved in the directory defined by out.folder and the original downloaded SPSS data files will be removed.

Note

It is not recommended to work further in the folder where the downloaded files reside, it is meant to be only for the downloaded (an possibly converted) files.

In some study cycles (e.g. TIMSS 2019 and PIRLS 2021), there are the so-called "bridge studies". These aim to test the differences between electronic and paper testing modes. When a study cycle contains data files from a bridge study, these will be downloaded too for the countries that conducted the study electronically.

As of now, PISA data can be downloaded only for the 2015, 2018 and 2022 cycles.

References

Foy, P. (Ed.). (2018). PIRLS 2016 User Guide for the International Database. TIMSS & PIRLS International Study Center.

See Also

lsa.convert.data

Examples

# Download and convert PIRLS 2016 data for Australia and Slovenia only and convert them
## Not run: 
lsa.download.data(study = "PIRLS", cycle = 2016, ISO = c("aus", "svn"), out.folder = "C:/Data")

## End(Not run)

# Same as the above, but download files for all countries
## Not run: 
lsa.download.data(study = "PIRLS", cycle = 2016, out.folder = "C:/Data")

## End(Not run)

# Download TIMSS 2019 data for grade 8 for South Africa and convert them
## Not run: 
lsa.download.data(study = "TIMSS", cycle = 2019, ISO = c("aus", "zaf"), POP = "Grade 8",
out.folder = "C:/Data")

## End(Not run)

# Download PISA 2012 data and covert them
## Not run: 
lsa.download.data(study = "PISA", cycle = 2012, out.folder = "C:/Data")

## End(Not run)



RALSA documentation built on April 4, 2025, 2:39 a.m.