explain where vignettes are available

NAMESPACE

@@ -7,6 +7,7 @@ export(join_speaker)
 export(party_colors)
 export(read_all)
 export(read_from_csv)
+export(read_from_csv_or_fetch)
 export(repair)
 export(word_usage_by_date)
 export(write_to_csv)

R/fetch.R

@@ -61,10 +61,3 @@ fetch_all <- function(download_dir="inst/records/", create=FALSE) {
     # if successful, set progressbar to 100%
     setTimerProgressBar(pb, 250)
 }
-
-stop_dir_not_creatable <- function(cond) {
-    # currently this has call: dir.create(download_dir)
-    # do we want to change this to fetch_all(...) ?
-    cond$message <- "Directory does not exist and can't be created. Probably because the path is not writeable."
-    stop(cond)
-}

R/helpers.R

@@ -19,6 +19,13 @@ check_directory <- function(path, create=F) {
     }
 }
 
+stop_dir_not_creatable <- function(cond) {
+    # currently this has call: dir.create(download_dir)
+    # do we want to change this to fetch_all(...) ?
+    cond$message <- "Directory does not exist and can't be created. Probably because the path is not writeable."
+    stop(cond)
+}
+
 # appends a file seperator at end of path if needed
 make_directory_path <- function(path) {
     if (!str_ends(path, .Platform$file.sep)) str_c(path, .Platform$file.sep)

R/parse.R

@@ -233,6 +233,11 @@ parse_speakerlist <- function(speakerliste_xml) {
 #' 
 #' @export
 write_to_csv <- function(tables, path="inst/csv/", create=F) {
+    is_valid_res(tables)
+    stopifnot("path must be of type character" = is.character(path))
+    stopifnot("create must be of type logical" = is.logical(create))
+
+    path <- make_directory_path(path)
     check_directory(path, create)
     write.table(tables$speaker, str_c(path, "speaker.csv"))
     write.table(tables$speeches, str_c(path, "speeches.csv"))
@@ -250,6 +255,9 @@ write_to_csv <- function(tables, path="inst/csv/", create=F) {
 #' 
 #' @export
 read_from_csv <- function(path="inst/csv/") {
+    stopifnot("path must be of type character" = is.character(path))
+
+    path <- make_directory_path(path)
     list(speaker = read.table(str_c(path, "speaker.csv")) %>%
              tibble() %>%
              mutate(id = as.character(id)),
@@ -259,5 +267,27 @@ read_from_csv <- function(path="inst/csv/") {
                     date = as.Date(date)),
          talks = tibble %$% read.table(str_c(path, "talks.csv")),
          comments = tibble %$% read.table(str_c(path, "comments.csv")),
-         applause = tibble %$% read.table(str_c(path, "applause.csv")))
+         applause = tibble %$% read.table(str_c(path, "applause.csv"))) -> res
+    is_valid_res(res)
+    res
+}
+
+#' Read records from csv or fetch
+#'
+#' @param path base directory where csv files are expected under path/csv
+#' and possibly records fetched and stored under path/records
+#' 
+#' @export
+read_from_csv_or_fetch <- function(path="inst/") {
+    path <- make_directory_path(path)
+    res <- tryCatch(read_from_csv(str_c(path, "csv/")),
+                    error = function(c) NULL)
+    if (!is.null(res)) return(res)
+    
+    fetch_all(str_c(path, "records/"), create=T)
+    read_all(str_c(path, "records/")) %>%
+        repair() ->
+        res
+    write_to_csv(res, str_c(path, "csv/"), create=T)
+    res
 }

README.md

@@ -9,6 +9,34 @@ Using the `remotes` package, this is easily installed via:
 ```r
 remotes::install_url("https://git.flavigny.de/christian/hateimparlament/archive/master.zip")
 ```
+If you want to build the vignettes, pass `build_vignettes = TRUE`. This takes a long time and
+fails sometimes, if bundestag.de times out, since
+in the beginning the necessary records are neither fetched nor parsed.
+
+## Install with vignettes
+
+An alternative for building
+the vignettes is to clone the repository and build the vignettes manually, e.g. on Linux
+```
+git clone https://git.flavigny.de/christian/hateimparlament
+cd hateimparlament
+```
+Then open a `R` shell and do
+```r
+devtools::load_all() # load package
+devtools::wd() # set working directory
+```
+Then fetch all records, read them and write the parsed tibbles to csv files.
+```r
+fetch_all(create = TRUE)
+read_all() %>% repair() -> res
+write_to_csv(res, create = TRUE)
+```
+Now you can install the package with vignettes by using
+```r
+devtools::install(build_vignettes = TRUE)
+```
+This makes all vignettes available via `browseVignettes()`.
 
 # Features
 

inst/reports/abschlussbericht.tex

@@ -1,16 +1,28 @@
 \documentclass{article}
+\usepackage[ngerman]{babel}
 \usepackage[top=2.5cm, bottom=2.5cm]{geometry}
-
+\title{Abschlussbericht}
+\author{Leon Burgard, Josua Kugler, Christian Merten}
 \begin{document}
+    \maketitle
     \section*{Projektbeschreibung}
-    Wir haben zunächst die Plenarprotokolle der 19. Wahlperiode von der Website automatisiert herunterladen lassen.
-    Als nächstes haben wir die Daten in ein für die Analyse sinnvolles Format gebracht, d.h. 5 Tibbles  und Fehler ausgebessert.
-    Daraufhin konnten wir mit der Analyse beginnen.
-    Insbesondere 
-    \section*{Werkzeuge aus der Vorlesung}
-    Wir haben, da es hauptsächlich um Datenanalyse ging, sehr viel mit tidyverse gearbeitet.
-    Ganz zu Beginn haben wir fürs fetchen der Protokolle rvest verwendet.
-    Für die Visualisierung haben wir ggplot2 sowie vignettes genutzt.
+    Unser Projekt \glqq Plenarprotokolle \grqq stellt mittels dem Paket \verb|hateimparlament| Funktionen zur Analyse der Plenarprotokolle der 19. Wahlperiode des deutschen Bundestages zur Verfügung. Diese Funktionen können in vier Bereiche unterteilt werden:
+    \begin{enumerate}
+        \item Herunterladen der Protokolle
+        \item Konvertierung der XML-Dateien in Tibbles
+        \item Reparieren von Fehlern
+        \item Analyse
+    \end{enumerate}
+    Das Herunterladen der Protokolle gelingt über die Funktion 
+    \verb|fetch_all()|, welche auf die Website des deutschen Bundestages zugreift und die XML-Dateien einzeln herunterlädt. Hierzu haben wir das Paket rvest verwendet, welches wir bereits in der Vorlesung kennengelernt haben.
+    Durch \verb|read_all()| werden diese heruntergeladenen XML-Dateien in eine benannte Liste mit fünf Tibbles (speaker, speeches, talks, comments und applause) geschrieben. Allerdings benötigt man diese Tibbles immer wieder und es ist ziemlich zeitaufwändig die XML-Dateien immer wieder neu in Tibbles einzulesen, deshalb haben wir zusätzlich eine Funkion \verb|write_to_csv()| geschrieben, die die fertigen Tibbles als CSV-Dateien speichert. Diese können dann sehr schnell durch \verb|read_from_csv()| eingelesen werden, wodurch viel Zeit gesparrt wird.
+    Da diese Protokolle kleine Fehler enthalten, müssen diese noch im nächsten Schritt bereinigt werden, was mit \verb|repair()| funktioniert. Hierbei wird das Paket tidyverse viel benutzt, welches insgesamt sehr viel in unserem Projekt beansprucht wird, da wir uns mit der Datenanalyse beschäftigen.
+    In \verb|analyse.R| stellen wir noch einige Hilfsfunktionen bereit, die es dem Nutzer vereinfachen die Daten auszuwerten. Beispielsweise steht schon eine Funktion zur Verfügung, die ein Balkendiagramm erstellt, bei dem jede Partei des Bundestages sperat ausgewertet wird. Hierbei wird das Paket \verb|ggplot2| verwendet.
+    Im letzten Schritt unseres Projekts haben wir Fragestellungen festgelegt, die wir mithilfe von unserem Paket beantworten wollten. Die Daten und unsere Ergebnisse visualisierten wir mithilfe von \verb|ggplot2| und \verb|tidyverse| in Vignetten. 
     \section*{Organisation des Teams}
+    Während der ersten Projektphase wurden hauptsächlich die Funktionen zum Herunterladen der Dateien und Konvertieren und Reparieren der Tibbles geschrieben. Dies geschah größtenteils in Einzelarbeit, wobei hierbei die gegenseitige Kontrolle und Nachfragen die Funktionen optimiert haben. Zwischendurch wurde immer mal wieder zu einer HeiConf-Konferenz einberufen, um sich selbst den Zwischenstand klar zu machen und die Herausforderungen für die nächsten Wochen zu besprechen.
+    In der zweiten Hälfte des Projekts kümmerten wir uns dann um die Analyse der Daten und stellten unsere Ergebnisse in Vignetten da und erzeugten Dokumentationen für alle Funktionen, die für den Nutzer wichtig sind.
+    \newpage
     \section*{Meine Beteiligung}
+    \input{meine_beteiligung.tex}
 \end{document}

man/read_from_csv_or_fetch.Rd

@@ -0,0 +1,15 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/parse.R
+\name{read_from_csv_or_fetch}
+\alias{read_from_csv_or_fetch}
+\title{Read records from csv or fetch}
+\usage{
+read_from_csv_or_fetch(path = "inst/")
+}
+\arguments{
+\item{path}{base directory where csv files are expected under path/csv
+and possibly records fetched and stored under path/records}
+}
+\description{
+Read records from csv or fetch
+}

vignettes/explicittopic.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "explicittopic"
+title: "Analysis of covered topics"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{explicittopic}
+  %\VignetteIndexEntry{Analysis of covered topics}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -34,9 +34,10 @@ read_all("../inst/records/") %>% repair() -> res
 ```
 We also used `repair` to fix a bunch of formatting issues in the records.
 
-For development purposes, we load the tables from csv files.
+For development purposes, we only fetch records if they are not already
+stored as csv files:
 ```{r}
-res <- read_from_csv('../inst/csv/')
+res <- read_from_csv_or_fetch('../inst/')
 ```
 
 ## Analysis

vignettes/genderequality.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "genderequality"
+title: "Differences in gender"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{genderequality}
+  %\VignetteIndexEntry{Differences in gender}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -35,10 +35,13 @@ read_all("../records/") %>% repair() -> res
 ```
 We also used `repair` to fix a bunch of formatting issues in the records.
 
-For development purposes, we load the tables from csv files.
+For development purposes, we only fetch records if they are not already
+stored as csv files:
 ```{r}
-res <- read_from_csv('../inst/csv/')
+res <- read_from_csv_or_fetch('../inst/')
 ```
+
+
 and unpack our tibbles
 ```{r}
 comments <- res$comments

vignettes/generalquestions.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "generalquestions"
+title: "General questions"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{generalquestions}
+  %\VignetteIndexEntry{General questions}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -34,9 +34,10 @@ read_all("../inst/records/") %>% repair() -> res
 ```
 We also used `repair` to fix a bunch of formatting issues in the records.
 
-For development purposes, we load the tables from csv files.
+For development purposes, we only fetch records if they are not already
+stored as csv files:
 ```{r}
-res <- read_from_csv('../inst/csv/')
+res <- read_from_csv_or_fetch('../inst/')
 ```
 
 ## Analysis

vignettes/hitlercomparison.Rmd

@@ -38,9 +38,10 @@ talks <- res$talks
 We also used `repair` to fix a bunch of formatting issues in the records and unpacked
 the result into more descriptive variables.
 
-For development purposes, we load the tables from csv files.
+For development purposes, we only fetch records if they are not already
+stored as csv files:
 ```{r}
-tables <- read_from_csv('../inst/csv/')
+tables <- read_from_csv_or_fetch('../inst/')
 
 comments <- tables$comments
 speeches <- tables$speeches

vignettes/interaction.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "interaction"
+title: "Interaction between fractions"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{interaction}
+  %\VignetteIndexEntry{Interaction between fractions}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -34,9 +34,10 @@ read_all("../inst/records/") %>% repair() -> res
 ```
 We also used `repair` to fix a bunch of formatting issues in the records.
 
-For development purposes, we load the tables from csv files.
+For development purposes, we only fetch records if they are not already
+stored as csv files:
 ```{r}
-res <- read_from_csv('../inst/csv/')
+res <- read_from_csv_or_fetch('../inst/')
 ```
 
 ## Analysis