## Modul 2: Diagramme verstehen Dieses Modul stellt ein interaktives Werkzeug als Hilfe zur Verbesserung des Verständnisses von Diagrammen bereit. Dazu werden den Nutzern Multiple-Choice-Fragen zu Charakteristiken des gezeigten Graphen präsentiert. Die Lösung und gegebenenfalls die falsch gewählte Antwort werden grafisch hervorgehoben. Ein zweiter Typ von Test ermöglicht es den Nutzern, Teile des Diagramms auszuwählen und zu skalieren, um einen in der Frage vorgegebenen Effekt zu erzielen. Dies soll zeigen, wie einfache Manipulationen die Interpretation von Graphen beeinflussen können. Erst wenn eine korrekte Lösung gefunden wurde, kann zur folgenden Aufgabe weitergegangen werden. ### Javascript Verzeichnisstruktur Für einen besseren Überblick sind die Quell-Dateien mit kurzen Beschreibungen aufgelistet: ``` ├── main.jsx // Einstiegspunkt für App *mit* Verwendung der API ("online mode") ├── main-offline.jsx // Einstiegspunkt für App *ohne* Verwendung der API ("offline mode") ├── config.js // Globale Konfiguration der WebApp ├── components // (p)react Komponenten │   ├── Index.jsx // Web App Haupt-Komponente │   └── partials │ ├── GraphItem.jsx // Komponente für d3 Visualisierungen │ ├── IntroItem.jsx // Komponente für die Einführung zu den Fragen │ └── QuestionItem.jsx // Komponente für Benutzereingaben für Fragen ├── content │   ├── Gruppe-x_item-y.json // Definitionen der Fragen │   ├── module.json // Definition der (meisten) Labels und Texte des User Interfaces │   └── offline.js // Definition der Reihenfolge der Fragen ├── d3 // d3 Module │   ├── configuration.js // Konfiguration für d3-Module │   ├── axes.js // Achsendefinitionen │   ├── main.js // d3 Haupt-Modul │   ├── defs.js // Defintionen für SVG-Element (clip-path, gradient) │   ├── gradient.js // Darstellung der Steigung innerhalb eines Intervalls (Fragetyp 3) │   ├── grid.js // Skalierendes Hintergrundraster │   ├── handleConnector.js // Definition der Verbindungslinien zwischen Anfassern (Fragetyp 3) │   ├── handleSymbols.js // Definition der Geometrie der Anfasser als SVG symbols (Fragetyp 3) │   ├── handle.js // Konstruktor und Definition des Verhaltens der Anfasser (Fragetyp 3) │   ├── legend.js // Legende der Graphen │   ├── bar.js // Balkendiagramm als Feedback für Benutzer │   ├── lineGraphs.js // Darstellung der Graphen │   ├── points.js // Hervorhebung der Lösung / falschen Antwort (Fragetyp 1) │   ├── scales.js // d3 Skalen für x- und y-Achsen │   ├── range.js // Definition eines Auswahlbereichs (Fragetyp 3) │   └── rangeController.js // Controller für Auswahlbereich; Kommunikation zwischen Visualisierungs-Modulen (untereinander) und Anwendung └── utilities    ├── api.js // API für Lese- und Schreibzugriff auf die Datenbank    ├── enableTouch.js    ├── fonts.js ├── formatter.js    ├── math.js ├── randomizer.js └── validator.js // Funktionen zur Validierung der Benutzerantworten ``` ### Wie ändere ich Inhalte und Daten? #### *Offline* Version Die Inhalte und Daten der 'offline'-Version sind in den `json`-Dateien Dateien unter `src/js/content` definiert. #### Labels ##### Umgebende Texte In `module.json` sind die umgebenden Texte und Labels definiert, die nicht direkt Teil der WebApp sind. Dies umfasst die einleitenden (`introtext`) und abschließenden Texte (`outrotext`) und die Labels der Buttons und Vergleichsansichten mit anderen Nutzern. { "title": "Wie werden Finanzstatistiken verzerrt?", "introtext": "Um zu lernen, wie Statistiken verzerrt werden, …", "outrotext": "Was haben Sie geübt? …", "success": "Sie haben die Lösung erreicht!", "next": "Weiter", "start": "Start", "restart": "Neustart", "usersVoteHeadline": "So wählten die User", "usersRight": "Andere Nutzer lagen richtig" } ##### Labels der WebApp Der Titel der Aufgabe, Achsenbezeichner und Legendentext werden aus der `json`-Datei der jeweiligen Aufgabe (Namensschema `Gruppe-_item-.json`) gelesen und können dort geändert werden (siehe anschließenden Abschnitt zu Daten). Die Beschriftung der x-Achse wird direkt aus den Daten übernommen, die y-Achse dagegen automatisch von der Javascript-Bibliothek [ d3js ](https://d3js.org) generiert. 
"text": "Welchen Gewinn erzielte Citroniger im 4. Quartal 2016?",
"antworten": [
    {
      "antwort": "15 Millionen",
      …
    },
    …
],
"data": [
    "id": 1,
    "konkurrent": "Apfelreich",
    "koordinaten": [
        { "x": "Q1/2013", "y": 21.29 },
        …
    ],
    …
],
#### Daten In der Datei `offline.js` wird die Reihenfolge der Fragen bzw. Aufgaben definiert. Die Daten der jeweiligen Aufgabe ist in der entsprechenden Datei benannt nach dem Schema `Gruppe-_item-.json` definiert. Zu jeder Aufgabe sind Metadaten definiert, wie die ID der Aufgabe, Titel (`text`) und `gruppe`, was den Aufgabentyp bezeichnet. Im `data` Array sind die Koordinaten und Metadaten der Graphen enthalten. { "id": 1, "konkurrent": "Apfelreich", "koordinaten": [ { "x": "Q1/2013", "y": 21.29 }, … ] } Es existieren drei verschiedene Aufgabentypen, wobei für die Verifikation der Antworten der ersten beiden Aufgabentypen spezifische Validierungsfunktionen definiert sind. Diese werden im Folgenden kurz beschrieben, die Details der Implementierung sind in `src/js/validator.js` dokumentiert. **1. Finden eines bestimmten x- oder y-Wertes eines Graphen z** Die Antworten dieses Typs bestehen aus einem Label (`"antwort"`) und Koordinaten für den entsprechenden Punkt, z.B.: { "antwort": "15 Millionen", "coordinates": {"x": "Q4/2016", "y": 15.00} } Zur Validierung der Antworten sind drei Funktionen defniert: - `validateX`: ein gegebener x-Wert wird verglichen mit dem x-Wert des Graphen, an dem ein y-Wert einen Schwellwert erstmals über- oder unterschreitet. "validation": { "function": "validateX", "graph": "Citroniger", "threshold": 0, "comparator": "gt" } Dabei gibt `graph` den betrachteten Graphen an, `x` bezeichnet den gefragten x-Wert des Graphen, `threshold` definiert den gefragten Schwellwert und mit dem Wert von `comparator` wird festgelegt, ob der gesuchte Wert über (`gt`) oder unter (`lt`) dem Schwellwert liegen soll. - `validateY`: ein gegebener y-Wert wird verglichen mit dem y-Wert des Graphen an der Stelle des gefragten x-Werts. "validation": { "function": "validateY", "graph": "Citroniger", "x": "Q4/2016" } Der betrachtete Graph wird unter `graph` angegeben, und `x` bezeichnet den x-Wert des Graphen, an dessen Stelle die Validierung der gegebenen Antwort (y-Wert) durchgeführt werden soll. - `validateGradientExtremum`: die Gradienten von benachbarten x-Werten des Graphen werden berechnet und das Maximum bzw. Minimum bestimmt. Der ermittelte x-Wert wird verglichen mit dem übergebenen x-Wert. "validation": { "function": "validateGradientExtremum", "extremum": "max", "graph": "Citroniger" } Der betrachtete Graph wird durch `graph` angegeben und `extremum` gibt an, ob das Minimum oder Maximum gebildet werden soll (`min` bzw. `max`). **2. Beurteilung und Vergleich der Entwicklung der Graphen (negative / positive / unbeständige Entwicklung, Mittelwert)** Bei diesem Aufgabentyp soll der Graph benannt werden, der die gefragte Eigenschaft besitzt. Um die Robustheit der WebApp nicht zu gefährden, und die Konsistenz mit anderen Aufgabentypen zu erhalten / erreichen, wird der Wert von `antwort` weiterhin als Label für die grafische Ausgabe, der Wert von `graph` wird dagegen für die Validierung verwendet. Im folgenden Beispiel sind beide Werte \*zufälligerweise\* identisch, es fällt aber nicht schwer, sich Szenarien vorzustellen, in denen diese Trennung sinvoll sein kann. { "antwort": "Apfelreich", "graph": "Apfelreich" }, - `validateProgressionExtremumGraph`: der übergebene Graph-Bezeicher wird mit dem des Graphen mit extemen Verlauf (positiv / negativ) über den betrachteten Zeitraum verglichen. "validation": { "function": "validateProgressionExtremumGraph", "extremum": "min" } Der einzige konfigurierbare Parameter `extremum` bestimmt, ob die Benutzereingabe gegen den Graphen mit dem maximalen (`max`) oder minimalen (`min`) Verlaufswert validiert werden soll. Dieser Wert wird einfach durch die Bildung der Differenz der y-Werte an Anfang und Ende des betrachteten Intervalls ermittelt. - `validateAverageExtremumGraph`: Diese Funktion ermittelt den Graphen, dessen Werte über dem betrachteten Intervall den größten oder kleinsten Durchschnitt bilden und überprüft, ob der übergebene Graph-Bezeichner diesem entspricht. "validation": { "function": "validateAverageExtremumGraph", "extremum": "max" } Der Parameter `extremum` bestimmt, ob der maximale (`max`) oder minimale (`min`) Durchschnitt betrachtet werden soll. - `validateVolatilityExtremumGraph`: der gegebene Graph-Bezeichner wird gegen den des Graphen mit extremer Volatilität validiert. "validation": { "function": "validateVolatilityExtremumGraph", "extremum": "max" } Diese Funktion ermittelt zunächst die Schwankung innerhalb jedes Graphen, indem die Differenzen zwischen benachbarten y-Werten gebildet und deren Beträge aufsummiert werden. Der Parameter `extremum` bestimmt, ob die Lösung der Aufgabe die maximale (`max`) oder minimale (`min`) Schwankung aufweisen soll. **3. Manipulation des Graphen, so dass im betrachteten Teilsegement die grafische Wirkung der Steigung / des Gefälles verstärkt bzw. abgeschwächt wird.** Bei diesem Aufgabentyp sollen Graphen so manipuliert werden, dass im betrachteten Teilsegement die grafische Wirkung der Steigung / des Gefälles verstärkt bzw. abgeschwächt wird. Dies geschieht durch das Verändern der Grenzen einer Auswahl, das vertikale und horizontale Skalieren der Graphen basierend auf der gewählten Auswahl. Die Steigung wird grafisch visualisiert, sobald sich beide Punkte gleichzeitig innerhalb des Auswahlbereichs und des sichtbaren Bereichs befinden. Wurde der Graph so transformiert, dass die betrachtete Steigung innerhalb der Grenzwerte liegt, dann wird die Steigungsstrecke grün gefärbt und der Button zum fortfahren zur nächsten Aufgabe eingeblendet. Die Grenzwerte sind mit der Aufgabe definiert in der `json`-Datei als `anstiegUntereGrenze` und `anstiegObereGrenze`. Die Grenzen des betrachteten Intervalls werden mit `untereGrenze` und `obereGrenze` festgelegt. #### *Online* Version