comparing-risks/doc/03_module.md

Modul 1: Risiken vergleichen

Dieses Modul bietet die Möglichkeit, Risiken spielerisch miteinander zu vergleichen. Aus den präsentierten Paaren von Ereignissen muss jeweils dasjenige mit der höheren Eintrittswahrscheinlichkeit gewählt werden. Es wird unmittelbar angezeigt, ob die Schätzung richtig war. Die 'online'-Version der WebApp zeigt in den folgenden Ansichten, wie man im Vergleich zu anderen Benutzern abschneidet.

Javascript Verzeichnisstruktur

Für einen besseren Überblick sind die Quell-Dateien unter src/js 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
│   ├── AnswerScreen.jsx
│   ├── FinalScreen.jsx
│   ├── Index.jsx             // Web App Haupt-Komponente
│   ├── QuestionScreen.jsx
│   ├── ScoreScreen.jsx
│   ├── TitleScreen.jsx
│   ├── UserVotesScreen.jsx
│   └── partials
│       ├── AnswerItem.jsx
│       ├── DonutGraphItem.jsx
│       ├── HeaderLightItem.jsx
│       ├── ResponseOptionItem.jsx
│       └── VoteItem.jsx
├── content                   // Definitionen der Inhalte
│   ├── module.json           // Labels und Texte des User Interfaces
│   └── questions.json        // Definitionen der Fragen
├── d3                        // d3 Module
│   ├── axes.js
│   ├── donutchart.js
│   ├── grid.js
│   ├── increment.js
│   ├── legend.js
│   ├── line.js
│   └── symbols.js
└── utilities                 // Werkzeuge und Dienste
    ├── api.js                // API für Lese- und Schreibzugriff auf die Datenbank
    ├── enableTouch.js
    ├── fonts.js
    ├── formatter.js
    └── randomizer.js

Wie ändere ich Bezeichner und Datenbasis?

Offline Version

Die Inhalte der 'offline'-Version sind in den json-Dateien Dateien unter src/js/content definiert.

Labels

Titel, Texte und Labels sind in module.json definiert. Dort kann man z.B. den einleitenden Text und die Labels der Buttons ändern.

Daten

Die Datenbasis diese Moduls ist eine einfache Liste von Ereignissen. Ein Ereignis kann durch eine ID eindeutig identifiziert werden und besteht ansonsten aus der Bezeichnung und dem "Basisrisiko". Letzteres stellt die Häufigkeit des Ereignisses dar, bezogen auf die Referenzgröße 100 000:

  {
    "id": 1,
    "bezeichnung": "Tod durch Erklettern des Mount Everests",
    "basisRisiko": 3500.00
  }

Online Version

Die Konfiguration für den Zugriff auf die API ist in src/js/config.js definiert.

  api: {
    random: 'M1_Risikopaare/Random',
    create: 'M1_RisikopaareUserData/Create',
    proportions: 'M1_RisikopaareUserData/CountsByPairId/',
    url: 'https://www.adaptivetoolbox.net/risikoatlas/api/'
  }

Dabei setzt sich eine Anfrage an die API aus der URL, dem entsprechenden Endpunkt und gegebenenfalls einem oder mehreren Parametern bzw. einem Für die Abfrage von Daten und das Erstellen neuer Einträge in der Datenbank sind folgende Endpunkte von der API definiert:

Ereignisdaten

Für alle auf Ereignise bezogenen Anfragen an die API werden GET Requests an die in der config.js festgelegte api.url verwendet. Folgende API Endpunkte sind definiert:

1. Abfrage eines Datensatzes mit zwei zufällig gewählten Ereignissen:

/M1_Risikopaare/Random

Zurückgegeben wird ein Objekt mit folgender Struktur:

{
    "id": 1700,
    "paar": [
        {
            "id": 32,
            "bezeichnung": "Tod durch Vorsätzliche Selbstbeschädigung",
            "basisRisiko": 12.64,
            "bezugsrahmen": "innerhalb eines Jahres",
            "referenzJahr": "2014",
            "referenz": "Destatis"
        },
        {
            "id": 59,
            "bezeichnung": "Tod durch Essen von 100 kohlegegrillten Steaks",
            "basisRisiko": 0.1,
            "bezugsrahmen": "innerhalb eines Jahres",
            "referenzJahr": "2010",
            "referenz": "wiki"
        }
    ]
}

1. Abfrage der Liste aller Ereignispaare:

/M1_Risikopaare/Liste

1. Abfrage eines spezifischen Ereigispaars:

/M1_Risikopaare/ById/{id}

wobei {id} für die ID des gesuchten Ereignispaares steht.

Benutzerdaten

Um den Vergleich zu anderen Nutzern zu ermöglichen werden die gewählten Antworten mit Benutzer-ID und Ereignispaar-ID gespeichert.

1. Erzeugen eines neuen Eintrags in der Datenbank:

/M1_RisikopaareUserData/Create

Per POST Request müssen dafür folgende Daten übermittelt werden:

• ID des Ereignispaars
• ID des aktuellen Nutzers
• ID des aktuellen Ereignispaars
• Angabe, ob die Antwort richtig oder falsch war.

1. Abfrage der "Stimmen" für Ereignisse aus einem Ereignispaar

/M1_RisikopaareUserData/CountsByPairId/?pairId={id}

Per GET Request muss die ID des Ereignispaars als Parameter übergeben werden.

Ein entsprechender Datensatz sieht wie folgt aus:

{
    "id": 1700,
    "paar": [
        { "id": 32, "anzahlStimmen": 1.0 },
        { "id": 59, "anzahlStimmen": 0.0 }
    ]
}

1. Abfrage der Anteile falscher und richtiger Antworten über alle Fragen und Benutzer hinweg

/M1_RisikopaareUserData/Proportions

liefert prozentuale Anteile in folgender Struktur:

{
    "richtig": 0.61931290622098423,
    "falsch": 0.38068709377901577
}

1. Abfrage des Verhältnisses der "Stimmen" für ein spezifisches Ereignispaar

/M1_RisikopaareUserData/ProportionsByPairId/?pairId={id}

1. Abfrage des vollständigen Datensatzes von Benutzerantworten

/M1_RisikopaareUserData/Liste

1. Abfrage einer bestimmten Antwort

/M1_RisikopaareUserData/ByRecordId/{id}

Zurückgegeben wird ein Datensatz, der einer Auswahl eines Benutzers aus einem Ereignispaar entspricht:

{
  "id": 1,
  "userId": 2,
  "risikoPaarId": 3,
  "correct": true
}

1. Abfrage aller Einträge eines Benutzers

/M1_RisikopaareUserData/ByUserId?userId={id}

Die id des gefragten Benutzers muss als Parameter des GET Requests übergeben werden.
Zurückgegeben wird eine Liste der entsprechenden Einträge:

[
    { "id": 1, "userId": 1, "risikoPaarId": 2, "correct": true },
    { "id": 2, "userId": 1, "risikoPaarId": 3, "correct": false },
    { "id": 3, "userId": 1, "risikoPaarId": 1, "correct": false }
]