README.Rmd

---
  output: github_document
  always_allow_html: true
---


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

# Multilateral <img src='man/figures/logo-v2.png' align="right" height="139" />

  <!-- badges: start -->

  [![R build status](https://github.com/MjStansfi/multilateral/workflows/R-CMD-check/badge.svg)](https://github.com/MjStansfi/multilateral/actions)
  
  [![CRAN](https://www.r-pkg.org/badges/version/multilateral)](https://www.r-pkg.org/badges/version/multilateral)

  <!-- badges: end -->

## Overview

The multilateral package provides one key function, that is `multilateral()`.
The user provides the necessary attributes of a dataset to calculate their choice of multilateral methods.

See [vignette](https://htmlpreview.github.io/?https://github.com/MjStansfi/multilateral/blob/main/doc/multilateral.html) for further information.

For some specific index calculation methods this package has been heavily influenced by Graham White's [IndexNumR package](https://github.com/grahamjwhite/IndexNumR). 



## Installation

```{r, eval = FALSE}
devtools::install_github("MjStansfi/multilateral")

library(multilateral)
```

## Usage

See bottom for all index and splice methods.

```{r example,echo=TRUE,warning=FALSE,message=FALSE,error=FALSE, results='hide',fig.keep='all'}
library(multilateral)
library(ggplot2)

tpd_index <- multilateral(period = turvey$month,
                          id = turvey$commodity,
                          price = turvey$price,
                          quantity = turvey$quantity,
                          splice_method = "geomean",
                          window_length = 13,
                          index_method = "TPD")

plot <- ggplot(tpd_index$index)+geom_line(aes(x = period, y = index))+theme_bw()

print(plot)

```

## Further detail

The function returns a list object containing 

* `index`: the continuous spliced index,
* `index_windows`: each individual window's index,
* `splice_detail`: splicing information.

```{r further-detail}
str(tpd_index) 
```

The `index_windows` returns all individual windows indexes before they were spliced. Below shows how you could (roughly) visualise this data
```{r windows}
library(dplyr)

#Get splice details to relevel each new index
update_factor <- tpd_index$splice_detail%>%
  mutate(update_factor  = cumprod(update_factor))%>%
  select(window_id, update_factor)


index_windows <- merge(tpd_index$index_windows,update_factor)

index_windows <-index_windows%>%mutate(updated_index = index*update_factor)
windows_plot <- ggplot(index_windows)+
  geom_line(aes(x = period, y = updated_index, group = window_id, colour = window_id))+
  theme_bw()

print(windows_plot)
```

`splice_detail` gives the user a break down of how the given periods index number is made up of both a 'revision factor' (from splicing) and the latest periods movement. This can be useful for diagnostics. 
```{r splice_detail}
head(tpd_index$splice_detail)
```

Below shows one way in which you could visualise contribution of revision factor verses the latest movement.
```{r visualise-contrib, message=FALSE}
library(dplyr)

#Period of interest
splice_detail <- tpd_index$splice_detail[period=="1973-02-28"]

#Log information to determine contribution
lwm_log <- log(splice_detail$latest_window_movement)
rf_log <- log(splice_detail$revision_factor)
sum_log <- sum(lwm_log+rf_log)

lwm_contrib <- lwm_log/sum_log
rf_contrib <- rf_log/sum_log


ggplot(mapping = aes(fill=c("Latest movement","Revision factor"),
                     y=c(lwm_contrib,rf_contrib),
                     x="1973-02-28"))+
  geom_bar(position="stack", stat="identity", width = 0.2)+
  theme_bw()+
  xlab("Date")+
  ylab("% Contribution")+
  labs(fill = "Contributor")+
  scale_fill_manual(values = c("#085c75","#d2ac2f"))


```

## Options

See [vignette](https://htmlpreview.github.io/?https://github.com/MjStansfi/multilateral/blob/main/doc/multilateral.html) for further information.

```{r table-summary, echo=FALSE, message=FALSE, warning=FALSE}
#Could re do this by method
library(dplyr)
library(kableExtra)
index_method_config <- yaml::read_yaml(system.file("config","index_method_config.yaml", package = "multilateral"))
splice_method_config <- yaml::read_yaml(system.file("config","splice_method_config.yaml", package = "multilateral"))
chain_method_config <- yaml::read_yaml(system.file("config","chain_method_config.yaml", package = "multilateral"))


methods <- names(index_method_config)
summary <- lapply(methods,function(x){index_method_config[[x]]})
summary <- data.table::rbindlist(summary)
summary[,description:=NULL]
summary$Method <- methods

colnames(summary) <- c("Name","Requires ID","Requires Features","Requires Quantity","Requires Weight","Can Restrict to Matched Sample","Method")

summary <- summary[,c("Method","Name","Requires ID","Requires Features","Requires Quantity","Requires Weight","Can Restrict to Matched Sample")]

knitr::kable(summary) %>%
  kableExtra::kable_styling(font_size = 12)
knitr::kable(as.data.frame(splice_method_config)) 
knitr::kable(as.data.frame(chain_method_config)) 
```