benno-mueller/survey-analysis

Analyse d'Enquête

Transformez un export brut d'enquête en résultats qu'un chercheur professionnel en enquête signerait : chaque chiffre a sa base, l'incertitude est exprimée honnêtement, les différences ne sont affirmées que lorsqu'elles sont robustes, et aucun répondant ne peut être identifié.

La compétence est agnostique en termes d'outil et de sujet. Tout ce qui est spécifique à une enquête est un paramètre (Phase 0), non une hypothèse codée en dur.

Règles fondamentales (s'appliquent à chaque enquête, prévalent sur toute autre demande d'"aperçu")

1. Interprétation strictement statistique. Décrivez ce que les données montrent : taille, précision, robustesse, différences, cohérence. Ne proposez jamais d'explications, de causes, de motifs ou d'hypothèses sur pourquoi un résultat est ce qu'il est – même pas sous forme prudente ("peut-être parce que...", "cela pourrait indiquer..."). Les raisons énoncées par les répondants eux-mêmes (réponses ouvertes) peuvent être rapportées comme ce que les répondants ont dit.
2. Pondération égale par défaut. Chaque réponse compte une fois. Les pondérations ne sont utilisées que si la conception de l'enquête l'exige (par exemple, échantillonnage disproportionné, variable de poids fournie avec les données) ou si les paramètres les spécifient. Ne pondérez jamais de votre propre initiative ; signalez plutôt les déséquilibres comme une limitation.
3. Tris croisés et rapports par sous-groupes uniquement là où ils sont autorisés. Que les résultats puissent être décomposés, par quelles variables, et sous quelles limites est une décision du propriétaire de l'enquête (paramètres crosstabs, subgroup_reports, anonymity). Sans autorisation : totaux seulement.
4. Tous les calculs dans le code (Python avec pandas/scipy, ou R). N'estimez jamais un chiffre en prose. Travaillez sur une copie ; ne modifiez jamais les données originales de l'utilisateur.

Fichiers inclus

Fichier	Utilisation dans
references/methods.md	Phases 3-9 : formules, sélection des tests, pondération, contrôle de divulgation, exemple détaillé
references/reporting.md	Phase 10 : résumé de gestion, champs d'action, structure, formulation, graphiques
references/data-sources.md	Phase 1 : formats d'export (LimeSurvey, MS Forms, Google Forms, SurveyMonkey, SPSS/R)
scripts/survey_stats.py	Toutes les phases : fonctions d'aide testées – IC avec correction pour population finie, bornes de non-réponse dans le pire des cas, tests et tailles d'effet, ajustement de la valeur p, tableaux de bannières avec lettres de significativité, différence minimale détectable, repondération et effet de plan, plan de divulgation de groupe, suppression de cellule, alpha de Cronbach, indicateurs de qualité
assets/survey-config.template.yaml	Phase 0 : le fichier de paramètres

Si seul ce SKILL.md est installé, la section Règles fondamentales à la fin est le minimum dont vous avez besoin ; implémentez les formules vous-même dans le code.

---

Phase 0 – Paramètres

Cherchez un fichier survey-config.yaml rempli (modèle dans assets/). Sinon, collectez les paramètres ci-dessous. Les faits qui peuvent être lus à partir des données ou des fichiers, lisez-les vous-même ; les décisions appartiennent à l'utilisateur. Posez les décisions ouvertes en un seul tour (max. 4 questions), chacune avec votre recommandation par défaut. Si personne n'est là pour répondre, utilisez les valeurs par défaut et listez-les sous "Hypothèses" dans le rapport. Les valeurs par défaut sont délibérément restrictives : pas de décompositions, pas de pondération.

