---
title: "ggsolvencyii"
author: "Marco van Zanden"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{ggsolvencyii}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
<!-- md_document: markdown_strict -->
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r,init,echo=FALSE,results=FALSE,warnings=FALSE,message=FALSE}
knitr::opts_chunk$set(collapse=TRUE,comment="#>",fig.path="z_ggsolvencyii-")
library(ggplot2)
library(ggsolvencyii)
```


```{r,logo, out.width='25%', fig.align='right', echo=FALSE, border = FALSE}
knitr::include_graphics('images/logo_engels_rvignettes.png')
```
The goal of ggsolvencyii is to provide 'ggplot2'-geom's to show the composition of the Solvency (II) Capital Requirement (SCR) from (diversified) risks and subrisks, whether for standard formula (SF) or (partial) intern models (IM/PIM).





## Installation

You can install ggsolvencyii from Github:

```{r github-installation, eval = FALSE}
# install.packages("devtools", "dplyr" , "magrittr")
devtools::install_github("vanzanden/ggsolvencyii")
# or from the binary in github.com/vanzanden/ggsolvencyii/binaries/windows
```

## Vignettes
The following vignettes are available or will be available soon 
check https://github.com/vanzanden/ggsolvencyii/tree/master/vignettes

* ggsolvencyii (this vignette)
* plotdetails 
* showcase
* coding_overview 

## example

ggsolvencyii builds on ggplot-functionality and provides three geom's: 
* `geom_sii_risksurface` 
* `geom_sii_riskoutline`
* `geom_sii_riskconnection`

These were used to produce the following plot which for example could be used for an ORSA report. 

the complete annotated code for the first figure is shown in vignette 'showcase'. A further elaboration on the inner workings of the package and the use of parameter-values and tables can be found in vignette "coding overview'.

```{r, showcase, echo=FALSE, results = 'hide' }
      ## the original dataset has three three-year scenarios, 
      ## only two years of two branches are used here 
        testdata <- sii_z_ex1_data[sii_z_ex1_data$id <= 7,]
        testdata <- testdata[testdata$time <= 2018,]

      ## printing SCR values and interdependency of 'id' and 'comparewithid'
        testdata[testdata$description == "SCR", ]
```

```{r, showcase2, echo=FALSE, fig.asp = 0.7, fig.width=7 }
## horizontalscaling to get round circles is depending on the dimensions of the canvas. 
## automated scaling to canvas size is on the to do list.
  horizontalscaling = .22 

ggplot2::ggplot() +
##  a plain vanilla plot of one SCR buildup, the 'current situation': 
  geom_sii_risksurface(data = testdata[testdata$id == 1, ], 
        mapping = ggplot2::aes(x = time, 
                               y = ratio,
                               ## x and y could for example also be 
                               ## longitude and latitude 
                               ## in combination with plotted map
                               value = value, 
                               id = id, 
                               description = description, 
                               fill = description, ## optional
                               color = description  ## optional
                               ),
            ## all parameters are shown here, 
            ## the values behind the outcommented are the default values
              ## how and what
                ## structure = sii_structure_sf16_eng,
                ## plotdetails = NULL,
              ## grouping
                # levelmax = 99, 
                # aggregatesuffix = "other",
              ## scaling
                ## since the data in this geom is only a subset 
                ## of 'testdata' manual scaling is needed
                ## each geom_sii_risksurface and geom_sii_riskoutline
                ## call returns the calculated (or given) maximum in an
                ## outputmessage
                maxscrvalue =  25.7433642812936,
                scalingx = horizontalscaling, 
                # scalingy = 1,
              ## rotation and squared
                # rotationdegrees = NULL,
                # rotationdescription = NULL, 
                # squared = FALSE,
              ## cosmetic
                lwd = 0.25,
                # alpha = 1
        ) +
  
  ggplot2::theme_bw() +

## Combining several geom-calls might result in unexpected ordering of the legends
## It can help to plot the dataset which results in the most individual risks first.  
  ggplot2::scale_fill_manual(name = "risks", values = sii_z_ex1_fillcolors) +
  
  ggplot2::scale_color_manual(name = "risks", values = sii_z_ex1_edgecolors) +

## a second instance of geom_sii_risksurface, all data (1+2*2 id's) is used
## by using a plotdetails dataframe not all calculated circle segments are plotted
  geom_sii_risksurface(data = testdata, 
          mapping = aes(x = time,y = ratio,value = value,  id = id, 
                                 description = description, 
                                 fill = description, color = description
                                 ),
  ## two plotdetailstables are used for this showcase: 
  ## this one indicates that only levels 1-3 are plotted in geom_sii_risksurface
  ## sii_z_ex1_plotdetails2 indicates only levels 4.xx and 5.xx are plotted
  ## this dataset has only 4.01, 4.02 levels present (market- and life subrisks )
      plotdetails = sii_z_ex1_plotdetails,
      scalingx = horizontalscaling, 
      lwd = 0.25,
      alpha = 1.0
  ) +

