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: Literal['RdYlGn_r', 'CMRmap_r', 'inferno_r', 'YlGnBu_r', 'viridis'] = 'RdYlGn_r', chart_title: str | None = None, chart_subtitle: str | None = None, chart_source: str | None = None)[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.

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 – (ColourMap, optional): Matplotlib colormap name used to symbolise the temporal bins; ‘RdYlGn_r’, ‘CMRmap_r’, ‘inferno_r’, ‘YlGnBu_r’ & ‘viridis’.

  • chart_title (str, optional) – Chart title.

  • chart_subtitle (str, optional) – Chart subtitle.

  • chart_source (str, optional) – Chart data source.

Raises:
Returns:

A tuple containing a DataFrame with the aggregate values used to create the chart, the matplotlib chart Figure and Axes objects.

Exceptions

class exceptions.AggregationError(agg: str, agg_column: str)[source]

Raised on incompatible aggregation value & function combination.

class exceptions.ModeError(mode: str, valid_modes: Iterable)[source]

Raised on incorrect chart mode value.