Outils de stratégie d'échantillonnage — référence des outils MCP
Les outils de stratégie d’échantillonnage définissent les distributions démographiques cibles qui servent à constituer des échantillons de répondants représentatifs. Une stratégie décrit une population : ses facteurs — des dimensions démographiques assorties de proportions cibles — et la manière dont l’ajustement à ces cibles est évalué (quality_metric, aggregation_method). La génération de vivier s’appuie sur ces facteurs pour sélectionner les répondants conformes à votre plan d’échantillonnage.
Une stratégie ne contient que des facteurs de répondant — des attributs connus avant que quiconque ne réponde. Une cible portant sur une réponse à l’enquête (par exemple une référence tirée de résultats électoraux ou d’un recensement) relève du lot qui contient les réponses, sous la forme d’une cible de calage de référence uniquement : voir set_calibration_targets.
list_sampling_strategies
Section intitulée « list_sampling_strategies »Liste toutes les stratégies d’échantillonnage, avec un filtre facultatif par projet ou par nom.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
project_id |
string |
Non | — | Filtre par identifiant de projet |
name |
string |
Non | — | Filtre par sous-chaîne, insensible à la casse |
limit |
integer |
Non | 100 |
Nombre maximal de résultats renvoyés |
Renvoie : { data: [...], count, limit }. Chaque élément comporte id, name, description, project_id, factor_count, quality_metric, created_at.
get_sampling_strategy
Section intitulée « get_sampling_strategy »Récupère une stratégie d’échantillonnage par son identifiant, avec la définition complète de ses facteurs.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
strategy_id |
string |
Oui | — | UUID de la stratégie |
Renvoie : l’objet stratégie complet : id, name, description, project_id, factors, quality_metric, aggregation_method, is_default, created_at, modified_at.
create_sampling_strategy
Section intitulée « create_sampling_strategy »Crée une stratégie d’échantillonnage dotée de facteurs de distribution démographique.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
string |
Oui | — | Nom de la stratégie |
project_id |
string |
Non | — | Identifiant du projet parent |
factors |
object[] |
Non | — | Définitions des facteurs de distribution (voir ci-dessous) |
quality_metric |
string |
Non | "rmse" |
"rmse", "mae", "chi_square" ou "max_deviation" ; toute autre valeur est refusée et rien n’est créé |
description |
string |
Non | — | Description de la stratégie |
Renvoie : l’objet stratégie complet (comme get_sampling_strategy).
Schéma d’un facteur
Section intitulée « Schéma d’un facteur »Chaque facteur du tableau factors définit une dimension de répondant. Une clé absente du schéma ci-dessous est refusée comme erreur de validation (REST 422) ; un facteur qui porte encore l’ancien champ source échoue donc au lieu d’être ignoré en silence :
| Champ | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
string |
Oui | — | Nom affiché (par ex. "Gender") |
attribute_path |
string |
Oui | — | Attribut du répondant (par ex. "gender", ou un attribut personnalisé) |
target_distribution |
object |
Oui | — | Correspondance catégorie → proportion. La somme doit valoir 1,0 (tolérance de ±0,01) |
factor_type |
string |
Non | "discrete" |
"discrete", "bucketed" ou "geographic" |
bucket_ranges |
array |
Non | — | Pour le type par tranches : liste de tuples [min, max, label] |
weight |
float |
Non | 1.0 |
Poids d’importance de ce facteur |
Exemple :
{ "name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}, "factor_type": "discrete", "weight": 1.0}create_default_strategy
Section intitulée « create_default_strategy »Crée une stratégie dotée des facteurs standard de distribution par sexe et par âge.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
string |
Oui | — | Nom de la stratégie |
project_id |
string |
Non | — | Identifiant du projet parent |
Renvoie : l’objet stratégie complet (comme get_sampling_strategy).
Facteurs par défaut :
- Sexe : homme 48 %, femme 50 %, autre 2 %
- Tranche d’âge : 18–24 (15 %), 25–34 (20 %), 35–44 (20 %), 45–54 (18 %), 55–64 (15 %), 65+ (12 %)
update_sampling_strategy
Section intitulée « update_sampling_strategy »Met à jour une stratégie d’échantillonnage existante (mise à jour partielle : seuls les champs fournis changent).
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
strategy_id |
string |
Oui | — | UUID de la stratégie |
name |
string |
Non | — | Nouveau nom |
description |
string |
Non | — | Nouvelle description |
factors |
object[] |
Non | — | Remplace tous les facteurs (sans fusion) |
quality_metric |
string |
Non | — | Nouvelle métrique de qualité, parmi les quatre ci-dessus ; toute autre valeur est refusée et rien ne change |
Renvoie : l’objet stratégie complet (comme get_sampling_strategy).
La mise à jour d’une stratégie ne modifie jamais un vivier déjà tiré à partir d’elle : chaque vivier conserve les paramètres de tirage avec lesquels il a été généré, et une actualisation refait le tirage sur les facteurs actuels de la stratégie, à la taille enregistrée sur le vivier lui-même.
delete_sampling_strategy
Section intitulée « delete_sampling_strategy »Supprime une stratégie d’échantillonnage. La suppression est bloquée si la stratégie est celle par défaut ou si des viviers y sont liés.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
strategy_id |
string |
Oui | — | UUID de la stratégie |
Renvoie : { strategy_id, deleted }
Gestion des erreurs
Section intitulée « Gestion des erreurs »Validation des facteurs
Section intitulée « Validation des facteurs »| Cas | Réponse |
|---|---|
| Champ obligatoire manquant | {"error": "Each factor must have 'name', 'attribute_path', and 'target_distribution'"} |
| La somme de la distribution ne vaut pas 1,0 | {"error": "Factor '{name}' target_distribution must sum to 1.0 (got {sum:.3f})"} |
Clé non déclarée par le schéma du facteur (par ex. source) |
validation_error (REST 422) indiquant le champ en trop |
La validation des facteurs s’applique à la fois à create_sampling_strategy et à update_sampling_strategy.
Protection de la stratégie par défaut
Section intitulée « Protection de la stratégie par défaut »| Cas | Réponse |
|---|---|
| Modification de la stratégie par défaut | {"error": "Cannot modify the default sampling strategy"} |
| Suppression de la stratégie par défaut | {"error": "Cannot delete the default sampling strategy"} |
Protection des viviers liés
Section intitulée « Protection des viviers liés »| Cas | Réponse |
|---|---|
| Suppression d’une stratégie liée à des viviers | {"error": "Cannot delete strategy: {count} pool(s) are linked to it"} |
Erreurs courantes
Section intitulée « Erreurs courantes »| Cas | Réponse |
|---|---|
| Stratégie introuvable | {"error": "Strategy {id} not found"} |
| L’appelant n’est pas propriétaire du projet de la stratégie | {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"} |