## this third instance of geom_sii_risksurface plots only the levels 4.01 and 4.02
## by using the other plotdetails dataframe.  
## A small alpha has the effect that these levels are less obtrusive, 
## giving a overview of SCR results, but still showing all information
## 'color is NA', in the options means it does only plot the surface of the polygons.
## (geom_polygon is the basis for the actual plotting),
  geom_sii_risksurface(data = testdata,
              mapping = ggplot2::aes(x = time, y = ratio, value = value,  id = id, 
                                     description = description, 
                                     fill = description #,
                                     ## outcommenting here is not enough to prevent
                                     ## outlines to be plotted ...
                                     # color = description
                                     ),
        plotdetails = sii_z_ex1_plotdetails2,
        scalingx = horizontalscaling, 
        alpha = 0.15,
      ## ... explicit no (edge)coloring is neccesary
        color = NA
        ) +
## Arrows are plotted to connect 'id' and 'comparewithid' combinations. 
## This helps in understanding the outlines of the following geom_sii_riskoutline call  
  geom_sii_riskconnection(data = testdata, 
                mapping = aes(x = time, y = ratio, id = id,
                    ## for geom_sii_riskconnection comparewithid is a required aesthetic.
                    ## (this is is not the case for geom_sii_riskoutline)
                      comparewithid = comparewithid ), 
                arrow = ggplot2::arrow(angle = 10, type = "open" ), 
                alpha = 0.15
                ) +
  
## geoms_sii_riskoutline uses other columns in plotdetails than geoms_sii_risksurface
## for each line segment for each defined description or level plotting can be
## switched on or off.
## a risk-partition (apart from the full circle SCR) has four outline segments. 
## two radii and an inner and outer circle segment.
## sii_z_ex1_plotdetails defines only the outer circle segments ('outline2') to be plotted
## for levels 1, 4.01 and 4.02 AND for the indivual risks operational and cp-default.
## these individual risks are on level 2 and 3 but have no subrisks.
  geom_sii_riskoutline(data = testdata, 
          mapping = aes(x = time, y = ratio, value = value,  id = id, 
                                 description = description, 
                                 comparewithid = comparewithid,
                        ),
    ## only sii_z_ex1_plotdetails is used with the outline-geom.
      plotdetails = sii_z_ex1_plotdetails,
      scalingx = horizontalscaling, 
      color = "red",
      lwd = 0.25,
      alpha = 0.6,
) 

## cleanup ============================================================== =====
rm(testdata) ; rm(horizontalscaling)
## ====================================================================== =====
```

The total surface (to the center point of each circle) of the outer segments show the size of undiversified risks. Diversification is made visible by the difference between the risk segment and the next segment nearer to the center of the plot. The red (out)lines are displayed for comparison with the previous SCR buildup. 


For troubleshooting `sii_debug_geom` provides an overview of present risk descriptions and levels in the data and supporting tables. 
  
```{r, debug, echo=FALSE, eval = FALSE}
t <- sii_debug_geom(data_descr = sii_z_ex1_data$description,structure = sii_structure_sf16_eng,aggregatesuffix = "other", levelmax = sii_levelmax_sf16_995,plotdetails = sii_z_ex1_plotdetails, fillcolors = sii_z_ex1_fillcolors, edgecolors = sii_z_ex1_edgecolors)    
knitr::kable(t$debug_description[37:45,])
knitr::kable(rbind(t$debug_level[1:13,],tail(t$debug_level,2)))
```

## Base plot and options

### base
An life insurer reports its solvency ratio following Standard Formula rules, with English names for all risks. It has a set of risks, diversification effects, and accumulations to the SCR for the current situation ('id'=1) and three three-year ORSA scenarios ('id' is 2-4, 5-7, 8-10). The results are stored in a datafile of which the first lines and columns are shown here: 
```{r origdata, echo = FALSE}
t <- tidyr::spread(data = sii_z_ex1_data, key = description, value = value)
t <- as.data.frame(t)
t <- t[order(t$id),]
t <- dplyr::select( t, id, time, comparewithid, ratio, SCR, dplyr::everything())
t <- t[1:3 ,1:8]
knitr::kable(x = t)
```

Variable sii_z_ex1_data is the tidyverse representation of the dataset above (the first lines for 'id' = 1, 2 or 3 are shown). 

```{r tidyversedata, echo = FALSE}
t <- sii_z_ex1_data[sii_z_ex1_data$id <= 3,]
t <- t[1:8 ,]
knitr::kable(x = t)
```

Variables sii_x_fillcolors... and sii_x_edgecolors are named lists with colorcodes for each risk-description
```{r colorlist, echo = FALSE}
t <- sii_x_fillcolors_sf16_eng
knitr::kable(head(t))
```

The SCR composition of the current situation (id = 1) is shown below

```{r example1,  warning = FALSE,fig.asp = 0.7, fig.width=5}
ggplot() +
  geom_sii_risksurface(
    data = sii_z_ex1_data[sii_z_ex1_data$id == 1, ],
    mapping = aes(x = time, 
                  y = ratio, 
                  id = id, 
                  value = value, 
                  description = description, 
                  color = description,
                  fill = description
                   ) ) +
