Plots#

This section provides an overview of the plotting capabilities available in pythermalcomfort. The library offers class-based utilities to visualize model results with Matplotlib. We also provide examples of how to create visually compelling and informative plots using popular Python libraries such as Matplotlib and Seaborn.

To use the plotting functions we included in pythermalcomfort, please install the optional dependencies using:

pip install pythermalcomfort[plots]

Typical Use Cases#

Comparing the results of different thermal comfort models.
Visualizing the impact of various parameters (e.g., temperature, humidity, clothing insulation) on model output.
Creating custom plots to communicate findings effectively.
Analyse the comfort levels in different environments.
Process, analyze, and visualise:
- climate data in different formats (e.g., CSV, Excel, JSON, EPW)
- results from building simulation software.
- results from sensor data.

Plotting Examples#

The pythermalcomfort.plots.matplotlib module includes configurable plotting classes. These classes can be used to compare model results and to visualize how variables affect outcomes.

The plot module has a sub-module for different backends, currently supporting Matplotlib only, but we plan to add support for other libraries in the future (e.g., Plotly, Bokeh, Seaborn).

All plotting APIs return Matplotlib handles that can be further customized. This allows users to create richer visualizations by adding overlays or modifying existing artists. The full list of customizable parameters is available in the class docstrings. Use the search functionality in the top-right corner to find specific functions.

Click on the links below to show some examples of the plotting functions available in pythermalcomfort. The full list of functions is available in the “Plotting Functions Reference” section at the end of this page.

Practical Recipes#

These examples combine different chart types with standard Matplotlib workflows to produce time series, overlays, and multi-panel figures.

Combined Plot Examples

Threshold Plot#

class pythermalcomfort.plots.matplotlib.ThresholdPlot(model_func)[source]#

Configure and render threshold regions for a selected model function.

The API is staged and explicit:

configure x and y axes,
set fixed model parameters,
define output thresholds and optional labels/colors,
render with plot().

The returned result contains editable Matplotlib artists, so users can apply additional styling with standard Matplotlib code.

Examples

from pythermalcomfort.models import pmv_ppd_iso
from pythermalcomfort.plots.matplotlib import ThresholdPlot

result = (
    ThresholdPlot(pmv_ppd_iso)
    .set_x_axis("tdb", 18.0, 34.0, resolution=0.2)
    .set_y_axis("rh", 20.0, 100.0, resolution=0.5)
    .set_params(vr=0.10, met=1.2, clo=0.5, wme=0.0)
    .set_regions(output="pmv", thresholds=[-0.5, 0.5])
    .plot(title="PMV Threshold Regions")
)
result.ax.set_xlabel("Air temperature [°C]")

set_regions(*, output, thresholds, labels=None, colors=None)[source]#

Configure output regions.

Parameters:

output (str) – Output field or column name.
thresholds (sequence of float) – Numeric boundary values that divide the output range into regions.
labels (sequence of str, optional) – Region labels. Must have length len(thresholds) + 1 when provided.
colors (sequence of str, optional) – Region colors. Must have length len(thresholds) + 1 when provided.

Returns:

ThresholdPlot – Self, to support method chaining.

Raises:

TypeError – If output is not a string.
ValueError – If output name is empty, or thresholds/labels/colors are invalid.

plot(*, ax=None, title=None, legend=True, show_lines=True, line_kws=None, fill_kws=None, legend_kws=None, invalid_color='#bdbdbd')[source]#

Render threshold regions and contours on a Matplotlib axis.

Parameters:

ax (Axes, optional) – Existing axis to draw on. If None, a new figure/axis is created with a default size of (7, 4) inches.
title (str, optional) – Optional axis title.
legend (bool) – Whether to draw a legend.
show_lines (bool) – Whether to draw threshold contour boundaries.
line_kws (dict, optional) – Keyword overrides forwarded to ax.plot for contour lines.
fill_kws (dict, optional) – Keyword overrides forwarded to ax.contourf for region fills. Keys color and facecolor are reserved and rejected.
legend_kws (dict, optional) – Keyword overrides forwarded to ax.legend.
invalid_color (str) – Color used for out-of-model/invalid grid areas.

Returns:

ThresholdPlotResult – Result with axis and artist handles.

Raises:

ValueError – If required configuration is missing, plotting inputs are invalid, or model evaluation/output extraction fails.

__init__(model_func)#

Initialize the grid plot builder.

Parameters:: model_func (callable) – Callable model function (typically from pythermalcomfort.models). Its signature is inspected to validate axis names and fixed parameters.

set_params(**kwargs)#

Set fixed model parameters used during grid evaluation.

Parameters:: **kwargs (Any) – Fixed model inputs passed unchanged to model evaluations.
Returns:: GridBasePlot – Self, to support method chaining.
Raises:: ValueError – If parameter names are invalid for the model signature or conflict with configured x/y axis parameters.

