---
title: "How to save plots on your hard drive in IsoriX?"
author: "Alexandre Courtiol, François Rousset & Stephanie Kramer-Schadt"
date: "`r Sys.Date()`"
output:
    pdf_document
vignette: >
  %\VignetteIndexEntry{Saving plot in IsoriX}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, initialization, echo=FALSE}
library(knitr)
set.seed(123)  ## set seed for entire manuscript
# set global options for knitr (if changed, all cashed chunked will be rerun!)
knitr::opts_chunk$set(cache=FALSE)
do.eval <- FALSE ## to check that it does work, put TRUE
```

Welcome to __IsoriX__, in this vignette we present the steps required for you to save your isoscape or assignment maps on your hard drive.

## Before starting

Please read the vignette ___Workflow___, if you haven't done so. You can access it by simply typing:

```{r, workflow, eval=FALSE}
vignette("Workflow", package="IsoriX")
```

We assume that you are still in the same R session than the one created during the simple workflow example. That implies that __IsoriX__ is loaded and that the objects we will use below have already been created.


## Saving IsoriX plots using Cairo

```{r, load isoscape, echo=FALSE, message=FALSE}
library(IsoriX)
load("../vignette_workflow/isoscape.rda")
```

There are many ways to save the plots we created during the workflow example. If you are not new to R you may already know some function to save plots (`pdf()`, `png()`...) that are readily available in R. Unfortunately, we encountered often some little annoying artifacts using these functions, such as white lines in the middle of the isoscape.

Our favorite way to create plots is thus to use the package __Cairo__. So, start by loading this package (after installing the package if you don't have it):

```{r, load Cairo}
library(Cairo)
```

Typing `?Cairo` will show you all possible file formats you can save your plots into (png, jpg, tiff, pdf...). Here we will show how to save our isoscape both as a png and as a pdf.

### Example: saving the isoscape

During the workflow example you have created the following isoscape:
```{r, show isoscape}
isoscape
```

Our goal is to save the plot of this isoscape on the hard drive so we can include it in a paper, poster or presentation. To do so we first store the plot into an R object that we call here `plot.mean.isoscape`:

```{r, make plot}
## we load the objects that are used to decorate the maps
data(worldcountries)
data(oceanmask)
data(isoscapepalette)

## we create the plot (but do not display it)
plot.mean.isoscape <- plot(
    x=isoscape,
    which="mean",
    borders=list(borders=worldcountries),
    mask=list(mask=oceanmask),
    palette=isoscapepalette,
    plot=FALSE
)
```
Note that we used the argument `plot=FALSE` so that the plot does not show up, you can also keep the default setting that will once again display the plot on your screen. It does not make any difference by when you handle many plots, it may be good to know that you don't have to display them (display takes time).

Let us first save this plot as a png file:

```{r, save plot, fig.show="hide", eval=do.eval}
CairoPNG(filename="Myisoscape.png", height=1080, width=1920, res=100)
plot.mean.isoscape
dev.off()
```

So you see, simple isn't it! You first initialize the creation of the plot with the function `CairoPNG()`, then you call your plot, then you tell your computer that you are done with `dev.off()`.

You just need to specify a filename, and the resolution of the file. The height and width are here considered to be in pixels. Here we chose the so-called Full-HD or 1080p resolution (1080x1920) because we wanted to observe the isoscape carefully on a monitor of that resolution. If your screen is Full-HD, try it and display the plot in full screen to get better results (if the plot does not match the definition of your screen, things can get ugly), if your screen is not, try another resolution. If you don't know what resolution your screen has, you can visit (http://www.whatismyscreenresolution.com/).

The parameter `res` is very useful as it rescales the line and fonts in the plot. So if every thing is too small increase the value and if everything looks too bold and ugly, decreases it.

If, like us, you don't indicate the path in the filename. The file will be now in your working directory which you can easily see by typing `getwd()`!

Let us now save this plot as a pdf file:

```{r, save plot2, fig.show="hide", eval=do.eval}
CairoPDF(file="Myisoscape.pdf", height=10, width=15)
plot.mean.isoscape
dev.off()
```

The arguments slightly differ with the function creating pngs. The argument setting the name of the file is now called `file` and not `filename`, the resolution has now to be provided in inches and the argument `res` does not exist for pdfs, but default results are usually fine.


## Saving IsoriX plots without Cairo

If you really don't manage to use __Cairo__ or if you don't want to use it, you can always use the simple out-of-the-box alternative offered by R. You just need to use different function calls:

* `CairoPNG()` --> `png()`

* `CairoPDF()` --> `pdf()`

Nothing else changes, the inputs should be the same and you still need to close the graphic device using `dev.off()` after ploting.


## Troubles with Cairo under MacOS?

One noticeable source of trouble comes with the installation of the package __Cairo__. On MacOS the package __Cairo__ does not always install/load successfully. Problems happen when the program `xquartz` is not present on the system. This program used to be shipped by defaults on old version of MacOS but it is no longer the case. So if you are in trouble, please start by installing [xquartz](https://www.xquartz.org/) outside R.





