---
title: "easyreporting standard usage"
author: "Dario Righelli"
date: "`r Sys.Date()`"
output: 
  BiocStyle::html_document:
    toc: true
vignette: >
  %\VignetteEncoding{UTF-8} 
editor_options: 
  chunk_output_type: console
---

<!--
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{easyreporting standard usage}
-->
  
```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = FALSE,
  comment = "#>",
  eval=TRUE
)
```

# Description

This vignettes will guide the user in the exploration of the functionalities of
easyreporting.

# Requirements 

For the usage you just need to load the **easyreporting** package, which will 
load the **R6** and **rmarkdown** packages.

```{r, eval=FALSE}
if(!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("easyreporting")
```


```{r}
library("easyreporting")
```

# easyreporting instance creation

For simplicity we setup a project directory path starting from the working 
directory for our report, but you can just enter any path.
The **filenamepath** and the **title** parameters are mandatory, while the 
**author(s)** paramenter is optional.

Once created the **easyreporting** class instance, we can use it in our further
code to make other operations.
It stores some variables for us, in order to not be called again during next 
opreations.
For example the name and the path of the report, the type of report
and the general rmarkdown options of the document.


```{r}
proj.path <- file.path(tempdir(), "general_report")

er <- easyreporting(filenamePath=proj.path, title="example_report",
                  author=c(
                      person(given="Dario", family="Righelli", 
                          email="fake_email@gmail.com",
                          comment=c(ORCID="ORCIDNUMBER", 
                                    url="www.fakepersonalurl.com",
                                    affiliation="Institute of Applied Mathematics, CNR, Naples, IT", 
                                    affiliation_url="www.fakeurl.com")),
                    person(given="Claudia", family="Angelini",
                    comment=c(ORCID="ORCIDNUMBER",
                              url="www.fakepersonalurl.com",
                              affiliation="Institute of Applied Mathematics, CNR, Naples, IT",
                              affiliation_url="www.fakeurl.com"))
                    )
                  )
                    


er <- easyreporting(filenamePath=proj.path, title="example_report",
                        author=c("Dario Righelli"))
```

# Code Chunks

*Easyreporting* enables to include rmarkdown titles from first (default) to 
sixth **level**.
The good norm, when writing reports, is always to add a title to a new code 
chunk (CC) followed by a natural language text, which describes the CC.

```{r}
mkdTitle(er, title="Code Chunks", level=1)

mkdGeneralMsg(er, "A simple paragraph useful to describe my code chunk...")
```

## Manually creating a code chunk

The most mechanical way to create and populate a CC is to manually open the CC,
to insert the code, and then to close it.
Here we show how to insert a variable assignenent inside a CC.

```{r}
mkdTitle(er, title="Manual code chunk", level=2)

mkdCodeChunkSt(er)
variable <- 1
mkdVariableAssignment(er, "variable", `variable`, show=TRUE)
mkdCodeChunkEnd(er)
```

## Code Chunks Options

By using the standard function *makeOptionsList*, it is possible to create a 
custom list of options (an *optionsList*),  as described from **rmarkdown**.
In this way we are able to personalize even single code chunks, depending on 
specific cases.

Here we create an optionsList where the includeFlag is set to *TRUE* 
(our default is *FALSE*).

When opening the code chunk, it is possible to pass the new optionsList to the 
easyreporting class *mkdCodeChunkSt* method.

```{r}
optList <- makeOptionsList(echoFlag=TRUE, includeFlag=TRUE)
mkdCodeChunkSt(er, optionList=optList)
mkdCodeChunkEnd(er)
```

## Adding personal files to source

If you have one or more files with some functions that you want to use inside
your code, it is possible to add them by using the *sourceFilesList* 
parameter.

```{r}
## moreover I can add a list of files to source in che code chunk
RFilesList <- list.files(system.file("script", package="easyreporting"), 
                        full.names=TRUE)
mkdCodeChunkSt(er, optionList=optList, sourceFilesList=RFilesList)
mkdGeneralMsg(er, message="(v <- fakeFunction(10))")
mkdCodeChunkEnd(er)
```

## Complete chunk creation

It is also possible to create a complete chunk by using the 
*mkdCodeChunkComplete* function.

```{r}
mkdCodeChunkComplete(er, code="v <- fakeFunction(11)")
```

Finally, it is possible to create a unique code chunk within all the 
functionalities desribed before.

```{r}
optList <- makeOptionsList(includeFlag=TRUE, cacheFlag=TRUE)

mkdCodeChunkCommented(er, 
                comment="This is the comment of the following code chunk",
                code="v <- fakeFunction(12)",
                optionList=optList,
                sourceFilesList=NULL)
```

# Compiling the report

Once finished our analysis it is possible to compile the produced rmarkdown report  simply by using the *compile* method.
The compile method appends a sessionInfo() to the report to trace all the packages and versions used for the analysis.

```{r, eval=FALSE}
compile(er)
```

# Session Info

```{r, tidy=TRUE}
sessionInfo()
```