Notes

tr / tdb auto-link — When the model accepts both tdb (dry-bulb temperature) and tr (mean radiant temperature), and one of them is used as an axis parameter, the other is automatically set to the same per-cell value if it is not explicitly supplied here. For example, if tdb is the x-axis and tr is omitted, every model call receives tr = tdb. Supply tr=<value> explicitly to override this behaviour.

set_x_axis(name, min_val, max_val, *, resolution)#

Set x-axis model parameter, range, and grid resolution.

Parameters:

name (str) – Model argument name mapped to the x-axis.
min_val (float) – Minimum x-axis value.
max_val (float) – Maximum x-axis value.
resolution (float) – Grid step along x-axis used for contour evaluation.

Returns:

GridBasePlot – Self, to support method chaining.

Raises:

TypeError – If name is not a string.
ValueError – If name is empty/invalid, conflicts with y-axis, conflicts with fixed params, or range/resolution are invalid.

set_y_axis(name, min_val, max_val, *, resolution)#

Set y-axis model parameter, range, and grid resolution.

Parameters:

name (str) – Model argument name mapped to the y-axis.
min_val (float) – Minimum y-axis value.
max_val (float) – Maximum y-axis value.
resolution (float) – Grid step along y-axis used for contour evaluation.

Returns:

GridBasePlot – Self, to support method chaining.

Raises:

TypeError – If name is not a string.
ValueError – If name is empty/invalid, conflicts with x-axis, conflicts with fixed params, or range/resolution are invalid.

class pythermalcomfort.plots.matplotlib.ThresholdPlotResult(fig, ax, lines, fills, legend)[source]#

Container with handles returned by ThresholdPlot.plot().

Variables:

fig (Figure) – Matplotlib figure containing the rendered threshold plot.
ax (Axes) – Matplotlib axis containing the rendered threshold plot.
lines (list of Line2D) – Contour boundary lines as editable artists.
fills (list of PolyCollection) – Filled threshold regions as artists.
legend (Legend or None) – Legend artist if legend=True, otherwise None.

Summary Plot#

class pythermalcomfort.plots.matplotlib.SummaryPlot(df)[source]#

Build and render a threshold summary plot from tabular model outputs.

The class works with an existing DataFrame that already contains the target model output column (e.g., pmv or utci).

__init__(df)[source]#

Initialize a summary plot builder from a DataFrame.

Parameters:

df (DataFrame) – Input DataFrame containing at least one output column to summarize.

Raises:

TypeError – If df is not a pandas DataFrame.
ValueError – If df is empty.

set_regions(*, output, thresholds, labels=None, colors=None)[source]#

Set output variable and threshold region configuration.

Parameters:

output (str) – Name of the DataFrame column to categorize.
thresholds (sequence of float) – Numeric boundary values that divide the output range into regions.
labels (sequence of str, optional) – Region labels. Must have length len(thresholds) + 1 when provided.
colors (sequence of str, optional) – Region colors. Must have length len(thresholds) + 1 when provided.

Returns:

SummaryPlot – Self, to support method chaining.

Raises:

TypeError – If output is not a string.
ValueError – If the output column is missing or has invalid values, or if thresholds/labels/colors are invalid.

plot(*, ax=None, title=None, vertical=False, legend=True, bar_kws=None, legend_kws=None)[source]#

Render a threshold summary plot for the configured output column.

Parameters:

ax (Axes, optional) – Existing axis to draw on. If None, a new figure/axis is created with a compact default size for the selected orientation.
title (str, optional) – Optional axis title. When both title and legend are shown the legend sits just above the chart and the title floats above it, matching the spacing used by ThresholdPlot.
vertical (bool) – If True, render a vertical stacked bar; otherwise horizontal.
legend (bool) – Whether to draw a colour-coded legend above the bar. When True, region labels are omitted from the bar itself.
bar_kws (dict, optional) – Keyword overrides forwarded to ax.bar or ax.barh for the stacked bar segments after SummaryPlot defaults are applied.
legend_kws (dict, optional) – Keyword overrides forwarded to ax.legend.

Returns:

SummaryPlotResult – Result with figure, axis, percentages, artists, and legend handle.

Raises:

ValueError – If regions are not configured first via set_regions().

class pythermalcomfort.plots.matplotlib.SummaryPlotResult(fig, ax, percentages, artists, legend)[source]#

Container with handles returned by SummaryPlot.plot().

Variables:

fig (Figure) – Matplotlib figure containing the summary plot.
ax (Axes) – Matplotlib axis containing the summary plot.
percentages (Series) – Percentage share per region, indexed by region label.
artists (list) – List of rendered bar and text artists.
legend (Legend or None) – Legend artist if legend=True, otherwise None.

Psychrometric Plot#

