added vignettes

.gitignore

@@ -2,3 +2,4 @@
 .Rhistory
 .RData
 .Ruserdata
+inst/doc

DESCRIPTION

@@ -11,10 +11,13 @@ License: MIT + file LICENSE
 Imports:
     plotrix
 Suggests:
+    knitr,
+    rmarkdown,
     testthat (>= 3.0.0),
     viridis
 URL: https://github.com/BenSt099/circlesplot
 BugReports: https://github.com/BenSt099/circlesplot/issues
 Encoding: UTF-8
 RoxygenNote: 7.3.1
 Config/testthat/edition: 3
+VignetteBuilder: knitr

R/circlesplot.R

@@ -112,7 +112,7 @@ circlesplot <- function(cp_vals=NULL, cp_text=NULL, cp_max=10L, cp_line_width=2L
       stop("[Error][circlesplot][Error in Parameter(s)]: Vector 'cp_color' should have same length as 'cp_vals'!")
     }
   }
-  if (!inherits(cp_title_size, "numeric") || !inherits(cp_title_size, "integer")) {
+  if (!inherits(cp_title_size, "numeric") && !inherits(cp_title_size, "integer")) {
     stop("[Error][circlesplot][Error in Parameter(s)]: Parameter 'cp_title_size' should be numeric / integer!")
   }
   if (cp_title_size < 1) {

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/cp_vignette.Rmd

@@ -0,0 +1,126 @@
+---
+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*:
+
+```
+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.:
+
+```
+circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=viridis(8), cp_title="Planets", cp_title_size=4)
+```
+
+**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.
+
+
+### Circles
+
+You can modify the line width / thickness of the circles with the *cp_line_width* parameter: 
+
+```
+circlesplot(cp_vals=diameter, cp_text=planets, cp_max=4L, cp_color=viridis(8), cp_title="Planets", cp_title_size=2, cp_line_width=3L)
+```
+
+**NOTE**: The *cp_line_width* parameter is optional. If you leave it blank, it will be set to 2L.
+
+
+### Result
+
+The final plot would look like this:
+
+![final plot, png-format](./vign_1.png){width=600}
+
+
+### 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.
+
+
+## Help
+
+If you need help or want to report an issue, request a new feature, please visit [Github](https://github.com/BenSt099/circlesplot).