---
title: "Get started with esquisse"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{get-started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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


<style>
img {
  max-width: 700px;
}
</style>



## Launch the addin

In RStudio, you can use the *Addins* menu : 

![](figures/launch-addin.png)


Or in the R console :

```{r}
esquisser()
```


To use a `data.frame` by default, if using the *Addins* menu highlight with the cursor a `data.frame` in source editor before launching addin.
Otherwise, pass the `data.frame` as first argument to the function :

```{r}
esquisser(mtcars)
```



## Import data into {esquisse}

If you don't have used a `data.frame` when launching the addin, a window to import data will appear.

This feature comes from package [{datamods}](https://github.com/dreamRs/datamods), you can find more documentation about it [here](https://dreamrs.github.io/datamods/articles/datamods.html).

![](figures/import-data.png)


## Create a plot

This is the main interface and the most interesting part of the addin (in example below, we use `penguins` dataset from [{palmerpenguins}](https://github.com/allisonhorst/palmerpenguins)) :

![](figures/esquisse.png)

You can select aesthetics to used by clicking the gear icon in top right corner, then drag-and-drop into aesthetics boxes to create a plot: 

![](figures/aesthetics.png)


A `geometry` is automatically picked to represent the data, according to data type. You can select an other `geom` with button in top right corner : 

![](figures/geometries.png)



## Controls

Five menus under plot area are available to set plot parameters, filter data and retrieve code to generate the plot.


### Labels & titles

This menu allow to set plot's title, subtitle, caption, axis and aesthetics labels :

![](figures/controls-labels.png)


### Plot options

Here you can modify plot parameters, options available in the menu depends on type of plot :

![](figures/controls-plot-options.png)


### Appearance

Here you can modify colors used and global theme :

![](figures/controls-appearance.png)



### Filter

Widgets to interactively filter data used in plot : 

![](figures/controls-filters.png)

The filter module is available in package [{datamods}](https://dreamrs.github.io/datamods/articles/datamods.html#filter).

The code used to filter the data will be available in the following menu.


### Code

In this menu, you can retrieve the code used to produce the plot, as well as the code used to filter the data.

![](figures/controls-code.png)

You can copy code to clipboard, or insert it in your current script.


## Export

You can save the plot created in various format by clicking the button in plot area's top-right corner:

![](figures/export.png)

With "More options", you can access a new window with more parameters to export the plot:

![](figures/export-options.png)



## Addin options

By default, esquisse is launched into a dialog window (if in RStudio), you can choose to use your browser if you prefer, or the Viewer pane.

```{r}
esquisser(viewer = "browser")
esquisser(viewer = "pane")
```


You can set display mode with an option (in .Rprofile for example) :

```{r}
options("esquisse.viewer" = "browser")
```



### Internationalization

Currently you can use {esquisse} in the following language: <img src="figures/i18n/gb.svg" height="16"/> english (default), <img src="figures/i18n/fr.svg" height="16"/> french (`"fr"`), <img src="figures/i18n/mk.svg" height="16"/> macedonian (`"mk"`), <img src="figures/i18n/al.svg" height="16"/> albanian (`"sq"`). Activate with:

```{r}
library(esquisse)
set_i18n("fr")
esquisser()
```

If you want another language to be supported, you can submit a Pull Request to add a CSV file like the one used for french (file is located in `inst/i18n` folder in the package, you can see it [here on GitHub](https://github.com/dreamRs/esquisse/blob/master/inst/i18n/fr.csv)).

See [{datamods} vignette](https://dreamrs.github.io/datamods/articles/i18n.html) for more on this topic.