FrameOn.viz.heatmap

FrameOnViz.heatmap(x: str | None = None, y: str | None = None, z: str | None = None, do_pivot: bool = False, agg_func: str | None = None, hide_first_column: bool = False, trim_top_n_x: int | None = None, trim_top_n_y: int | None = None, trim_top_n_direction: Literal['top', 'bottom'] = 'top', trim_top_n_agg_func: Literal['mean', 'median', 'sum', 'count', 'nunique'] = 'count', category_orders: Dict[str, str | List[str]] | None = None, labels: Dict[str, str] | None = None, fill_value: float | int | None = None, **plotly_kwargs) → CustomFigure

Creates an enhanced heatmap visualization with support for data aggregation, filtering, and advanced customization.

Parameters:

xstr, optional

Column name for x-axis (required for pivot mode)

ystr, optional

Column name for y-axis (required for pivot mode)

zstr, optional

Column name for values (required for pivot mode)

do_pivotbool, default False

Whether to create a pivot table before visualization

agg_funcstr, optional

Aggregation function for pivot mode. Options: ‘mean’, ‘median’, ‘sum’, ‘count’, ‘nunique’, ‘min’, ‘max’

hide_first_columnbool, default False

Whether to skip first column in cohort analysis or other cases

trim_top_n_xint, optional

Only for aggregation mode. The number of top categories x axis to include in the chart. For top using num column and agg_func.

trim_top_n_yint, optional

Only for aggregation mode. The number of top categories y axis to include in the chart. For top using num column and agg_func

trim_top_n_directionstr, optional

Trim from bottom or from top. Default is ‘top’

trim_top_n_agg_funcstr, default ‘count’

Aggregation function for top-N filtering

category_ordersdict, optional

Specifies order of categories on axes. Keys can be ‘x’ or ‘y’,

values can be:

• List of categories in desired order

• String specifying sorting method:

  • ‘category ascending/descending’ - alphabetical

  • ‘count ascending/descending’ - by value count

  • ‘sum/mean/median/min/max ascending/descending’ - by aggregated value

labelsdict with str keys and str values (default {})

Sets names used in the figure for axis titles (keys x and y), colorbar title and hoverlabel (key color). The values should correspond to the desired label to be displayed. If img is an xarray, dimension names are used for axis titles, and long name for the colorbar title (unless overridden in labels). Possible keys are: x, y, and color.

fill_valueint, float, default None

fill_value for pd.pivot_table. Value to replace missing values with (in the resulting pivot table, after aggregation).

plotly_kwargs

Additional keyword arguments to pass to the Plotly Express function. Default is None

Returns

CustomFigure

Interactive Plotly figure object