lsa.download.data {RALSA}R 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:

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:

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:

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)



[Package RALSA version 1.5.5 Index]