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/parse.R

@@ -271,3 +271,23 @@ read_from_csv <- function(path="inst/csv/") {
     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,26 +9,34 @@ Using the `remotes` package, this is easily installed via:
 ```r
 remotes::install_url("https://git.flavigny.de/christian/hateimparlament/archive/master.zip")
 ```
-Since the fetching and reading is very slow and depends on an internet connection, all vignettes
+If you want to build the vignettes, pass `build_vignettes = TRUE`. This takes a long time and
-use `read_from_csv` to read already parsed tibbles from `.csv` files.
+fails sometimes, if bundestag.de times out, since
+in the beginning the necessary records are neither fetched nor parsed.
 
-That's why, if you want to build the vignettes yourself, you need to
+## Install with vignettes
-download the source code, e.g. on Linux
+
+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 start `R` and do
+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
-devtools::load_all()
 fetch_all(create = TRUE)
 read_all() %>% repair() -> res
 write_to_csv(res, create = TRUE)
 ```
-Then finally, do:
+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.
+    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:
-    Als nächstes haben wir die Daten in ein für die Analyse sinnvolles Format gebracht, d.h. 5 Tibbles  und Fehler ausgebessert.
+    \begin{enumerate}
-    Daraufhin konnten wir mit der Analyse beginnen.
+        \item Herunterladen der Protokolle
-    Insbesondere 
+        \item Konvertierung der XML-Dateien in Tibbles
-    \section*{Werkzeuge aus der Vorlesung}
+        \item Reparieren von Fehlern
-    Wir haben, da es hauptsächlich um Datenanalyse ging, sehr viel mit tidyverse gearbeitet.
+        \item Analyse
-    Ganz zu Beginn haben wir fürs fetchen der Protokolle rvest verwendet.
+    \end{enumerate}
-    Für die Visualisierung haben wir ggplot2 sowie vignettes genutzt.
+    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

@@ -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}
 ---
@@ -20,7 +20,7 @@ library(dplyr)
 library(ggplot2)
 library(stringr)
 library(tidyr)
-library(rvest)
+library(xml2)
 ```
 
 ## Preparation of data
@@ -33,13 +33,15 @@ Second, those `.xml` files, need to be parsed into `R` `tibbles`. This is accomp
 ```r
 read_all("../records/") %>% repair() -> res
 ```
-We also used `repair` to fix a bunch of formatting issues in the records and unpacked
+We also used `repair` to fix a bunch of formatting issues in the records.
-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}
-res <- read_from_csv('../inst/csv/')
+res <- read_from_csv_or_fetch('../inst/')
 ```
+
+
 and unpack our tibbles
 ```{r}
 comments <- res$comments
@@ -48,53 +50,33 @@ speaker <- res$speaker
 talks <- res$talks
 ```
 
-Bevor we can do our analysis, we have to assign a gender to our politicans.
+Bevor we can do our analysis, we have to assign a gender to our politicans. We do this
+by reading the gender from the master data of all members of parliament, which is
+fetched from bundestag.de.
 
 ```{r}
-extract_href <- function(sel, html) {
+xml_get <- function(node, name) {
-  html %>%
+    res <- xml_text(xml_find_all(node, name))
-    html_node(sel) %>%
+    if (length(res) == 0) NA_character_
-    html_attr("href")
+    else res
 }
 
-first_content_p_text <- function(url) {
+x <- read_xml("../inst/masterdata.xml")
-  res <- NA
+mdbs <- xml_find_all(x, "MDB")
-  i <- 1
+
-  while(is.na(res)) {
+ids <- c()
-    read_html(url) %>% 
+genders <- c()
-      html_node(str_glue("#mw-content-text > div.mw-parser-output > p:nth-child({i})"))  %>% 
+for (mdb in mdbs) {
-      html_text() -> res
+    xml_get(mdb, "ID") -> mdb_id
-    i <- i + 1
+    xml_find_first(mdb, "BIOGRAFISCHE_ANGABEN") %>%
-  }
+        xml_get("GESCHLECHT") ->
-  res
+        mdb_gender
+    ids <- c(ids, mdb_id)
+    genders <- c(genders, if (mdb_gender == "männlich") "male" else "female")
 }
 
-abgeordneten_list_html <- read_html(
+gender <- tibble(id = ids, gender = genders)
-  "https://de.wikipedia.org/wiki/Liste_der_Mitglieder_des_Deutschen_Bundestages_(19._Wahlperiode)")
+speaker_with_gender <- left_join(res$speaker, gender)
-
-selectors <- str_glue("#mw-content-text > div.mw-parser-output > table:nth-child(20) > tbody > tr:nth-child({2:709}) > td:nth-child(2) > a")
-link_part2 <- sapply(selectors, extract_href, abgeordneten_list_html)
-link <- str_c("https://de.wikipedia.org", link_part2)
-
-text <- sapply(link, first_content_p_text)
-text %>% 
-  str_extract(" ist ein.") %>% 
-  str_replace(" ist eine", "female") %>% 
-  str_replace(" ist ein ", "male") ->
-  gender
-
-text %>% 
-  str_extract("^([:upper:]?[:lower:]+[\\s\\-]?)*") %>% 
-  str_trim() -> 
-  names
-
-gender <- tibble(speaker = names,
-                 gender = gender)
-
-speaker %>% 
-  unite("speaker", vorname, nachname, sep = " ") %>% 
-  right_join(gender, by = "speaker") -> 
-  speaker_with_gender
 ```
 
 ## Analyse
@@ -179,9 +161,8 @@ speeches %>%
   summarize(n = n()) %>%
   ungroup() %>% 
   arrange(-n) %>%
-  left_join(speaker, by=c("speaker" = "id")) %>% 
+  join_speaker(res) %>%
-  unite(name, vorname, nachname, sep = " ") %>% 
+  left_join(gender, by=c("speaker"="id")) %>% 
-  inner_join(gender, by=c("name"= "speaker")) %>% 
   group_by(gender) %>% 
   summarise(absolute=sum(n)) %>%
   filter(gender %in% c("female", "male")) %>%

vignettes/generalquestions.Rmd

@@ -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

@@ -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