class pythermalcomfort.plots.matplotlib.PsychrometricPlot(model_func)[source]#

Configure and render a psychrometric chart with threshold regions.

Inherits from ThresholdPlot and strictly enforces hr (humidity ratio) on the y-axis. Any model temperature parameter (tdb, tr, etc.) may be used on the x-axis. Grid evaluation converts humidity ratio back to relative humidity before calling the underlying model. Constant-RH background curves are drawn on top of the threshold regions.

Examples

from pythermalcomfort.models import pmv_ppd_iso
from pythermalcomfort.plots.matplotlib import PsychrometricPlot

result = (
    PsychrometricPlot(pmv_ppd_iso)
    .set_x_axis("tdb", 10.0, 36.0, resolution=0.2)
    .set_y_axis("hr", 0.0, 0.030, resolution=0.0005)
    .set_params(vr=0.10, met=1.2, clo=0.5, wme=0.0)
    .set_regions(output="pmv", thresholds=[-0.5, 0.5])
    .plot(title="PMV — Psychrometric Chart")
)

set_x_axis(name, min_val, max_val, *, resolution)[source]#

Set x-axis; any model temperature parameter is accepted.

Common choices are 'tdb' (dry-bulb temperature) and 'tr' (mean radiant temperature). The RH curves and saturation boundary overlaid on the chart are computed using the x-axis values as the reference temperature, so accuracy is highest when 'tdb' is used.

Parameters:

name (str) – Model argument name mapped to the x-axis (e.g. 'tdb', 'tr').
min_val (float) – Minimum value.
max_val (float) – Maximum value.
resolution (float) – Grid step along the x-axis.

Returns:

PsychrometricPlot – Self, to support method chaining.

Raises:

ValueError – If name is not a valid model argument, or range/resolution are invalid.

set_y_axis(name, min_val, max_val, *, resolution)[source]#

Set y-axis; must be 'hr' (humidity ratio).

The standard model-argument check is bypassed because thermal comfort models accept rh (relative humidity), not hr directly. Grid evaluation handles the conversion internally.

Parameters:

name (str) – Must be 'hr'.
min_val (float) – Minimum humidity ratio (kg/kg).
max_val (float) – Maximum humidity ratio (kg/kg).
resolution (float) – Grid step along the y-axis.

Returns:

PsychrometricPlot – Self, to support method chaining.

Raises:

ValueError – If name is not 'hr', conflicts with a fixed parameter set via set_params(), or if range/resolution are invalid.

plot(*, ax=None, title=None, legend=True, show_lines=True, line_kws=None, fill_kws=None, legend_kws=None, invalid_color='#bdbdbd')[source]#

Render the psychrometric chart with threshold regions and RH curves.

Delegates to ThresholdPlot.plot() for contour rendering, then overlays:

A white fill masking the physically impossible RH > 100 % area, starting exactly at the smooth saturation curve.
Dotted constant-RH background curves at 10 % intervals.

Parameters:

ax (Axes, optional) – Existing axis to draw on. If None, a new figure/axis is created with a default size of (7, 4) inches.
title (str, optional) – Optional axis title.
legend (bool) – Whether to draw a legend.
show_lines (bool) – Whether to draw threshold contour boundaries.
line_kws (dict, optional) – Keyword overrides forwarded to ax.plot for contour lines.
fill_kws (dict, optional) – Keyword overrides forwarded to ax.contourf for region fills. Keys color and facecolor are reserved and rejected.
legend_kws (dict, optional) – Keyword overrides forwarded to ax.legend.
invalid_color (str) – Color used for out-of-model/invalid grid areas.

Returns:

ThresholdPlotResult – Result with axis and artist handles.

__init__(model_func)#

Initialize the grid plot builder.

Parameters:: model_func (callable) – Callable model function (typically from pythermalcomfort.models). Its signature is inspected to validate axis names and fixed parameters.

set_params(**kwargs)#

Set fixed model parameters used during grid evaluation.

Parameters:: **kwargs (Any) – Fixed model inputs passed unchanged to model evaluations.
Returns:: GridBasePlot – Self, to support method chaining.
Raises:: ValueError – If parameter names are invalid for the model signature or conflict with configured x/y axis parameters.

Notes

set_regions(*, output, thresholds, labels=None, colors=None)#

Configure output regions.

Parameters:

output (str) – Output field or column name.
thresholds (sequence of float) – Numeric boundary values that divide the output range into regions.
labels (sequence of str, optional) – Region labels. Must have length len(thresholds) + 1 when provided.
colors (sequence of str, optional) – Region colors. Must have length len(thresholds) + 1 when provided.

Returns:

ThresholdPlot – Self, to support method chaining.

Raises:

TypeError – If output is not a string.
ValueError – If output name is empty, or thresholds/labels/colors are invalid.