solarpy.plotting.plot_shading_heatmap

solarpy.plotting.plot_shading_heatmap#

solarpy.plotting.plot_shading_heatmap(value, solar_azimuth, solar_elevation, azimuth_bin_size=1.0, elevation_bin_size=1.0, encoding='max', cmap='viridis', norm=None, northern_hemisphere=True, horizon=None, colorbar=True, colorbar_label=None, ax=None, pcolormesh_kwargs=None)#

Plot a heatmap of solar irradiance in azimuth–elevation space.

Each cell of the heatmap represents a bin of solar azimuth (x-axis) and solar elevation (y-axis). Cell colour encodes the value returned by encoding for all observations in that bin.

It is recommended to first filter out obvious outliers using automatic QC checks.

Parameters:

  • value (array-like of float) – Irradiance time series. Value can be normalized with respect to extraterrestrial irradiance.

  • solar_azimuth (array-like of float) – Solar azimuth angle in degrees (0–360, measured clockwise from North). Must be the same length as value.

  • solar_elevation (array-like of float) – Solar elevation angle in degrees (0–90 above the horizon). Must be the same length as value.

  • azimuth_bin_size (float, optional) – Width of each azimuth bin in degrees. Default is 1.0.

  • elevation_bin_size (float, optional) – Height of each elevation bin in degrees. Default is 1.0.

  • northern_hemisphere (bool, optional) – Set to False for southern hemisphere sites. The sun transits north there, so the solar azimuth path crosses 0°/360°. When False, azimuths are shifted to centre the plot around north, keeping the sun path continuous. Default is True.

  • horizon (pd.Series, optional) – Horizon elevation profile to overlay on the heatmap. The index must contain azimuth angles in degrees and the values must contain the corresponding horizon elevation angles in degrees. Matches the output of solarpy.horizon.get_horizon_mines().

  • encoding (callable or str, optional) – Reduction function applied to the values in each bin. Accepts any string supported by scipy.stats.binned_statistic_2d ('max', 'min', 'mean', 'median', 'sum', 'count'), or a callable that takes a 1-D np.ndarray and returns a scalar, e.g. lambda x: np.quantile(x, 0.95). Default is 'max'.

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

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

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

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

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

  • pcolormesh_kwargs (dict, optional) – Extra keyword arguments forwarded directly to ax.pcolormesh. Note that cmap, norm, and shading are set by the function and will raise a TypeError if passed here. Default is None.

Returns:

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

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

Return type:

tuple[Figure, Axes]

Notes

For the heatmap to be useful for detecting shading in solar irradiance measurement data, the data frequency needs to be less than 10 minutes.

Only data points with solar_elevation >= 0 are included; negative elevations (sun below the horizon) are discarded.

Examples

>>> import solarpy
>>> import pandas as pd
>>> import pvlib
>>> from matplotlib.colors import TwoSlopeNorm
>>> times = pd.date_range("2023-01-01", periods=24*8760, freq="min", tz="UTC")
>>> loc = pvlib.location.Location(latitude=55.68, longitude=12.57)
>>> solpos = loc.get_solarposition(times)
>>> dni_clear = loc.get_clearsky(times)["dni"]
>>> # create a fictional shading object
>>> shading = (solpos['azimuth']>90) & (solpos['azimuth']<110) & (solpos['elevation']<8)
>>> dni_clear[shading] = 0  # does not receive direct irradiance
>>> dni_extra = pvlib.irradiance.get_extra_radiation(times)
>>> fig, ax = solarpy.plotting.plot_shading_heatmap(
...     value=dni_clear / dni_extra,
...     solar_azimuth=solpos["azimuth"],
...     solar_elevation=solpos["elevation"],
...     cmap=solarpy.plotting.two_part_colormap(),
...     norm=TwoSlopeNorm(vmin=0, vcenter=0.05, vmax=0.7),
... )
Contents