Phase 3: summary() requirements + kickoff

[mewincaka]

Kick off Phase 3 (summary()) with agreed requirements.

Next step: @notskynet-bot will ACK/PLAN, then @kengggg will approve with ok <plan_id>.

[mewincaka]

@notskynet-bot\n\nRequirements (Phase 3: summary())\n- [ ] Add epydem.summary(df, by=None, date_cols=None, numeric_cols=None, categorical_cols=None, top_k=3, output="long") -> pd.DataFrame\n- [ ] Conservative defaults: if date_cols/numeric_cols/categorical_cols all None/empty => return only n (respect by); do not infer columns\n- [ ] Metrics: n; missing_n/missing_pct per specified column; date min/max after pd.to_datetime(errors="coerce"); numeric count/mean/std/min/p25/median/p75/max; categorical top_1..top_k + top_#_n with deterministic tie-break (count desc, then string(value) asc; missing token )\n- [ ] Output: default long schema by..., column, metric, value; optional wide pivots metrics\n- [ ] Tests: by vs no-by; default-only-n; date coercion; numeric quartiles; categorical tie-breaking\n- [ ] Docs: README example(s) for summary()

[mewincaka]

CI is green ✅ — ready for review: #7

[mewincaka]

@notskynet-bot

Requirements (Phase 3: summary())

• Add epydem.summary(df, by=None, date_cols=None, numeric_cols=None, categorical_cols=None, top_k=3, output="long") -> pd.DataFrame

• Conservative defaults (strict):

  • If date_cols, numeric_cols, and categorical_cols are all None/empty => return only n (respecting by)
  • Do not infer columns automatically

• Metrics:

  • n per group
  • Missingness per specified column: missing_n, missing_pct
  • Date cols: min, max after pd.to_datetime(..., errors="coerce") (invalid -> missing)
  • Numeric cols: count, mean, std, min, p25, median, p75, max
  • Categorical cols: top_1..top_k and top_#_n
    • deterministic tie-break: count desc, then string(value) asc
    • missing token: <NA>

• Output:

  • default output="long" schema: by..., column, metric, value
  • optional output="wide" pivots metrics into columns (index includes by... + column)

• Tests:

  • by vs no-by
  • default-only-n behavior
  • date coercion behavior
  • numeric quartiles
  • categorical tie-breaking

• Docs: add README example(s) for summary()