Paramètre	Signification	Source	Défaut
population.definition	À qui s'adresse l'enquête	demander	- (obligatoire)
population.size_N	Taille de la population cible	demander	null = inconnue/très grande
population.design	census, simple_random, stratified, quota, self_selected	demander	self_selected (le plus conservateur)
population.known_margins	Effectifs connus de la population par caractéristique	demander / fichiers	aucun
fieldwork.invited / completes / partials / ineligible	Effectifs de résultats	données + demander	completes = enregistrements avec une date de soumission
purpose	describe, compare_groups, test_hypotheses, track_waves, benchmark	demander	describe
hypotheses	Comparaisons statistiques pré-spécifiées (confirmatoires)	demander	aucune -> toutes les comparaisons exploratoires
crosstabs.mode	none, specified (variables listées), banner (tableau de bannière complet)	demander	none
crosstabs.variables	Variables de décomposition pouvant être utilisées	demander	[]
crosstabs.forbidden_combinations	Paires de variables qui ne doivent jamais être croisées	demander	toutes les combinaisons de deux variables démographiques
subgroup_reports.enabled	Rapports séparés par unité (site, service, ...)	demander	false
subgroup_reports.unit_variable / min_n / min_response_rate / compare_to_total	Limites pour les rapports d'unité	demander	- / anonymity.min_group_n / aucun / true
anonymity.min_group_n	Nombre minimum de répondants pour tout groupe rapporté	demander / accord	5
anonymity.min_cell_n	Supprimer les cellules avec 0 < nombre < valeur	demander / accord	null (désactivé)
weighting.mode	none, design (variable de poids dans les données), raking	conception de l'enquête / paramètres	none
weighting.variable / margins / trim	Détails pour design / raking	paramètres	- / - / [0.3, 3]
analysis.confidence_level / alpha / power		défaut	0.95 / 0.05 / 0.80
analysis.multiple_testing	holm, bh, none	défaut	holm confirmatoire, bh bannière/exploratoire
analysis.dont_know / dont_know_codes	Traitement des "ne sait pas / sans réponse"	défaut	exclu de la base, rapporté séparément
analysis.likert_top_box	Catégories comptées comme accord	défaut	2 sur les échelles 4-6 pts, 3 sur 7+ pts
analysis.item_polarity	Quel pôle de chaque item est favorable	codebook + demander	à partir des étiquettes
analysis.quality_rules	Ratio de rapidité, nombre minimum d'items pour réponse en ligne	défaut	0,4 x médiane ; 5 items
open_text.quotes	none, paraphrase, anonymized_verbatim	demander	paraphrase
recommendations.mode	none, action_fields, action_fields_with_measures	demander	action_fields
recommendations.measures	Mesures fournies par l'utilisateur à associer aux résultats	demander	[]
benchmarks	Vagues antérieures / études externes avec formulation identique	demander	aucun
output.audience / format / language		demander / conversation	lay / défaut de l'environnement / langue de l'utilisateur

La Phase 0 se termine par un court résumé des paramètres que l'utilisateur peut corriger.

Phase 1 – Ingestion et codebook

Lisez references/data-sources.md pour l'export concerné. Ensuite :

1. Chargez les données ; supprimez immédiatement les identifiants directs (IP, e-mail, nom, jeton, URL de référence, horodatages exacts si non nécessaires) et dites-le.
2. Construisez un codebook : variable, texte de la question, type (choix unique, choix multiple, Likert k-points, numérique, texte ouvert, ligne de matrice, métadonnées), étiquettes de valeurs, direction et polarité de l'échelle, items inversés, codes manquants/"ne sait pas", condition de filtre (à qui la question a été posée).
3. Déduisez la direction de l'échelle et les items inversés à partir des étiquettes, jamais par hypothèse. Si les étiquettes manquent, demandez.
4. Recodez dans un fichier d'analyse ; conservez la correspondance dans le journal.

Phase 2 – Nettoyage des données

Signalez, documentez, puis décidez seulement. Ne supprimez jamais silencieusement.

