summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/amnestyreport/sample.Rmd
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/amnestyreport/sample.Rmd')
-rw-r--r--macros/latex/contrib/amnestyreport/sample.Rmd156
1 files changed, 133 insertions, 23 deletions
diff --git a/macros/latex/contrib/amnestyreport/sample.Rmd b/macros/latex/contrib/amnestyreport/sample.Rmd
index daa2ad3076..07de47664d 100644
--- a/macros/latex/contrib/amnestyreport/sample.Rmd
+++ b/macros/latex/contrib/amnestyreport/sample.Rmd
@@ -24,13 +24,18 @@ output:
toc: true
keep_tex: true
citation_package: natbib
+classoption: freefonts, nologo
header-includes:
- \renewcommand{\thesection}{\Alph{section}}
bibliography: "examplereferences.bib"
+vignette: >
+ %\VignetteIndexEntry{amenstyreportR}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
library(amnestyreportR)
-setup_amnesty_plots()
+setup_amnesty_plots(options='freefonts, nologo')
# use
# setup_amnesty_plots(draft=TRUE)
# to make fast draft plots
@@ -71,39 +76,104 @@ War crimes are serious crimes committed during armed conflicts, which could incl
From \url{https://www.amnesty.org/en/latest/campaigns/2015/07/beginners-guide-human-rights-jargon/}
\clearpage
-# Introduction to the appendix {.unnumbered}
+# Introduction {.unnumbered}
+In this document we discuss the use of `amnestyreport.cls`, and accompanying `R` package \& `pandoc` template for writing Amnesty International Reports.
+You can either use an `Rnw` file with \LaTeX\ syntax, or an `Rmd` file with R Markdown syntax. In both cases you need:
-This appendix accompanies the Amnesty International report “*Some Amnesty Report Title*”. The report used an innovative mixed-methods research approach to capture the experiences of survivors of violence from multiple perspectives. The mixed-methods approach involved interviews with survivors and experts; desk research, including reviews of existing literature [See @SecondRef2022]\textsuperscript{,}[See also @FirstRef2023, p.12] and media articles [@FirstRef2023, p. 23]; formal requests to relevant officials for public information access; and quantitative analysis of a representative sample of court judgments.
+* The \LaTeX\ class file `amnestyreport.cls`,
+* A properly installed `R` package `amnestyreportR`,
+* Optionally Amnesty International fonts and logo (see below).
-This appendix provides more detail on each aspect of the quantitative research methodology, in-depth empirical analysis of the judgment data, and a codebook that describes the manual coding procedure employed. The data that Amnesty International extracted from these cases on judgments, defendants and victims is publicly available at \url{https://data.link}.
+If you use R Markdown syntax rather than \LaTeX\ syntax, you also need
-\autoref{sec:methodology} describes how court decisions on \ violence were identified and selected for analysis. \autoref{sec:results} analyses the data from the judgments. Empirical analysis was performed using the R programming language for statistical computing. \autoref{sec:codebook} explains the rules used to manually code data from judgments (codebooks) as well as the data available to the public.
+* The `pandoc` template `amnestytemplate.tex`
-\clearpage
+## A note about the fonts and logos {.unnumbered}
+
+If you have an established relationship with Amnesty International, you may use their fonts and logos in your report. You need to install the fonts, and the file with the logo (rename it to `Amnesty_logo.png`). Otherwise you need the options `freefonts, nologo` in your preamble for \LaTeX\ or the line
+`classoption: freefonts, nologo` in the RMD preamble.
+
+## Rmd premable example {.unnumbered}
+
+If you use Rmd, you need to specify in your preamble that
+
+* You are using the template `amnestytemplate.tex` rather than the generic `pandoc` template;
+* You are using `xelatex` (or `lualatex`) rather than a 8-bit engine `podflatex`.
-# Research methodology \label{sec:methodology}
+For example this file has the following preamble:
+
+
+```
+---
+title: "RMarkdown report example"
+subtitle: "An example report for Amnesty output"
+titleimage: "BoschFragment"
+titleimagecaption: "The Garden of Earthly Delights is the modern title
+given to a triptych oil painting on oak panel painted by the Early
+Netherlandish master Hieronymus Bosch, between 1490 and 1510, when
+Bosch was between 40 and 60 years old. It has been housed in the
+Museo del Prado in Madrid, Spain since 1939.\n\n
+\\textcopyright{} Image: Public domain.\n\n
+\\textcopyright{} Caption: Wikipedia contributors, 2023, released
+under Creative Commons Attribution-ShareAlike License 4.0"
+copyrightyear: 2023
+firstpublicationyear: 2022
+reportindex: ABXC/AAAA/2022
+blurb: "This sample output of Rmarkdown with TeX shows the general
+commands and options of the amnestyinternational TeX class. It is based
+on the text by Jule Krueger."
+
+output:
+ pdf_document:
+ template: amnestytemplate.tex
+ latex_engine: xelatex
+ toc: true
+ keep_tex: true
+ citation_package: natbib
+classoption: freefonts, nologo
+header-includes:
+ - \renewcommand{\thesection}{\Alph{section}}
+bibliography: "examplereferences.bib"
+---
+```
-This section describes the steps taken in the research methodology. We are using the R built-in iris data to compute an example table and figure in \autoref{sec:results} below.
\clearpage
-# Empirical analysis \label{sec:results}
+# Cross-references and bibliography \label{cross-ref}
+
+You can use the standard \LaTeX\ and R Markdown facilities for references.
+
+The package uses `biblatex` with the `bibtex` backend for citations to provide footnote citations, [See @SecondRef2022]\textsuperscript{,}[See also @FirstRef2023, p.12] and [@FirstRef2023, p. 23]. However, due to idiosyncrasies of `pandoc` we need to specify `natbib` as the citation engine in the preamble. Never mind biblatex warnings during the processing.
+
+
+Below in \autoref{sec:figures_tables} we show the examples of tables and figures provided by the package.
-This section conducts the empirical analysis and results. Irises are beautiful flowers that come in different types, shapes and sizes. In this report, we look at different species of irises in terms of petal size.\footnote{This is how you can add a footnote. Some footnotes are very long, and some are several lines log, but this is OK. Just make sure the indentation is right.}
+# Figures and tables \label{sec:figures_tables}
-```{r total number iris, echo=FALSE}
+## Inline expressions
+
+Irises are beautiful flowers that come in different types, shapes and sizes. In this report, we look at different species of irises in terms of petal size.\footnote{This is how you can add a footnote. Some footnotes are very long, and some are several lines log, but this is OK. Just make sure the indentation is right.}
+
+
+We define the variable `N_iris` and use it inline in the following example:
+
+```{r total_number_iris}
N_iris <- nrow(iris)
```
-There are a total of `r N_iris` iris flower specimen in the built-in \textbf{iris} data.
+There are a total of `r N_iris` (coded as \texttt{`}\texttt{r N\_iris}\texttt{`}) iris flower specimen in the built-in \textbf{iris} data.
+
-## Subsection with a table example
-We are make an example table from the built-in \textit{iris} data (see \autoref{tab:species}). The \emph{kableExtra} package is used to emphasize the last line
+## A table
-```{r make an example table from iris data, echo=FALSE}
+Here is an example of a table using `kable` package and `amnesty_table` function:
+
+
+```{r example_table, eval=FALSE}
iris %>%
count(Species) %>%
mutate(percent = n/sum(n)*100) %>%
@@ -111,19 +181,55 @@ iris %>%
across(where(is.factor), ~'Total'))) %>%
amnesty_table(row.names = FALSE,
align = "lrr",
- caption="\\label{tab:species}Frequency distribution of iris species.",
+ caption="\\label{tab:species}
+ Frequency distribution of iris species.",
position="!ht",
col.names = c("Species", "Number of species", "(%)"),
digits=2) %>%
kableExtra::row_spec(4, bold=TRUE)
```
+
+We can typeset it with sideways caption using `\sideTableCaptions`:
+\sideTableCaptions
+
+```{r example_table, echo=FALSE, eval=TRUE}
+```
+
+Alternatively, we can typeset it with normal captions using `\normalTableCaptions`:
+\normalTableCaptions
+```{r example_table_1, echo=FALSE}
+iris %>%
+ count(Species) %>%
+ mutate(percent = n/sum(n)*100) %>%
+ bind_rows(summarise(., across(where(is.numeric), sum),
+ across(where(is.factor), ~'Total'))) %>%
+ amnesty_table(row.names = FALSE,
+ align = "lrr",
+ caption="\\label{tab:species1}
+ Frequency distribution of iris species.",
+ position="!ht",
+ col.names = c("Species", "Number of species", "(%)"),
+ digits=2) %>%
+ kableExtra::row_spec(4, bold=TRUE)
+```
+
+
+
\FloatBarrier
-## Subsection with a figure example
+## Figures
+
+Normally the figures are prepared in separate \LaTeX\ runs. This might be very slow, so you may want to use the draft mode for the editing runs. Before making the figures, you need to issue the `R` command `setup_amnesty_plots(options=..., draft=...)`. The `options` are those that are passed to \LaTeX\ class; if you do not have Amnesty International fonts, use `freefonts`. The `draft` can be either `TRUE` or `FALSE` (for quick plots). For example
+
+```{r setup_example, eval=FALSE}
+setup_amnesty_plots() # You have Amnesty fonts and logo
+setup_amnesty_plots(options='freefonts, nologo') # No Amnesty fonts
+setup_amnesty_plots(draft=TRUE) # Draft mode
+```
We are using the \textit{ggplot2} package to make an example figure from the built-in iris data. As can be seen in \autoref{fig:species-petal-size}, the virginica species of iris has the largest petal size in comparison to the other two iris species. Note that it is recommended to use both color and line shape to convey the same information for the benefit of color blind users.
-```{r make an example figure from iris data, echo=FALSE, fig.cap="\\label{fig:species-petal-size}Distribution of petal length and petal width, by iris species.", fig.align="center", fig.height = 3, fig.width = 6}
+```{r species-petal-size, echo=FALSE, fig.cap="Distribution of petal length and petal width, by iris species.", fig.align="center", fig.height = 3, fig.width = 6}
iris %>%
ggplot(aes(x=Petal.Length, y=Petal.Width, color=Species, fill=Species,
shape=Species)) +
@@ -131,23 +237,26 @@ iris %>%
xlab("Petal Length") + ylab("Petal Width")
```
-We use viridis scale optimized for color blind users both for the discrete (\autoref{fig:species-petal-size}) and continuous (\autoref{fig:petal-size-sepal-size}) scales.
-```{r, fig.cap="\\label{fig:petal-size-sepal-size}Distribution of petal and sepal sizes", fig.align="center", fig.height = 3, fig.width = 6, echo=FALSE}
+
+We use viridis scale optimized for color blind users both for the discrete (\autoref{fig:species-petal-size}) and continuous (\autoref{fig:petal-size-sepal-size}) scales. We also use `\sideFigureCaptions` to typeset the caption on the side
+\sideFigureCaptions
+
+```{r, petal-size-sepal-size, fig.cap="Distribution of petal and sepal sizes", fig.align="center", fig.height = 3, fig.width = 4, echo=FALSE}
iris %>% ggplot + geom_point(aes(Petal.Length, Petal.Width, color=Sepal.Length)) +
labs(x="Petal Length", y="Petal Width", colour="Sepal Length")
```
\clearpage
-# Data and codebooks \label{sec:codebook}
+# Other typographic features
## A subsection heading
### A subsubsection heading
#### A subsubsubsection heading
-The custom formatting does add a line break after a subsubsubsection heading as Amnesty style requires.
+We have line break after a subsubsubsection heading as Amnesty style requires.
#### Type of iris species (Species)
This variable indicates the different botanical types of iris species.
@@ -159,9 +268,10 @@ This variable indicates the different botanical types of iris species.
\end{description}
-An example of a quotation
+An example of a quotation.
> All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.
>
> \attribution{Universal Declaration of Human Rights}
+