Bausteine Computergestützter Datenanalyse

Leitfaden zur Erstellung von Bausteinen

Autor:innen

Lukas Arnold

Simone Arnold

Florian Bagemihl

Matthias Baitsch

Marc Fehr

Franca Hollmann

Maik Poetzsch

Sebastian Seipel

Veröffentlichungsdatum

10. Oktober 2025

Lizenzangabe mit maschinenlesbaren Icon nach TULLU(BA)-Regel + Jahr: Titel, Urhebende, Lizenz, Link zur Lizenz. Ursprungsort. (Bearbeitung). (Ausnahmen). Jahr

Symbol des Lizenzhinweises Creative Commons BY

Bausteine Computergestützter Datenanalyse. Leitfaden zur Erstellung von Bausteinen von Lukas Arnold, Simone Arnold, Florian Bagemihl, Matthias Baitsch, Marc Fehr, Franca Hollmann, Maik Poetzsch und Sebastian Seipel ist lizensiert unter CC BY 4.0. Das Werk ist abrufbar auf GitHub. Ausgenommen von der Lizenz sind alle Logos Dritter und anders gekennzeichneten Inhalte. 2025

Zitiervorschlag

Arnold, Lukas, Simone Arnold, Florian Bagemihl, Matthias Baitsch, Marc Fehr, Franca Hollmann, Maik Poetzsch, und Sebastian Seipel. 2025. „Bausteine Computergestützter Datenanalyse. Leitfaden zur Erstellung von Bausteinen“. https://github.com/bausteine-der-datenanalyse/bcd-styleguide.

BibTeX-Vorlage

