understanding-graphs/doc/03_module.md

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 <defs> (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 Bezeichner und Datenbasis?

Um den Benutzern den Vergleich zu anderen zu ermöglichen, wird die Anbindung an eine Datenbank ermöglicht. Diese ist über eine API anzusprechen, die im Abschnitt "Online Version" dokumentiert ist. Es ist aber genauso möglich, auf diese Datenbankanbindung zu verzichten und stattdessen nur "lokale" Daten zu nutzen. Die dafür relevanten Dateien sind unter "Offline Version" dokumentiert.

Offline Version

Die "lokalen" Inhalte und Daten 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-<x>_item-<a>.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 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-<x>_item-<y>.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 },
    …
  ]
}

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",
  "korrekt": false,
  "coordinates": {"x": "Q4/2016", "y": 15.00}
}

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:

{
  "antwort": "Apfelreich",
  "korrekt": true
},

3. Manipulation des Graphen, so dass im betrachteten Teilsegment 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 Teilsegment 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

Die Konfiguration für den Zugriff auf die API ist in src/js/config.js definiert. Ein Request wird zusammengesetzt aus der URL der API, einem Endpunkt und optionalen Informationen, die je nach HTTP Methode als Parameter der URL angehängt werden, oder im Message Body des Requests verschickt werden.

Anwendungsdaten

1. Abfrage aller Aufgaben in einer Liste. Die Ordnung (Id) entspricht der Ordnung der in der Excel-Datei abgelegten Liste. Aufgaben sind zusätzlich qualifiziert durch "Gruppe" (int) und "Item" (string), aus denen der Name konstruiert wird (Gruppe=2, Item="c" => Name="Frage 2c")

GET api/M2_Aufgaben/Liste

1. Abfrage einer spezifischen Aufgabe

GET api/M2_Aufgaben/ById/{id}

1. Abfrage einer Liste von Aufgaben, die zu einer bestimmten Gruppe gehören

GET api/M2_Aufgaben/Gruppe?gruppe={gruppe}

Abfrage einer durch eine Gruppe und Item qualifizierte Aufgabe????

GET api/M2_Aufgaben/Auswahl?gruppe={gruppe}&item={item}

Benutzerdaten

1. Abfrage aller Benutzer-Daten

GET api/M2_AufgabenUserData/Liste

1. Abfrage eines spezifischen Benutzer-Datensatzes

GET api/M2_AufgabenUserData/ById/{id}

1. Abfrage aller Daten für einen bestimmten Benutzer

GET api/M2_AufgabenUserData/ByUserId?userId={userId}

1. Gibt die UserData für eine durch eine Gruppe und Item qualifizierte Aufgabe zurück

GET api/M2_AufgabenUserData/ByAufgabe?gruppe={gruppe}&item={item}

1. Gibt die UserData für eine durch die AufgabeId qualifizierte Aufgabe zurück

GET api/M2_AufgabenUserData/ByAufgabeId?aufgabeId={aufgabeId}

1. Gibt für alle Fragen die Anteile korrekter und falscher Antworten zurück

GET api/M2_AufgabenUserData/Proportions

1. Gibt für eine bestimmte Frage die Anteile korrekter und falscher Antworten zurück

GET api/M2_AufgabenUserData/ProportionsByAufgabeId?aufgabeId={aufgabeId}

1. Erzeugt einen neuen Datenrecord in der M2_AufgabeUserData-Tabelle. Dabei sind die Angaben der AufgabeId und der UserId erforderlich, um die Antworten einer Aufgabe/einem User zuordnen zu können. Die Id wird nicht spezifiziert, da diese von der Datenbank automatisch zugewiesen wird

POST api/M2_AufgabenUserData/Create