tips.qmd

---
title: "Tips with R Markdown"
author: "R Félix"
eval: false
bibliography: references.bib
---

## Source vs. Visual mode {#sourcevisual}

You may want to work directly in the **Visual** mode, to "what you see is what you get", and switch to the **Source** mode for very specific code things.

![Source mode](images/clipboard-3294062401.png){width="600"}

![Visual mode](images/clipboard-680202013.png){width="600"}

## Suggestions

/

Type `Ctrl + /` to search for anything you want to include

![](images/clipboard-550443476.png){width="295"}

## Cross-references {#crossreference}

You can refer to sections, figures, tables, and equations in your document using the `@ref` syntax.

### With Sections

You can refer to sections like this: `[Section 1](#Introduction)`.
This will show as "[Section 1](#Introduction)".

### With figures

You can refer to figures like this: `\@ref(fig:plot1)`.
This will show as "Figure [1]()".
For that, you need to add a label to the figure chunk, like this: `{#fig:plot1}`.
or `fig.cap="\label{plot1} Caption of the plot"` in your r chunk.

```{r plot1, out.width="100%", fig.cap="\\label{plot1} Caption of the plot"}
plot(cars)
```

### With tables

You can refer to tables like this: `\@ref(tab:table1)`.
This will show as "Table [1]()".
For that, you need to add a label to the table caption like this:

```{r table1}
# example with kable
knitr::kable(head(iris),
             caption = "\\label{table1}Caption of the table", # label here
             fotmat = latex,
             booktabs = TRUE)
```

::: {.callout-tip appearance="simple"}
You don't need to use an ordered number, but just a name/label to your figures and tables.
R markdown will handle then the order of them and provide them **sequential numbering**.
:::

## Create a table of contents {#toc}

You can create a table of contents (**toc**) with the headings of your document, a list of tables (**lot**) or a list of figures (**lof**), simply by adding the following in the YAML:

``` yaml
---
title: "My Report"
author: "Your Name"
date: "2024-12-10"
output: pdf_document
toc: true
numbersections: true
number-depth: 3
lof: true
lot: true
---
```

## Include an image

To include a image that is not produced with R or Python (for instance a methods flowchart), you can click on **insert image** in Visual mode, browse your image file, adjust the size, and provide a proper caption.

If it is produced with **R** or **Py**, simply let your code do it for you.
Example:

```{r, fig.cap="A proper caption for a ggplot."}
#| eval: true
#| include: true
#| message: false
library(ggplot2)
ggplot(mpg, aes(displ, hwy, colour = class)) + 
  geom_point()
```

### Image position

By default, LaTeX puts your images on the **top of a page**, or arranges them in order to get the minimum white spaces possible.
That is why LaTeX documents look so nice an pretty.

Nevertheless, you can force the position of your image by adding the following to your chunk: `fig.pos = "H".` Other options:

-   **h**: Place the float here, i.e., approximately at the same point it occurs in the source text.
-   **t**: Position at the top of the page (*default*)
-   **b**: Position at the bottom of the page.
-   **p**: Put on a special page for floats only.
-   **!**: Override internal parameters LaTeX uses for determining “good” float positions.
-   **H**: Place the float at precisely the location in the LaTeX code. This requires the float package (`\usepackage{float}`).

## Inline math

You can use your results along the text, so every time you run the document, the results are also updated.
Example:

Results show that `r runif(1)*100`% of the population uses car as a main mode of transport.
3+2 = `r 3+2` is a nice number.

This is how you would write it:

```         
Results show that `r runif(1)*100` % of the population uses car as a main mode of transport. 3+2 = `r 3+2` is a nice number.
```

You can directly call your previously set variables.

## LaTeX packages {#latexpkgs}

Sometimes, you need to use some LaTeX packages to customize your document.
To use those, you can add the following in the YAML:

``` yaml
preamble: |
  \biboptions{authoryear}
  \usepackage{url}
  \usepackage{pdflscape}
  \usepackage{float}
  \usepackage{booktabs}
  \usepackage{longtable}
  \usepackage{makecell}
  \usepackage{multirow}
```

## Awsome tables with `kbl`

[kable](https://bookdown.org/yihui/rmarkdown-cookbook/kable.html) and [kableExtra](https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_html.html) allows to create pretty tables with R.

```{r}
#| eval: true
library(kableExtra)
cardata = mtcars[1:5, 1:6]

kbl(cardata,
    caption = "An awsome table about cars.") |>
  kable_styling() 
```

Check out the documentation for `.pdf` format: <https://haozhu233.github.io/kableExtra/awesome_table_in_pdf.pdf>

## Change colors of references and links {#colorurl}

To color your references and urls you can add the following to your yaml:

``` yaml
---
link-citations: true
linkcolor: teal
urlcolor: teal
---
```

## Add a landscape page

To include a landscape page in your pdf, for instance to present a very large table, you should use the `\usepackage{lscape}` in your [yaml preamble](#latexpkgs), and add the following code in [Source mode](#sourcevisual), before and after your table chunk:

```         
\begin{landscape}

Your code to make a large table

\end{landscape}
```

## Converting to word `.doc`

It can be handful to convert your nice `.pdf` to a `.doc` file to send it to your supervisor, instead of a LaTeX or pdf file.

To do so, you can simply open your favorite word processor and open your pdf file inside.
Click OK to convert when prompt.

![Example of this pdf book opened in MS Word](images/clipboard-1432672920.png){fig-align="center"}

Make some adjustments (sometimes it requires margins, spacing or line numbers), save it as `.doc` or `.docx`, and you are ready to go!

No headings, table of contents, citations, cross-references, figures, tables are missing.

## Elsevier paper example

Example of a paper written in R Markdown and submitted in **pdf** and **LaTeX** for the Elsevier journal Computers, Environment and Urban Studies:\
<https://github.com/U-Shift/biclar/blob/master/paper/PaperCEUS/PaperCEUS.Rmd>

This can be useful to get an idea how things work, and compare with the final result [@félix2025].

## Knitr in Project vs. Document

If your R Markdown (`.Rmd)` document is not in the root of your RStudio Project (`.Rproj` ) (*i.e.* - in the same folder), and if you have data or images that are in paths reffered to the project, you may want to change the knit configurations for it to work.

Go to Tools \> Global options \> R Markdown

In that case select *Evaluate chunks in **Project** directory.*

![](images/clipboard-1427534723.png){width="463"}

## Source Files when submitting to a journal

Usually journals accept the latex file (`.tex`) along the .pdf.

For that, you should prepare a `SourceFiles.zip` including:

-   The LaTeX file `paper.tex`

-   The used bibliography `references.bib`

-   A citation style if used `transportation_research.csl`

-   Any images files in a `img` folder

-   The `paper.pdf` file