Dataclock API
The main chart function is dataclock.
Dataclock
- class charts.dataclock(data: DataFrame, date_column: str, agg_column: str | None = None, agg: Literal['count', 'max', 'mean', 'median', 'min', 'sum'] = 'count', mode: Literal['YEAR_MONTH', 'YEAR_WEEK', 'WEEK_DAY', 'DOW_HOUR', 'DAY_HOUR'] = 'DAY_HOUR', cmap_name: str = 'RdYlGn_r', cmap_reverse: bool = False, spine_color: str = 'darkslategrey', grid_color: str = 'darkslategrey', default_text: bool = True, *, chart_title: str | None = None, chart_subtitle: str | None = None, chart_period: str | None = None, chart_source: str | None = None, **fig_kw)[source]
Create a data clock chart from a pandas DataFrame.
Data clocks visually summarise temporal data in two dimensions, revealing seasonal or cyclical patterns and trends over time. A data clock is a circular chart that divides a larger unit of time into rings and subdivides it by a smaller unit of time into wedges, creating a set of temporal bins.
TIP: Palettes - https://python-graph-gallery.com/color-palette-finder/
- Parameters:
data (DataFrame) – DataFrame containing data to visualise.
date_column (str) – Name of DataFrame datetime64 column.
agg (str) – Aggregation function; ‘count’, ‘mean’, ‘median’, ‘mode’ & ‘sum’.
agg_column (str, optional) – DataFrame Column to aggregate.
mode (Mode, optional) – A mode key representing the temporal bins used in the chart; ‘YEAR_MONTH’, ‘YEAR_WEEK’, ‘WEEK_DAY’, ‘DOW_HOUR’ & ‘DAY_HOUR’.
cmap_name – (str, optional): Name of a matplotlib/PyPalettes colormap, to symbolise the temporal bins; ‘RdYlGn_r’, ‘CMRmap_r’, ‘inferno_r’, ‘Alkalay2’, ‘viridis’, ‘a_palette’ etc.
cmap_reverse (bool) – Reverse cmap colors flag.
spine_color (str) – Name of color to style the polar axis spines.
default_text (bool, optional) – Flag to generating default chart annotations for the chart_title (‘Data Clock Chart’) and chart_subtitle (‘[agg] by [period] (rings) & [period] (wedges)’).
chart_title (str, optional) – Chart title.
chart_subtitle (str, optional) – Chart subtitle.
chart_period (str, optional) – Chart reporting period.
chart_source (str, optional) – Chart data source.
fig_kw (dict) – Chart figure kwargs passed to pyplot.subplots.
- Raises:
AggregationColumnError – Expected aggregation column value.
AggregationFunctionError – Unexpected aggregation function value.
EmptyDataFrameError – Unexpected empty DataFrame.
MissingDatetimeError – Unexpected data[date_column] dtype.
ModeError – Unexpected mode value is passed.
- Returns:
A tuple containing a DataFrame with the aggregate values used to create the chart, the matplotlib chart Figure and Axes objects.
Utility
- class utility.add_colorbar(ax: ~matplotlib.axes._axes.Axes, fig: ~matplotlib.figure.Figure, cmap_name: str, cmap_reverse: bool, vmax: float, dtype: ~numpy.dtype[~typing.Any] | None | type[~typing.Any] | ~numpy._typing._dtype_like._SupportsDType[~numpy.dtype[~typing.Any]] | str | tuple[~typing.Any, int] | tuple[~typing.Any, ~typing.SupportsIndex | ~collections.abc.Sequence[~typing.SupportsIndex]] | list[~typing.Any] | ~numpy._typing._dtype_like._DTypeDict | tuple[~typing.Any, ~typing.Any] = <class 'numpy.float64'>)[source]
Add a colorbar to a figure, sharing the provided axis.
- Parameters:
ax (Axes) – Chart Axis.
fig (Figure) – Chart Figure.
dtype (DTypeLike) – Colourbar values dtype.
cmap_name (CmapNames) – Name of matplotlib colormap.
vmax (float) – maximum value of the colorbar.
dtype – Data type for colorbar values.
- Returns:
A Colorbar object with a cmap and normalised cmap.
- class utility.add_text(ax: Axes, x: float, y: float, text: str | None = None, **kwargs)[source]
Annotate a position on an axis denoted by xy with text.
- Parameters:
ax (Axes) – Axis to annotate.
x (int) – Axis x position.
y (int) – Axis y position.
text (str, optional) – Text to annotate.
- Returns:
Text object with annotation.
Exceptions
- class exceptions.AggregationFunctionError(agg: str, valid_functions: Iterable)[source]
Raised on unexpected aggregation function.