Loading data

How to load data into R

Author

Søren O’Neill & Steen Harsted

Published

February 8, 2024

Sooner or later, you will need to important data into R from some external container like a file or a database.

In the following we will provide some help to getting started with the most common such files and databases.

1 Data formats

R can read data from many different sources, including:

  • CSV
  • Microsoft Excel
  • REDCap
  • STATA, SPS and SAS
  • SQLite
  • JSON

Read more about each format on the tabs below.

Also, check out R’s own format for storing data to files: RDS – jump to Section 2

1.1 What is a CSV file?

  • CSV is an acronym for ‘Comma Separated Values’.
  • It is a format for storing data in a simple text file.
  • CSV files inherit all the benefits of working with simple text files: small size, simple format, universal access, maximum portability, minimum learning curve, future proofed, etc.
  • Conversely, CSV files are limited in the complexity of the data it can store: only simple tabular data.
  • You can read more about CSV files here wiki.

1.2 An example file

An example of a CSV file could look like this:

id,test,value,group,note
1,1,12,"A",""
1,2,14,"B",""
2,1,15,"C","My note"
2,2,13,"A",""

From the raw text of the CSV file we can deduce, that the data consists of 5 variables, delimited by ‘,’. We can deduce that from the first header line, which contains variable names separated by commas.

Note that a CSV file does not necessarily include a title line.

We can take a guess as to the meaning of the variables from their names in line 1, but we can not know.

The CSV files includes 4 lines with data in addition to the header line.

Now ask yourself

  • What is the data type of each variable? (integer, numerical, factors/categorical, etc)?
  • What are the allowed or valid values for each variable?
  • What happens if a variable is missing

…such meta-data is not stored within a CSV file and we need to keep tabs on it ourselves: It is a good idea to maintain a data definition file along with the CSV file itself, which described the data in more detail.

Alternatively, the packages csvy uses a YAML header in combination with CSV data to include a data definition.

And here is the same data presented as a table, which makes it easier on the human eye.

id test value group note
1 1 12 A
1 2 14 B
2 1 15 C My note
2 2 3 A

As it happens, the comma is probably a poor choice as the default delimiter.

In the English speaking world, decimal numbers are typed as 0.25. However, in some countries, including Denmark, decimal numbers can be written as 0,25 (note the comma versus the period).

This means there is a risk that decimal commas can be mistaken for value-delimiting commas, and vice versa. Consider this simple example: 3,5 – is that two values 3 and 5 separated by a comma, or is it 3\(\frac{1}{2}\) written as a decimal number? It is impossible to say.

Thus, it is common to use a semi-colon instead of a comma as the data delimiter to avoid such issues.

1.3 Tidyverse solution

  • Tidyverse includes the package readr which provides a number of functions to read CSV files.
  • The function read_delim() is the generic function which reads tabular data delimited by whatever character is specified in the function call.
  • The functions read_csv(), read_tsv() and read_csv2() are just special cases of read_delim() (using comma, tab and semi-colon as delimiters).

Base R includes the function read.table() which also has a number of special cases, including read.csv() that also serves to read tabular data from CSV files. Note the use of dot rather than an underscore in the function name.

1.4 RTFM – Read the fine manual

Acquaint yourself with the read_delim() function using the help function in RStudio.

Note that a csv file should end with an empty line – more specifically, that the invisble end-of-line character is necessary to indicate the end of the last line.

1.5 Try it out

Ideally, use you own CSV data file for these exercises.

Alternatively, you will find a sample CSV file here

  • Inspect the data with my_data and str(my_data).
library(readr)
my_data <- read_csv(here("path_to_file", "fil.csv"))
my_data
str(my_data)

