Zum Inhalt springen
Wissensdatenbank

Bundle-Tools — MCP-Tool-Referenz

Ein Bundle verbindet ein Projekt, einen Fragebogen und eine nicht leere Auswahl der Kampagnen dieses Fragebogens mit genau einer linearen Datensatzkette Bronze → Silver → Gold. Mit diesen Tools verwalten Sie das Bundle selbst und seine Qualitätsauswertung. Die Stufenoperationen auf Bundle-Ebene (Extraktion, Codierung + Gewichtung, Verfeinerung, Export) finden Sie unter Datensatz-Tools.

Legt ein Pipeline-Bundle an.

Parameter Typ Erforderlich Standard Beschreibung
name string Ja — Name des Bundles
project_id string Ja — Zugehöriges Projekt (Schreibzugriff erforderlich)
questionnaire_id string Ja — Fragebogen, dessen abgeschlossene Umfragen in Bronze einfließen
campaign_ids string[] Ja — Auszuwertende Auswahl an Kampagnen. Mindestens eine ist anzugeben: Die Messbasis eines Bundles sind die Umfragen der ausgewählten Kampagnen

Rückgabe: { bundle_id, name }


Listet Pipeline-Bundles auf, optional gefiltert auf ein Projekt.

Parameter Typ Erforderlich Standard Beschreibung
project_id string Nein — Nur Bundles dieses Projekts zurückgeben

Rückgabe:

{
"items": [
{
"id": "...",
"name": "Wave 1",
"project_id": "...",
"questionnaire_id": "...",
"campaign_ids": ["..."],
"chain": {
"bronze": {"dataset_id": "...", "status": "ready"},
"silver": {"dataset_id": "...", "status": "processing"}
}
}
],
"count": 1
}

Die Schlüssel von chain sind die Stufen, für die ein Datensatz existiert (bronze/silver/gold). Eine Stufe ohne Datensatz fehlt einfach – behandeln Sie sie als missing.


Erstellt eine tiefe Kopie der fertigen Datensätze und Konfigurationen eines Bundles als unabhängige Variante.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — Quell-Bundle
name string Nein "{source} (copy)" Name der Kopie

Rückgabe: { bundle_id, cloned_stages } – cloned_stages nennt die Stufen (bronze/silver/gold), für die ein fertiger Datensatz zum Kopieren vorlag.

Die Kopie beginnt mit einer byteidentischen Kopie jeder fertigen Stufe und übernimmt dieselben Stufenkonfigurationen (Codierungsauswahl samt Dimensions-Codebuch, Gewichtungsziele, Feldspezifikationen der Verfeinerung). So lässt sie sich unabhängig neu ableiten – etwa mit anderen Gewichtungszielen –, ohne das ursprüngliche Bundle anzutasten. Auf diese Weise vergleichen Sie Varianten (andere Gewichtung, andere Verfeinerung) derselben Rohextraktion.


Löscht ein Bundle samt seiner Datensatzkette.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — Zu löschendes Bundle

Rückgabe: { success: true }

Das Bundle wird vorläufig gelöscht (Soft Delete): Es wird zusammen mit den Datensätzen seiner Kette sofort als gelöscht markiert, die zugrunde liegenden Datendateien räumt kurz darauf ein Wartungsprozess im Hintergrund auf.


Qualität wird am Bundle gemessen, nicht an einzelnen Datensätzen. Drei der vier Repräsentativitätsmaße werden an der neu zuweisbaren aktuellen Strategie des Bundles (current_strategy_id) gemessen – weisen Sie eine zu, sonst lauten sie nicht measured. Ein per Raking angewendetes Kalibrierungsziel ist die Gewichtungsanweisung, kein Benchmark: Würde man das gewichtete Ergebnis an der Vorgabe messen, auf die die Gewichtung zielte, schnitte ein erfolgreicher Raking-Lauf schon konstruktionsbedingt gut ab. Ein reines Benchmark-Kalibrierungsziel ist das Gegenteil: ein externer Wert, auf den die Gewichtung nie zielte, weshalb die Stichprobe daran gemessen wird.