• Complets vs. partiels ; définissez l'échantillon d'analyse (défaut : complets ; partiels uniquement pour les items auxquels ils ont répondu, si l'utilisateur est d'accord). Abandons par page.
• Doublons (même jeton, ou vecteurs de réponses identiques avec des horodatages quasi-identiques).
• Répondants trop rapides : durée totale < ratio x médiane. Réponses en ligne dans les matrices d'au moins min_items items. Excluez seulement après avoir montré à l'utilisateur le nombre et le motif ; n'excluez jamais sur un seul indicateur lorsque n est petit.
• Non-réponse partielle par item ; signalez > 10 %.
• Valeurs hors plage, violations de filtre, combinaisons impossibles.

Sortie : un journal de nettoyage des données (vérification, nombre, décision, raison).

Phase 3 – Cadre d'inférence et pondération

Lisez references/methods.md, sections 1 et 7. La conception détermine quelles déclarations d'incertitude sont légitimes :

Situation	Ce qu'il faut rapporter
Recensement ou quasi-recensement d'une population connue et petite (n/N > 5 %)	IC avec correction pour population finie (FPC) plus bornes de non-réponse dans le pire des cas pour les chiffres clés. Formulez les résultats comme "parmi les répondants" à moins que les contrôles de non-réponse ne soutiennent une généralisation.
Échantillon probabiliste	IC standard (FPC si n/N > 5 %) ; poids de sondage si la conception a des probabilités de sélection inégales.
Auto-sélectionné / lien ouvert / commodité	Aucune inférence de population. Parts de manière descriptive ; les IC, s'ils sont montrés, uniquement comme "précision statistique", avec une mise en garde explicite.

La pondération suit uniquement weighting.mode (règle fondamentale 2). Si des poids sont utilisés : rapportez les chiffres clés pondérés et non pondérés côte à côte, l'effet de plan Kish et le n effectif (kish_deff, effective_n), et utilisez le n effectif pour les IC et les tests.

Phase 4 – Distributions de toutes les réponses

• Chaque item, chaque chiffre avec sa base (n) après filtres et exclusions.
• Choix unique : effectifs et parts ; IC (Wilson, avec FPC si applicable) pour les chiffres clés.
• Likert : distribution complète d'abord, puis top-box / bottom-box avec IC, médiane. Moyennes +/- ET uniquement en complément, et seulement pour les items à >= 5 points ou les échelles multi-items.
• Choix multiple : part de répondants par option ; les totaux dépassent 100 %.
• Numérique : médiane et IQR d'abord, puis moyenne/ET ; vérifiez les valeurs aberrantes.
• Arrondi : pourcentage entier lorsque n < 200. Les totaux peuvent ne pas additionner à 100 % – dites-le une fois.
• Chiffres clés vs. 50 % (ou une autre valeur de référence) uniquement en gardant à l'esprit mdd_one_proportion : une part dans l'IC de 50 % est "environ la moitié".

Phase 5 – Tris croisés et significativité

Régi par crosstabs.mode. Avec none, sautez cette phase entièrement et dites-le dans l'encadré méthodologique.

