solarpy.plotting.plot_intraday_heatmap

solarpy.plotting.plot_intraday_heatmap#

solarpy.plotting.plot_intraday_heatmap(time, values, resolution=1, cmap='viridis', norm=None, plot_colorbar=True, colorbar_label='', ax=None, pcolormesh_kwargs=None)#

Plot a heatmap of intraday time series data.

Each column of the heatmap represents one calendar date; each row represents one time bin of resolution minutes. Cell colour encodes the mean of values falling in that date and bin. Dates with no data are included as all-NaN columns so the time axis is always contiguous.

Parameters:

  • time (array-like of datetime-like) – Timestamps corresponding to each value. Must be convertible to numpy.datetime64.

  • values (array-like of float) – Observed values, one per timestamp. Must be the same length as time.

  • resolution (int, optional) – Bin size in minutes. Must evenly divide 1440. Default is 1 (one row per minute). Use 10 for 10-minute bins, 60 for hourly bins, etc.

  • cmap (str, optional) – Matplotlib colormap name. Default is "viridis".

  • norm (matplotlib.colors.Normalize, optional) – Normalization instance to map data values to the colormap range. Accepts any matplotlib.colors norm, e.g. Normalize, LogNorm, TwoSlopeNorm, BoundaryNorm. If None (default), linear normalization over the data range is used.

  • plot_colorbar (bool, optional) – Whether to plot a colorbar. Default is True.

  • colorbar_label (str, optional) – Label displayed alongside the colorbar. Default is "".

  • pcolormesh_kwargs (dict, optional) – Extra keyword arguments forwarded directly to ax.pcolormesh. Useful for parameters not exposed explicitly, such as vmin, vmax, alpha, or rasterized. Note that cmap, norm, and shading are set by the function and will raise a TypeError if passed here. Default is None.

  • ax (matplotlib.axes.Axes, optional) – Axes to draw on. If None, a new figure and axes are created.

Returns:

  • fig (matplotlib.figure.Figure) – The figure containing the heatmap.

  • ax (matplotlib.axes.Axes) – The axes containing the heatmap.

Raises:

ValueError – If time and values have different lengths, if either is empty, or if resolution does not evenly divide 1440.

Return type:

tuple[Figure, Axes]

Notes

When multiple values fall in the same bin their mean is displayed. Missing bin/date combinations are shown as white cells.

The y-axis runs from midnight (00:00) at the bottom to 23:59 at the top (for 1-minute resolution). X-axis tick density adapts to the date range: daily labels for short ranges, weekly or monthly for longer ones.

Examples

Minute-resolution data over two weeks:

>>> import solarpy
>>> import numpy as np
>>> import pandas as pd
>>> mins = np.arange(14 * 1440)
>>> time = pd.Timestamp("2024-01-01") + pd.to_timedelta(mins, unit='min')
>>> values = np.sin(mins / 1440 * np.pi) + 0.1 * np.random.randn(len(mins))
>>> fig, ax = solarpy.plotting.plot_intraday_heatmap(
...     time, values, cmap="viridis")

Ten-minute bins over one year:

>>> mins = np.arange(365 * 144) * 10
>>> time = pd.Timestamp("2024-01-01") + pd.to_timedelta(mins, unit='min')
>>> values = np.random.randn(len(mins))
>>> fig, ax = solarpy.plotting.plot_intraday_heatmap(
...     time, values, resolution=10)
Contents