grattandata/README.Rmd at master · grattan/grattandata · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(grattandata)
```

# grattandata
<!-- badges: start -->
[![R-CMD-check](https://github.com/grattan/grattandata/workflows/R-CMD-check/badge.svg)](https://github.com/grattan/grattandata/actions)
<!-- badges: end -->


Easily load microdata from the Grattan Institute data warehouse in R. Users will require access to the Grattan Institute data warehouse.

## Get access to the data warehouse

Speak to a Grattan R user to get access to the data warehouse. Post in `#r_at_grattan` Slack if you're not sure who to speak to.

Note that access to some parts (most) of the warehouse requires you to be an approved user of the relevant microdata.

## Installation

You can install `grattandata` from Github as follows:

```{r eval=FALSE}
# If the `remotes` package is not installed, install it
if(!require(remotes)) {
  install.packages("remotes")
}

# Install `grattandata` from GitHub using remotes like this:
remotes::install_github("grattan/grattandata",
                        dependencies = TRUE,
                        upgrade = "always",
                        build_vignettes = TRUE)
```


## Read microdata with `read_microdata()`

The core function of the package is `read_microdata()`. If you give `read_microdata()` a unique fragment of a filename - with or without the directory names - it will load the relevant file for you. Don't worry about upper case and lower case letters - either, or a mix of both, will work.

Here are some working examples using the Victorian Government's [VISTA](https://transport.vic.gov.au/about/data-and-research/vista) travel dataset:

```{r eval=FALSE}
vista_12_16_p <- read_microdata("P_VISTA12_16_SA1_V1.csv")

vista_12_16_p  <- read_microdata("csv/P_VISTA12_16_SA1_V1.csv")

vista_12_16_p  <- read_microdata("victoria/vista/2009/csv/P_VISTA12_16_SA1_V1.csv")

```

If you give `read_microdata()` a filename fragment that matches multiple files, it will return an informative error message telling you which files match your fragment. For example:

```{r error=TRUE}
vista <- read_microdata("VISTA12_16_")

```

You can now  identify which file you want to load, and be more specific with the fragment that you pass to `read_microdata()`.

### Data stored elsewhere
Some data - like HILDA - can't be stored on Dropbox with our other microdata. The function `add_microdata_location()` enables you to tell the {grattandata} package where to look for this off-warehouse microdata. You use it like this:

```{r eval=FALSE}
add_microdata_location(path = file.path("documents", "hilda"))

read_microdata("hilda_wave1.dta")
read_microdata("hilda_wave2.dta")
```

### Package vignette
For more, see the package vignette by typing `browseVignettes("grattandata")`. This should open a tab in your web browser - click 'HTML'.