Features

This chapter covers the core features and capabilities of Cohort Tool.

Features

• Retention analysis — Track what percentage of users remain active over time
• Flexible cohorts — Group by month, week, or day
• Heatmap output — HTML retention heatmap with color-coded cells
• Average retention — See the overall retention curve across all cohorts
• JSON export — Machine-readable results for dashboards and further analysis
• CLI and library — Use from the command line or import as a module

Requirements

• Python 3.10+
• No external dependencies (stdlib only)

Quick Start

Follow this guide to get Cohort Tool up and running in your environment.

Quick Start

# Monthly cohort retention
python src/cohort_tool.py --events examples/sample_cohort_data.json --cohort-by month

# Weekly cohorts with HTML heatmap
python src/cohort_tool.py --events data.json --cohort-by week --html heatmap.html

# Export results
python src/cohort_tool.py --events data.json --output retention.json --periods 12

Output Example

================================================================================
  COHORT RETENTION (MONTH)
  Total users: 450
================================================================================

  Cohort          Size     P0     P1     P2     P3     P4
  --------------------------------------------------------
  2026-01           80  100.0%  72.5%  58.8%  45.0%  38.8%
  2026-02           95  100.0%  68.4%  52.6%  41.1%
  2026-03          110  100.0%  70.9%  55.5%
  2026-04           85  100.0%  65.9%
  2026-05           80  100.0%
  --------------------------------------------------------
  Average                100.0%  69.4%  55.6%  43.0%  38.8%