Die Repräsentativitätsauswertung des Bundles in einem Aufruf – eine Stichprobe, verfolgt von der Designabsicht bis zum Ergebnis:

  1. Strategie → Pool (selection) – hat die Stichprobenziehung das Design erreicht? Je Pool, aus dem die Kampagnen des Bundles gezogen haben; zusammengefasst nur, wenn alle dieselbe Strategie verwenden. Bewertet anhand der Werte, die für jedes Mitglied beim Ziehen des Pools festgehalten wurden. Ein Pool ohne vollständige Aufzeichnung ergibt not_measurable (pool_has_no_complete_snapshot)
  2. Strategie → Ist (fielded) – wie weit lag die realisierte Basis vor der Gewichtung daneben? Mit Aufschlüsselung je Kampagne; no_strategy, solange keine Strategie zugewiesen ist
  3. Strategie → Gewichtet (weighted) – hat die Gewichtung das Design wiederhergestellt? Gemessen an derselben Strategie wie (2), sodass sich beide genau um das unterscheiden, was die Gewichtung zurückgewonnen hat
  4. Pool → Ist (fielding_shift) – was hat die Feldphase selbst beigetragen? Bezogen auf den Pool und nur über Umfragen aus dem Pool, beantwortet also eine andere Frage als (1)–(3) und ist kein vierter Punkt auf deren Skala
  5. Antwortqualität (response) – Entropie, Straightlining, Cronbachs Alpha, Akquieszenz, Nonresponse (siehe die Referenz der Qualitätsmetriken)

Daneben beschreibt excluded_profile, was der Vollständigkeitsschwellenwert des Bundles entfernt hat, im Vergleich zu dem, was er behalten hat – verglichen anhand der Faktoren der Strategie selbst, denn zwei Zeilenzahlen können nicht sagen, ob ein Schnitt eine Verzerrung eingeführt hat. Eine leere ausgeschlossene Menge meldet empty statt einer Abweichung von null.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — UUID des Bundles

Rückgabe: { quality: {...} } – die fünf Maße plus excluded_profile sowie Kontext zu Kette und Strategie. Jedes Maß trägt einen state (measured, not_measurable, no_strategy, no_weighted_factors, empty, not_derived, processing, invalidated, error) mit einem reason, sodass ein nicht messbares oder fehlschlagendes Maß nie die anderen verdeckt und eine Null nie für eine Bewertung gehalten wird. Gemessene Payloads enthalten Gesamtscore, zusammengesetzten Fehler und eine Abweichungsanalyse je Faktor; die gewichtete Payload enthält zusätzlich weighting_diagnostics (Designeffekt, effektive Stichprobengröße) – die Varianzkosten der Wiederherstellung. fielded und weighted tragen jeweils benchmarks: Jedes reine Benchmark-Kalibrierungsziel wird je Kategorie mit der ungewichteten und der gewichteten Stichprobe verglichen, neben der Strategiebewertung und nie in deren zusammengesetztem Wert; bewertet wird mit oder ohne aktuelle Strategie. weighted trägt außerdem raking_reached: den gewichteten Anteil jedes Raking-Ziels im Vergleich zu seinem Zielwert. Das zeigt, wie nahe das Raking gekommen ist, und ist nie eine Bewertung. Ein Benchmark auf einer Spalte, auf die das aktuelle Silver per Raking gewichtet wurde (seine Rolle hat sich nach der Ableitung geändert), erscheint bis zur nächsten Ableitung auf weighted unter raking_reached statt unter benchmarks, da diese Gewichte darauf angepasst wurden. comparison_ready ist nur true, solange Bronze und Silver des Bundles beide existieren und ready sind – genau dann antwortet compare_bundle_quality, statt abzulehnen. Ein ausstehendes, fehlgeschlagenes oder ungültig gewordenes Silver hat trotzdem eine ID; lesen Sie daher dieses Flag und nicht die Datensatz-IDs.

Ein Bronze, das unter einer älteren Version des Extraktionsschemas extrahiert wurde, wird nicht bewertet: fielded, fielding_shift, response, excluded_profile und weighted lauten jeweils not_measurable mit dem Grund bronze_schema_stale, bis das Bronze neu extrahiert (create_bronze_dataset) und das Silver erneut abgeleitet wurde. selection liest keinen Datensatz und wird weiterhin bewertet.