@misc{BCD-Styleguide-2025,
 title={Bausteine Computergestützter Datenanalyse. Leitfaden zur Erstellung von Bausteinen},
 author={Arnold, Lukas and Arnold, Simone and Bagemihl, Florian and Baitsch, Matthias and Fehr, Marc and Hollmann, Franca and Poetzsch, Maik and Seipel, Sebastian},
 year={2025},
 url={https://github.com/bausteine-der-datenanalyse/bcd-styleguide}}

1 Einleitung

Die Bausteine Computergestützter Datenanalyse wurden mit Quarto erstellt. Quarto ist ein quelloffenes Publikationssystem, das die Programmiersprachen Python, R, Julia und Observable sowie verschiedene Publikationsformate wie HTML, PDF, MS Word oder ePub unterstützt. Dieses Dokument ist ein Leitfaden und Gestaltungsrichtlinie zur Bearbeitung und Neuerstellung von Bausteinen.

Nach einer kurzen Einführung zur Installation (Kapitel 2) und allgemeinen Nutzung von Quarto (Kapitel 3) wird die Verwendung von Elementen wie Grafiken und Code-Blöcken in Kapitel 4 erläutert. Stilistische Hinweise sind dabei kursiv gesetzt.

2 Installation

Um Bausteine zu bearbeiten oder eigene Bausteine im Stil von BCD zu erstellen, benötigen Sie:

eine lokale Installation von Quarto,
eine Entwicklungsumgebung (VS Code, Jupyter, RStudio, Neovim, Text Editor) mit der jeweiligen Quarto-Erweiterung,
eine Installation der Programmiersprachen Python und / oder R sowie
die für die jeweilige Programmiersprache verwendeten Pakete.

Siehe: Quarto Get Started

3 Quarto Markdown Dateien

Quarto Markdown Dateien bestehen aus zwei Teilen: Dem YAML-Header und dem in Quarto Markdown geschriebenen Inhalt.

3.1 YAML-Header

YAML (“YAML Ain’t Markup Language”) ist eine Sprache zum Schreiben von Konfigurationsdateien. Der YAML-Header steht am Beginn einer Quarto Markdown Datei. Der YAML-Header enthält die Metadaten eines Dokuments, steuert die technische Ausführung der Dokumentenerstellung und konfiguriert global das Verhalten und Erscheinungsbild von Grafiken, Programmcode und anderen Elementen. Der YAML-Header wird mit --- begonnen und beendet, Kommentare können mit einer # gesetzt werden.

Metadaten

---
# Metadaten / meta data
title: "Bausteine Computergestützter Datenanalyse"
subtitle: "Leitfaden zur Erstellung von Bausteinen"
author:
  - Lukas Arnold
  - Simone Arnold
  - Florian Bagemihl
  - Matthias Baitsch
  - Marc Fehr
  - Maik Poetzsch
  - Sebastian Seipel
---

Konfiguration

Für die Dokumentenerstellung können an unterschiedliche Formate angepasste Einstellungen vorgenommen werden. Auf die korrekte Einrückung zusammenhängender Blöcke ist zu achten.

format:
  html: # 2 Leerzeichen oder 1 Tab
    option: parameter # 4 Leerzeichen oder 2 Tabs
    option: parameter
  pdf:  
    option: parameter  
    option: parameter

Spracheinstellungen

lang: de setzt die Dokumentensprache auf Deutsch. Die Standardeinstellung ist Englisch: lang: en. Weitere Einstellungen können mit der Option language auch für mehrere Sprachen konfiguriert werden. Eine Liste der Optionen findet sich auf GitHub.

language:
  de:
    toc-title: Inhalt # Titel des Inhaltsverzeichnisses
  en:
    toc-title: Contents # title for table of contents

Hinweis 1: Spracheinstellungen

crossref: 
  fig-title: Abbildung
  fig-prefix: Abbildung
  tbl-title: Tabelle
  tbl-prefix: Tabelle
  sec-prefix: Abschnitt

Quellenverwaltung und Zitation

Die Quellen werden über eine Bibliografiedatei im Format BibLaTeX (.bib) verwaltet. Diese Datei wird im Arbeitsordner angelegt und im YAML-Header mit ‘bibliography: bibliography.bib’ eingebunden.

Bibliografiedatei: bibliography.bib

In der Bibliografiedatei werden Einträge wie folgt abgelegt:

# Printmedien
@book{Hemingway1952,
  title={The Old Man and the Sea},
  author={Hemingway, Ernest},
  year={1952},
  publisher={Charles Scribner's Sons},
  URL={https://www.testurl.com/testurl},
  urldate ={2000-12-31}
}

# Onlineressourcen
@online{Quarto-get-started,
author = {Quarto},
title = {Get Started},
year = {},
url = {https://quarto.org/docs/get-started/},
urldate = {2024-02-27}
}

# mehrere Autor:innen
@online{R-Markdown-Cookbook,
  author = {Xie, Yihui and Dervieux, Christophe and Rieder, Emily},
  title = {R Markdown Cookbook},
  year = {2024},
  url = {https://bookdown.org/yihui/rmarkdown-cookbook/},
  urldate = {2024-03-04}
}

Quarto nutzt Pandoc zur Formatierung von Zitaten und Quellennachweisen. Pandoc nutzt standardmäßig den Chicago-Stil, das Nachweise im Nummern- und im Autor-Jahr-System definiert. In den Bausteinen werden Quellen im Autor-Jahr-System CMOS nachgewiesen.

Zitierstil: Autor-Jahr-System biblio-style: authoryear CMOS Kurzanleitung; @Hemingway1952 Hemingway (1952); [@Hemingway1952] (Hemingway 1952); [@Hemingway1952, 53] (Hemingway 1952, 53)

Hinweis 2: Quellennachweise

Das Erscheinungsbild des Quellenverzeichnisses unterscheidet sich in HTML und PDF leicht.

Ergänzen: bausteinübergreifende Quellenverwaltung.
Marc: Wenn man ein Quarto Projekt anlegt, kann man global den Pfad setzen.

3.2 Quarto Markdown

Quarto Markdown ist eine Erweiterung von Markdown, einer maschinenlesbaren Auszeichnungssprache für die Formatierung von Texten und weiteren Elementen wie Grafiken oder Programmcode. Eine Übersicht über die von Quarto Markdown unterstützten Formate bieten die Quarto Hilfeseiten. Quarto Markdown basiert auf Pandoc. Das Pandoc Handbuch kann bei spezifischen Fragen oder Problemen weiterhelfen.

Elementspezifische Optionen

Das Verhalten und Erscheinungsbild einzelner Elemente kann abweichend von den globalen Einstellungen durch elementspezifische Optionen kontrolliert werden. Abhängig vom jeweiligen Element werden Optionen mit einer bestimmten Syntax übergeben:

Codezellen werden durch führende Kommentarzeilen parametrisiert. (Anders als in R Markdown sollen Zelloptionen nicht in der geschweiften Klammer übergeben werden.)
- In Python, R und Julia mit #| option: parameter
- In Graphviz und Observable JavaScript mit //| option: parameter
- In Mermaid mit %%| option: parameter
Objekte wie Überschriften, Callout Blocks, Divs, Grafiken und Tabellen werden mit geschweiften Klammern gesteuert {option="parameter"}

Die Konfigurationsmöglichkeiten werden in Kapitel 4 erläutert.

Divs

Divs bieten vielfältige Möglichkeiten, Abschnitte zu formatieren. Divs werden mit mindestens drei Doppelpunkten ::: eingeleitet und beendet (vier und mehr Doppelpunkte helfen bei verschachtelten Divs, den Üblick zu behalten). Optionen werden in geschweiften Klammern übergeben. Die folgende Div …

::: {layout-ncol=2}

Text in Spalte 1

Text in Spalte 2
:::

… erzeugt ein zweispaltiges Layout:

Text in Spalte 1

Text in Spalte 2

Siehe: Quarto Divs

Besondere Bedeutung haben Divs für:

das Layout in mehreren Zeilen oder Spalten und die Abstandsformatierung (Ein Beispiel ist der Lizenzhinweis am Anfang des Dokuments). Quarto Figure Panels
Layout von Code-Blöcken in einem Tabset Panel
Conditional Content zur formatabhängigen Einbindung von Inhalten. Quarto Conditional Content
Erweiterte Möglichkeiten für Querverweise. Quarto Cross-Reference Div Syntax
Sonderformate wie Callout Blocks (siehe Kapitel 4).

Programmcode

Quarto Markdown kann Code von verschiedenen Programmiersprachen ausführen: Python, R, Julia und Observable JavaScript. Dazu unterstützt Quarto die Engines Knitr und Jupyter zur dynamischen Berichterstellung. (Quarto Frequently Asked Questions)

Python-Code wird mit Jupyter verarbeitet. Dazu muss eine lokale Installation von Python vorhanden sein. Die Installationsdatei sollte von der Python Homepage bezogen werden.

Darstellung des Renderpfads von Quarto Markdown zu Jupyter zu Markdown zu Pandoc zum gewünschten Format, z. B. PDF, Worddatei oder HTML. — Jupyter Engine, Quelle

R-Code wird mit Knitr verarbeitet. Dazu muss eine lokale Installation von R vorhanden sein, in der die Pakete knitr, rmarkdown sowie für die Ausführung von Python-Code das Paket reticulate installiert sind.

Darstellung des Renderpfads von Quarto Markdown zu Knitr zu Markdown zu Pandoc zum gewünschten Format, z. B. PDF, Worddatei oder HTML. — Knitr Engine, Quelle

Wird in einem Quarto-Dokument sowohl Python- als auch R-Code benutzt, wird die Knitr Engine zur Erstellung des Dokuments verwendet.

Codeblöcke werden mit ``` eingeschlossen und die zu verwendende Progammiersprache in geschweiften Klammern übergeben.

``` {python}

print(“Hello World from Python!”)

```

Hello World from Python!

``` {r}

print(“Hello World from R!”)

```

[1] "Hello World from R!"

4 Gestaltung von Elementen

4.1 Text

Regulärer Text wird in Markdownsyntax durch Sonderzeichen formatiert. Diese Sonderzeichen können durch ein vorangestellte Backslash \ in der Ausgabe sichtbar gemacht werden.

Stylesheets

Mithilfe von eigenen Stylesheets in Form von .css oder .scss-Dateien lassen sich eine Vielzahl an Layoutoptionen in der HTML-Ausgabe anpassen (W3Schools). Eine simple Einstellung wie

.neuer-begriff { 
    color: green; 
    font-weight: bold; 
}

sorgt dafür, dass einzelne Wörter durch Verwendung von [Beispielwort]{.neuer-begriff} grün eingefärbt werden und fett gedruckt sind: Beispielwort. Dabei werden die Eigenschaften der geschweiften Klammer auf alle Inhalte der eckigen Klammer angewendet. Änderungen in der .css-Datei werden dann global auf alle Elemente angewendet, sodass diese nicht einzeln geändert werden müssen. Die Verwendung einer .css-Datei kann im YAML-Header geregelt werden.

format:
  html: 
    css: cssdatei.css

Damit diese Elemente auch in der PDF-Ausgabe funktionieren können diese Einstellungen analog in LaTeX definiert werden:

\newcommand{\neuerbegriff}{\textcolor{green}}

(Anmerkung: Dieses Beispiel ist lediglich grün, aber nicht fett gedruckt.) Auch diese Verwendung wird über den YAML-Header geregelt.

format:
  pdf: 
    include-in-header:
      - macros.tex

Für eine fortgeschrittene Anwendungsmöglichkeit siehe Kapitel 4.2.0.1. Eine kleine Auswahl an Beispielen für Stylesheets anderer Projekte mit unterschiedlichem Grad an Komplexität können hier gefunden werden:

4.2 Callout Blocks

Callout Blocks eignen sich dazu, ausgewählte Inhalte hervorzuheben. Callout Blocks können umfangreich angepasst werden.

:::{.callout-note}
Es gibt fünf Typen von callouts: 
`note`, `tip`, `warning`, `caution`, und `important`.
:::

Hinweis