Track D — Chapter 9: Visualization and reporting that doesn’t mislead

PyPI workbook run (Track D)

From inside your Track D workbook folder (created by pystatsv1 workbook init --track d --dest ...), run:

pystatsv1 workbook run |trackd_run|

Outputs are written under outputs/track_d/ by default. If you’re unsure what a file is for, start with Track D Outputs Guide.

To see the full chapter-by-chapter run map (D00–D23), see Track D chapter index (PyPI).

Optional: write to a custom output folder:

pystatsv1 workbook run |trackd_run| --outdir outputs/track_d_custom

Interpretation prompts (quick self-check):

  • What is the accounting or business measurement goal in this chapter?

  • Which invariant/check would catch a “numbers look fine but are wrong” mistake here?

Chapter 9 introduces a conservative plotting + reporting style contract for Track D. The point is not to make beautiful charts — it is to make charts that are hard to misread and hard to misuse.

In business settings, a chart is often treated as “proof.” This chapter teaches how to match the intent of a chart to its design, and how to add small guardrails so the visuals remain honest.

Learning objectives

By the end of Chapter 9, you should be able to:

  • Choose the right chart for the question (trend vs. comparison vs. distribution).

  • Avoid common visualization pitfalls (“chart crimes”) such as y-axis truncation, cherry-picked time windows, and ambiguous labels.

  • Produce a one-page executive story: a compact narrative that summarizes the key insights from a small chart pack (strictly limited to 10 bullets).

What we implement in code

This chapter implements two things:

  1. A reusable style/guardrails module:

  • pystatsv1.trackd.reporting_style (source: src/pystatsv1/trackd/reporting_style.py)

  1. A Chapter 9 driver that produces a small, compliant “chart pack” + manifest:

  • scripts/business_ch09_reporting_style_contract.py

The style contract (rules)

The style contract lives in pystatsv1.trackd.reporting_style as STYLE_CONTRACT.

Note: scripts/_reporting_style.py is kept as a small shim for backward compatibility with older Track D scripts and workbook templates. It is intentionally conservative so later chapters can reuse it.

Allowed chart types

  • Line: trends over time (monthly KPIs, DSO).

  • Bar: categorical comparisons (by product, by department) with a zero baseline.

  • Histogram: distribution shape.

  • ECDF: distribution tails (what fraction is below a threshold?).

  • Box: distribution comparison across groups.

  • Scatter: relationships between two variables.

  • Bridge (waterfall): reconcile a change (e.g., net income) into additive components.

Labeling rules

  • Title required.

  • X and Y labels required.

  • Include units in labels where possible (e.g., “Days”, “$”, “%”).

  • Legends only when multiple series are present.

  • Month labels should be shown as YYYY-MM.

Axis guardrails

  • Bar charts start at zero (default guardrail against y-axis tricks).

  • Avoid dual axes.

  • For ratio charts (margins, growth), include a 0 reference line when helpful.

Distributions (e.g., A/R payment lag)

Skewed business distributions (like days-to-pay) should be communicated using a pair of views:

  • Histogram + vertical markers for mean, median, and a tail marker such as p90.

  • ECDF to reveal tails (e.g., “90% of payments are within X days”).

Chapter outputs

Running Chapter 9 writes these outputs to the chosen outdir:

  • ch09_style_contract.json - The style contract rules in a portable format.

  • ch09_figures_manifest.csv - A manifest (audit log) of each figure: filename, chart type, labels, and guardrail note.

  • ch09_executive_memo.md - A “10-bullet max” executive memo generated from the same inputs.

  • ch09_summary.json - A small structured summary (paths + counts).

  • figures/*.png - The example chart pack:

    • kpi_revenue_net_income_line.png

    • kpi_margins_line.png

    • ar_dso_line.png

    • ar_days_hist.png

    • ar_days_ecdf.png

    • net_income_bridge.png

How to run

From the repo root (Windows / Git Bash):

python -m scripts.business_ch09_reporting_style_contract \
  --datadir data/nso_v1 \
  --outdir outputs/track_d/ch09 \
  --seed 123

The command expects NSO v1 simulator exports in --datadir. Chapter 9 reuses Chapter 8’s computations (KPIs + A/R metrics) and focuses on consistent presentation.

Reading the manifest

The manifest exists so a reviewer can answer:

  • What chart type was used?

  • Are labels present?

  • Is there an explicit note when a guardrail matters?

In practice, this makes visual outputs auditable during code review.

Visualization pitfalls (“chart crimes”)

Common problems this chapter is designed to prevent:

  • Y-axis truncation in bar charts to exaggerate differences.

  • Ambiguous labels (“Revenue” without units, unclear time period).

  • Cherry-picked time windows that hide seasonality or volatility.

  • Smoothing away volatility that management should see.

  • Dual-axis charts that encourage accidental correlation.

End-of-chapter problems

1) Chart correction

You are given three misleading charts (examples might include a truncated bar chart or an over-smoothed line chart).

Task:

  • Rebuild each chart using Chapter 9 helpers.

  • Add a one-paragraph justification explaining what was misleading and how you fixed it.

Deliverable:

  • “Before” (original) + “After” (corrected) figures.

  • A short justification that references the style contract guardrails.

2) Variance waterfall (“bridge chart”)

A bridge chart explains how a value changed from one period to the next. It reduces storytelling bias because the components must reconcile to the start and end totals.

In this repo, Chapter 9 ships an audit-friendly net income bridge:

  • Start: prior month net income

  • Components: revenue change, COGS change, operating expense change

  • Residual: “Other / rounding” to reconcile exactly (if needed)

  • End: latest month net income

Task:

  • Review the generated bridge chart and confirm the sign conventions.

  • Write a short paragraph summarizing the dominant drivers.

Deliverable:

  • figures/net_income_bridge.png

  • 1 paragraph interpretation (no false precision)

3) The 10-bullet memo

Write a narrative executive summary based on a provided chart pack.

Rules:

  • Maximum 10 bullets.

  • Every bullet must reference a chart or a metric.

  • No false precision (prefer rounding: “$1.0M” instead of “$1,000,043.22”).

Deliverable:

  • A markdown memo.

  • Include a short “assumptions and caveats” section.

What’s next

Chapter 10 will build on this chapter by translating distributions into probability-and-risk statements (e.g., “we will miss payroll 1 out of 20 months”) and by communicating uncertainty without false precision.