visualization_generator

Visualization functions for cohort analysis using Plotly.

This module provides core visualization functions to help analyze and interpret cohort data generated by the generate_cohort_data function.

repeatradar.visualization_generator.plot_cohort_heatmap(cohort_data: DataFrame, title: str | None = None, color_scale: str = 'Blues', show_values: bool = True, value_format: str = '.0f', width: int = 800, height: int = 600, show_colorscale: bool = True, reverse_y_axis: bool = True) → Figure[source]

Create a heatmap visualization of cohort data.

This function generates an interactive heatmap using Plotly to visualize cohort analysis results. The heatmap displays cohorts on the y-axis and analysis periods on the x-axis, with color intensity representing the metric values.

Parameters:

  • cohort_data (pd.DataFrame) – Cohort data in pivot format (cohorts as rows, periods as columns)

  • title (Optional[str], optional) – Title for the plot. If None, a default title will be generated, defaults to None

  • color_scale (str, optional) – Color scale for the heatmap. Common options: “Blues”, “Viridis”, “RdYlBu”, “Plasma”, defaults to “Blues”

  • show_values (bool, optional) – Whether to show values on the heatmap cells, defaults to True

  • value_format (str, optional) – Format string for displaying values (e.g., “.0f” for integers, “.1f” for 1 decimal), defaults to “.0f”

  • width (int, optional) – Width of the plot in pixels, defaults to 800

  • height (int, optional) – Height of the plot in pixels, defaults to 600

  • show_colorscale (bool, optional) – Whether to show the color scale bar on the right side of the plot, defaults to True

  • reverse_y_axis (bool, optional) – Whether to reverse the y-axis order (newer cohorts at top), defaults to True

Raises:

ValueError – If input DataFrame is empty or invalid color scale is provided

Returns:

Plotly figure object for the heatmap

Return type:

go.Figure

Examples:

>>> cohort_data = generate_cohort_data(df, date_column='date', user_column='user')
>>> fig = plot_cohort_heatmap(cohort_data, title="User Retention Cohorts")
>>> fig.show()
repeatradar.visualization_generator.plot_retention_curves(retention_data: DataFrame, title: str | None = None, show_legend: bool = True, width: int = 900, height: int = 600, max_cohorts: int | None = 10) → Figure[source]

Create line plots showing retention curves for different cohorts.

This function generates an interactive line chart showing how retention rates change over time for different cohorts. Each line represents a cohort, and the x-axis represents analysis periods while the y-axis shows retention rates.

Parameters:

  • retention_data (pd.DataFrame) – Retention rate data in pivot format (should be retention percentages)

  • title (Optional[str], optional) – Title for the plot, defaults to None

  • show_legend (bool, optional) – Whether to show the legend, defaults to True

  • width (int, optional) – Width of the plot in pixels, defaults to 900

  • height (int, optional) – Height of the plot in pixels, defaults to 600

  • max_cohorts (Optional[int], optional) – Maximum number of cohorts to display (None for all), defaults to 10

Returns:

Plotly figure object for the retention curves

Return type:

go.Figure

Examples:

>>> retention_data = generate_cohort_data(df, date_column='date', user_column='user',
...                                       calculate_retention_rate=True)
>>> fig = plot_retention_curves(retention_data)
>>> fig.show()