Repräsentativitätsvergleich Bronze gegen Silver für die Kette des Bundles, gemessen an der aktuellen Strategie des Bundles. Entscheidend ist das Feld recovery: eine einfache Differenz des gewichteten mittleren Fehlers über die Strategiefaktoren, die auf beiden Seiten gemessen wurden. Gleiche Fehlerreduktionen auf unterschiedlichem absolutem Niveau ergeben so gleiche Werte, und zwei Bundles werden vergleichbar. Haben die beiden Messungen keinen gemeinsamen gemessenen Faktor, ist der Wert null mit einem recovery_reason statt 0.0 – es gab nichts Vergleichbares, und das ist nicht dasselbe, als hätte die Gewichtung nichts bewirkt.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — UUID des Bundles

Rückgabe: { comparison: {...} } mit recovery (dem oben beschriebenen Gesamtwert) und recovery_per_factor – derselben Subtraktion je Faktor, in Fehlereinheiten. Beide sind Fehlerdifferenzen, keine Prozentwerte: Ein positiver Wert bedeutet, dass die Gewichtung den Fehler um diesen Betrag verringert hat. Ein Prozentwert je Faktor lässt sich hier nicht sinnvoll angeben, denn sein Nenner wäre der Bronze-Fehler – genau die Größe, die die Gewichtung gegen null treiben soll. Bronze und Silver müssen zuerst ready sein. Eine noch nicht fertige Kette schlägt mit einem Konfliktfehler fehl (409 mit {"error": "conflict"} über REST), nicht mit einem Validierungsfehler – schließen Sie die Ableitung ab oder starten Sie sie neu und vergleichen Sie dann.

Der eigene state des Vergleichs ist measured, wenn beide Seiten bewertet wurden. Er ist no_strategy, wenn das Bundle keine aktuelle Strategie hat, und not_measurable mit dem Grund bronze_schema_stale, wenn das Bronze unter einer älteren Version des Extraktionsschemas extrahiert wurde. In beiden Fällen sind bronze, silver und recovery null, und der Aufruf ist erfolgreich. Den veralteten Zustand beheben Sie, indem Sie neu extrahieren (create_bronze_dataset) und das Silver erneut ableiten.


Der Codierungsstand der offenen Antworten des Bundles: was codiert werden darf, welche Fragen der Analyst ausgewählt hat und – je ausgewählter Frage – die dafür vorgeschlagenen Dimensionen, ihre Kategorien, welche davon ausgewählt sind und ob der eingeschränkte Pfad ohne Zugangsdaten sie erzeugt hat. Lesen Sie dies, bevor Sie auswählen oder neu ableiten.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — UUID des Bundles

