flowchart LR
A("Autor*innen") -->|Anfrage| B(RDM-Team)
B -->|Entwürfe| A
B -->|"Illustration (pdf)"| C(icona<br>Grafikbüro)
C ---> D("Gedruckte<br>Buchreihe")
B --->|"Illustration (pdf)"| E("Forschungsdaten-<br>plattform")
B --->|"Datensatz<br>(csv, geojson)"| E
B --->|Metadaten| E
B --->|"Code (R)"| F(sgb-figures)
B --->|"Datensatz (csv)"| F
B --->|"Metadaten (json)"| F
F <-.-> E
style B fill:#3a1e3e,color:#fff,stroke:#3a1e3e
style D fill:#86bbd8,stroke:#86bbd8
style E fill:#86bbd8,stroke:#86bbd8
style F fill:#ffe880
click B href "/team.html" "Team für Forschungsdatenmanagement"
click D href "https://emono.unibas.ch/stadtgeschichtebasel/" "Open Access-Version"
click E href "/products/coding/plattform/index.html" "Dokumentation der Forschungsdatenplattform"
click F href "https://github.com/stadt-geschichte-basel/sgb-figures/" "sgb-figures auf GitHub"
Diagramme und Statistiken
Datenvisualisierung mit R
Das Team für Forschungsdatenmanagement und Public History hat für die neunbändige Buchreihe eine Reihe von Abbildungen erstellt. Unter Verwendung der von den einzelnen Autoren von Stadt.Geschichte.Basel bereitgestellten Rohdaten konzipierte das RDM-Team Karten, Diagramme und andere Arten von Visualisierungen (Mähr 2022) für die Veröffentlichung in der gedruckten und der Online-Version (OA) der Buchreihe.
In den Bänden der Stadt.Geschichte.Basel spielen Statistiken und deren Visualisierungen eine wesentliche Rolle. Sie ermöglichen es, die historische Entwicklung Basels nicht nur narrativ, sondern auch quantitativ zu erfassen und darzustellen. Beispielsweise können Bevölkerungswachstum, wirtschaftliche Entwicklungen oder infrastrukturelle Veränderungen über die Jahrhunderte hinweg anhand von statistischen Daten analysiert und mittels Plots veranschaulicht werden. Dies bietet den Leser*innen eine tiefere und anschaulichere Einsicht in die komplexen historischen Prozesse der Stadt.
Datenveröffentlichung
Die Veröffentlichung dieser statistischen Daten und der darauf basierenden Visualisierungen geschieht auf der Forschungsdatenplattform. Für die Bereitstellung von Code und R-Environment zur Weiterverwendung und Bearbeitung der Rohdaten wurde zusätzlich das GitHub-Repository sgb-figures eingerichtet, in dem die Daten, umfassende Metadaten (s. Datenmodell) sowie zur Grafikerstellung verwendeter Code aufbereitet werden. Damit wird die Auffindbarkeit und Nachnutzung der Projektinhalte erleichtert. Die Daten folgen den FAIR-Prinzipien (Findable, Accessible, Interoperable, Reusable) und sind unter offenen Lizenzen verfügbar, um den Zugang zu den historischen Forschungsdaten sowie ihre Reproduzierbarkeit zu gewährleisten.
Das sgb-figures-Repository speichert ausschließlich Code und Daten für Tabellen und Diagramme (auch als Plots bezeichnet). Für andere Arten der Datenvisualisierung im Zusammenhang mit Stadt.Geschichte.Basel verweisen wir auf die umfangreiche RDM-Dokumentation.
Arbeitsschritte zur Erstellung von Visualisierungen
Ausgangspunkt für jede Grafik sind Daten, die die Autor*innen von Stadt.Geschichte.Basel dem RDM-Team zur Verfügung gestellt haben. Mit Hilfe von R (vgl. Software) bereinigen wir die Daten, aggregieren ggfs. mehrere Quellen zu einem Datensatz für die Visualisierung, schreiben diese Daten in eine CSV-Datei und speichern Informationen zum Datensatz in einer begleitenden JSON-Metadatendatei, die gemäss dem W3C-Standard für tabellarische Daten und Metadaten im Web strukturiert ist (W3C 2022).
Die Data Stewards im RDM-Team von Stadt.Geschichte.Basel erstellen auf dieser Datengrundlage Visualisierungen für die Buchreihe, oft in mehreren Iterationen und in enger Zusammenarbeit mit den Forscher*innen (Twente und Mähr 2025; Münch u. a. 2023). Es werden eigens entwickelte Designprinzipien und Farbkonzepte implementiert, um eine möglichst einheitliche Bildsprache für alle Produkte zu gewährleisten. Die fertigen Produkte werden dann für den Druck und die langfristige Archivierung aufbereitet (Abbildung 1).
Während die für jedes Diagramm generierte PDF-Datei, die entsprechende Legende und die CSV-Datensätze auf die Forschungsdatenplattform hochgeladen werden, sind die zur Bereinigung der Daten und zur Erstellung des Diagramms verwendeten R-Skripte auf der Plattform nur über die Metadaten der Medienobjekte mit einem Link zu sgb-figures auf GitHub verknüpft.
Repository-Struktur
Die Datensätze und R-Skripte zur Erstellung der Diagramme sind im sgb-figures-Repository verfügbar und bieten eine reproduzierbare R-Umgebung, um die weitere Arbeit mit dem verfügbaren Code zu ermöglichen. Unter Verwendung des Open Research Template werden die Forschungsdaten unter Anwendung der in The Turing Way beschriebenen Best Practices aufbereitet und dokumentiert. Dieser strukturierte Ansatz umfasst ein automatisiertes Release-Management, die integrierte Archivierung mit Zenodo, eine strukturierte Dokumentation via Quarto und langfristige Zugänglichkeit über GitHub Pages (Mähr und Twente 2025).
R-Skripte, erstellte Diagramme, verarbeitete Daten und Metadatendateien sind nach der folgenden Ordnerstruktur sortiert:
build/– Hilfsskripte zum Erstellen der Diagrammedata/– Datensätzedocs/– Dokumentation zu den Daten und dem Repositoryoutput/– erzeugte PDF-Dateiensrc/– Quellcode für die Datenverarbeitung und die Erstellung von Diagrammen
Eine genauere Beschreibung des Repositoriums ist in der englischsprachigen Dokumentation verfügbar.
Workflow zur Erstellung der Diagramme
Von den Rohdaten als Input bis zur veröffentlichten Abbildung spielen eine Reihe von Objekten eine Rolle im Erstellungsprozess. Das Vorgehen wird hier anhand eines fiktiven Beispiels illustriert – die Abbildung abb01313, veröffentlicht in Stadt.Geschichte.Basel Band <n>.
Software
Alle Diagramme werden mit R erstellt. Zusätzlich zu ggplot2 (Wickham 2016) und anderen Teilen des tidyverse verwendet dieses Projekt mehrere Packages für die Datenverarbeitung und -visualisierung, darunter here (Müller und Bryan 2020) und renv (Ushey und Wickham 2025) zur Bereitstellung einer reproduzierbaren Umgebung sowie csvwr (Gower 2022) zur Erstellung von Metadatendateien.
Code, Daten und Dokumentation werden zur Versionsverwaltung in git eingecheckt und in einem GitHub-Repository gespeichert. Mit prettier (Long 2025) wird der Programmcode formatiert. Für R-Skripte werden zu diesem Zweck styler (Müller und Walthert 2024) und lintr (Hester u. a. 2025) eingesetzt. Die R-Umgebung einschließlich aller erforderlichen Pakete kann mit der Datei renv.lock1 wiederhergestellt werden. Die Dokumentation wird mit Quarto (Allaire u. a. 2022) gerendert und auf GitHub Pages gehostet.
Datenverarbeitung
Der erste Schritt des Workflows besteht darin, die Rohdaten zu verarbeiten und einen annotierten Datensatz zu erstellen, der sowohl zur Veröffentlichung als auch zur Verwendung als Input für die Erstellung einer Abbildung bereit ist (Abbildung 2). Das Skript in src/01313/01313_clean.R lädt die Rohdatendatei aus data/raw/Band<n>/01313/ 01313_Data_raw.xlsx als data01313 in die R-Umgebung, verarbeitet den Datensatz (Umformatierung von Spalten, Umwandlung von absoluten in relative Werte usw.) und exportiert die bereinigten Daten nach data/clean/Band<n>/01313/01313_3_Data.csv. Zusätzlich wird für die Metadaten ein Listenobjekt meta01313 in R erstellt und in data/clean/Band<n>/01313/01313_3_Data.csv-metadata.json geschrieben (siehe Datenmodell).
flowchart LR
clean_script <--->|Daten laden| rawdata([01313_Data_raw.xlsx])
clean_script([01313_clean.R]) -->|Daten aufräumen| data01313(data01313)
clean_script -->|Daten<br>annotieren| meta01313(meta01313)
data01313 -->|Daten exportieren| csv01313([01313_3_Data.csv])
meta01313 -->|Metadaten exportieren| json01313([01313_3_Data.csv-metadata.json])
style csv01313 fill:#ffe880
style json01313 fill:#fff3e0
style clean_script fill:#86bbd8,stroke:#86bbd8
style data01313 fill:#c0dceb,stroke:#c0dceb
style meta01313 fill:#c0dceb,stroke:#c0dceb
Plot erstellen
Nachdem der Datensatz vorbereitet wurde, kann er zum Erstellen eines Plots (Abbildung 3) verwendet werden. Dazu wird das Skript in src/01313/01313_plot.R ausgeführt. Dabei wird zunächst das eben beschriebene Skript zur Datenverarbeitung geladen, um sicherzustellen, dass der Plot anhand aktueller Dateien erstellt wird. Die Daten werden als data01313 in R geladen. Bei Bedarf werden weitere Transformationen angewendet (z. B. Erstellen benutzerdefinierter Beschriftungen, Aggregieren von Spalten, Bearbeiten von Daten für eine bessere Lesbarkeit usw.). Das Abbildungsobjekt plot01313 wird mit ggplot2 erstellt. Aus technischen Gründen müssen Plot und Legende als separate Dateien exportiert werden2. Daher wird das R-Objekt separate_legend mit ggpubr (Kassambara 2025) erstellt. Beide Objekte werden dann als PDF-Dateien 01313_1_Plot.pdf und 01313_2_Legende.pdf unter output/Band<n>/01313 gespeichert. Beim Erstellen der Abbildungen mithilfe der Daten im Repository sgb-figures werden die Plots nicht mit der Hausschrift von Stadt.Geschichte.Basel exportiert, sondern mit einer System-Standardschrift.
Für die Druckausgabe von Stadt.Geschichte.Basel nahm das RDM-Team vor der Übergabe der Abbildungen an das Grafikbüro zur Erstellung der veröffentlichten Bücher kleinere Nachbearbeitungen mit Adobe Illustrator vor, um drucktechnischen Anforderungen, kurzfristigen Änderungen durch die Autor*innen usw. Rechnung zu tragen.
flowchart LR
plot_script([01313_plot.R]) <--> |Daten<br>laden| clean_script([01313_clean.R])
plot_script --> |Daten<br>transformieren| data01313(data01313)
data01313 -->|Plot-Objekt<br>erstellen| plot01313(plot01313)
plot01313 --->|Plot<br>exportieren| export01313([01313_1_Plot.pdf])
plot01313 -->|Legende<br>extrahieren| legend01313(separate_legend)
legend01313 -->|Legende<br>exportieren| exportlegend([01313_2_Legende.pdf])
plot_script ----->|Vorschau-Website erzeugen| infopage([01313.qmd])
style clean_script fill:#86bbd8,stroke:#86bbd8
style plot_script fill:#86bbd8,stroke:#86bbd8
style data01313 fill:#c0dceb,stroke:#c0dceb
style plot01313 fill:#c0dceb,stroke:#c0dceb
style legend01313 fill:#c0dceb,stroke:#c0dceb
style export01313 fill:#ffe880
style exportlegend fill:#ffe880
style infopage fill:#fff3e0
Zusätzlich zur Abbildung selbst erstellt das Skript 01313_plot.R eine separate qmd-Datei in docs/plots/. Diese Seite wird für die mit GitHub Pages gehostete Dokumentation des sgb-figures-Repositorys gerendert, um eine Vorschau von Diagramm und Daten anzuzeigen. Diese Quarto-Datei enthält eine Vorschau der Abbildung selbst, eine Tabelle mit dem für die Erstellung der Grafik verwendeten Datensatz sowie ausgewählte Metadaten zum Datensatz, die aus der Datei json geparst wurden. Metadaten, die die Grafik (das Medienobjekt) selbst beschreiben, sind nur auf der Forschungsdatenplattform verfügbar.
Anwender*innen können einige npm-Skripte nutzen, um die Erstellung der Diagramme direkt über die Kommandozeile zu ermöglichen. Durch Ausführen von npm run list wird eine Liste aller verfügbaren Plots mit der entsprechenden Medien-ID ausgegeben. Mit dieser ID können der Plot, die Metadaten und die qmd-Dateien mit npm run plot <ID> generiert werden. Eine vollständige Liste aller verfügbaren npm-Skripte bietet das Repository-README.
Datenmodell
Metadaten für die auf der Forschungsdatenplattform vorgestellten Elemente werden gemäss einem Datenmodell bereitgestellt, das vom Team für Forschungdatenmanagement der Stadt.Geschichte.Basel entwickelt wurde, um den Anforderungen der vielfältigen im Projekt verwendeten Quellen gerecht zu werden. Das Datenmodell (und der anschliessende Annotationsprozess) folgen dem Handbuch zur Erstellung diskriminerungsfreier Metadaten für historische Quellen und Forschungsdaten (Mähr und Schnegg 2024), das ebenfalls von Stadt.Geschichte.Basel entwickelt wurde.
Für die Datensätze in sgb-figures wurde das Datenmodell von Stadt.Geschichte.Basel geringfügig angepasst, um auf die abweichenden Anforderungen an die Veröffentlichung tabellarischer Daten reagieren zu können. Dazu wurden die Empfehlungen des W3C-Standards für tabellarische Daten und Metadaten im Internet (W3C 2022) konsultiert und mit dem csvwr package (Gower 2022) implementiert.
Metadaten für die csv-Datensätze, die im Zusammenhang mit der Grafikerstellung Verwendung finden, werden in einer separaten json-Datei gespeichert. Im Folgenden wird die Integration der annotierten Datensätze im sgb-figures-Repository in das Datenmodell von Stadt.Geschichte.Basel wieder mit dem fiktiven Beispiel-Metadatenobjekt abb01313 illustriert.
Abbildung 4 veranschaulicht das Datenmodell mit Metadatenfeldern für ein Beispiel-Metadatenobjekt abb01313, das ein untergeordnetes Medienobjekt m01313 hat. Wenn ein Metadatenobjekt mehr als ein untergeordnetes Medienobjekt hat, werden die id-Werte der untergeordneten Objekte fortlaufend nummeriert: m01313_1, m01313_2 usw. (genauso wird mit ggfs. mehreren csv-Datensätzen verfahren). In diesem Fall ist m01313 ein sgb-figures-Plot, das mit dem Datensatz m01313_3 als Grundlage erstellt wurde. Dieser Datensatz wiederum wird durch den Metadatensatz 01313_3_Data.csv-metadata.json beschrieben.
classDiagram
direction LR
class metadata["metadata json<br><i>beschreibt csv-Datei</i>"]
class metadata2["metadata object<br><i>beschreibt Medienobjekt(e)</i>"]
class media["media object"]
class csv["csv dataset"]
metadata "1" --> "1" csv
csv "1" --> "*" media
media "m" <-- "n" metadata2
class csv {
id (01313_3)
}
class metadata {
id (01313_3_Data.csv-metadata)
url (01313_3_Data.csv)
[columns] (title, datatype, description)
media_id (m01313_3)
[isPartOf]
title
description
[creator] (incl. ORCID)
[contributor] (incl. ORCID)
publisher
date (EDTF)
coverage
type
format
source
language (ISO 639-2 code)
[relation]
rights
license
modified (ISO 8601)
bibliographicCitation
}
%%| no label for namespaces, see https://github.com/mermaid-js/mermaid-live-editor/issues/1452
namespace sgb_datamodel {
class media {
id (m01313)
title
[subject;subject] (keywords from GenderOpen Index)
description
[abstract] (alt attribute for alternative text)
[creator] (incl. link to Wikidata)
[publisher] (incl. link to Wikidata)
date
temporal
type
format
extent
[source] (Source and catalogue link)
language (ISO 639-2 code)
[relation] (internal links to other items, link to GitHub, further information)
rights
license
}
class metadata2 {
id (abb01313)
title
[subject;subject]
description
temporal
language (ISO 639-2 code)
[isPartOf;isPartOf] (Data DOIs)
}
}
style csv fill:#F7CB45,stroke:#777
style metadata fill:#fff3e0,stroke:#777
style media fill:#FFFFFF,stroke:#777,color:#3A1E3E
click media href "https://dokumentation.stadtgeschichtebasel.ch/products/coding/plattform/#datenmodell" "Main Data Model Documentation"
click metadata2 href "https://dokumentation.stadtgeschichtebasel.ch/products/coding/plattform/#datenmodell" "Main Data Model Documentation"
Literatur
Allaire, J. J., Charles Teague, Yihui Xie, und Christophe Dervieux. 2022. „Quarto“. Zenodo. https://doi.org/10.5281/ZENODO.5960048.
Gower, Robin. 2022. „csvwr: Read and Write CSV on the Web (CSVW) Tables and Metadata“. https://robsteranium.github.io/csvwr/.
Hester, Jim, Florent Angly, Russ Hyde, Michael Chirico, Kun Ren, Alexander Rosenstock, und Indrajeet Patil. 2025. „lintr: A ’Linter’ for R Code“. https://lintr.r-lib.org.
Kassambara, Alboukadel. 2025. „ggpubr: ’ggplot2’ Based Publication Ready Plots“. https://rpkgs.datanovia.com/ggpubr/.
Long, James. 2025. „prettier: An Opinionated Code Formatter“. https://prettier.io/.
Mähr, Moritz. 2022. „Research Data Management in (Public) History“. Keynote. Istituto Svizzero di Roma. https://doi.org/10.5281/zenodo.6637118.
Mähr, Moritz, und Noëlle Schnegg. 2024. „Handbuch zur Erstellung diskriminierungsfreier Metadaten für historische Quellen und Forschungsdaten: Erfahrungen aus dem geschichtswissenschaftlichen Forschungsprojekt Stadt.Geschichte.Basel“. Basel: Zenodo. https://doi.org/10.5281/ZENODO.11124720.
Mähr, Moritz, und Moritz Twente. 2025. „One Template to Rule Them All: Interactive Research Data Documentation with Quarto“. Digital Humanities Tech Symposium, Universidade NOVA de Lisboa. https://maehr.github.io/one-template-to-rule-them-all/.
Müller, Kirill, und Jenny Bryan. 2020. „here: A Simpler Way to Find Your Files“. https://doi.org/10.32614/CRAN.package.here.
Müller, Kirill, und Lorenz Walthert. 2024. „styler: Non-Invasive Pretty Printing of R Code“. https://styler.r-lib.org.
Münch, Cristina, Nico Görlich, Moritz Mähr, und Moritz Twente. 2023. „Karten als "boundary objects" oder wie man mit Geodaten historische Thesen bildet“. Poster. Digital History-Tagung, Humboldt-Universität zu Berlin. https://doi.org/10.5281/zenodo.7960744.
Ushey, Kevin, und Hadley Wickham. 2025. „renv: Project Environments“. https://rstudio.github.io/renv/.
W3C. 2022. „Model for Tabular Data and Metadata on the Web“. https://w3c.github.io/csvw/syntax/.
Wickham, Hadley. 2016. ggplot2: Elegant Graphics for Data Analysis. New York: Springer. https://ggplot2.tidyverse.org.
Fußnoten
Mit dem npm-Script
npm run setupwird eine Abkürzung angeboten, um die nötigen R-Pakete und Abhängigkeiten zu installieren.↩︎Aus technischen Gründen werden die eigentliche Abbildung und die dazugehörige Legende während des Buchproduktionsprozesses in der Regel in separaten PDF-Dateien gespeichert. Diese beiden Dateien werden programmatisch als ein Objekt dargestellt (
plot01313) und daher in diesem Zusammenhang gemeinsam als ein Objekt bezeichnet.↩︎