Plot types
This page is a WIP of plot types and examples. Plots are in active development and this page may quickly become out of date.
Python files related to plots are available under C:\ProgramData\BHoM\Extensions\PythonCode\LadybugTools_Toolkit\src\ladybugtools_toolkit\plot
Some plot types return an axis object rather than a figure object. This provides more flexibility as multiple axes can now be added to the same figure.
To set up a figure with a single axis:
import matplotlib.pyplot as plt
from ladybugtools_toolkit.plot import utci_journey
fig, ax = plt.subplots(1, 1, figsize=(10,3))
utci_journey([23,34,12], ax=ax)
This sets up a figure with a single subplot (the 1, 1 means 1 subplot along and 1 subplot down), sets its size, and adds a utci_journey to the figure.
Create a plot of the condensation potential for a given set of timeseries dry bulb temperature and dew point temperature.
Args:
dry_bulb_temperature (pd.Series):
The dry bulb temperature dataset.
dew_point_temperature (pd.Series):
The dew point temperature dataset.
ax (plt.Axes, optional):
An optional plt.Axes object to populate. Defaults to None,
which creates a new plt.Axes object.
dbt_quantile (float, optional):
The quantile of the dry bulb temperature to use for the
condensation potential calculation. Defaults to 0.1.
dpt_quantile (float, optional):
The quantile of the dew point temperature to use for the
condensation potential calculation. Defaults to 0.9.
**kwargs:
A set of kwargs to pass to plt.plot.
Returns:
plt.Axes: The plt.Axes object populated with the plot.
from ladybug.epw import EPW
from ladybugtools_toolkit.ladybug_extension.datacollection import collection_to_series
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
temp = collection_to_series(epw.dry_bulb_temperature)
dewp = collection_to_series(epw.dew_point_temperature)
from ladybugtools_toolkit.plot._condensation_potential import condensation_potential
condensation_potential(temp, dewp)Plot the heating and cooling degree days from a given EPW object.
Args:
epw (EPW):
An EPW object.
heat_base (float, optional):
The temperature at which heating kicks in. Defaults to 18.
cool_base (float, optional):
The temperature at which cooling kicks in. Defaults to 23.
**kwargs:
Additional keyword arguments to pass to the plot. These can include:
heat_color (str):
The color of the heating degree days bars.
cool_color (str):
The color of the cooling degree days bars.
figsize (Tuple[float]):
The size of the figure.
Returns:
Figure:
A matplotlib Figure object.
You can plot heating and cooling in the same plot (degree_days), or plot them separately (heating_degree_days), (cooling_degree_days)
from ladybug.epw import EPW
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
from ladybugtools_toolkit.plot._degree_days import degree_days
from ladybugtools_toolkit.plot._degree_days import heating_degree_days
from ladybugtools_toolkit.plot._degree_days import cooling_degree_days
degree_days(epw)
heating_degree_days(epw)
cooling_degree_days(epw)Plot evaporative cooling potential (DBT - DPT).
Args:
dbt (pd.Series):
A pandas Series containing Dry Bulb Temperature data.
dpt (pd.Series):
A pandas Series containing Dew Point Temperature data.
ax (plt.Axes, optional):
The matplotlib axes to plot the figure on. Defaults to None.
**kwargs:
Additional keyword arguments to pass to the heatmap function.
Returns:
plt.Axes: The matplotlib axes.
from ladybug.epw import EPW
from ladybugtools_toolkit.ladybug_extension.datacollection import collection_to_series
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
temp = collection_to_series(epw.dry_bulb_temperature)
dewp = collection_to_series(epw.dew_point_temperature)
from ladybugtools_toolkit.plot._evaporative_cooling_potential import evaporative_cooling_potential
evaporative_cooling_potential(temp,dewp)Plot radiant cooling potential.
Args:
dpt (pd.Series):
A pandas series of dew point temperature.
ax (plt.Axes, optional):
The matplotlib axes to plot the figure on. Defaults to None.
**kwargs:
Additional keyword arguments to pass to matplotlib.pyplot.plot.
Returns:
plt.Axes: The matplotlib axes.
from ladybug.epw import EPW
from ladybugtools_toolkit.ladybug_extension.datacollection import collection_to_series
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
dewp = collection_to_series(epw.dew_point_temperature)
from ladybugtools_toolkit.plot._radiant_cooling_potential import radiant_cooling_potential
radiant_cooling_potential(dewp)Create a plot which shows where the seasohn threshholds are for the input EPW object.
Args:
epw (EPW):
An EPW object.
ax (plt.Axes, optional):
A matplotlib axes object. Default is None which uses the current axes.
color_config (dict[str, str], optional):
A dictionary of colors for each season. If None, then default will be used.
**kwargs:
title (str):
The title of the plot. If not provided, then the name of the EPW file is used.
from ladybug.epw import EPW
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
from ladybugtools_toolkit.plot._seasonality import seasonality_comparison
seasonality_comparison(epw)Create a sky matrix image.
Args:
epw (EPW):
A EPW object.
ax (plt.Axes, optional):
The matplotlib Axes to plot on. Defaults to None which uses the current Axes.
analysis_period (AnalysisPeriod, optional):
An AnalysisPeriod. Defaults to AnalysisPeriod().
density (int, optional):
Sky matrix density. Defaults to 1.
show_title (bool, optional):
Show the title. Defaults to True.
show_colorbar (bool, optional):
Show the colorbar. Defaults to True.
**kwargs:
Additional keyword arguments to pass to the plotting function.
Returns:
Figure:
A matplotlib Figure object.
from ladybug.epw import EPW
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
from ladybugtools_toolkit.plot._skymatrix import skymatrix
skymatrix(epw)Plot a sun-path for the given Location and analysis period.
Args:
location (Location):
A ladybug Location object.
ax (plt.Axes, optional):
A matplotlib Axes object. Defaults to None.
analysis_period (AnalysisPeriod, optional):
_description_. Defaults to None.
data_collection (HourlyContinuousCollection, optional):
An aligned data collection. Defaults to None.
cmap (str, optional):
The colormap to apply to the aligned data_collection. Defaults to None.
norm (BoundaryNorm, optional):
A matplotlib BoundaryNorm object containing colormap boundary mapping information.
Defaults to None.
sun_size (float, optional):
The size of each sun in the plot. Defaults to 0.2.
show_grid (bool, optional):
Set to True to show the grid. Defaults to True.
show_legend (bool, optional):
Set to True to include a legend in the plot if data_collection passed. Defaults to True.
Returns:
plt.Axes:
A matplotlib Axes object.
from ladybug.epw import EPW, Location
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
location = epw.location
from ladybugtools_toolkit.plot._sunpath import sunpath
sunpath(location)Plot cloud cover categories from an EPW file.
Args:
epw (EPW):
The EPW file to plot.
ax (plt.Axes, optional):
A matploltib axes to plot on. Defaults to None.
Returns:
plt.Axes:
The matplotlib axes.
from ladybug.epw import EPW, Location
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
location = epw.location
from ladybugtools_toolkit.plot._misc import hours_sunlight
hours_sunlight(location)Create a monthly histogram of a pandas Series.
Args:
series (pd.Series):
The pandas Series to plot. Must have a datetime index.
bins (list[float]):
The bins to use for the histogram.
ax (plt.Axes, optional):
An optional plt.Axes object to populate. Defaults to None, which creates a new plt.Axes object.
labels (list[str], optional):
The labels to use for the histogram. Defaults to None, which uses the bin edges.
show_year_in_label (bool, optional):
Whether to show the year in the x-axis label. Defaults to False.
show_labels (bool, optional):
Whether to show the labels on the bars. Defaults to False.
show_legend (bool, optional):
Whether to show the legend. Defaults to False.
**kwargs:
Additional keyword arguments to pass to plt.bar.
Returns:
plt.Axes:
The populated plt.Axes object.
from ladybug.epw import EPW
from ladybugtools_toolkit.ladybug_extension.datacollection import collection_to_series
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
dbt = collection_to_series(epw.dry_bulb_temperature)
bins = [-30, -20, -10, 0, 10, 20, 30]
from ladybugtools_toolkit.plot._monthly_histogram_proportion import monthly_histogram_proportion
monthly_histogram_proportion(dbt, bins)Create a psychrometric chart using a LB backend.
Args:
epw (EPW):
An EPW object.
cmap (Colormap, optional):
A colormap to color things with!.
Default is "viridis".
analysis_period (AnalysisPeriod, optional):
An analysis period to filter values by.
Default is whole year.
wet_bulb (bool, optional):
Plot wet-bulb temperature constant lines instead of enthalpy.
Default is False.
psychro_polygons (PsychrometricPolygons, optional):
A PsychrometricPolygons object to use for plotting comfort polygons.
Default is None.
figsize (tuple[float, float], optional):
A tuple of floats for the figure size.
Default is (10, 7).
Returns:
plt.Figure:
A Figure object.
from ladybug.epw import EPW
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
from ladybugtools_toolkit.plot._psychrometric import psychrometric
psychrometric(epw)Create a combined heatmap/histoghram figure for a UTCI data collection.
Args:
utci_collection (HourlyContinuousCollection):
A ladybug HourlyContinuousCollection object.
utci_categories (Categories, optional):
A Categories object with colors, ranges and limits. Defaults to UTCI_DEFAULT_CATEGORIES.
show_colorbar (bool, optional):
Set to True to show the colorbar. Defaults to True.
**kwargs:
Additional keyword arguments to pass.
Returns:
Figure:
A matplotlib Figure object.
from ladybug.epw import EPW
from ladybugtools_toolkit.external_comfort.typology import Typology
from ladybugtools_toolkit.external_comfort.simulate import SimulationResult
from ladybugtools_toolkit.external_comfort.material import Materials
from ladybugtools_toolkit.external_comfort.externalcomfort import ExternalComfort
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
dbt = epw.dry_bulb_temperature
typology = Typology(identifier="Unshaded, wind (baseline)")
ground_material = Materials.Generic_HW_Concrete
shade_material = Materials.Generic_25mm_Wood
sr = SimulationResult(epw_path, ground_material, shade_material)
ec = ExternalComfort(sr, typology)
from ladybugtools_toolkit.plot._utci import utci_heatmap_histogram
utci_heatmap_histogram(ec.universal_thermal_climate_index)Create a histogram showing the distribution of UTCI values.
Args:
utci_collection (HourlyContinuousCollection):
A ladybug HourlyContinuousCollection object.
ax (plt.Axes, optional):
A matplotlib Axes object to plot on. Defaults to None.
utci_categories (Categories, optional):
A Categories object with colors, ranges and limits. Defaults to UTCI_DEFAULT_CATEGORIES.
show_labels (bool, optional):
Set to True to show the UTCI category labels on the plot. Defaults to False.
**kwargs:
Additional keyword arguments to pass to the plotting function.
Returns:
plt.Axes:
A matplotlib Axes object.
from ladybug.epw import EPW
from ladybugtools_toolkit.external_comfort.typology import Typology
from ladybugtools_toolkit.external_comfort.simulate import SimulationResult
from ladybugtools_toolkit.external_comfort.material import Materials
from ladybugtools_toolkit.external_comfort.externalcomfort import ExternalComfort
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
dbt = epw.dry_bulb_temperature
typology = Typology(identifier="Unshaded, wind (baseline)")
ground_material = Materials.Generic_HW_Concrete
shade_material = Materials.Generic_25mm_Wood
sr = SimulationResult(epw_path, ground_material, shade_material)
ec = ExternalComfort(sr, typology)
from ladybugtools_toolkit.plot._utci import utci_histogram
utci_histogram(ec.universal_thermal_climate_index)Plot the shade benefit category.
Args:
unshaded_utci (HourlyContinuousCollection | pd.Series):
A dataset containing unshaded UTCI values.
shaded_utci (HourlyContinuousCollection | pd.Series):
A dataset containing shaded UTCI values.
comfort_limits (tuple[float], optional):
The range within which "comfort" is achieved. Defaults to (9, 26).
location (Location, optional):
A location object used to plot sun up/down times. Defaults to None.
color_config (dict[str, str], optional):
A dictionary of colors for each shade-benefit category.
If None then defaults will be used.
figsize (tuple[float], optional):
The size of the figure. Defaults to (15, 5).
**kwargs:
Additional keyword arguments to pass to the plotting function.
title (str, optional):
The title of the plot. Defaults to None.
Returns:
plt.Figure:
A figure object.
from ladybug.epw import EPW
from ladybugtools_toolkit.external_comfort.typology import Typology
from ladybugtools_toolkit.external_comfort.simulate import SimulationResult
from ladybugtools_toolkit.external_comfort.material import Materials
from ladybugtools_toolkit.external_comfort.externalcomfort import ExternalComfort
epw_path = r" Paste path to epw file inside quotation marks "
epw = EPW(epw_path)
dbt = epw.dry_bulb_temperature
typologyOne = Typology(identifier="Unshaded", wind_speed_multiplier=2)
typologyTwo = Typology(identifier="Shaded", wind_speed_multiplier=0.5)
ground_material = Materials.Generic_HW_Concrete
shade_material = Materials.Generic_25mm_Wood
sr = SimulationResult(epw_path, ground_material, shade_material)
ecUnshaded = ExternalComfort(sr, typologyOne)
ecShaded = ExternalComfort(sr, typologyTwo)
from ladybugtools_toolkit.plot._utci import utci_shade_benefit
utci_shade_benefit(ecUnshaded.universal_thermal_climate_index, ecShaded.universal_thermal_climate_index)