Rückgabe: { candidates, kinds, selected, discovered, units, awaiting_review, coding_outcome, bronze_status, silver_status, pending_review }.

  • candidates – jede Freitext-Einheit, die das Bronze dieses Bundles anbietet, jeweils {unit_key, title, control_type, roster_block_id, columns}. Nur Textarea kommt infrage, und das Erscheinen hier sagt nichts über die Codierung aus: Was die Spalte enthält, ist die Klassifizierung durch den Analysten (kinds), und die Einheit muss klassifiziert sein, bevor sie ausgewählt werden kann. Editbox ist in QML eine numerische Eingabe (sie verlangt ein Minimum und ein Maximum), ihre Antworten sind also Anzahlen und Beträge und kein Text, den ein Codebuch beschreiben kann. Ein Roster ist ein Kandidat, dessen columns die Bronze-Spalten nennen, die er zusammenführt; eine Unterfrage einer QuestionGroup und eine Matrix-Zelle bleiben jeweils eigene Kandidaten.
  • kinds – die Antwortart je Kandidat laut Analyst, ohne Standardwert durchgereicht: descriptive (Fließtext, nach Bedeutung codiert), nominal (ein festes Vokabular, nach exaktem Wert codiert) oder identifier (benennt eine Person oder einen Eintrag, wird nie codiert). Ein Kandidat ohne Eintrag ist nicht klassifiziert und kann nicht ausgewählt werden; null bedeutet, dass noch nichts klassifiziert wurde. Hier schreibgeschützt: Klassifiziert wird in Balansor, und kein Tool schreibt eine Art.
  • selected – die gespeicherte Auswahl der Einheiten, ohne Standardwert durchgereicht: null heißt „noch nicht gewählt“, [] heißt „gewählt: nichts“. Nur Letzteres ist eine Entscheidung, die jemand getroffen hat.
  • discovered – ordnet jeder codierten Einheit {column: dimension label} zu – die Aufzeichnung, welche Spalten die letzte Ableitung tatsächlich ausgegeben hat.
  • units – der Dimensionsstand je Einheit, geschlüsselt nach Einheitsschlüssel. Jeder Eintrag enthält reviewed (hat jemand entschieden, welche Dimensionen zu Spalten werden?), selected (die gewählten Dimensions-IDs; null, solange nicht geprüft, und [] für „geprüft, nichts gewählt“), degraded (die Runde stammt aus dem Pfad ohne Zugangsdaten – daran unterscheidet man ein echtes Ergebnis mit einer Dimension von der einen Dimension dieses Pfads), answered / missing und dimensions. Jede Dimension enthält ihre Slot-id, label, den eingefrorenen column-Namen, ihre origin (proposed / authored / degraded oder verbatim für die eine Exaktwert-Dimension einer nominalen Einheit), ob sie selected ist, ihre categories als {id, label} (nur {id} bei einer verbatim-Dimension, deren Kategorie -1 das reservierte Sonstiges ist), die counts der Zuordnungen je Spalte und overlap – wie viele der eigenen Kategorien dieser Dimension eine durchschnittliche Antwort zusätzlich erfüllt hat. Dieser Wert sagt etwas über das Codebuch aus, nicht über die Befragten.
  • awaiting_review – die ausgewählten Einheiten, deren Dimensionen noch niemand geprüft hat. Diese Einheiten erzeugen keine codierte Spalte, während die Ableitung trotzdem erfolgreich ist; deshalb werden sie ausdrücklich genannt statt erschlossen.
  • coding_outcome – was die letzte Ableitung versucht und wofür sie keine Spalte erhalten hat: {attempted, coded, lost}, jeder lost-Eintrag {unit_key, kind} mit kind als not_codable, unclassified oder no_column. Scheitert eine Einheit, scheitert die Ableitung nicht – die Spalten der anderen Einheiten sind ein verwertbares Ergebnis –, ohne dieses Feld gäbe es also gar kein Signal für den Verlust: Der Datensatz steht auf ready, und discovered oben nennt die Einheit weiterhin aus einer früheren Ableitung, weil diese Zuordnung bewusst über Läufe hinweg erhalten bleibt. Prüfen Sie dies, bevor Sie ein Silver als vollständig melden. null bedeutet, dass die Ableitung nichts aufgezeichnet hat, und das ist nicht dasselbe, wie nichts verloren zu haben: Jedes Silver, das vor Einführung dieses Felds abgeleitet wurde, befindet sich in diesem Zustand, und erst eine leere lost-Liste sagt aus, dass ein Lauf nichts verloren hat. Der Grund eines Verlusts wird bewusst auf kind reduziert – die zugrunde liegende Meldung kann beliebiger Text sein, und diese Schnittstelle gibt nie etwas aus, das die Antwort einer befragten Person enthalten könnte.
  • bronze_status steht neben silver_status, weil leere candidates zweierlei bedeuten können – es wurde noch kein Bronze extrahiert, oder dieser Fragebogen stellt überhaupt keine Freitextfrage – und die Liste allein das nicht unterscheiden kann.
  • pending_review – true, solange eine der beiden Entscheidungen aussteht: ein fertiges Bronze mit Kandidaten, aber ohne Auswahl der Einheiten, oder eine ausgewählte Einheit, deren Dimensionen noch geprüft werden müssen.

Über diese Schnittstelle gelangt nie wörtlicher Antworttext von Befragten nach außen. Eine Kategorie wird nur als ID und Bezeichnung ausgegeben, und die Beispielantworten je Dimension werden gar nicht ausgegeben – beides existiert für die eigene Prüfoberfläche der Forschenden in Balansor. Die Kategoriebezeichnungen einer nominalen Einheit sind Antworten von Befragten, daher werden ihre Kategorien als IDs mit Anzahlen und ohne Bezeichnung ausgegeben.

