PsyRAT v0.1.0-beta

0.1.0-beta — 2026-09-09

First version to carry an explicit maturity label. -beta states that the API and the shape of the
outputs are still moving. It is not a statement that the estimates are provisional: see the design
maturity table below, which is per-design.

Design maturity

These labels describe verification status in this repository, not a judgment about the
underlying statistics. Read them together with the evidence-tier table in README.md
(Validation and Testing), which explains what a green run of each suite does and does not prove.

Maturity	Designs	What the label means
Supported	One-facet and test-retest reliability (Gaussian, and gamma where offered); subject-level error variances; two-event difference scores, non-concurrent; the four-event difference-of-differences (analysis 9, non-concurrent by construction); reliability from splits (Gaussian only); the dynamic/conditional family except analysis 20 under gamma; the person-specific dynamic non-concurrent DoD designs (analyses 28/29, single-occasion and retest, in both likelihood families - the Gaussian arms shipped 2026-08-20; gamma is location-scale only)	Covered by the unit and accuracy suites, and by live CmdStan recovery against known variance components where a recovery test exists (the gaps are listed below the table).
Experimental	Concurrent (correlated-residual) difference scores under the Gamma family with per-person ν (dispersion=1; analyses 7, 8, 10; the only gamma arm analysis 8 has)	Convergence is not validated in this repository. A live subject-level run reached R̂ ≈ 2.5 with ESS ≈ 2 on one fit. These designs need long warmup and, in practice, threaded compute. The runtime convergence gate (R̂ > 1.1) warns you about a specific fit, and the three live-recovery tests skip rather than pass when a fit has not converged. Treat any estimate from these designs as unverified until you have checked its diagnostics yourself.
Tractability checked, robustness not	The group-level concurrent difference designs under global fixed dispersion (dispersion=2, the default for analyses 7 and 10; analysis 8 has no such arm, since global dispersion is a group-level estimand)	One simulated known-truth dataset converged cleanly (max R̂ = 1.000; recovered G = 0.941 against a true 0.939). That establishes tractability at one set of sampler settings on one dataset. It is not a robustness result: there is no sweep over sample size, trial count, or real data.
Development-only	Analysis 20 (two-facet subject-level concurrent dynamic difference) under Gamma, location-scale	Ships and runs, but no empirical anchor exists for its two-facet cut-copula configuration and no user-facing label says so on screen or in an export; treat its estimates as unverified.
Not implemented	Analyses 15/16, 17/18 and 21/22 under Gamma; every splits design under Gamma; the exact-shared covariance count arm (not user-reachable); concurrent static DoD ("9 + rescor")	Barred pending an estimand decision. Requesting them errors rather than silently substituting a different model.

Validation coverage behind the Supported label is not uniform, and the gaps are recorded here
rather than closed for this release (owner ruling 2026-09-05): the Gaussian four-event
difference-of-differences (analysis 9) has a live planted-truth recovery only through the native
HMC engine, not through CmdStan; the Gaussian subject-level dynamic designs (analyses 26 and 27)
share the fits of analyses 11 and 14 and have no recovery test of their own; the gamma arm of
analysis 19 is checked only by a replay of an external reference fit that runs no sampler; and
the splits designs (analyses 23 and 24) have no independent-oracle row. The CmdStan recoveries
for those arms are filed as post-beta work.

The dispersion parameterization actually used is recorded in the provenance block of every copula
export, so a saved table states which of the two rows above it belongs to.

Changed

• The Gaussian difference-of-differences priors are configurable. Analysis 9 was the one
  design with every prior fixed inside its Stan builder and its native HMC log-posterior, so a
  'priors' override never reached it (the subject-level family still keeps its intercept,
  between-person and residual log-SD constants fixed and exposes only priors.sserr.sig_trl). They are now priors.dod (b_cell, b_sigma_cell,
  sd_id, sd_trial, lkj; owner ruling 2026-09-05) at the former constants, so the generated
  Stan and the native fit are unchanged unless a value is set. A result saved before the family
  existed still prints Priors: PsyRAT defaults, because a family absent from a stored prior set
  is at its default by construction.
