How to read and design a cohort retention heatmap
A cohort heatmap should place acquisition cohorts in rows, elapsed age in columns, and a consistently defined retention metric in cells. Leave future periods blank, show cohort size, use a perceptually ordered color scale with labeled values, and add a weighted retention curve. Read vertical patterns as lifecycle effects and diagonals as possible calendar events, then verify them in the underlying counts.
What changes the answer
- Blank unobservable cells instead of assigning zero.
- Show counts beside percentages.
- Use an ordered color scale with sufficient contrast.
- Separate lifecycle patterns from calendar shocks.
From the field · Mobile-app product analyst
Design an app retention heatmap that marks unobservable periods
January users have six months of observation while June users have only one. Filling unavailable June cells with zero makes the newest cohort look like it collapsed even though those months have not occurred.
Columns used in the example
user_id · signup_date · activity_date · cohort_month · months_since_signup · active_flag
Follow it with your own file
- Create one cohort anchor and one active definition.
- Retain each cohort's starting denominator and calculate only observable periods.
- Render future/unavailable cells as blank or not yet observed, never zero.
- Use a consistent color scale and label material values directly.
Check: Spot-check user timelines and verify that each cell uses the intended denominator. Confirm the triangular unavailable area is visually distinct from observed zero retention.
What needs resolving first
Retention heatmaps look authoritative even when partial periods, tiny cohorts, inconsistent denominators, or a saturated color scale drive the apparent pattern.
The triangular shape carries meaning
Older cohorts have more observable ages, so valid matrices are triangular. Filling the empty triangle with zero makes recent cohorts look like they failed in periods that have not occurred.
Display cohort size at age zero and consider suppressing unstable percentages below a minimum count.
Read three directions
Across a row shows one cohort aging. Down a column compares cohorts at equal age. A diagonal aligns with one calendar period and may reveal an outage, campaign, pricing change, or measurement break.
Color attracts attention; numeric labels and counts determine whether the pattern is material.
Build the result step by step
- Validate the cohort matrix: Confirm stable cohort assignment, age calculation, denominator, reactivation, and observable cells.
- Choose scale and labels: Use one ordered palette, readable contrast, percentage labels, and a visible legend.
- Add context: Show starting cohort count, weighted curve, annotations, and selected benchmarks.
- Interpret patterns carefully: Distinguish row, column, and diagonal effects, then inspect counts and events.
Heatmap components and purpose
| Component | Purpose | Failure if missing |
|---|---|---|
| Cohort size | Show evidence base | Small groups look decisive |
| Blank future cells | Represent observability | Missing time appears as churn |
| Legend and labels | Quantify color | Readers infer wrong magnitude |
| Weighted curve | Summarize trajectory | Visual scan lacks overall context |
Warning signs in the file
- The right edge is filled with zeroes.
- Tiny cohorts have extreme colors without counts.
- The legend starts above zero and exaggerates differences.
- A diagonal band affects several cohort ages at one calendar time.
Make the output easy to check
- Metric defined
- Future cells blank
- Counts shown
- Scale consistent
- Labels accessible
- Patterns verified
Doing these steps in Prepyr
Upload a CSV working copy in Prepyr. Describe the result you need: Read and design a cohort retention heatmap without treating incomplete recent periods as churn. Check the columns selected, preview any proposed changes, and compare the output with the source before applying or exporting it.
Prepyr steps used here: Cohort analysis · Heatmaps · Annotations · Report blocks
A retention visualization that makes cohort quality and lifecycle decay visible without confusing missing observation time with churn.
Questions readers usually ask next
Should high retention always use green?
Not necessarily. Use an accessible sequential palette; reserve red-green semantics carefully.
Can I compare cohorts of different sizes?
Yes, but show sizes and uncertainty because small groups produce unstable rates.
Why is there a diagonal pattern?
Several cohorts likely experienced the same calendar event at different ages; investigate that date.