Die Auswahl der Einheiten ist über MCP/REST mit set_coding_selection (siehe unten) schreibbar, denn sie ist eine Einschätzung über die Frage, getroffen, bevor irgendein Modell gelaufen ist. Eine Spalte klassifizieren, Dimensionen auswählen, umbenennen und ihre Kategorien bearbeiten ist es nicht und wird es auch nicht werden – das sind Einschätzungen über die eigenen Daten der Forschenden und über generierte Inhalte, und dafür gibt es bewusst auf keinem Transportweg ein Tool. Ein Agent, der die Pipeline steuert, sollte pending_review: true und die Liste awaiting_review seinem Benutzer vorlegen, statt darüber hinweg neu abzuleiten. Den vollständigen Ablauf beschreibt Codierung offener Antworten.


Legt fest, welche Freitext-Einheiten dieses Bundle in Kategorien codiert. Die Auswahl ist eine Analyseentscheidung je Bundle in der Silver-Konfiguration, keine Eigenschaft des Fragebogens, und sie kann nur Spalten nennen, die bereits als descriptive oder nominal klassifiziert wurden (siehe kinds bei get_bundle_coding).

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — UUID des Bundles
selected string[] Ja — Vollständige Ersatzmenge der Codierungs-Einheitsschlüssel, im Vokabular, das candidates von get_bundle_coding anbietet

Rückgabe: { bundle_id, selected }.

Erfordert Managerrechte und einen identifizierten Benutzer – Aufrufe nur mit Service-Token werden abgelehnt, sodass kein unbeaufsichtigter Lauf eine Auswahl treffen kann, für die niemand einsteht. Legen Sie den Forschenden die Kandidaten und ihre kinds vor und schreiben Sie deren Antwort, statt selbst für sie zu wählen. Eine nicht klassifizierte oder als identifier klassifizierte Einheit wird mit Begründung abgelehnt, und das Tool schreibt nichts. Ein Agent kann nicht klassifizieren; bitten Sie die Forschenden daher, dies in der Codierungsauswahl der Silver-Seite zu tun.

Die Liste ist eine vollständige Ersatzmenge, keine Differenz, und eine leere Liste ist eine Entscheidung („nichts codieren“), kein Weglassen. Ein Schlüssel, der kein Kandidat im Bronze dieses Bundles ist, wird abgelehnt – auch der Spaltenname einer einzelnen Roster-Iteration, der wie eine echte Spalte aussieht, aber nichts zusammenführen würde. Lesen Sie die Kandidatenliste erneut und wählen Sie stattdessen den Schlüssel der zusammengeführten Einheit. Eine geänderte Auswahl ist eine Silver-Eingabe: Sie macht ein fertiges Silver und alles Nachgelagerte ungültig und gilt ab der nächsten Ableitung (eine bereits laufende Ableitung behält die Auswahl, mit der sie begonnen hat).

Das Abwählen einer Einheit, auf der ein Kalibrierungsziel beruht, wird hier nicht abgelehnt – dieser Konflikt zeigt sich erst bei der Ableitung, die mit weighting_factor_deselected ablehnt, sodass sich die Konfiguration in beliebiger Reihenfolge korrigieren lässt.


Weist dem Bundle seine aktuelle Stichprobenstrategie zu (oder entfernt sie) – den Maßstab, an dem selection, fielded und weighted messen. Erfordert Managerrechte und einen identifizierten Benutzer (Aufrufe nur mit Service-Token werden abgelehnt); für die Zuweisung einer Strategie ist zudem Zugriff auf das Projekt der Strategie nötig. Eine Neuzuweisung berechnet alle drei Maße neu; die Kalibrierungsziele, die die Gewichtungsanweisung bilden, bleiben unberührt.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — UUID des Bundles
strategy_id string Nein null Zuzuweisende Strategie; null entfernt die Zuweisung

Rückgabe: { bundle_id, strategy_id, strategy_name }

Eine Stichprobenstrategie enthält nur Faktoren der Befragten. Um die Verteilung einer Umfrageantwort in der Stichprobe an einem externen Wert zu messen (etwa die Parteipräferenz an einem Wahlergebnis), fügen Sie diesen Wert dem Bundle mit set_calibration_targets als reines Benchmark-Kalibrierungsziel hinzu.