• Exported table headers now write the reliability cutoff with four decimal places instead of
  two (now Dependability Cutoff: 0.8000; previously Dependability Cutoff: 0.80). This changes the
  header of every table that carries the cutoff line (the difference-of-differences and variance
  tables carry none). The cutoff is a recorded analytic input: it is
  consumed at full precision to pick the minimum trial count that defines the retained sample, and
  the cutoff field accepts any value in (0, 1). At two decimals a cutoff carrying a third or fourth
  decimal — as a sensitivity grid stepping .025 produces — was written to file as a different
  threshold than the one applied; a run at 0.9999 recorded 1.00. Estimates in the table body
  (coefficients, credible intervals, SEM) are unchanged at two decimals; this is the input/estimate
  distinction, not a change to the reporting convention. Four decimals matches the format the
  toolbox already used for its other user-typed threshold (Criterion Cutoff). Filed as B36.
• Version string is 0.1.0-beta (was 0.1.0, which understated the toolbox against a Version
  History reaching 0.5.2). Filed as B4.
• Log-nu subject-level gamma residuals now pool the population person-by-trial term (analyses 6,
  8, and 26 under gammascale = 1, the "Log-nu (relative dispersion / CV)" popup or
  'gammascale', 1). Each participant's residual was the conditional observation-level variance
  alone; it omitted the induced person-by-trial term of the log-linked mean surface that the
  group-level residual carries and that the location-scale parameterization (the default since
  2026-08-07) already pooled. Every per-participant coefficient on the log-nu path was therefore
  optimistically biased, by an amount that depends on the person and trial log-SDs (about 1% to
  about 50% of the residual across the design points examined). Per-participant coefficients from
  those runs change, and so do the affected runs' own group-level residual, within-person SD, and
  ICC rows, which read the same pooled population reference; runs of other designs and every
  location-scale run are unchanged. The export header of an affected run now carries a "POOLED"
  residual line. Filed as S20.

Added

• Gaussian arms for the person-specific dynamic non-concurrent difference-of-differences
  (analyses 28/29). Until 2026-08-20 these two designs were the only routed analyses with no
  Gaussian implementation ("no Gaussian model of the estimand has been derived"); an owner ruling
  reopened that closed decision and the arms shipped with their own derivation, recorded in the
  project's internal formula audit. Identity link on the mean (negative ERP amplitudes
  are in scope, unlike the gamma arm), log link on the person-specific residual SD, the same
  nonconcurrent counterfactual estimand and disclosures, and the same read-outs minus the
  chi-square-specific per-person nu columns. CmdStan-only for now (native_key = ''), like
  analyses 25-27. Validation is in-repo by design: no external reference bundle exists for a
  Gaussian DoD, so the live planted-truth recovery tests for both analyses are the load-bearing
  gates, alongside closed-form longhand checks, the identity-link theorem pins, and a full-space
  tie to the static Gaussian DoD kernel.
• CITATION.cff at the repository root. Previously the only DOI in README.md belonged to the
  2017 ERA Toolbox paper, so a user following the README to cite PsyRAT would have cited a
  different tool. The citation file lists Rocha et al. (2026), the source of the estimators the
  toolbox implements, first under references and asks for the software version alongside it; it
  deliberately carries no preferred-citation key, because in CFF 1.2.0 that key makes citation
  tooling emit the paper instead of the software. It also lists Rast & Clayson (in press) and the
  2021 ERA Toolbox test-retest paper under references, and carries an inline note to revisit that
  decision when the dedicated PsyRAT software publication is released. A matching "How to cite" section was added to README.md.
• A user manual, documentation/manual/: 18 chapters plus a glossary and a reference list,
  written for this toolbox rather than inherited from the ERA Toolbox. Four worked tutorials run on
  the simulated datasets in test_data/, and every reference value they print came from a real run
  at the settings its chapter states, transcribed with provenance in
  documentation/manual/tutorial_expected_values.md. The same content ships as one generated PDF,
  documentation/manual/psyrat_manual.pdf, rebuilt from the chapters at each release.
• This changelog.

Fixed

• Subject-level plots on an events-only or groups-only run were untitled. Every panel of the
  caterpillar plot fell through to an empty title, so a reader could not tell which panel belonged
  to which event; the panels now carry the event or group name. Groups-by-events runs were already
  titled "group: event" and are unchanged.
• **Closing the "Chains did not converge" dialog with the window's close box errored after the fit
  had...