1.6 Exercises

  • What happens is a value is missing?
  • What happens if a value-delimiting-character is missing?
  • What happens if you add a value-delimiting-character inside a text data point, e.g. between ‘My’ and ‘note’ in the example csv file?
  • What happens if you use read_csv() and read_csv2() respectively without specifying a delimiter?
  • What happens if you set the parameter col_names = FALSE?
  • What happens if you set the parameter na = "NA"?
  • Look at the data structure as revealed by the str() function: Are all you variables of the type you expected them to be?
    • How could you use the parameter col_types to specify data types?

Remember, this text is in a side-ordered tab about CSV files. To read about Excel fils, STATA files, etc scroll back up to the tabs…

1.7 What is an Excel file?

  • Microsoft Excel is a spreadsheet program – that means it includes many other features than simply storing data in tabular format.
  • There are (at least) two different versions of excel files (xls and xlsx) – read_excel() (from the readxl package) should handle both.
  • If you use excel files there are a couple of issues you need to pay attention to:
    • An excel file can contain more than one ‘sheet’ – you may need to specify which sheet to load
    • Character encoding – Microsoft often uses ISO character encoding. It may be prudent to ensure that you file uses UTF8 or UTF16 character encoding instead.
    • Data type conversion?

1.8 Tidyverse solution

  • Tidyverse includes the package readxl which provides a number of functions to read excel files.

1.9 RTFM – Read the fine manual