Bearbeitet die Kalibrierungsziele des Bundles – die editierbare Vorgabe, auf die derive_silver/code_open_ends gewichten, plus die reinen Benchmark-Ziele, an denen die Bundle-Qualität die Stichprobe misst. Ein Raking-Ziel ist die Gewichtungsanweisung, nicht der Benchmark: Das gewichtete Maß wird an der aktuellen Strategie gemessen, sodass ein Satz von Kalibrierungszielen, der das Design verfehlt, als Abstand zu diesem Design erscheint und nicht als perfekter Score gegenüber dem eigenen Ziel. Die Ziele werden einmalig aus den Faktoren der aktuellen Strategie vorbelegt, wenn Forschende die Silver-Stufe in Balansor zum ersten Mal öffnen; danach sind sie von der aktuellen Strategie unabhängig. Erfordert Managerrechte und einen identifizierten Benutzer.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — UUID des Bundles
weighting object Nein — Vollständiger Ersatzblock {use_strategy_factors, factors}
factors array Nein — Kurzform für weighting={factors, use_strategy_factors: false} – wer eine reine Faktorliste übergibt, verzichtet damit bereits darauf, der Live-Strategie zu folgen

Jeder Faktor ist {column, target_distribution, name?, factor_type?, bucket_ranges?, role?} – column nennt eine einfache Spalte, die im codierten Datenrahmen bereits existiert (eine Bronze-Antwort- oder Befragtenattribut-Spalte, eine codierte Dimension einer offenen Antwort oder einen Indikator einer Mehrfachauswahl-Option), und target_distribution ordnet jedem Wert seinen Zielanteil zu (Summe 1.0).

role ist raked (Standard: Silver gewichtet auf das Ziel hin) oder benchmark (es wird nicht darauf gewichtet; get_bundle_quality misst die erhobene und die gewichtete Stichprobe daran). Jede Zielspalte kann beide Rollen annehmen, auch Befragtenattribute. Der Aufruf ersetzt die gesamte Liste. Lesen Sie daher die aktuellen Ziele mit get_bundle (dort nennt jedes Ziel seine role) und senden Sie jedes mit seiner Rolle zurück: Ein Ziel ohne role wird als Raking-Ziel gespeichert. Eine Liste, in der jedes Ziel ein Benchmark ist, wird mit weighting_factor_none_raked abgelehnt, weil das Raking nichts hätte, worauf es gewichten könnte.

Ein Ziel kann auch ein benutzerdefiniertes Attribut der Befragten nennen. Seine Spalte ist _custom_<key>, wobei <key> der Schlüssel des Attributs im Eintrag der befragten Person ist (_custom_region für custom_attributes.region). Ein benutzerdefiniertes Attribut wird nur dann in einen Datensatz extrahiert, wenn ein Faktor einer Stichprobenstrategie oder ein Kalibrierungsziel des Bundles es nennt. Über ein Ziel gelangt ein neues Attribut also in den Datensatz: Es muss noch nicht im Bronze enthalten sein. Welche Attribute das Bronze enthält, lesen Sie aus custom_attribute_keys von get_dataset_schema.

Rückgabe: { bundle_id, weighting, warnings }. warnings ist eine Liste von Hinweisen zu einem erfolgreichen Speichervorgang und leer, wenn es nichts zu sagen gibt. Sie enthält einen Eintrag, wenn die gespeicherten Ziele auf ein benutzerdefiniertes Attribut gewichten, mit dem das Bronze des Bundles nicht extrahiert wurde: Extrahieren Sie das Bronze neu (create_bronze_dataset), bevor Sie Silver ableiten, sonst wird die Ableitung mit weighting_attributes_not_extracted abgelehnt. Trägt keine befragte Person des Bundles ein Attribut dieses Namens, ist der Name falsch; korrigieren Sie ihn stattdessen. Ohne Bronze gibt es keine Warnung, weil die erste Extraktion jedes genannte Attribut schreibt. Der Text ist derselbe Satz, den Forschende beim Speichern der Ziele in Balansor sehen.

