README.Rmd

---
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%"
)
```

# pipaux

<!-- badges: start -->
[![R-CMD-check](https://github.com/PIP-Technical-Team/pipaux/workflows/R-CMD-check/badge.svg)](https://github.com/PIP-Technical-Team/pipaux/actions?workflow=R-CMD-check)
<!-- badges: end -->

`pipaux` manages the auxiliary data used in the PIP workflow. It basically
does two things. [1] It updates the auxiliary data and makes sure to keep 
it unchanged when it the raw data has not been modified. [2] it loads the 
data into memory.

## Installation

You can install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("PIP-Technical-Team/pipaux")
```

```{r, include = FALSE}

last_item <- function(x, word = "and") {
  if (!(is.character(x))) {
    warning("`x` must be character. coercing to character")
    x <- as.character(x)
  }

  lx <- length(x)
  if (lx == 1) {
    y <- x
  }
  else if (lx == 2) {
    y <- paste(x[1], word, x[2])
  }
  else {
    y <- c(x[1:lx-1], paste(word, x[lx]))
    y <- paste(y, collapse = ", ")
  }
  return(y)
}


```

```{r setup}
library(pipaux)
```

```{r numb-func, include = FALSE}
lf <- lsf.str("package:pipaux", pattern = "^pip_")
  lf <- as.character(lf)
  num_functions <- length(lf)
```

Even though `pipaux` has more than `r num_functions` functions, most of its features 
can be executed by only using functions `pipaux::load_aux` and `pipaux::update_aux`, which wrappers of other measure-specific functions. 

## Loading data

```{r functions-av, include = FALSE}
  lf <- lsf.str("package:pipaux", pattern = "^pip_[a-z]{3}$")
  lf <- as.character(lf)
  lf <- gsub("pip_", "", lf)
```

Loading auxiliary data can be done using the function `pipaux::load_aux`, whose 
first argument is the name of the `measure` to be loaded. The measures available
are **`r last_item(lf)`**. 

So, loading the `cpi` database could be done by typing, 
`load_aux(measure = "cpi")` or `pip_cpi("load")`. 

```{r equal-load, echo=TRUE}
identical(load_aux(measure = "cpi"), pip_cpi("load"))
identical(load_aux(measure = "ppp"), pip_ppp("load"))
identical(load_aux(measure = "pop"), pip_pop("load"))
```

## Updating data

Updating the auxiliary data in PIP uses the same syntax as loading it. 
Data could be updated using the function `pipaux::load_aux` of any of the measure 
specific functions. Before each version of `pipaux` is released, it is verified whether 
there is any auxiliary database that is not up to date. So, these functions are 
seldom used. 

```{r equal-update, echo=TRUE}
# this, 
update_aux(measure = "cpi")

# is equivalent to this, 
pip_cpi("update")

# And this
update_aux(measure = "ppp")

# is equivalent to this, 
pip_ppp("update")
```

`pipaux` checks whether the hash of each database has changed and updates the data 
in case it has changed. If it has not changed, it notifies the user. The user can 
force the update by using `force = TRUE` as part of the arguments.