Acquaint yourself with the readxl()` function using the help function in RStudio.

1.10 Try it out

Ideally, use you own excel data file for these exercises.

Alternatively, you will find a sample xlsx file here

  • Inspect the data with my_data and str(my_data).
library(readxl)
my_data <- read_excel(here("path_to_file", "fil.xls"))
my_data
str(my_data)

1.11 Exercises

??

The simplest way to use REDCap data is to export it from the REDCap web-portal to an appropriate file format and import that into R.

  • Firstly, log into the REDCap web portal
  • Go to ‘My Projects’
  • Find the project from which you want to download data
  • In the left-hand side menu, choose Applications / Exports, Reports and Stats
  • Then click ‘Export data’
  • Select the option ‘R Statistical Software’ and click ‘Export data’
  • Now click each of the two icons (lower right) labelled R and DATA

1.12 Data structure

The data will be exported as a standard csv file. Read more about that above in the CSV tab.

The CSV file will be accompanied by an R script file, which contains R code that will read the CSV file and wrangle the data into an R data frame called ‘data’.

If your data does not change on a regular basis, we would suggest that you run the R script once to generate the ‘data’ data frame and then export to an RDS file and load that into your own R scripts. Read more about the RDS file format in Section 2 below.

Note The R script file depends on the Hmisc package being installed.

1.13 Direct database access

It is possible to access the underlying SQL database on which REDCap is built, directly from R code. See this link for more information.

This will require a valid access token. The REDCap administrator should be able to provide you with such a token, if permitted.

Tidyverse provides the package ‘haven’ which enables R to read and write various data formats used by other statistical packages.

It currently supports:

  • SAS: read_sas() reads .sas7bdat + .sas7bcat files and read_xpt() reads SAS transport files (versions 5 and 8). write_xpt() writes SAS transport files (versions 5 and 8).
  • SPSS: read_sav() reads .sav files and read_por() reads the older .por files. write_sav() writes .sav files.
  • Stata: read_dta() reads .dta files (up to version 15). write_dta() writes .dta files (versions 8-15).

SQLite is a light weight implementation of a Structured Query Language (SQL) database.

If your data set is dynamic in nature, with data being added, removed or edited regularly, you should consider using an SQL database to store data. The SQLite is about as light-weight and simple an SQL database as you can find.

To quote Hadley Wickham:

RSQLite is the easiest way to use a database from R because the package itself contains SQLite; no external software is needed.

You can find a good introduction to R’s SQLite implementation here and here.

2 RDS

R also provides its own data file formats, RDS and RDATA with the suffixes .Rds and .Rda or .Rdata.

2.1 RDS

  • RDS is short for R Data Serialization. RDS can store any R data, including data which is complex in nature and asymmetrical such as e.g. a list of lists of variable lengths.
  • RDS is not a simple text file – it is a compressed format not well suited for human readers
  • RDS is however, a simple and efficient way to store and retrieve data which already exist in R memory.
  • RDS is used to store a discrete data object (such as a variable containing a dataframe for instance) to a single file. When re-loaded, that data is re-assigned to a variable.

2.2 RDA

  • For most uses, the RDA format not as well suited as RDS
  • It stores multiple variables in a single file
  • When re-loading, the data is not re-assigned but stored in the same variable names as they were saved in – this can prove a problem by overwriting existing variables of the same name.
  • If Reproducible Research is a priority, stick to RDS.

Read more about the rds format here.

Før eller siden vil du skulle importere data i R fra en ekstern kilde som en fil eller en database.

I det følgende giver vi nogle tips til at komme i gang med de mest almindelige filtyper og databaser.

3 Dataformater

R kan læse data fra mange forskellige kilder, herunder:

  • CSV
  • Microsoft Excel
  • REDCap
  • STATA, SPSS og SAS
  • SQLite
  • JSON

Læs mere om hvert format i fanerne nedenfor.

Se også R’s eget format til lagring af data i filer: RDS – spring til Section 4.

3.1 Hvad er en CSV-fil?

  • CSV er en forkortelse for ‘Comma Separated Values’.
  • Det er et format til lagring af data i en simpel tekstfil.
  • CSV-filer har alle fordelene ved simple tekstfiler: lille størrelse, simpelt format, universel adgang, maksimal portabilitet, minimal læringskurve, fremtidssikring osv.
  • Omvendt er CSV-filer begrænset i kompleksiteten af de data, de kan gemme: kun simple tabulære data.
  • Du kan læse mere om CSV-filer her wiki.

3.2 Et eksempel på en CSV-fil

Et eksempel på en CSV-fil kunne se sådan ud:

id,test,value,group,note
1,1,12,"A",""
1,2,14,"B",""
2,1,15,"C","My note"
2,2,13,"A",""

Ud fra den rå tekst i CSV-filen kan vi udlede, at data består af 5 variabler, adskilt med ‘,’. Det kan vi udlede fra den første header-linje, som indeholder variabelnavne adskilt med kommaer.

Bemærk at en CSV-fil ikke nødvendigvis indeholder en titel-linje.

Vi kan gætte på variablernes betydning ud fra deres navne i linje 1, men vi kan ikke vide det med sikkerhed.

CSV-filen indeholder 4 linjer med data ud over header-linjen.

Overvej nu:

  • Hvad er datatype for hver variabel? (heltal, numerisk, kategorisk osv.)
  • Hvad er de tilladte eller gyldige værdier for hver variabel?
  • Hvad sker der, hvis en variabel mangler?

…sådanne metadata er ikke gemt i en CSV-fil, og vi skal selv holde styr på dem: Det er en god ide at vedligeholde en datadefinition-fil sammen med selve CSV-filen, som beskriver dataene mere detaljeret.

Alternativt bruger pakken csvy en YAML-header kombineret med CSV-data til at inkludere en datadefinition.

Og her er de samme data præsenteret som en tabel, hvilket gør det lettere for det menneskelige øje.

id test value group note
1 1 12 A
1 2 14 B
2 1 15 C My note
2 2 3 A

Som det hænder, er kommaet sandsynligvis et dårligt valg som standard-adskiller.

I den engelsktalende verden skrives decimaltal som 0.25. Men i nogle lande, herunder Danmark, kan decimaltal skrives som 0,25 (bemærk kommaet i stedet for punktum).

Dette betyder, at der er en risiko for, at decimalkommaer kan forveksles med værdi-adskillende kommaer og omvendt. Overvej dette simple eksempel: 3,5 – er det to værdier, 3 og 5, adskilt af et komma, eller er det 3½ skrevet som et decimaltal? Det er umuligt at sige.

Derfor er det almindeligt at bruge et semikolon i stedet for et komma som data-adskiller for at undgå sådanne problemer.

3.3 Tidyverse-løsning

  • Tidyverse inkluderer pakken readr, som giver en række funktioner til at læse CSV-filer.
  • Funktionen read_delim() er den generelle funktion, som læser tabulære data adskilt af en valgfri karakter specificeret i funktionskaldet.
  • Funktionerne read_csv(), read_tsv() og read_csv2() er blot specialtilfælde af read_delim() (som bruger henholdsvis komma, tabulator og semikolon som adskillere).

Base R inkluderer funktionen read.table(), som også har en række specialtilfælde, herunder read.csv(), som også bruges til at læse tabulære data fra CSV-filer. Bemærk brugen af punktum i stedet for en understregning i funktionsnavnet.

3.4 RTFM – Læs manualen

Sæt dig ind i funktionen read_delim() ved at bruge hjælpefunktionen i RStudio.

Bemærk at en CSV-fil skal slutte med en tom linje – mere specifikt, at den usynlige slut-på-linje-karakter er nødvendig for at indikere afslutningen på sidste linje.

3.5 Prøv det selv

Brug ideelt set din egen CSV-datafil til disse øvelser.

Alternativt finder du en eksempelfil her.

  • Inspicer dataene med my_data og str(my_data).
library(readr)
my_data <- read_csv(here("path_to_file", "fil.csv"))
my_data
str(my_data)

3.6 Øvelser

  • Hvad sker der, hvis en værdi mangler?
  • Hvad sker der, hvis en værdi-adskiller mangler?
  • Hvad sker der, hvis du tilføjer en værdi-adskiller inde i en tekstdatapunkt, f.eks. mellem ‘My’ og ‘note’ i eksempelfilen?
  • Hvad sker der, hvis du bruger read_csv() og read_csv2() henholdsvis uden at specificere en adskiller?
  • Hvad sker der, hvis du indstiller parameteren col_names = FALSE?
  • Hvad sker der, hvis du indstiller parameteren na = "NA"?
  • Se på datastrukturen, som afsløres af funktionen str(): Er alle dine variabler af den type, du forventede?
    • Hvordan kunne du bruge parameteren col_types til at specificere datatyper?

Husk, denne tekst er i en sideordnet fane om CSV-filer. For at læse om Excel-filer, STATA-filer osv., scroll op til fanerne…

3.7 Hvad er en Excel-fil?

  • Microsoft Excel er et regnearksprogram – det betyder, at det inkluderer mange andre funktioner end blot at lagre data i tabelformat.
  • Der findes (mindst) to forskellige versioner af Excel-filer (.xls og .xlsx) – read_excel() (fra pakken readxl) burde kunne håndtere begge.
  • Hvis du bruger Excel-filer, er der et par ting, du skal være opmærksom på:
    • En Excel-fil kan indeholde mere end ét ‘ark’ – du skal muligvis specificere, hvilket ark der skal indlæses.
    • Tegnkodning – Microsoft bruger ofte ISO-tegnkodning. Det kan være klogt at sikre, at din fil bruger UTF8- eller UTF16-tegnkodning i stedet.
    • Datatypekonvertering?

3.8 Tidyverse-løsning

  • Tidyverse inkluderer pakken readxl, som giver en række funktioner til at læse Excel-filer.

3.9 RTFM – Læs manualen

Sæt dig ind i funktionen read_excel() ved at bruge hjælpefunktionen i RStudio.

3.10 Prøv det selv

Brug ideelt set din egen Excel-datafil til disse øvelser.

Alternativt finder du en eksempelfil her.

  • Inspicer dataene med my_data og str(my_data).
library(readxl)
my_data <- read_excel(here("path_to_file", "fil.xls"))
my_data
str(my_data)

3.11 Øvelser

??

Den enkleste måde at bruge REDCap-data er at eksportere dem fra REDCap-webportalen til et passende filformat og importere det i R.

  • Først skal du logge ind på REDCap-webportalen
  • Gå til ‘Mine projekter’
  • Find projektet, som du vil downloade data fra
  • I menuen til venstre vælger du Applikationer / Eksporter, Rapporter og Statistikker
  • Klik derefter på ‘Eksporter data’
  • Vælg muligheden ‘R Statistical Software’ og klik på ‘Eksporter data’
  • Klik nu på de to ikoner (nederst til højre) med etiketterne R og DATA

3.12 Datastruktur

Dataene vil blive eksporteret som en standard-CSV-fil. Læs mere om det ovenfor i CSV-fanen.

CSV-filen vil blive ledsaget af en R-scriptfil, som indeholder R-kode, der læser CSV-filen og bearbejder dataene til en R-dataramme kaldet ‘data’.

Hvis dine data ikke ændrer sig regelmæssigt, foreslår vi, at du kører R-scriptet én gang for at generere ‘data’-datarammen og derefter eksporterer den til en RDS-fil og indlæser den i dine egne R-scripts. Læs mere om RDS-filformatet i Section 4 nedenfor.

Bemærk R-scriptfilen afhænger af, at pakken Hmisc er installeret.

3.13 Direkte databaseadgang

Det er muligt at få adgang til den underliggende SQL-database, som REDCap er bygget på, direkte fra R-kode. Se dette link for mere information.

Dette kræver en gyldig adgangstoken. REDCap-administratoren skal kunne give dig en sådan token, hvis det er tilladt.

Tidyverse leverer pakken ‘haven’, som gør det muligt for R at læse og skrive forskellige dataformater

Det understøtter i øjeblikket:

  • SAS: read_sas() læser .sas7bdat + .sas7bcat filer, og read_xpt() læser SAS transportfiler (versioner 5 og 8). write_xpt() skriver SAS transportfiler (versioner 5 og 8).
  • SPSS: read_sav() læser .sav filer, og read_por() læser de ældre .por filer. write_sav() skriver .sav filer.
  • Stata: read_dta() læser .dta filer (op til version 15). write_dta() skriver .dta filer (versioner 8-15).

SQLite er en letvægtsimplementation af en Structured Query Language (SQL) database.

Hvis dit datasæt er dynamisk af natur, hvor data bliver tilføjet, fjernet eller redigeret regelmæssigt, bør du overveje at bruge en SQL-database til at gemme data. SQLite er en af de letteste og simpleste SQL-databaser, der findes.

For at citere Hadley Wickham:

RSQLite er den nemmeste måde at bruge en database fra R, fordi pakken selv indeholder SQLite; der er ikke behov for ekstern software.

Du kan finde en god introduktion til R’s SQLite-implementation her og her.

4 RDS

R tilbyder også sine egne datafilformater, RDS og RDATA, med filendelserne .Rds og .Rda eller .Rdata.

4.1 RDS

  • RDS står for R Data Serialization. RDS kan gemme alle typer R-data, inklusiv data, der er komplekse og asymmetriske, som fx en liste af lister med variabel længde.
  • RDS er ikke en simpel tekstfil – det er et komprimeret format, der ikke er særligt velegnet til mennesker.
  • RDS er dog en simpel og effektiv måde at gemme og hente data, der allerede eksisterer i R-hukommelsen.
  • RDS bruges til at gemme et enkelt dataobjekt (som fx en variabel, der indeholder en data frame) i en enkelt fil. Ved genindlæsning bliver data tildelt til en variabel igen.

4.2 RDA

  • For de fleste anvendelser er RDA-formatet ikke så velegnet som RDS.
  • Det gemmer flere variabler i en enkelt fil.
  • Ved genindlæsning bliver data ikke gen-tildelt, men gemt i de samme variabelnavne, som de blev gemt i – dette kan være problematisk, da eksisterende variabler med samme navn kan blive overskrevet.
  • Hvis Reproducible Research er en prioritet, bør du holde dig til RDS.

Læs mere om RDS-formatet her.