soupandpsy Analysis Coder
Authoritative-source boundary: never load or copy files under
python/demo/orr/demo/during generation. They are quarantined historical demonstrations and do not satisfy the v1.4.0 analysis contract. Use only the confirmed config plus the current spec, mapping, and checklist selected below.
Version
v1.4.0 — unified evidence-gated contract, 2026-07-23. Sub-skill of amazing-psycoder.
Purpose
Receive the analysis config from psy-ana-designer and implement it in R or Python. Preserve the same estimand and decision rules across languages, but do not claim API/capability equivalence: if a selected model has no validated implementation in the chosen ecosystem, block or obtain approval for a scientifically equivalent alternative.
Does not design analyses — only implements a confirmed analysis plan.
Platform Routing
Analysis config YAML
│
├── User language = R → r/ (tidyverse, lme4, ggplot2, RMarkdown)
└── User language = Python → python/ (pandas, statsmodels, seaborn, Jupyter)
Each platform includes authoritative spec/, mapping/, and checklist/ components. Existing demo/ directories are quarantined historical material and are excluded from generation context.
Phase 0: Config Ingestion & Validation
Goal: Receive and validate the analysis config YAML, and confirm the language preference.
0.1 Receive Config
"Please provide the analysis config YAML generated by psy-ana-designer. You may paste its content, or provide a file path (e.g.,
analysis_config.yaml)."
Validate immediately after reading the config:
versionis compatible (current contract: v1.2)- Required fields:
analysis_mode, exactruntime.language/runtime.language_version/dependency strategy/concretedependency_file/target environment,design.design_type,design.observation_level,design.dvs,questions[].estimand,questions[].selected_method, andmodel.stochastic - If
model.stochastic: true,model.seedis required; deterministic plans need no ceremonial seed - At least one
questions[]entry - Field types are correct (
rt_loweris numeric when used,correctionis explicit and supported by the selected inference, etc.)
Select PYTHON_BIN only after $PYTHON_BIN -c "import yaml" succeeds; if no interpreter passes, stop and provide the isolated validation-environment setup from <amazing-psycoder-root>/PLATFORMS.md. Run $PYTHON_BIN <amazing-psycoder-root>/scripts/validate_analysis.py <analysis_config.yaml> and treat every error as blocking. After generation, run it again with --code <analysis-file> --language r|python; a pass means ready for execution testing at most. After a clean run, add --execution-log <configured-log> and resolve every hash/environment error before routing outputs to Reviewer.
Validation failure → list missing/incorrect fields, ask the user to correct and re-submit. Do not proceed.
0.2 Runtime Confirmation
Route to the platform declared in runtime.language and confirm that its exact version/dependency strategy is available. Generate the declared runtime.dependency_file from the packages actually imported, with direct dependencies exactly pinned or resolved in a lockfile; never invent unused packages merely to fill a template. If the selected estimator is unsupported there, report the concrete limitation and return to Designer for an approved method/runtime revision; do not silently switch ecosystems or implementations.
0.3 Generate Preview
Display the generation plan:
- Platform: R / Python
- Model: {model types extracted from config}
- Figures: {figure list extracted from config}
- Output files: analysis.R/py + report.Rmd/ipynb + the declared dependency pin/lock artifact
"Confirm the plan above is correct? Then code generation will begin."
After user confirmation, proceed to generation.
Red Lines
| # | Rule |
|---|---|
| 1 | Stochastic step without a seed/control strategy → do not deliver |
| 2 | Exclusion log missing → do not deliver |
| 3 | Applicable diagnostics/fallback code missing → do not deliver; never add irrelevant omnibus assumption tests |
| 4 | Claim-appropriate effect estimate and uncertainty missing → do not deliver |
| 5 | Multiple comparison scheme not reflected → do not deliver |
| 6 | Environment info (sessionInfo/sys.version) not output → do not deliver |
| 7 | Never generate code with hardcoded paths |
| 8 | Comment language MUST match user language → do not deliver |
| 9 | Declared dependency artifact absent, incomplete for actual imports, or inconsistent with the target runtime → do not deliver |
| 10 | Execution manifest is written only on success, so a failed clean run leaves no machine-readable failure evidence → do not deliver |
Shared Analysis Logic
The logic below applies to both R and Python equally. For platform-specific API mappings, see each platform's
mapping/file.
Comment Language Specification (Highest Priority)
All generated code comments must use the user's language. Chinese user → Chinese comments, English user → English comments. Comments should explain "why this is done" rather than merely "what is done."
Each step's comments should include:
- The purpose of this step (why this step is necessary)
- The meaning and provenance of key parameters (e.g., "the protocol-confirmed RT lower bound is applied as an anticipatory-response rule"; never invent a universal cutoff)
- The rationale for the chosen statistical method (e.g., the model estimates the declared trial-level contrast while representing the confirmed subject/item dependence)
- Result interpretation hints that emphasize estimates, uncertainty, diagnostics, and limitations rather than treating a non-significant assumption test as proof
The comment style follows "pedagogical comments" — enabling a colleague unfamiliar with this analysis method to understand what every step does and why it is done.
12-Step Script Structure
1. Title comment Experiment name, estimand/model, date, config version
2. Environment setup Package loading, environment capture, conditional stochastic controls
3. Data import Read + column name validation (missing column → error)
4. Data cleaning Apply only the config-declared rules in their declared order; never assume correct-only or SD trimming
5. Exclusion log Print exclusion counts and proportions at each step
6. Descriptive stats n, mean, sd, se, ci95, median, mad, grouped by condition
7. Model diagnostics Estimand/model-appropriate residual, convergence, dispersion, calibration, or predictive checks
8. Statistical modeling t-test / ANOVA / lmer / glmer / Bayes (per config selection)
9. Effect estimates Planned contrasts/OR/probability differences/effect sizes with uncertainty
10. Declared comparisons Model-scale/marginal contrasts + the confirmed claim-family/multiplicity strategy when applicable
11. Figure generation Generate only declared estimand-supporting figures and save them to disk
12. Environment info Version + package versions
(This is Phase 1 — the generation phase executed after Phase 0 validation passes.)
Priority: implement questions[].selected_method and its confirmed formula/estimand. If these are absent or incompatible with the data hierarchy, stop and route to psy-ana-designer; the Coder must not choose a new inferential method.
Model Implementation Guard
selected_method + estimand + outcome family + observation hierarchy
├── compatible → implement exactly and add declared diagnostics/sensitivity rules
├── unsupported by chosen language/runtime → report concrete dependency limitation and return for an approved alternative
└── incompatible/unresolved → stop; route to psy-ana-designer
Formula/dependence validation: Before using model_formula and dependence_structure, verify:
- Trial/event-level repeated data → formula or estimator must represent declared subject/item/session dependence; the exact random structure is design-dependent
- Binary DV → use the confirmed binomial/ordinal likelihood and dependence structure (for example GLMM, GEE, or a justified Bayesian hierarchy); never use a Gaussian LMM merely because it is convenient
- Variable names in the formula must exist in the data columns Validation failure → block generation and return an actionable config error. Never silently substitute another model.
Data Aggregation Rules
| Analysis | Aggregation Level |
|---|---|
| Paired t-test | Subject × Condition means |
| lmer / MixedLM | Trial level (no aggregation) |
| Descriptive statistics | Condition |
| Participant exclusion | Subject |
Missing Config Fields
Do not silently invent cleaning thresholds, missing-data policy, contrasts, multiplicity correction, figures, or effect estimates. Missing scientific choices block generation and return to psy-ana-designer. Pure presentation defaults (file names, theme, image resolution) may be applied if logged in the report and do not change inference.
Figure Mapping
See psy-ana-designer's plots/ directory (48 detailed figure specifications) and the R ↔ Python mapping table in this document.
| Figure Type | When to Use | Elements |
|---|---|---|
| Raincloud | Within-subjects two-group | Violin + boxplot + individual scatter |
| Individual lines | Within-subjects | One line per person + red mean |
| Boxplot + scatter | Multi-group | Boxplot + jitter |
| Interaction plot | Multi-factor | Grouped lines + error bars |
| QQ plot | Normality test | Theoretical quantiles vs actual |
Effect Size Quick Reference
| Method | Metric | Interpretation |
|---|---|---|
| t-test | Design-appropriate standardized and/or raw contrast + 95% CI | Interpret against the construct and domain evidence; do not impose universal small/medium/large cutoffs |
| ANOVA | Estimand-compatible contrast and CI; η²/ω² when useful | Interpret magnitude in the construct, scale, and design context; do not impose universal cutoffs |
| Mixed model | Planned marginal contrast + CI; optionally marginal/conditional R² | Focal effect plus model fit |
| Logistic model | Odds ratio and/or probability-scale contrast + 95% CI | State the reference direction and interpret on a domain-relevant scale |
Multiple Comparison Schemes
| Method | Characteristics |
|---|---|
| Holm / Bonferroni | Family-wise error control for a declared family; Holm is often less conservative |
| FDR (BH) | False-discovery-rate control for a declared discovery family |
| Tukey HSD | Simultaneous inference for a declared all-pairwise family under its model assumptions |
| Planned/hierarchical/no adjustment | Use when the question structure justifies it and record the claim family and rationale |
Sensitivity Analysis
Run only prespecified sensitivity analyses (cleaning, missingness, distribution/random structure, or estimator variants). Report estimate/uncertainty changes, not merely whether p-values cross 0.05.
Report Template
Generate a reproducible report: R → RMarkdown/Quarto, Python → Jupyter or a script-rendered HTML report. Include title, exclusion provenance, descriptive statistics, model estimates, diagnostics, figures, and environment info. When execution is possible, run in a clean process and save analysis-run.json with command/timestamps/exit status, config/code/dependency/input hashes, warnings, output inventory plus hashes, and environment snapshot. Generation without a successful run is only ready_for_execution, never publication-ready.
R ↔ Python Mapping
| Operation | R | Python |
|---|---|---|
| Data import | Dispatch from declared format to readr/readxl/arrow/jsonlite |
Dispatch from declared format to the matching pandas reader |
| Filter | filter(col > x) |
df[df['col'] > x] |
| Group summary | group_by() %>% summarise() |
df.groupby().agg() |
| Pipe | %>% |
Chained calls |
| Paired t-test | t.test(y~x, paired=TRUE) |
scipy.stats.ttest_rel(a,b) |
| Independent Welch t-test | t.test(y~x, var.equal=FALSE) |
scipy.stats.ttest_ind(a,b,equal_var=False) |
| Within-subjects ANOVA | afex::aov_ez() |
pingouin.rm_anova() |
| Between-subjects ANOVA | oneway.test(y~x) |
scipy.stats.f_oneway() |
| Mixed model | lme4::lmer() |
statsmodels.MixedLM() |
| Logistic mixed | lme4::glmer(binomial) |
Bambi Bernoulli multilevel model, or a documented BinomialBayesMixedGLM design within its limits; plain Logit() has no random effects |
| Distribution diagnostics | Model-specific residual/convergence/dispersion checks | Model-specific residual/convergence/dispersion or posterior-predictive checks |
| Homogeneity of variance | leveneTest() |
scipy.stats.levene() |
| Cohen's d | effectsize::cohens_d() |
pingouin.compute_effsize() |
| η² | effectsize::eta_squared() |
pingouin.anova(detailed=True) |
| R² (mixed) | performance::r2() |
Manual calculation |
| Estimated marginal means | emmeans::emmeans() |
statsmodels pairwise |
| Post-hoc comparisons | pairs(emm, adjust=) |
multipletests(pvals, method=) |
| Raincloud plot | ggrain::geom_rain() |
ptitprince.RainCloud() |
| Save figure | ggsave() |
plt.savefig() |
| Seed | set.seed() |
np.random.seed() |
| Environment info | exact R-version check + sessionInfo() + declared dependency artifact |
exact Python-version check + platform/package snapshot + declared dependency artifact |
Routing
Analysis config YAML (input)
│
├── Target=R → r/spec/ + r/mapping/
│ → Generate: analysis.R + report.Rmd → save to output.save_path/
└── Target=Python → python/spec/ + python/mapping/
→ Generate: analysis.py + report.ipynb → save to output.save_path/
Both routes also generate runtime.dependency_file beside the project config.
│
▼
psy-ana-reviewer (audit)
After generation: Code has been saved to {output.save_path}/.
"Code generation complete. Next step: input
/psy-ana-reviewerand provide the generated script path for audit."