theme_bw() +
scale_fill_manual(name = "Risks",values = sii_x_fillcolors_sf16_eng) +
scale_color_manual(name = "Risks",values = sii_x_edgecolors_sf16_eng)

```


### structure

`Geom_sii_risksurface` uses one default table for this plot `sii_structure_sf16_eng`. It defines each risks by indicating from which combined 'child'-risks and diversification (suffix 'd') it is made up. Passing another structure table makes this geom usable for localisation or for internal models. 


```{r structuretext, eval = FALSE}
head(sii_structure_sf16_eng, 13)
```

```{r structure, echo = FALSE}
knitr::kable(head(sii_structure_sf16_eng,15))
```

### levelmax
To prevent cluttering of the legend it is possible to group the smallest items of a level by providing a levelmax-table in such a way that the indicated maximum items in that level is not exceeded. the example is on another dataset `sii_z_ex2_data`, with only one SCR result. 
```{r levelmaxtext, eval = FALSE}
sii_levelmax_sf16_993
```

```{r levelmax, echo=FALSE }
knitr::kable(sii_levelmax_sf16_993)
```

```{r examplelevelmax,  warning = FALSE, message = FALSE,fig.asp = 0.7, fig.width=5}
ggplot() +
  geom_sii_risksurface(
    data = sii_z_ex2_data,
    mapping = aes(x = time, y = ratio, id = id, value = value, 
                  description = description, 
                  # color = description,
                  fill = description  
                  ),
    color = "black",
    levelmax = sii_levelmax_sf16_993) +
theme_bw() +
scale_fill_manual(name = "Risks",values = sii_x_fillcolors_sf16_eng) # +
# scale_color_manual(name = "Risks",values = sii_x_edgecolors_sf16_eng)

```

### Rotation and squared 

Rotationdescription rotates the plot in such a way that the indicated item (can be on either level, i.e. works also on 'life' or 'operational') is plotted on just on the righthandside of '12 o'clock'. rotationdegrees is then added.

The option squared makes a square plot, with the surface of all segments still in proportion. The angle between the 'radial'lines of equal sized segments differ, based on the position of the segment. 
```{r rotationsquare, warning = FALSE, message = FALSE,fig.asp = 0.7, fig.width=5}
ggplot() +
  geom_sii_risksurface(
    data = sii_z_ex2_data,
    mapping = aes(x = time, y = ratio, id = id, value = value, 
                           description = description, 
                           fill = description, color = description),
                  squared = TRUE,
                  rotationdescription = 'm_equity',
                  rotationdegrees = -45) +
theme_bw() +
scale_fill_manual(name = "Risks",values = sii_x_fillcolors_sf16_eng) +
scale_color_manual(name = "Risks",values = sii_x_edgecolors_sf16_eng)
```
The second plot shows a comparison between a circle and square plot of the same data. Note that the radius of the SCR circle is smaller than the size of the SCR square !!

```{r, circlesquare, echo=FALSE, fig.asp = 1, fig.width=3}
## vergelijk grootte van rond en square in een figuur =================== =====

ggplot2::ggplot() +
  geom_sii_risksurface(data = sii_z_ex2_data,
              mapping = ggplot2::aes(x = 10, y = 5 , id = id, value = value
                                     ,description = description
                                    ,fill = description
                                    ,color = description
                                    ),
              # color = NA
              lwd = .75
              ,alpha = 0.6,
              show.legend = FALSE
  ) +
  geom_sii_risksurface(data = sii_z_ex2_data,
              mapping = ggplot2::aes(x = 10, y = 5 , id = id, value = value,
                            description = description
                            ,fill = description
                                        ),
              color = "black",
              lwd = .5,
              squared = TRUE,
              # rotationdegrees = 45,
              alpha = .2,
              show.legend = FALSE
   )
```

### Scaling
all SCR-buildups from a single call to `geom_sii_risksurface` or `geom_sii_riskoutline` plot are by default scaled in such a way that the largest SCR has a plotradius of one. When combining more calls, with several datasets a manual `maxscrvalue`-value can be given as a parameter. To prevent distortion, depending on the scale of x and y axis, `scalingx` and `scalingy` parameters are available.

### Plotdetails
The plotdetails table can be passed as a parameter to `geom_sii_risksurface` and `geom_sii_riskoutline`. It indicates whether to actual plot surfaces or outlinesegments (1 to 4) *after* the composition of the round (or squared) layout of segments. An example is the seperate plotting of inner and outer segments, with different transparancy in the showcase, or only plotting the outline of the SCR itself and the lowest risklevels. See the separate vignette for a detailed explanation.

## Outlines, comparewithid
If the optional aes `comparewithid` is passed to `geom_sii_riskoutline` a link is made between the x and y value of an 'id' and the SCR composition of that SCR buildup where `comparewithid` references to. This can be used to overlay the outline of one SCR over the surfaceplot of another. This for easy comparison between the two. See vignettes "geom_sii_riskoutline" and "geom_sii_riskconnection" for details
