---
title: "Choosing conversion factors"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Choosing conversion factors}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## The `source` argument

Use the `source` argument in `convertGDP` to control the source of the underlying conversion factors (GDP deflators, MERs and PPPs). This can be one of the sources shipped with the package or a user-defined object.

### Package internal 'sources'

There are two `source` options shipped with the package, `wb_wdi` and `wb_wdi_linked`, **with `wb_wdi` set as the default**. Pass the name of a shipped source to the source argument to use it.

```{r}
library(GDPuc)

my_gdp <- tibble::tibble(
  iso3c = "USA", 
  year = 2010:2014, 
  value = 100:104
)

convertGDP(
  gdp = my_gdp, 
  unit_in = "constant 2010 LCU", 
  unit_out = "constant 2014 Int$PPP",
  source = "wb_wdi_linked",
  verbose = TRUE
)
```

Use the function `print_source_info` to print information on a specific, or all available sources.

```{r}
print_source_info("wb_wdi")
print_source_info()
```

Use the `:::` operator to take a closer look at sources shipped with GDPuc.

```{r, eval=FALSE}
GDPuc:::wb_wdi
```

###  User-defined 'source' objects

Any tibble with columns:

-   "iso3c" (character),
-   "year" (numeric),
-   "GDP deflator" (numeric),
-   "MER (LCU per US$)" (numeric),
-   "PPP conversion factor, GDP (LCU per international $)" (numeric)

can be used as a source of conversion factors.

```{r}
my_custom_source <- tibble::tibble(
  iso3c = "USA", 
  year = 2010:2014, 
  "GDP deflator" = seq(1, 1.1, 0.025),
  "MER (LCU per US$)" = 1,
  "PPP conversion factor, GDP (LCU per international $)" = 1,
)
print(my_custom_source)

convertGDP(
  gdp = my_gdp, 
  unit_in = "constant 2010 LCU", 
  unit_out = "constant 2014 Int$PPP",
  source = my_custom_source,
  verbose = TRUE
)
```

## The `use_USA_cf_for_all` argument

In some cases it may be desirable to use the US conversion factors for all countries. For instance, when converting global scenario data from modelling efforts, in US$MER, to another base year. Setting the `use_USA_cf_for_all` to `TRUE` ensures that all countries are converted with the US conversion factors. 

```{r}
my_gdp <- tibble::tibble(
  iso3c = c("USA", "IND"), 
  value = 100
)

# Normal conversion, with country specific conversion factors
convertGDP(
  gdp = my_gdp, 
  unit_in = "constant 2005 US$MER", 
  unit_out = "constant 2020 US$MER",
  verbose = TRUE
)

# Using the US conversion factors for both countries
convertGDP(
  gdp = my_gdp, 
  unit_in = "constant 2005 US$MER", 
  unit_out = "constant 2020 US$MER",
  use_USA_cf_for_all = TRUE,
  verbose = TRUE
)
```