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

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

## Introduction

The __circlesplot__ library helps you display proportions between different objects. Say earth is 3.6 times bigger than the moon. How can you visualize that? It would be helpful if you could draw earth and moon with their exact diameter to make your readers aware of the difference in size. This is where the lib comes into play. It plots two circles with the given diameter next to each other, so readers can observe the ratio. Although it is extremely helpful to visualize planets, it can also be used for other things too.

The first step to visualize proportions will be to include the library:

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

## Usage

### Basic plotting

To actually plot something, we need some data and associated labels. Note that both vectors are required and should have the same size.

```r
diameter = c(4879.4,12103.6,12756.3,6792.4,142984,120536,51118,49528)
planets = c('Mercury','Venus','Earth','Mars','Jupiter','Saturn','Uranus','Neptune')
```

Now we can plot it:

```r
circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L)
```

### Further adjustments

The *cp_max* parameter is an integer that should be at least 1. It specifies how many circles or planets should be in a row.
A *cp_max=3L* with 8 planets would result in a plot with circles arranged like:

```
A B C
D E F
G H
```

A *cp_max=4L* with 8 planets would result in a plot with circles arranged like:

```
A B C D
E F G H
```

**NOTE**: The *cp_max* parameter is optional. If you leave it blank, it will set the default number of circles in a row to **10**.


### Color

Now we want to add some color. This can be done via the *cp_color* parameter. You specify colors like this:

```r
colors = c('#D1BBD7', '#AE76A3', '#882E72', '#1965B0', '#5289C7', '#7BAFDE', '#4EB265', '#90C987')
circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=colors)
```

If you want to use a special color scheme like *viridis*, you have to include the package

```r
library(viridis)
```

and set the parameter *cp_color*:

```r
circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=viridis(8))
```

**NOTE**: Every circle has to have a color. So the color-vector has to have the same length as the vectors *diameter* and *planets*. 

**NOTE**: The *cp_color* parameter is optional. If you leave it blank, it will set all colors to white (#FFFFFF).

### Title

The title can be set via *cp_title*. To increase the size of the title, use *cp_title_size*, e.g.:

```r
circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=viridis(8), cp_title="Planets", cp_title_size=2)
```

**NOTE**: Both parameters are optional. If you leave them blank, *cp_title* will be left blank and *cp_title_size* will be set to 1.5.

### Order

If you want to automatically order your results, you can set the *cp_sort*-parameter. Per default, it is set to 'none'.
But you can also set it to 'asc' (ascending) or 'desc' (descending):

```r
circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=viridis(8), cp_title="Planets", cp_title_size=2, cp_sort='desc')
```


### Circles

You can modify the line width / thickness of the circles with the *cp_line_width* parameter: 

```r
circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=viridis(8), cp_title="Planets", cp_title_size=2, cp_sort='desc', cp_line_width=3L)
```

**NOTE**: The *cp_line_width* parameter is optional. If you leave it blank, it will be set to 2L.


### Tight Spacing

As you can see in the final [Result](#Result), the spacing between rows is set optimistically. If you want a tighter layout, you can use the parameter *cp_tight_spacing*.
It is a (numeric) number between 1.0 and 2.0. A spacing of _1.0_ will maintain the current graph spacing. A spacing of _2.0_ will result in a very tight layout.

```
circlesplot(..., cp_tight_spacing=1.3)
```

### Shapes

The default plot consists of circles. If you want, you can also set the parameter *cp_shape* to _'square'_ to draw squares instead of circles.

```
circlesplot(..., cp_shape='squares')
```

### Result

The final plot would look like this:

![final plot, pdf-format](./vign_1.png){width=400}

### Return value

The *circlesplot*-function returns a recordedPlot-object. Therefore, you can save a plot to a variable and later plot the circlesplot:

```r
cp <- circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=viridis(8), cp_title="Planets", cp_title_size=2.5, cp_sort='desc', cp_line_width=3L)
# ...
cp
```


### Exporting

You may observe that the output in *RStudio* lacks some quality, especially the rounding of the circles. If you export it as *png-file*, it will stay like that. The recommendation is to export the plot as a *pdf-file* which has better quality. 

**ATTENTION**:
You may see something unexpected in *RStudio*: When you create the plot and it is displayed in the lower right window (in the plots tab), it seems like that a part of the plot is cut off but this happens only due to the size of the lower right window. Either resize it or use the following *R*-code to save the plot as *pdf*:

```r
pdf("path/to/your/pdf/plot1.pdf")
circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=viridis(8), cp_title="Planets", cp_sort='desc')
dev.off() 
```


## Help

If you need help, want to report an issue or request a new feature, please visit [Github](https://github.com/BenSt099/circlesplot).