Add coding-box intro

_quarto.yml

@@ -181,8 +181,17 @@ website:
                         - tasks/design/simple-forms/Abi_Player/Praktische_Hinweise.qmd
               - href: tasks/design/speedtest/index.qmd
                 text: Speedtest
-          - text: "Antworten kodieren"
-            href: tasks/coding/index.qmd
+          - section: "Kodierschema"
+            href: tasks/coding-scheme/index.qmd
+      - section: "Kodieren und Auswerten"
+        href: coding/index.qmd
+        contents:
+            - section: "Datenstrukturen"
+              href: coding/data-structures/index.qmd
+              contents:
+                - href: coding/data-structures/response.qmd
+                  text: Antwort
+                - coding/data-structures/coding-scheme.qmd
       - href: Schulungsmaterial/index.qmd
         text: "Schulungsmaterial"
       - href: news/index.qmd

coding/data-structures/index.qmd

@@ -0,0 +1,7 @@
+---
+lang: de
+title: "Datenstrukturen"
+---
+
+* [response](response.qmd)
+* [coding-scheme](coding-scheme.qmd)

coding/data-structures/response.qmd

@@ -0,0 +1,56 @@
+---
+lang: de
+title: Datenstruktur "Antwort"
+---
+
+Die Spezifikation in englischer Sprache finden Sie [hier](https://iqb-specifications.github.io/response).
+
+# Übersicht
+
+| Parameter | erforderlich | Beschreibung / mögliche Werte | Beispiele |
+|--|:-:|------------------|:--:|
+| id | x | String; identifiziert die Variable innerhalb der Unit; zulässig: `^[0-9a-zA-Z_]+$` | "01a" |
+| status | x | String aus einer Aufzählung; s. u. | "NOT_REACHED" |
+| value | x | kann verschiedene Datentypen annehmen, s. u. | ["9", null] |
+| subform | - | String; wird benutzt, um das ggf. mehrfache Auftreten der Variablen (z. B. in Kopien bei Unterformularen) zu kennzeichnen | "p01" |
+| code | - | Integer; steht für die zutreffende Kategorie entspr. Kodierschema | 2 |
+| score | - | Integer; steht für die Bewertung des Codes, also die Übereinstimmung mit einer als "richtig" angenommenen Antwort | 0 |
+
+# Status
+
+Der Status-Wert übernimmt eine wichtige Anzeigefunktion für die Position einer Antwort im Entstehungs- und Verarbeitungsprozess. Die Datenstruktur wird nicht nur bei der Beantwortung der Testitems oder Fragen im Player genutzt, sondern auch während der Kodierung und Ableitung von neuen Variablen.
+
+| Wert | Beschreibung |
+|--|-------------|
+|`UNSET`|Ausgangszustand beim Anlegen von Variablen. Sollte eine Variable an ein Interaktionselement gebunden sein, dann erhält sie jedoch sofort den Status `NOT_REACHED`.|
+|`NOT_REACHED`|Ausgangszustand beim Anlegen von Variablen, die an ein Interaktionselement gebunden sind.|
+|`DISPLAYED`|Variablen, die an ein Interaktionselement gebunden sind, bekommen diesen Status, wenn sie der Testperson präsentiert wurden - also sichtbar sind.|
+|`PARTLY_DISPLAYED`|Diesen Zustand erhalten abgeleitete Variablen, die von Variablen abgeleitet wurden mit dem Status `PARTLY_DISPLAYED` oder mit `DISPLAYED` sowie außerdem den Status `NOT_REACHED` oder `UNSET`.|
+|`VALUE_CHANGED`|Dieser Status zeigt an, dass eine Interaktion stattgefunden hat und also der Wert (Value) auszuwerten ist. Bei abgeleiteten Variablen zeigt dieser Status eine erfolgreiche Ableitung an.|
+|`DERIVE_ERROR`|Dieser Status zeigt an, dass eine Ableitung fehlgeschlagen ist. Dies kann sich beispielsweise auf einen Typkonflikt (numerisch, Text) beziehen und ist in den meisten Fällen über eine Anpassung des Kodierschemas korrigierbar. Der Status bezieht sich allerdings nicht darauf, ob die zugrundeliegenden Variablen einen unzureichenden Status haben, sondern es geht um technische Fehler beim Ableitungsprozess.|
+|`DERIVE_PENDING`|Dieser Status zeigt an, dass eine Ableitung nicht möglich ist, weil mindestens eine Variable, die zur Ableitung nötig ist, den Status `CODING_INCOMPLETE` oder `CODING_ERROR` hat. Im Arbeitsablauf "wartet" diese Variable also darauf, dass eine manuelle Kodierung zu `CODING_COMPLETE` führt und der Autocoder neu angestoßen wird.|
+|`NO_CODING`|Bei diesem Status wurde festgestellt, dass keine Informationen für eine Kodierung vorliegen (keine Codes sind im Kodierschema definiert). Das stellt eine Fehlersituation dar. |
+|`INVALID`|Es wurde bei diesem Status eine Antwort festgestellt, die außerhalb des zulässigen Bereiches liegt. Beispielsweise wurde zwar zunächst ein Text eingegeben, dann aber alles gelöscht, so dass eine leere Antwort gespeichert wurde. Mit diesem Code werden auch Spaßantworten "Mir ist langweilig" kodiert.|
+|`CODING_INCOMPLETE`|Dieser Code zeigt nach einem Durchlauf einer Kodierprozedur an, dass keiner der vorgesehenen Codes als zutreffend angesehen wurde. Dieser Kodierfall muss dann manuell gesichtet werden.|
+|`CODING_ERROR`|Während der Kodierung ist ein Fehler aufgetreten, der die Bewertung der Antwort verhindert hat. Dies kann ein technischer Fehler bei der Anzeige (Replay) für das manuelle Kodieren sein, aber auch Typkonflikte zwischen dem Wert und dem Kodierschema können die Ursache sein.|
+|`INTENDED_INCOMPLETE`|Die Kodierung der Variablen ist nicht abgeschlossen, aber dies stellt keinen Fehler dar. Es handelt sich hier z. B. um Variablen, die über andere Wege kodiert werden sollen (z. B. Rating oder Übersetzung in Berufe-Codes außerhalb der regulären Kodierprozesse). Es kann auch sein, dass der Variablenwert erst durch eine Ableitung ausgewertet wird und innerhalb der Variable keine isolierte Bewertung möglich ist.|
+|`CODING_COMPLETE`|Die Kodierung der Variablen ist erfolgreich abgeschlossen.|
+
+::: {.callout-caution}
+## Status bei Ableitung
+Für die Interpretation der aggregierten (abgeleiteten) Variablen spielt der Status eine herausragende Rolle. [Siehe hier](../coding/missings.qmd#fälle-innerhalb-einer-unit) für eine detaillierte Beschreibung.
+:::
+
+# Value Types
+
+* array<string | null>
+* array<number | null>
+* array<boolean | null>
+* number
+* string
+* null
+* boolean
+
+::: {.callout-caution}
+In Computersprachen, die eine strikte Typisierung erzwingen, ist diese Variabilität des Datentyps ärgerlich. JSON als Datenformat bietet dies zwar an, in der Praxis ist aber oft eine Transformation in den Datentyp `String` gebräuchlich.
+:::

coding/index.qmd

@@ -0,0 +1,30 @@
+---
+lang: de
+title: "Kodieren und Auswerten"
+lightbox: true
+---
+
+In diesem Abschnitt finden Sie detaillierte Informationen für die Verarbeitung von Antworten. Als Zielgruppen gelten
+
+* **Wissenschaftler\*innen**, die die Antwortverarbeitung planen, managen und teilweise durchführen sowie
+* **Software-Entwickler\*innen**, die mit Programmierungen die Antwortverarbeitung unterstützen.
+
+Anleitungen für die Definition des Kodierschemas finden [Sie hier](../tasks/coding-scheme/index.qmd).
+
+Lesen Sie weiter:
+
+* [Datenstrukturen](data-structures/index.qmd)
+
+# IQB-Kodierbox
+
+Die Webanwendung IQB-Kodierbox befindet sich in Entwicklung. Sobald die Erprobungen weiter fortgeschritten sind, finden Sie an dieser Stelle weitere Informationen. Die folgende Darstellung zeigt schematisch die Funktionen:
+
+![](assets/Konzept_Kodierbox.png)
+
+* Die Testinhalte für die Testdurchführung werden auch in der Kodierbox benötigt.
+* **Datencheck**: Damit ist eine erste Prüfung der Daten möglich. Es kann festgestellt werden, ob die Daten vollständig sind oder Widersprüche aufweisen.
+* Mit der Funktion **Replay** kann der jeweils letzte Stand der Bearbeitung einer Aufgabe durch eine Testperson abgerufen werden. Dieser von anderen Funktionen unabhängige Zugriff soll eine manuelle Kodierung durch externe Dienstleister ermöglichen.
+* **Autocoder**: Mit Hilfe des Kodierschemas werden alle Antworten automatisch kodiert, soweit dies möglich ist. Ein erster Lauf identifiziert die Fälle, die manuell kodiert werden müssen.
+* **Manuelle Kodierung**: Für die Kodierung durch Personen sind komplexe Abläufe nötig. Zunächst muss ein Kodierdesign entworfen werden (z. B. Anteil der Doppelkodierungen), Schulungen durchgeführt, Kodierjobs zugewiesen und ausgewertet sowie die Ergebnisse zusammengeführt werden. Ein zweiter Autocoder-Lauf ermittelt die offenen Variablenableitungen.
+* Ein **Basis-Cleaning** deckt die häufigsten Probleme in den Daten auf. Testpersonen, die Mindestbedingungen nicht erfüllen, werden entfernt und Fehler im Kodierschema werden aufgedeckt. Hierzu sind auch die Protokolle der Testdurchführung auszuwerten.
+* Mit dem **Output** kann dann fortgesetzt werden: Manuelles Datencleaning, Skalierung, Aggregieren und weitere Datenanalysen.

tasks/coding-scheme/index.qmd

@@ -0,0 +1,18 @@
+---
+lang: de
+title: "Kodierschema"
+---
+
+Bei der Aufgabenerstellung im Studio werden Frageelemente in einer Unit angeordnet. Die Beantwortung dieser Frageelemente erzeugt Antwortwerte. Um Schlussfolgerungen hinsichtlich der Bewertung einer Antwort zu ziehen, werden die Antwortwerte Kategorien zugeordnet. Im einfachsten Fall gibt es die Kategorien richtig und falsch, sowie Kategorien für fehlende Werte. Die Zuordnung erfolgt durch die Erstellung von Regeln und Instruktionen. Diese sagen dann ganz grob ausgedrückt, diese Antwort ist falsch, und diese Antwort ist richtig.
+
+* Die Zuordnung einer Antwort zu einer Kategorie nennen wir **Kodierung**. Man vergibt für eine Antwort einen Code.
+* Wir unterscheiden **Regeln** für die automatische Kodierung und **Instruktionen** für die manuelle Kodierung.
+* Die Gesamtheit der Regeln und Instruktionen zur Kodierung der Antworten einer Aufgabe nennen wir **Kodierschema**.
+* Den Teil der Studioprogrammierung, mit dem wir das Kodierschema definieren, nennen wir **Schemer**. Es handelt sich um ein austauschbares Verona-Modul wie der Player und der Editor.
+
+Dieser Abschnitt thematisiert die Definition eines Kodierschemas als Teil der Aufgabenentwicklung.
+
+::: {.callout-note}
+Das Kodierschema ist grundsätzlich sehr offen und flexibel. Für eine effiziente Kodierung und Datenauswertung hat das IQB jedoch zahlreiche Konventionen und Vorgehensweisen eingeführt, die in diesem Abschnitt als notwendig beschrieben sind.
+:::
+