README.Rmd

---
output: github_document
---

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

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```


[![Build Status](https://travis-ci.org/tpall/boulder.svg?branch=master)](https://travis-ci.org/tpall/boulder)
[![Coverage Status](https://img.shields.io/codecov/c/github/tpall/boulder/master.svg)](https://codecov.io/github/tpall/boulder?branch=master)

## boulder - access Estonian health statistics

boulder is designed for querying and downloading data from [Estonian Health Statistics And Health Research Database](http://pxweb.tai.ee/PXWeb2015/index_en.html) (TAI). 
Name 'Boulder' is from Brand Estonia toolbox [boulders](https://brand.estonia.ee/design/boulders/).

> bouldeR: In our nature, the giant erratic boulders appear unexpectedly in the forest or on the beach. In our visual communication, they play a similar disruptive role. The use of boulders is not compulsory. [Brand Estonia](https://brand.estonia.ee/design/boulders/)

## Verbs
Package has two main functions `get_all_tables()` and `pull_table()`.

- `get_all_tables()` downloads list of available database tables and 
- `pull_table()` downloads your table of interest based on table name. 

Table descriptions are available in 'Title' column of data frame produced by `get_all_tables()`. 
By default `get_all_tables()` uses local table supplied with the package.
To download fresh list of database tables from TAI use `local = FALSE` argument.


`pull_table()` converts "." and "..", apparently denoting missing values, to NA-s, and filters out some summary rows, generally coded by "0"-s, to reduce table size in attempt to avoid hitting size limit of POST request.
Otherwise, variables and their names are not modified, as prepended dots ".", ".." to the variable names indicate their hierarchy.
It's strongly advisable to compare downloaded table to the table available on the TAI website.

Package interacts with pxweb API at TAI. 
There is also official pxweb API package [rOpenGov/pxweb](https://github.com/rOpenGov/pxweb) allowing interactive browsing through databases.

## Installation
Install package from GitHub:
``` r
devtools::install_github("tpall/boulder")
```

## Usage
Parse data from __json__ file manually downloaded from [Estonian Health Statistics Database](http://pxweb.tai.ee/PXWeb2015/index_en.html) into a data frame.

```{r}
library(boulder)
path_to_PK10.json <- system.file("extdata", "PK10.json", package = "boulder", mustWork = TRUE)
pk10 <- json_to_df(path_to_PK10.json)
```

Download table "RK01" from database:
```{r}
# load library
library(boulder)

# check available tables
tabs <- get_all_tables(lang = "en")
tabs

# dowload table of interest
rk01 <- pull_table("RK01", lang = "en")
rk01

# look at the table title and date of last update
comment(rk01)
```