Jeder Speichervorgang prüft die Schlüssel jedes Ziels anhand des Fragebogens des Bundles, für beide Rollen, in Balansor wie über MCP/REST. Ein Schlüssel auf einer Antwortspalte muss eine der Optionen dieser Frage benennen, per Optionscode ("1") oder Optionsbezeichnung ("Yes"); ein vertippter Code bei einem Benchmark würde sonst als Phantom-Abweichung bewertet.

Fall Ergebnis
Ein Schlüssel, den die Frage nicht anbietet Abgelehnt (400), mit Nennung des Ziels, der Spalte, der nicht passenden Schlüssel sowie der akzeptierten Codes und Bezeichnungen: Target 'Recommend' targets keys that are neither an option code nor an option label of 'q_cp07': 'Exit interview' offers no option ['Maybe'] and accepts, by code or label: 1 (Yes), 2 (No).
Eine Spalte, deren Optionen nicht jeden Wert benennen (ein Schieberegler, Freitext), oder ein Fragebogen, der sich nicht lesen lässt Gespeichert, mit einem warnings-Eintrag, dass die Schlüssel nicht geprüft wurden
Eine Befragtenattribut-Spalte (_demographic_*, _custom_*), eine codierte Dimension einer offenen Antwort oder ein Ziel mit Klassen (Buckets) Von dieser Regel nicht geprüft (die Vorabprüfung unten und die Ableitung gelten weiterhin)

Folgende Bedingungen werden mit einem Konfliktfehler abgelehnt, bevor etwas geschrieben wird – dieselbe Vorabprüfung, die auch die Silver-Ableitung selbst durchführt:

  • ein Ziel, das eine Codierungskategorie nennt, die abgelehnt wurde oder inzwischen aus dem letzten Codierungslauf verschwunden ist;
  • ein Ziel, das eine rohe Antwortspalte einer Mehrfachauswahl nennt. Diese Spalte speichert eine Kombination der gewählten Optionen, sodass jede beobachtete Kombination zu einer eigenen Gewichtungszelle würde. Zielen Sie stattdessen auf die Indikatorspalten je Option – ein Ziel pro Option;
  • zwei Ziele auf derselben Spalte oder mit demselben Namen;
  • eine Liste, in der jedes Ziel ein reiner Benchmark ist, während die Ziele den gesamten Gewichtungssatz bilden (use_strategy_factors ist false, wie bei der Kurzform factors), sodass das Raking nichts hätte, worauf es gewichten könnte (weighting_factor_none_raked). Ein Bundle, das weiterhin seiner Strategie folgt, gewichtet per Raking auf die Faktoren der Strategie und darf ausschließlich Benchmarks enthalten.

Zeigt eine Vorschau, wie die Kalibrierungsziele eines anderen Bundles in dieses kopiert würden. Das Tool meldet, welche Ziele der Quelle zu diesem Bundle passen und welche nicht, und schreibt nichts. Zum Kopieren führen Sie addable mit den aktuellen Zielen dieses Bundles zusammen und speichern das Ergebnis mit set_calibration_targets, dessen Prüfungen beim Speichern erneut laufen. Erfordert Managerrechte, Schreibzugriff auf dieses Bundle und Lesezugriff auf das Quell-Bundle; eine Quelle, die Sie nicht lesen dürfen, antwortet genau wie eine nicht vorhandene. Die Silver-Seite in Balansor bietet dieselbe Aktion als Aus einem anderen Bundle kopieren an; sie füllt den Editor und speichert erst, wenn Sie speichern.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — Das Bundle, in das die Ziele kopiert würden
source_bundle_id string Ja — Das Bundle, dessen Ziele kopiert werden

Rückgabe: { bundle_id, source_bundle_id, addable, rejected }. addable enthält die passenden Ziele, jeweils mit ihrer role. rejected enthält die übrigen, jeweils mit name, column, role, einem lesbaren detail und einem reason:

reason Bedeutung
no_bronze Dieses Bundle hat noch kein Bronze, es gibt also keine Spaltenliste zum Abgleich; extrahieren Sie zuerst das Bronze
column_missing Die Spalte ist weder im Bronze dieses Bundles noch ein Befragtenattribut (_demographic_<field>, _custom_<key>) noch eine codierte Dimension in seinem Codebuch
unknown_code Ein Schlüssel ist keine Option, die der Fragebogen dieses Bundles für diese Spalte anbietet (die Prüfung der Antwortcodes)
preflight:<code> Das Ziel würde hier an einer Bedingung der Vorabprüfung scheitern, z. B. preflight:weighting_factor_duplicated, wenn dieses Bundle bereits ein Ziel mit diesem Namen oder dieser Spalte hat. Eine Liste nur aus Benchmarks ist hier kein Grund: Das wird an der Liste beurteilt, die Sie am Ende speichern

Extraktion, Codierung + Gewichtung, Verfeinerung und Export werden alle mit einer bundle_id über die Datensatz-Tools aufgerufen. Ein typischer Ablauf:

  1. create_bundle → bundle_id erhalten
  2. create_bronze_dataset(bundle_id) → Bronze extrahieren
  3. code_open_ends(bundle_id) (oder sein Alias derive_silver) → codiert offene Antworten und gewichtet dann auf die Kalibrierungsziele; ergibt Silver
  4. create_gold_dataset(bundle_id, operations=[...]) → Silver mithilfe des Operationskatalogs zu Gold verfeinern
  5. export_dataset(dataset_id, format) → eine beliebige fertige Stufe exportieren
  6. get_bundle_quality(bundle_id) → die Repräsentativitätsauswertung zu jedem Zeitpunkt

Die Schritte 2 bis 4 in einem einzigen Aufruf. Jeder Schritt ist dasselbe oben aufgeführte Tool, es entstehen also dieselben Datensätze und dieselben Audit-Ereignisse, und jede Ablehnung, die eine einzelne Stufe liefern würde, erhalten Sie hier unverändert – plus stopped_at_step, das angibt, aus welcher Stufe ein Abbruch stammt.

Parameter Typ Erforderlich Standard Beschreibung
bundle_id string Ja — Das Bundle, dessen Kette ausgeführt wird
include_demographics boolean Nein true Die extrahierten Bronze-Zeilen um demografische Merkmale der Befragten anreichern. false wird mit named_attributes_require_enrichment abgelehnt, wenn das Bundle ein benutzerdefiniertes Attribut nennt (siehe create_bronze_dataset)
gold_name string Nein — Name des Gold-Datensatzes. Standard ist "{bundle_name} — Gold"; die Gold-Konfiguration selbst stammt weiterhin aus der gespeicherten Konfiguration des Bundles

Rückgabe: { task_id, status, step, bundle_id, bronze_dataset_id, silver_dataset_id }. Fragen Sie task_id mit get_task_status ab, bis der Lauf completed, partial oder failed erreicht. Die Abfrage meldet die Stufe, in der sich der Lauf befindet, und nach Abschluss die Datensatz-ID jeder Stufe (bronze_dataset_id, silver_dataset_id, gold_dataset_id) sowie gold_skipped: die Einträge der gespeicherten Gold-Konfiguration, die der Build übergangen hat, weil das Silver ihre Spalte nicht mehr enthält – in der Form, die create_gold_dataset als skipped zurückgibt. Die Liste ist leer, wenn nichts übergangen wurde.

Während Sie warten, geschehen nur die Bronze-Extraktion und das Einreihen der Silver-Ableitung. Gold kann erst beginnen, wenn das Silver ready ist – bis dahin vergehen Minuten mit Codierung und Gewichtung. Der Gold-Schritt läuft daher eigenständig nach Abschluss der Ableitung, und der Lauf bleibt durchgehend abfragbar.

Zwei Dinge sollten Sie wissen:

  • Ein Abbruch lässt das Gebaute bestehen. Ein Bronze ist das Bronze des Bundles, ob nun ein Gold folgte oder nicht; es wird also nichts rückgängig gemacht. Ein erneuter Lauf setzt auf denselben Zeilen auf, statt eine Stufe zu duplizieren.
  • Die Berechtigungen der gesamten Kette werden geprüft, bevor etwas gebaut wird. Die Kette berührt sowohl die Abonnementstufe Gateway als auch die des KI-Assistenten (die Codierungsableitung benötigt Letztere). Ein Abonnement, das nur die erste abdeckt, wird daher von vornherein abgelehnt, statt ein Bronze zu erhalten, aus dem es nichts ableiten kann.