# catalog/operations/analysis/spec_curve_stats.yaml

id: analysis_spec_curve_stats
name: Specification Curve Statistics
description: >
  Compute summary statistics and sensitivity decomposition for a multiverse
  specification curve. Takes arrays of effect sizes and parameter labels,
  returns median, IQR, ANOVA-based sensitivity ranking, and robustness scores.
  Part of the spatial multiverse analysis capability (UC-038).
version: 1.0.0
category: analysis
type: table-to-table
default_implementation: rust-wasm

inputs:
  - name: effects
    type: array
    element_type: float64
    description: Effect sizes from each specification (e.g., correlation coefficients)
    required: true
  - name: p_values
    type: array
    element_type: float64
    description: P-values from each specification (optional)
    required: false
  - name: param_labels
    type: object
    description: >
      Map of parameter names to arrays of string labels. Each array must have
      the same length as effects. E.g., {"spatial_unit": ["tract", "tract", "zip", ...]}
    required: true

# Structural: ANOVA-based sensitivity decomposition on any multiverse
# specification curve. Pure statistics, no concept linkage. requires: omitted.

outputs:
  - name: summary
    type: object
    description: >
      Specification curve summary: n_specs, median, mean, std, iqr_low,
      iqr_high, min, max, pct_positive, pct_significant
  - name: sensitivity
    type: array
    element_type: object
    description: >
      Per-parameter sensitivity decomposition: param_name, eta_squared,
      f_statistic, p_value, rank, group_means. Ranked by eta_squared
      descending (most influential parameter first).

params:
  significance_threshold:
    type: float
    default: 0.05
    description: P-value threshold for counting significant specifications

# backends: audited 2026-08-14 (defect 50). NOTHING dispatches this op: no arm in folia-engine
# `dispatch_op`, no `registerOp`/OP_TABLE entry in packages/compute, no `_BUILTIN_OP_MAP`
# key in folia/compute.py, no backend manifest. Declared EMPTY on purpose — an absent
# block would be indistinguishable from one nobody ever wrote.
# packages/compute-wasm/src/stats_ops.rs:1765 `spec_curve_summary` exists as a crate fn (wasm shim at stats_ops.rs:2507); nothing registers an op for it.
backends: {}

granularity:
  output_resolution: null
  requires_continuous: false

uncertainty:
  error_model: analytical
  factors:
    - name: f_distribution_approximation
      description: >
        P-values use Wilson-Hilferty normal approximation to F distribution.
        Accurate for df > 5, approximate for smaller degrees of freedom.
      severity: low
      mitigations:
        - "Use statrs crate for exact F CDF in v2"
        - "Treat p-values as approximate rankings, not exact probabilities"
  limitations:
    - "One-way ANOVA assumes independence across specifications (often violated)"
    - "eta_squared can be inflated with small group sizes"
    - "NaN effects are excluded from all statistics"

execution:
  realtime_max_specs: 10000
  cost_per_spec: 0.0
  time_per_1000_specs_ms: 5
  memory_profile: low
  profile:
    cpu: low
    memory: low
    io: none
  scaling:
    model: linear
    parallelizable: false

cache_policy:
  ttl_days: 365
  invalidate_on: [source_update]

display_hints:
  chart:
    renderer: observable-plot
    chartType: specification_curve
    description: >
      Two-panel chart: sorted effect sizes on top, parameter coloring
      strips on bottom. Hover for spec details, click to load full results.
  table:
    renderer: tanstack-table
    description: Full specification results table, sortable by any column

ui:
  icon: bar-chart-2
  color: "#7C3AED"

references:
  - Steegen, S. et al. (2016). Increasing Transparency Through a Multiverse Analysis.
  - Simonsohn, U. et al. (2020). Specification curve analysis. Nature Human Behaviour.
  - Kedron, P. & Holler, J. (2026). Recent advances in R&R in CaGIS. DOI 10.1080/15230406.2025.2512084