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

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

## The `replace_NAs` argument

Use the `replace_NAs` argument in `convertGDP` to handle missing conversion factors.  

### `replace_NAs` = NULL or NA  
 
By default, `replace_NAs` is `NULL`, and NAs are returned along with a warning.
Set `replace_NAs = NA` to explicitly return NAs without the warning.  

Below, the `return_cfs` argument is set to `TRUE` to inspect the conversion factors, along side the result.


```{r}
library(GDPuc)

# Test with Venezuela -> iso3c = VEN
my_gdp <- tibble::tibble(
  iso3c = c("VEN"),
  year = 2010:2014,
  value = 100:104
)

x <- convertGDP(
  gdp = my_gdp,
  unit_in = "constant 2005 Int$PPP",
  unit_out = "constant 2019 Int$PPP",
  return_cfs = TRUE
)
x$result

x$cfs
```
To eliminate the warning:
```{r}
x <- convertGDP(
  gdp = my_gdp, 
  unit_in = "constant 2005 Int$PPP", 
  unit_out = "constant 2019 Int$PPP",
  replace_NAs = NA
)
```

You can also use the `GDPuc.warn` option to suppress warnings from `convertGDP` in general (see ["Silence warnings"](https://pik-piam.github.io/GDPuc/articles/warn.html)).

### `replace_NAs` = 0  

If set to 0, resulting NAs are set to 0.

```{r}
my_gdp <- tibble::tibble(
  iso3c = "VEN",
  year = 2010:2014,
  value = 100:104
)

x <- convertGDP(
  gdp = my_gdp,
  unit_in = "constant 2005 Int$PPP",
  unit_out = "constant 2019 Int$PPP",
  replace_NAs = 0,
  return_cfs = TRUE
)
x$result

x$cfs
```


### `replace_NAs` = "no_conversion"  

If set to "no_conversion", NAs are replaced with the values in the gdp argument.

```{r}
my_gdp <- tibble::tibble(
  iso3c = "VEN",
  year = 2010:2014,
  value = 100:104
)

x <- convertGDP(
  gdp = my_gdp,
  unit_in = "constant 2005 Int$PPP",
  unit_out = "constant 2019 Int$PPP",
  replace_NAs = "no_conversion",
  return_cfs = TRUE
)
x$result

x$cfs
```


### `replace_NAs` = "linear"

If set to "linear", missing conversion factors are inter- and extrapolated linearly. For the extrapolation, the closest 5 data points are used.

```{r}
my_gdp <- tibble::tibble(
  iso3c = "VEN",
  year = 2010:2014,
  value = 100:104
)

x <- convertGDP(
  gdp = my_gdp,
  unit_in = "constant 2005 Int$PPP",
  unit_out = "constant 2019 Int$PPP",
  replace_NAs = "linear",
  return_cfs = TRUE
)
x$result

x$cfs
```

### `replace_NAs` = "regional_average"

If set to "regional_average", the regional GDP-weighted averages will be used. Requires a region-mapping, and a column in the source object with GDP data at PPP, to be used as weight. **May lead to misleading results, use with care!**

```{r}
my_gdp <- tibble::tibble(
  iso3c = "VEN",
  year = 2010:2014,
  value = 100:104
)

my_mapping_data_frame <- tibble::tibble(
  iso3c = c("VEN", "BRA", "ARG", "COL"),
  region = "LAM"
)

x <- convertGDP(
  gdp = my_gdp,
  unit_in = "constant 2005 Int$PPP",
  unit_out = "constant 2019 Int$PPP",
  replace_NAs = "regional_average",
  with_regions = my_mapping_data_frame,
  return_cfs = TRUE
)
x$result

x$cfs

# Compare the 2019 PPP with the 2005 PPP. They are not in the same order of magnitude. 
# Obviously, being a part of the same region, does not mean the currencies are of the same strength.
```

### `replace_NAs` = c("linear", "...")

If a vector is passed, with "linear" as first element, then the operations are done in sequence. 
For example for c("linear", 0), missing conversion factors are first inter- and extrapolated linearly but 
if any missing conversion factors still lead to NAs, these are replaced with 0.

```{r}
# Create an imaginary country XXX, and add it to the Latin America region
my_gdp <- tibble::tibble(
  iso3c = c("VEN", "XXX"),
  year = 2010,
  value = 100
)

my_mapping_data_frame <- tibble::tibble(
  iso3c = c("VEN", "BRA", "ARG", "COL", "XXX"),
  region = "LAM"
)

x <- convertGDP(
  gdp = my_gdp,
  unit_in = "constant 2005 Int$PPP",
  unit_out = "constant 2019 Int$PPP",
  replace_NAs = c("linear", 0),
  with_regions = my_mapping_data_frame,
  return_cfs = TRUE
)
x$result

x$cfs
```

### Deprecated: `replace_NAs` = 1

If set to `1`, missing conversion factors are set to 1. **To be deprecated, use with care!**

```{r}
my_gdp <- tibble::tibble(
  iso3c = "VEN",
  year = 2010:2014,
  value = 100:104
)

x <- convertGDP(
  gdp = my_gdp,
  unit_in = "constant 2005 Int$PPP",
  unit_out = "constant 2019 Int$PPP",
  replace_NAs = 1,
  return_cfs = TRUE
)
x$result

x$cfs

# Why is the deflator above not 1? That is because for VEN, only the deflator value in 2019 was set to 1. 
# In 2005 the deflator was in the order of magnitude of 100. Obviously setting the deflator to 1 in 2019 is 
# completely misleading.
```