Outils de lot — référence des outils MCP
Un lot associe un projet, un questionnaire et un sous-ensemble non vide de campagnes de ce questionnaire à une seule chaîne linéaire de jeux de données Bronze → Silver → Gold. Ces outils gèrent le lot lui-même et son bilan de qualité ; pour les opérations d’étape propres au lot (extraction, codage et pondération, affinage, export), voir Outils de jeu de données.
create_bundle
Section intitulée « create_bundle »Crée un lot de pipeline.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
string |
Oui | — | Nom du lot |
project_id |
string |
Oui | — | Projet propriétaire (accès en écriture requis) |
questionnaire_id |
string |
Oui | — | Questionnaire dont les enquêtes terminées alimentent le Bronze |
campaign_ids |
string[] |
Oui | — | Sous-ensemble de campagnes à mesurer. Doit en nommer au moins une : la base de mesure d’un lot est constituée des enquêtes des campagnes qu’il sélectionne |
Renvoie : { bundle_id, name }
list_bundles
Section intitulée « list_bundles »Liste les lots de pipeline, avec un filtre facultatif sur un projet.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
project_id |
string |
Non | — | Limite aux lots appartenant à ce projet |
Renvoie :
{ "items": [ { "id": "...", "name": "Wave 1", "project_id": "...", "questionnaire_id": "...", "campaign_ids": ["..."], "chain": { "bronze": {"dataset_id": "...", "status": "ready"}, "silver": {"dataset_id": "...", "status": "processing"} } } ], "count": 1}Les clés de chain sont les étapes qui ont un jeu de données (bronze/silver/gold) ; une étape encore dépourvue de jeu de données est simplement absente — considérez-la comme missing.
clone_bundle
Section intitulée « clone_bundle »Copie en profondeur les jeux de données prêts et les recettes d’un lot dans une variante indépendante.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | Lot source |
name |
string |
Non | "{source} (copy)" |
Nom du clone |
Renvoie : { bundle_id, cloned_stages } — cloned_stages indique les étapes (bronze/silver/gold) qui disposaient d’un jeu de données prêt à copier.
Le clone part d’une copie octet pour octet de chaque étape prête et reprend les mêmes recettes d’étape (sélection de codage et son livre de codes de dimensions, cibles de pondération, spécifications des champs d’affinage) : il peut ainsi être redérivé indépendamment — par exemple avec d’autres cibles de pondération — sans toucher au lot d’origine. C’est ainsi que l’on compare des variantes (pondération différente, affinage différent) d’une même extraction brute.
delete_bundle
Section intitulée « delete_bundle »Supprime un lot et sa chaîne de jeux de données.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | Lot à supprimer |
Renvoie : { success: true }
La suppression est logique : le lot et les jeux de données de sa chaîne sont marqués comme supprimés immédiatement ; leurs fichiers de données sous-jacents sont nettoyés peu après par un processus de maintenance en arrière-plan.
Outils de qualité
Section intitulée « Outils de qualité »La qualité se mesure au niveau du lot, et non sur chaque jeu de données. Trois des quatre mesures de représentativité sont évaluées par rapport à la stratégie actuelle du lot (current_strategy_id), qui peut être réaffectée : affectez-en une avant d’attendre qu’elles soient à l’état measured. Une cible de calage calée est la consigne de pondération, pas une référence : évaluer le résultat pondéré par rapport à la spécification que la pondération visait donnerait mécaniquement un bon score à tout calage réussi. Une cible de calage de référence uniquement est l’inverse : un chiffre extérieur que la pondération n’a jamais visé, et par rapport auquel l’échantillon est donc évalué.
get_bundle_quality
Section intitulée « get_bundle_quality »Le bilan de représentativité du lot en un seul appel — un même échantillon suivi de l’intention de plan jusqu’au livrable :
- Stratégie → Vivier (
selection) — l’échantillonnage a-t-il atteint le plan prévu ? Calculé pour chaque vivier dans lequel les campagnes du lot ont puisé, et agrégé uniquement lorsqu’elles s’accordent sur une même stratégie. Évalué à partir des valeurs de chaque membre enregistrées au moment du tirage du vivier ; un vivier sans enregistrement complet renvoienot_measurable(pool_has_no_complete_snapshot) - Stratégie → Réel (
fielded) — de combien la base réalisée s’écartait-elle avant pondération ? Avec une ventilation par campagne ;no_strategytant qu’aucune stratégie n’est affectée - Stratégie → Pondéré (
weighted) — la pondération a-t-elle rétabli le plan ? Évalué par rapport à la même stratégie que (2), de sorte que l’écart entre les deux correspond exactement à ce que la pondération a récupéré - Vivier → Réel (
fielding_shift) — quelle a été la contribution du terrain lui-même ? Rapporté au vivier, et calculé sur les seules enquêtes issues du vivier : cette mesure répond donc à une autre question que (1)–(3) et n’est pas un quatrième point sur la même échelle - Qualité des réponses (
response) — entropie, straightlining (réponses en ligne droite), alpha de Cronbach, acquiescement, non-réponse (voir la Référence des indicateurs de qualité)
En complément, excluded_profile décrit ce que le seuil de complétude propre au lot a écarté, par rapport à ce qu’il a conservé — comparé sur les facteurs de la stratégie elle-même, car deux nombres de lignes ne peuvent pas dire si une coupe a introduit un biais. Un ensemble exclu vide renvoie empty plutôt qu’un écart nul.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | UUID du lot |
Renvoie : { quality: {...} } — les cinq mesures, plus excluded_profile et le contexte de chaîne et de stratégie. Chacune porte un state (measured, not_measurable, no_strategy, no_weighted_factors, empty, not_derived, processing, invalidated, error) accompagné d’une reason : une mesure impossible à calculer ou en échec ne masque donc jamais les autres, et un zéro n’est jamais pris pour une note. Les mesures calculées comprennent le score global, l’erreur composite et une analyse des écarts par facteur ; la mesure pondérée porte aussi weighting_diagnostics (effet de plan, taille d’échantillon effective) — le coût en variance de la récupération. fielded et weighted portent chacune benchmarks : chaque cible de calage de référence uniquement, évaluée catégorie par catégorie sur l’échantillon non pondéré et sur l’échantillon pondéré, à côté de la note de la stratégie et jamais dans son composite ; ces cibles sont évaluées qu’il y ait ou non une stratégie actuelle. weighted porte aussi raking_reached : la part pondérée de chaque cible calée face à sa cible, qui montre à quel point le calage s’en est approché et n’est jamais une note. Une cible de référence portant sur une colonne sur laquelle le Silver actuel a été calé (son rôle a changé après la dérivation) apparaît dans raking_reached et non dans benchmarks de weighted jusqu’à la prochaine dérivation, puisque ces poids ont été ajustés sur elle. comparison_ready vaut true uniquement tant que le Bronze et le Silver du lot existent tous deux et sont ready, c’est-à-dire exactement quand compare_bundle_quality répond au lieu de refuser ; un Silver en attente, en échec ou invalidé a toujours un identifiant : lisez donc cet indicateur plutôt que les identifiants des jeux de données.
Un Bronze extrait selon une ancienne version du schéma d’extraction n’est pas évalué : fielded, fielding_shift, response, excluded_profile et weighted valent chacune not_measurable, avec la raison bronze_schema_stale jusqu’à ce que le Bronze soit réextrait (create_bronze_dataset) et le Silver dérivé de nouveau. selection ne lit aucun jeu de données et reste évaluée.
compare_bundle_quality
Section intitulée « compare_bundle_quality »Comparaison de représentativité Bronze/Silver pour la chaîne du lot, évaluée par rapport à la stratégie actuelle du lot. Le chiffre à lire est son champ recovery : une simple différence de l’erreur moyenne pondérée sur les facteurs de la stratégie mesurés des deux côtés ; des réductions d’erreur égales à des niveaux absolus différents donnent ainsi des chiffres égaux, et deux lots sont comparables. Lorsque les deux mesures n’ont aucun facteur mesuré en commun, il vaut null avec une recovery_reason plutôt que 0.0 — rien n’était comparable, ce qui n’équivaut pas à une pondération qui n’aurait rien apporté.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | UUID du lot |
Renvoie : { comparison: {...} } avec recovery (le chiffre global décrit ci-dessus) et recovery_per_factor — la même soustraction par facteur, en unités d’erreur. Ce sont toutes deux des différences d’erreur, et non des pourcentages : un chiffre positif signifie que la pondération a réduit l’erreur d’autant. Un pourcentage par facteur n’aurait pas de sens ici, car son dénominateur serait l’erreur du Bronze, précisément la quantité que la pondération cherche à ramener vers zéro. Le Bronze et le Silver doivent d’abord être tous deux ready ; une chaîne pas encore prête échoue avec une erreur de conflit (409 avec {"error": "conflict"} en REST) plutôt qu’avec une erreur de validation — terminez ou relancez la dérivation, puis comparez.
Le state de la comparaison elle-même vaut measured lorsque les deux côtés ont été évalués. Il vaut no_strategy lorsque le lot n’a pas de stratégie actuelle, et not_measurable avec la raison bronze_schema_stale lorsque le Bronze a été extrait selon une ancienne version du schéma d’extraction ; dans les deux cas, bronze, silver et recovery valent null et l’appel réussit. Pour sortir de l’état obsolète, réextrayez le Bronze (create_bronze_dataset) et dérivez de nouveau le Silver.
get_bundle_coding
Section intitulée « get_bundle_coding »L’état du codage des questions ouvertes du lot : ce qui peut être codé, les questions que l’analyste a choisies et — pour chaque question choisie — les dimensions proposées, leurs catégories, celles qui sont sélectionnées et si elles proviennent du mode dégradé sans identifiants. Consultez-le avant de sélectionner ou de redériver.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | UUID du lot |
Renvoie : { candidates, kinds, selected, discovered, units, awaiting_review, coding_outcome, bronze_status, silver_status, pending_review }.
candidates— chaque unité de texte libre que propose le Bronze de ce lot, sous la forme{unit_key, title, control_type, roster_block_id, columns}. SeulTextareaest admis, et figurer ici n’implique rien quant au codage : la nature du contenu de la colonne relève de la classification de l’analyste (kinds), et l’unité doit être classée avant de pouvoir être sélectionnée.Editboxest une saisie numérique en QML (il exige un minimum et un maximum) : ses réponses sont des effectifs et des montants, non du texte qu’un livre de codes pourrait décrire. Un Roster constitue un seul candidat, dontcolumnsnomme les colonnes Bronze qu’il regroupe ; une sous-question de QuestionGroup et une cellule de Matrix restent chacune un candidat à part entière.kinds— le type de réponse attribué par l’analyste à chaque candidat, transmis sans valeur par défaut :descriptive(texte rédigé, codé selon le sens),nominal(vocabulaire fixe, codé sur la valeur exacte) ouidentifier(désigne une personne ou un enregistrement, jamais codé). Un candidat sans entrée est non classé et ne peut pas être sélectionné ;nullsignifie que rien n’a été classé. En lecture seule ici : l’analyste effectue la classification dans Balansor, et aucun outil n’écrit de type.selected— le choix d’unités enregistré, transmis sans valeur par défaut :nullsignifie « pas encore choisi »,[]signifie « choisi : rien ». Seul le second est une décision prise par quelqu’un.discovered— associe chaque unité codée à{column: dimension label}: la trace des colonnes que la dernière dérivation a effectivement produites.units— l’état des dimensions par unité, indexé par clé d’unité. Chaque entrée portereviewed(quelqu’un a-t-il décidé quelles dimensions deviennent des colonnes ?),selected(les identifiants des dimensions choisies,nulltant que rien n’a été revu et[]pour « revu, rien choisi »),degraded(cette série de dimensions provient du mode sans identifiants — c’est ce qui distingue un véritable résultat à une seule dimension de l’unique dimension produite par ce mode),answered/missingetdimensions. Chaque dimension porte sonidd’emplacement, sonlabel, le nom figé de sacolumn, sonorigin(proposed/authored/degraded, ouverbatimpour l’unique dimension à valeur exacte d’une unité nominale), son étatselected, sescategoriessous la forme{id, label}({id}seulement pour une dimensionverbatim, dont la catégorie-1est l’autre réservée), lescountsd’affectation par colonne etoverlap— le nombre de catégories propres à cette dimension qu’une réponse moyenne franchit aussi, ce qui renseigne sur le livre de codes plutôt que sur les répondants.awaiting_review— les unités sélectionnées dont personne n’a revu les dimensions. Ces unités ne produisent aucune colonne codée alors que la dérivation réussit quand même : c’est pourquoi la liste est explicite plutôt que déduite.coding_outcome— ce que la dernière dérivation a tenté sans en obtenir de colonne :{attempted, coded, lost}, chaque entrée delostétant{unit_key, kind}aveckindparminot_codable,unclassifiedouno_column. L’échec d’une unité ne fait pas échouer la dérivation — les colonnes des autres unités représentent un vrai travail — si bien que, sans ce champ, la perte ne laisserait aucune trace : le jeu de données afficheready, etdiscoveredci-dessus nomme encore l’unité issue d’une dérivation antérieure, car cette correspondance est volontairement conservée d’une exécution à l’autre. Vérifiez-le avant de déclarer un Silver complet.nullsignifie que la dérivation n’a rien enregistré, ce qui n’est pas la même chose que n’avoir rien perdu : tout Silver dérivé avant l’existence de ce champ est dans cet état, et c’est une listelostvide qui indique qu’une exécution n’a rien perdu. La cause d’une perte est volontairement réduite àkind: le message sous-jacent peut être un texte quelconque, et cette interface n’émet jamais rien qui puisse contenir la réponse d’un répondant.bronze_statusfigure à côté desilver_statusparce qu’une listecandidatesvide peut signifier deux choses différentes — aucun Bronze n’a encore été extrait, ou ce questionnaire ne pose aucune question ouverte — et que la liste seule ne permet pas de les distinguer.pending_review—truetant que l’une ou l’autre décision reste en suspens : un Bronze prêt avec des candidats mais sans sélection d’unités, ou une unité sélectionnée en attente de revue de ses dimensions.
Aucun verbatim de répondant ne sort jamais par cette interface. Une catégorie n’est exposée que par son identifiant et son libellé, et les exemples de réponses par dimension ne sont pas exposés du tout — les deux sont réservés à l’espace de revue du chercheur dans Balansor. Les libellés de catégorie d’une unité nominale sont des réponses de répondants : ses catégories sont donc exposées sous forme d’identifiants avec effectifs, sans libellé.
La sélection d’unités est accessible en écriture via MCP/REST avec set_coding_selection ci-dessous, car il s’agit d’un jugement sur la question, porté avant l’exécution de tout modèle. Classer une colonne, sélectionner des dimensions, les renommer et modifier leurs catégories ne l’est pas, et ne le sera pas — ce sont des jugements sur les propres données du chercheur et sur du contenu généré, et il n’existe délibérément aucun outil pour cela, quel que soit le canal. Un agent qui pilote le pipeline doit signaler pending_review: true et la liste awaiting_review à son utilisateur plutôt que de redériver en passant outre. Voir Codage des questions ouvertes pour le flux complet.
set_coding_selection
Section intitulée « set_coding_selection »Définit les unités de texte libre que ce lot code en catégories. Ce choix est une décision d’analyse propre au lot, portée par la recette Silver, et non une propriété du questionnaire ; il ne peut nommer que des colonnes que l’analyste a déjà classées comme descriptive ou nominal (voir kinds dans get_bundle_coding).
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | UUID du lot |
selected |
string[] |
Oui | — | Ensemble de remplacement complet des clés d’unité de codage, dans le vocabulaire que proposent les candidates de get_bundle_coding |
Renvoie : { bundle_id, selected }.
Nécessite les droits de gestionnaire et un utilisateur identifié — les appels munis d’un seul jeton de service sont rejetés, afin qu’une exécution sans surveillance ne puisse pas effectuer une sélection sans que personne n’en réponde. Présentez les candidats et leurs kinds au chercheur et enregistrez la réponse qu’il vous donne, plutôt que de choisir à sa place. Une unité non classée ou classée identifier est refusée avec sa raison, et l’outil n’écrit rien ; un agent ne pouvant pas classer, demandez au chercheur de le faire dans le sélecteur de codage de la page Silver.
La liste est un ensemble de remplacement complet, et non un différentiel ; une liste vide est une décision (« ne rien coder »), pas un oubli. Une clé qui n’est pas un candidat du Bronze de ce lot est refusée — y compris le nom de colonne d’une seule itération de Roster, qui ressemble à une vraie colonne mais ne regrouperait rien ; relisez la liste des candidats et sélectionnez plutôt la clé d’unité regroupée. Un changement de sélection est une entrée du Silver : il invalide un Silver prêt et tout ce qui en découle, et s’applique à la prochaine dérivation (une dérivation déjà en cours conserve la sélection avec laquelle elle a démarré).
Désélectionner une unité sur laquelle repose une cible de calage n’est pas refusé ici : ce conflit apparaît lors de la dérivation, qui refuse avec weighting_factor_deselected, afin que la recette puisse être corrigée dans un ordre ou dans l’autre.
assign_bundle_strategy
Section intitulée « assign_bundle_strategy »Affecte (ou retire) la stratégie d’échantillonnage actuelle du lot — la référence par rapport à laquelle selection, fielded et weighted sont évaluées. Nécessite les droits de gestionnaire et un utilisateur identifié (les appels munis d’un seul jeton de service sont rejetés) ; affecter une stratégie exige aussi l’accès au projet de cette stratégie. La réaffecter recalcule ces trois mesures ; cela ne touche pas aux cibles de calage, qui constituent la consigne de pondération.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | UUID du lot |
strategy_id |
string |
Non | null |
Stratégie à affecter ; null retire l’affectation |
Renvoie : { bundle_id, strategy_id, strategy_name }
Une stratégie d’échantillonnage ne contient que des facteurs de répondant. Pour évaluer l’échantillon par rapport à un chiffre extérieur portant sur une réponse à l’enquête (par exemple la préférence partisane face à un résultat électoral), ajoutez-le à ce lot comme cible de calage de référence uniquement avec set_calibration_targets.
set_calibration_targets
Section intitulée « set_calibration_targets »Modifie les cibles de calage du lot — la spécification modifiable vers laquelle derive_silver/code_open_ends pondèrent, ainsi que les cibles de référence uniquement par rapport auxquelles la qualité du lot est évaluée. Une cible calée est la consigne de pondération, pas la référence : la mesure pondérée est évaluée par rapport à la stratégie actuelle, de sorte qu’un ensemble de cibles de calage qui s’écarte du plan apparaît comme une distance à ce plan plutôt que comme un score parfait au regard de son propre objectif. L’ensemble est initialisé une seule fois à partir des facteurs de la stratégie actuelle, la première fois qu’un chercheur ouvre l’étape Silver dans Balansor ; il est ensuite indépendant de la stratégie actuelle. Nécessite les droits de gestionnaire et un utilisateur identifié.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | UUID du lot |
weighting |
object |
Non | — | Bloc de remplacement complet {use_strategy_factors, factors} |
factors |
array |
Non | — | Raccourci pour weighting={factors, use_strategy_factors: false} — fournir une simple liste de facteurs revient en soi à renoncer au suivi en direct de la stratégie |
Chaque facteur est {column, target_distribution, name?, factor_type?, bucket_ranges?, role?} : column désigne, par son seul nom, une colonne déjà présente dans la table codée (une colonne de réponse Bronze ou d’attribut de répondant, une dimension de question ouverte codée, ou un indicateur d’option de choix multiple), et target_distribution associe chaque valeur à sa proportion cible (la somme valant 1,0).
role vaut raked (par défaut : le Silver pondère vers la cible) ou benchmark (aucune pondération sur cette cible ; get_bundle_quality évalue par rapport à elle l’échantillon réalisé et l’échantillon pondéré). Toute colonne cible peut prendre l’un ou l’autre rôle, attributs de répondant compris. L’appel remplace la liste entière : lisez donc les cibles actuelles avec get_bundle (chaque cible y indique son role) et renvoyez chacune avec son rôle ; une cible envoyée sans role est enregistrée comme calée. Une liste dont toutes les cibles sont de référence est refusée avec weighting_factor_none_raked, car le calage n’aurait rien sur quoi pondérer.
Une cible peut aussi nommer un attribut personnalisé de répondant. Sa colonne est _custom_<key>, où <key> est la clé de l’attribut dans l’enregistrement du répondant (_custom_region pour custom_attributes.region). Un attribut personnalisé n’est extrait dans un jeu de données que si un facteur de stratégie d’échantillonnage ou une cible de calage du lot le nomme : c’est donc par une cible qu’un nouvel attribut entre dans le jeu de données, sans qu’il doive déjà figurer dans le Bronze. Les attributs que contient le Bronze se lisent dans custom_attribute_keys de get_dataset_schema.
Renvoie : { bundle_id, weighting, warnings }. warnings est une liste de remarques sur une sauvegarde réussie, vide lorsqu’il n’y a rien à signaler. Elle contient une entrée lorsque les cibles enregistrées pondèrent sur un attribut personnalisé avec lequel le Bronze du lot n’a pas été extrait : réextrayez le Bronze (create_bronze_dataset) avant de dériver le Silver, faute de quoi la dérivation est refusée avec weighting_attributes_not_extracted. Si aucun répondant du lot ne porte d’attribut de ce nom, c’est le nom qui est erroné : corrigez-le plutôt. En l’absence de Bronze, il n’y a pas d’avertissement, car la première extraction écrit tous les attributs nommés. Le texte est la même phrase que voit un chercheur lorsqu’il enregistre les cibles dans Balansor.
Le contrôle des codes de réponse
Section intitulée « Le contrôle des codes de réponse »Chaque enregistrement vérifie les clés de chaque cible par rapport au questionnaire du lot, pour les deux rôles, dans Balansor comme via MCP/REST. Une clé portant sur une colonne de réponse doit désigner l’une des options de cette question, par son code ("1") ou son libellé ("Yes") ; sans cela, un code mal saisi sur une cible de référence serait évalué comme un écart fantôme.
| Cas | Résultat |
|---|---|
| Une clé que la question ne propose pas | Refusé (400), avec le nom de la cible, la colonne, les clés sans correspondance et les codes et libellés acceptés : 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). |
| Une colonne dont les options ne nomment pas toutes les valeurs (curseur, texte libre), ou un questionnaire illisible | Enregistré, avec une entrée dans warnings indiquant que les clés n’ont pas été vérifiées |
Une colonne d’attribut de répondant (_demographic_*, _custom_*), une dimension de question ouverte codée ou une cible par tranches |
Non vérifié par cette règle (le contrôle préalable ci-dessous et la dérivation s’appliquent toujours) |
Contrôle préalable
Section intitulée « Contrôle préalable »Les situations suivantes sont refusées avec une erreur de conflit avant toute écriture — le même contrôle préalable que celui qu’exécute la dérivation Silver elle-même :
- une cible qui nomme une catégorie de codage rejetée, ou qui a depuis disparu du dernier codage ;
- une cible qui nomme une colonne brute de réponse à choix multiple. Cette colonne enregistre une combinaison des options choisies : chaque combinaison observée deviendrait sa propre cellule de pondération. Ciblez plutôt les colonnes d’indicateur par option — une cible par option ;
- deux cibles portant sur la même colonne ou le même nom ;
- une liste dont toutes les cibles sont de référence uniquement alors que ces cibles constituent tout l’ensemble de pondération (
use_strategy_factorsvautfalse, comme avec le raccourcifactors), de sorte que le calage n’aurait rien sur quoi pondérer (weighting_factor_none_raked). Un lot qui suit encore sa stratégie cale sur les facteurs de celle-ci et peut ne contenir que des cibles de référence.
preview_calibration_targets_copy
Section intitulée « preview_calibration_targets_copy »Prévisualise la copie des cibles de calage d’un autre lot dans celui-ci. L’outil indique quelles cibles de la source conviennent à ce lot et lesquelles ne conviennent pas, et n’écrit rien. Pour copier, fusionnez addable avec les cibles actuelles de ce lot et enregistrez le résultat avec set_calibration_targets, dont les contrôles s’exécutent de nouveau à la sauvegarde. Nécessite les droits de gestionnaire, l’accès en écriture à ce lot et l’accès en lecture au lot source ; une source que vous ne pouvez pas lire répond exactement comme une source inexistante. La page Silver de Balansor propose la même action sous Copier depuis un autre lot, qui remplit l’éditeur et n’enregistre rien tant que vous n’enregistrez pas.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | Lot dans lequel les cibles seraient copiées |
source_bundle_id |
string |
Oui | — | Lot dont les cibles sont copiées |
Renvoie : { bundle_id, source_bundle_id, addable, rejected }. addable contient les cibles qui conviennent, chacune avec son role. rejected contient les autres, chacune avec name, column, role, un detail lisible et une reason :
reason |
Signification |
|---|---|
no_bronze |
Ce lot n’a pas encore de Bronze, il n’y a donc aucune liste de colonnes à laquelle se référer ; extrayez d’abord le Bronze |
column_missing |
La colonne n’est ni dans le Bronze de ce lot, ni un attribut de répondant (_demographic_<field>, _custom_<key>), ni une dimension codée de son livre de codes |
unknown_code |
Une clé n’est pas une option que le questionnaire de ce lot propose sur cette colonne (le contrôle des codes de réponse) |
preflight:<code> |
La cible échouerait ici à une condition du contrôle préalable, par ex. preflight:weighting_factor_duplicated lorsque ce lot a déjà une cible de ce nom ou sur cette colonne. Une liste entièrement de référence n’est pas une raison ici : ce critère s’applique à la liste que vous enregistrez en définitive |
Opérations d’étape
Section intitulée « Opérations d’étape »L’extraction, le codage et la pondération, l’affinage et l’export s’appellent tous avec un bundle_id via les Outils de jeu de données. Un flux type :
create_bundle→ obtenirbundle_idcreate_bronze_dataset(bundle_id)→ extraire le Bronzecode_open_ends(bundle_id)(ou son aliasderive_silver) → coder les questions ouvertes, puis pondérer selon les cibles de calage, ce qui produit le Silvercreate_gold_dataset(bundle_id, operations=[...])→ affiner le Silver en Gold à l’aide du catalogue d’opérationsexport_dataset(dataset_id, format)→ exporter n’importe quelle étape prêteget_bundle_quality(bundle_id)→ le bilan de représentativité à tout moment
run_bundle_pipeline
Section intitulée « run_bundle_pipeline »Les étapes 2 à 4 en un seul appel. Chaque étape est le même outil que ci-dessus : les mêmes jeux de données sont produits, les mêmes événements d’audit sont enregistrés, et tout refus qu’opposerait une étape seule vous est renvoyé ici à l’identique — avec en plus stopped_at_step, qui indique de quelle étape provient l’arrêt.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
bundle_id |
string |
Oui | — | Lot dont la chaîne doit être exécutée |
include_demographics |
boolean |
Non | true |
Enrichit les lignes Bronze extraites avec les données démographiques des répondants. false est refusé avec named_attributes_require_enrichment lorsque le lot nomme un attribut personnalisé (voir create_bronze_dataset) |
gold_name |
string |
Non | — | Nom du jeu de données Gold. Par défaut "{bundle_name} — Gold" ; la recette Gold elle-même provient toujours de la recette enregistrée du lot |
Renvoie : { task_id, status, step, bundle_id, bronze_dataset_id, silver_dataset_id }. Interrogez task_id avec get_task_status jusqu’à ce que l’exécution atteigne completed, partial ou failed ; l’interrogation indique l’étape en cours et, une fois l’exécution terminée, l’identifiant du jeu de données de chaque étape (bronze_dataset_id, silver_dataset_id, gold_dataset_id) ainsi que gold_skipped : les entrées de la recette Gold enregistrée que la construction a mises de côté parce que le Silver n’a plus leur colonne, sous la forme que create_gold_dataset renvoie en tant que skipped. Cette liste est vide lorsque rien n’a été mis de côté.
Seules l’extraction du Bronze et la mise en file de la dérivation Silver ont lieu pendant que vous attendez. Le Gold ne peut pas démarrer avant que le Silver soit ready, ce qui demande plusieurs minutes de codage et de pondération : l’étape Gold s’exécute donc d’elle-même une fois la dérivation terminée, et l’exécution peut être interrogée à tout moment.
Deux points à retenir :
- Un arrêt conserve ce qui a été construit. Un Bronze est le Bronze du lot, qu’un Gold l’ait suivi ou non : rien n’est annulé. Une nouvelle exécution reprend sur les mêmes lignes au lieu de dupliquer une étape.
- Les droits de toute la chaîne sont vérifiés avant toute construction. La chaîne couvre à la fois le niveau passerelle et le niveau assistant IA (la dérivation avec codage nécessite ce dernier) : un abonnement qui ne couvre que le premier est donc refusé d’emblée, plutôt que de recevoir un Bronze dont il ne pourrait rien dériver.
Documentation associée
Section intitulée « Documentation associée »- Outils de jeu de données — paramètres d’extraction, de codage et de pondération, d’affinage et d’export
- Référence des indicateurs de qualité — définitions des métriques, formules, seuils d’interprétation
- Analyse des données avec Balansor — le tableau du pipeline du lot du point de vue du chercheur
- Codage des questions ouvertes — le fonctionnement du codage des questions ouvertes au sein de la dérivation Silver