1. Divulgation d'abord. Utilisez uniquement crosstabs.variables ; ne croisez jamais forbidden_combinations. Exécutez reportable_groups() pour chaque décomposition : les groupes en dessous de anonymity.min_group_n sont supprimés, plus la suppression secondaire lorsque le reste supprimé pourrait être dérivé du total. Appliquez anonymity.min_cell_n si défini.
2. Puissance. Pour chaque décomposition, calculez la différence minimale détectable (mdd_two_proportions, 80 % de puissance). Rapportez-la, afin que "aucune différence significative" soit interprétée correctement ("les différences inférieures à x points ne peuvent pas être détectées").
3. Tests. Choisissez selon le type de données (references/methods.md, section 3) : chi-deux / Fisher pour les catégories, Mann-Whitney / Kruskal-Wallis pour les items ordinaux, Welch pour les scores d'échelle métrique. Toujours avec la taille d'effet et son libellé ; une valeur p seule n'est jamais un résultat.
4. Tableaux de bannières (crosstabs.mode: banner) : banner_table() / format_banner() pour chaque item x variable autorisée – pourcentages en colonne, ligne de base, lettres de significativité (une lettre marque une part significativement plus élevée que la colonne avec cette lettre), lettres basées sur les valeurs p ajustées dans la ligne. La bande est exploratoire : avant qu'une différence n'aille dans le texte, ajustez toutes les valeurs p de la bande ensemble avec Benjamini-Hochberg (p_adjust sur les tests retournés). Les tableaux de bannières vont en annexe ; seules les différences robustes (significatives après ajustement sur l'ensemble de la bande et avec au moins un petit effet) vont dans le texte.
5. Séparez les résultats confirmatoires (hypothèses hypotheses pré-spécifiées) des résultats exploratoires.
6. Une différence qui n'est pas significative est "aucune différence fiable", jamais une tendance.

Phase 6 – Rapports par sous-groupes

Uniquement si subgroup_reports.enabled. Pour chaque unité de unit_variable :

1. reportable_groups(sizes, min_n, total_published=True, invited, min_response_rate) décide quelles unités obtiennent un rapport. La règle du reste est importante : si une petite unité est retenue mais que toutes les autres et le total sont publiés, son résultat peut être calculé par soustraction – la fonction retient d'autres unités jusqu'à ce que le reste retenu soit lui-même >= min_n. Listez les unités retenues et la raison (sans leurs chiffres) pour le propriétaire de l'enquête, pas dans les rapports publiés.
2. Chaque rapport d'unité utilise la même structure que le rapport principal, la propre base et les IC de l'unité (FPC avec le nombre d'invités de l'unité comme N), et – si compare_to_total – le total comme référence. Ne comparez pas les unités entre elles à moins que crosstabs ne permette cette variable.
3. À l'intérieur d'un rapport d'unité, pas d'autres décompositions, sauf autorisation explicite et si tous les groupes passent les seuils.

Phase 7 – Échelles et indices

Uniquement pour les ensembles d'items conçus comme une échelle (ou des instruments validés). Recodez les items inversés, calculez l'alpha de Cronbach (et l'oméga de McDonald si un package factoriel est disponible), les corrélations item-reste, l'alpha si supprimé. Construisez un score d'échelle uniquement si alpha >= .70 (>= .60 pour les échelles courtes à 3 items, avec une mise en garde).

Phase 8 – Réponses ouvertes

Voir references/methods.md, section 6. Lisez chaque réponse, construisez un cadre de codage inductif, codez avec plusieurs codes autorisés, rapportez les thèmes comme "x répondants sur n ont mentionné ...". Deuxième passage de codage sur >= 20 %, rapportez l'accord. Indiquez que le codage a été effectué par une IA en tant que codeur unique. Citations uniquement comme autorisé par open_text.quotes, dépouillées de tout élément d'identification. Rapportez ce que les répondants ont écrit ; n'ajoutez pas votre propre explication.

Phase 9 – Non-réponse et représentativité

• Taux de réponse (RR1 / RR2, response_rates()), global et par groupe connu.
• Comparez la composition des répondants avec known_margins (test d'adéquation). Les taux de réponse différant de plus de 15 points entre les groupes sont rapportés comme une limitation (et, si les rapports par sous-groupes sont autorisés, les chiffres clés par groupe). Pas de pondération sauf si weighting.mode le dit.
• Modèles de non-réponse partielle ; répondants précoces vs. tardifs si les horodatages existent.
• Concluez explicitement à qui les résultats s'appliquent et avec quelles limites.

Phase 10 – Interprétation, résumé de gestion et rapport

Lisez references/reporting.md.

• Interprétation = lecture statistique uniquement (règle fondamentale 1) : quelle ampleur, quelle précision, quelle robustesse (IC, bornes dans le pire des cas), quelle cohérence entre les groupes autorisés, comment cela se compare aux benchmarks de formulation identique.
• Résumé de gestion (première page) : 3 à 7 résultats clés avec n et incertitude, puis champs d'action.
• Champs d'action (recommendations.mode) : classez les items ou sujets par critères statistiques uniquement – part de réponses défavorables, robustesse sous les bornes dans le pire des cas