Plugins 〉Psychart

Panel

community

Psychart

Overview
Installation
Change log
Related content

Psychart v5.0.0

A Psychrometric Chart for Monitoring Data Center Health & Human Comfort

View air conditions on a psychrometric chart.

What is a psychrometric chart?

Psychrometric charts are charts adopted by ASHRAE that plot various thermodynamic properties of air-vapor mixtures. These charts are particularly useful in HVAC applications. The following properties describe what's called a state of air. Two properties are needed to fix the state of air, which means that two properties are needed in order to calculate every other property. The following 4 properties are plotted by Psychart by default:

Dry Bulb
- The temperature of air using a dry thermometer.
Wet Bulb
- Wet bulb temperature can be practically explained by the temperature of a surface where water is evaporating.
Dew Point
- Water will condense from the air at or below this temperature.
Relative Humidity
- A ratio of vapor pressure in the air to the saturation vapor pressure. 0%rh indicates absolutely dry air, and 100%rh indicates saturated air.

Psychart also has the capability to derive the following state variables, which are optionally displayed using the Show Advanced State Variables switch in series display options.

Vapor Pressure
- The partial pressure of water in the vapor-air mixture.
Humidity Ratio
- Weight of water vapor per weight of dry air.
Enthalpy
- In thermodynamics, refers to the total heat content of the vapor-air mixture.
Specific Volume
- Amount of volume taken up by one unit of mass of the vapor-air mixture.
Degree of Saturation
- The ratio of the humidity ratio of moist air to that of saturated moist air.

Getting started

This section will go over the options in the panel editor.

Panel options

This is the default panel options for all Grafana panels which gives the user access to the panel title, description, panel links, and repeat options.

Chart options

These options affect how the chart itself is displayed.

Allows the user to select whether measurements are being reported in US or SI units, optionally show or hide the legend, set the local altitude, graph bounds, optionally render a Mollier diagram, and optionally display ASHRAE comfort regions (envelopes). Also, allows the user to adjust the major axis intervals by expanding "Axis Intervals." Axes for humidity ratio are only shown when rendering a Mollier diagram.

Comfort Regions

For data center envelopes, these comfort regions follow the 2021 ASHRAE standard and are designed for data centers and IT spaces of various criticality. For human comfort envelopes, these comfort regions follow the ASHRAE-55 guidelines published in 2017. These human comfort envelopes are a function of metabolic rate (MET, which is dependent on the indoor activity), clothing level (CLO), and air speed. In both cases, the envelopes show the target region for conditioned air supplied into the indoor space.

Data options

These options help process the incoming data.

Psychart is capable of plotting several data series of states per panel. The amount of data series is defined by the series count. Due to the fact that 2 properties are needed to fix the state, at least two numeric time-dependent fields are required. The user must select whether those two fields are dry bulb and wet bulb, dry bulb and dew point, or dry bulb and relative humidity. These fields must then be entered into the field selectors below respectively.

It is important to note that one or two queries may be necessary depending on the data structure. One single query may be sufficient to return the two fields needed to fix the state. Other times, one query will be needed to obtain the dry bulb field and another for relative humidity field, for example.

Different data series are independent from one another - one series may incorporate dry bulb and wet bulb measurements, and another may incorporate dry bulb and dew point measurements, for instance.

Series display options

This section configures each individual data series.

First, a legend must be set. This will name your data series as well as add a label when hovering the cursor over the plotted data. This supports Grafana dashboard variables, written as ${variable}. After the legend name is set, then select the 2 data series that represent the 2 psychrometric measurements to fix the state.

The rest of the options change the visual appearance of data within the chart. This allows the user to change the point radius, optionally draw a line between adjacent points in time, and select a color gradient for the data series. Gradients always use the more saturated/contrasting colors for the more recent data points, regardless of which theme (light/dark) is preferred. The user can also optionally select to view the advanced state variables that were described in the introduction.

Errors & Troubleshooting

Some errors can arise from the Data options section due to the fact that wet bulb and dew point must be less than or equal to the dry bulb temperature and relative humidity must be within the range of 0-1. If relative humidity is a driving measurement, make sure that the measurement type is correct (0-1 or 0%-100%). For other measurements, make sure that they are being reported correctly.

Psychart matches up values with similar timestamps. For a dry bulb & relative humidity series, the dry bulb measurement timestamp must match that of the relative humidity timestamp in order to be recognized as a single point. The Query options in the query inspector may provide the tools required to fix any time discrepancies.

Importantly, if there is missing data in one field, for example if dry bulb temperature has not been reporting for the last 5 minutes, no new states are calculated, and no new data is plotted in Psychart for the last 5 minutes to avoid the display of inaccurate data.

Psychart works best both visually and practically when observing a narrow span of time. If Psychart is loading very slowly, try to decrease the Time range in Grafana. Both absolute and relative time spans are accepted by Psychart. If the data still seems too cluttered, try disabling connecting points with a line, reducing the point radius, or reducing the amount of data series rendered on a single panel.

If data seems to be hidden, make sure that the graph bounds encompass the range of all the data. Also, double check to make sure that none of the series are disabled in the legend. If they are, click on their series name to re-render them onto Psychart.

Finally, if there are issues after upgrading to a newer version of Psychart, (for example the regions are not being rendered) try to open the panel editor, reapply your customization settings, and save the panel. Sometimes, the panel options are not properly stored from version to version.

License

Psychart was created by Nicolas Ventura, owned by Berkeley Lab, a DOE funded national laboratory, and is distributed under the BSD-3-Clause-LBNL license.

Plugin ID	Last Updated	Version
`ventura-psychrometric-panel`	`2025-04-23`	`5.0.0`

Installing Psychart on Grafana Cloud:

For more information, visit the docs on plugin installation.

Changelog

5.0.0

Break out Psychart source code into its own npm package. Major updates include:
- Adding a legend! Legend is interactive; clicking on a series name in the legend will toggle its points visibility
- Mollier diagrams now will show humidity ratio on their x-axis, instead of dew point
- Units are shown both on the axis labels and in the axis tooltips
- Psychart now calculates degree of saturation, which can be shown in "advanced" mode!
Standalone app: Enter data display options after generating chart, and while plotting data
Add more examples and instructions into the provisioning dashboard
Remove all screenshots, new screenshots of new version will be added in a future update
Use builtin <PanelDataErrorView> Grafana React element to show errors
Organize folder structure to better match Grafana's default plugin
No longer need to package all gradient icons with the plugin! Icons are now generated on-the-fly and their URLs are generated.
Panel editor changes:
- Add toggle to show legend
- Add options to adjust axis major intervals
- Remove "enabled" switch (since series can now be hidden by simply clicking on their name in the legend)
Re-package new screenshots with the plugin
Add (empty) unit tests file
Minor updates in main README (e.g. mention variable interpolation, fix broken link)
Add build attestation in Grafana workflow
Add options migration handling from version 4.x.x to version 5.x.x
Update to the latest version of @grafana/create-plugin (5.19.5)

4.5.4

Update to the latest version of @grafana/create-plugin (5.11.1)
Update dependency versions

4.5.3

Update to the latest version of @grafana/create-plugin (5.9.3)
- Address Dependabot security vulnerabilities
- Update node version to 22
Thank you to the Grafana team for addressing #1328!

4.5.2

Update to the latest version of @grafana/create-plugin (5.5.2)
Fixed a bug where data series would initially be disabled, for existing dashboards that upgraded to plugin version 4.5.1

4.5.1

Add an option called Enable when unchecked, will hide data series
Update to the latest version of @grafana/create-plugin (5.3.10)

4.5.0

Add new comfort region: Comfort Zone of the Building Bioclimatic Chart (based on Milne and Givoni 1979 & ASHRAE 55-2017)
Update to the latest version of @grafana/create-plugin (5.2.2)

4.4.0

Update to the latest version of @grafana/create-plugin (4.16.3)
- Grafana version required: >=10.4.0
Update dependency versions

4.3.2

Update to the latest version of @grafana/create-plugin (4.12.0)
Remove dependency on Grafana legacy classes
Update dependency versions in pages.yml workflow file
- NodeJS updated to version 20

4.3.1

Update to the latest version of @grafana/create-plugin (4.10.1)
Track package-lock.json in repository

4.3.0

Update to the latest version of @grafana/create-plugin (4.6.2)
- Grafana version required: >=10.3.3
- Compatibility check workflow is now fixed!
Update dependency versions of smath (1.8.5) and viridis (1.1.4)
Support the ability to render Mollier Diagrams by mirroring Psychart on the x=y line (thanks for the idea, @yevgeny7!)
Improve panel interior padding by splitting it into x and y values instead of using a single value
Add placeholders in all panel option fields (shown when field is empty)
Min/max values for dbMax and dpMax options are now dynamically calculated so that dbMax must be strictly greater than or equal to dpMax
Improve code quality by...
- Changing let to const
- Adding readonly modifiers where possible
- Adding explicit access modifiers (by default, TypeScript sets all class members public if not specified)
Minor Webpack configuration simplifications (standalone app)
Fix bug where relative humidity was displayed from 0-1 instead of 0-100%
Update screenshots

4.2.2

Bug fix where region shading gradient was not reversed for light theme
Updates to standalone app
- Add option for rendering IBM TS4500 ambient envelopes
- Use script defer and remove window load event listener

4.2.1

Update dependency versions
Clean script can now remove backups
Minor cleanups within Psychart class

4.2.0

Add LBL/DOE notice in README
Replace custom JMath with smath dependency for linear interpolation functions
Replace custom Color with viridis dependency for color gradient functions
- Allow all default/builtin gradients from this package, adds >10 new gradients to Psychart!
- Use "Purplish" palette for region shading
Default series names are numbered instead of lettered
Maximum of 100 data series rendered on Psychart
Remove default exports over preference to named exports (undo change from 4.0.1)
Region shading is now affected by your Grafana theme for better contrast
Add IBM TS4500 ambient condition envelopes

4.1.0

Update to the latest version of @grafana/create-plugin (4.0.1)
Add link to issues in main README page and plugin page
Minor updates to runner update command (select non-hidden files only)
Correctly set the license type in package.json (thank you, @nagisa!) #10 and README
Add extra stats towards the bottom of the plugin README
Remove duplicate images in build output

4.0.6

Update to the latest version of @grafana/create-plugin (3.5.0)
- Updates workflow action dependency versions, thanks to my pull request!
Update dashboard provisioning configuration
- Datasource is random 30Hz data stream
Add -U flag in runner that will automatically re-build with latest version of @grafana/create-plugin

4.0.5

Update to the latest version of @grafana/create-plugin (3.1.3)

4.0.4

Update to the latest version of @grafana/create-plugin (2.11.1)

4.0.3

Update to the latest version of @grafana/create-plugin (2.10.1)
- Use grafana/plugin-actions/build-plugin action
Add popularity badge in plugin README

4.0.2

Add banner image in GitHub repository
Update to the latest version of @grafana/create-plugin (2.8.0)
- Except for grafana/plugin-actions/build-plugin action
- Add dashboard provisioning
Major updates to runner file
- Check options using getopts
- Redesign logic/error messages for plugin validation and publishing

4.0.1

Make exports default where possible
Reverse gradients for light theme
- The most saturated colors are the more recent data points, regardless of which theme
Fix bug where normalized values would return a value outside of [0, 1] when min = max
Minor improvements in region colorizing
Updated some screenshots in README
- Showing the panel editor options
- Example with multiple data series
Standalone app only published on version releases

4.0.0

Psychart now has the ability to render multiple data series
- Options are shown as nested options under Data options in the panel editor
- Can now be labeled, and Psychart will show the series label in the hover text
- Supports different styles for different series
- Series count limit: 104 (send me an email if you would like this increased)
Psychart will only attempt to plot data if the data series name is a valid option
Panel editor options are now automatically validated
- Deprecated options are now deleted from dashboard settings
Reference files with relative paths without the ./
Data points now just store dry bulb + other value + measurement type, where other is either wet bulb, dew point, or relative humidity, depending on the measurement type
Add version number in README.md
Update to the latest version of @grafana/create-plugin (2.6.0)
- Node version upgraded to v20
Gradient icons are now automatically generated based on gradient definitions
Gradient icons are now shown in standalone app when setting up Psychart
Added 4 new gradients! Credit
- Emerald
- Mint
- Sunset
- Dusk

3.3.1

Change -r flag to -g flag in runner (restarts local Grafana instance)
Fix edge case in normalize function where min = max
Psychrometric regions now utilize the full scale of the gradient
Improve error checking for psychrometric states (remove nuisance error)
Update data formatter for newer Grafana API version

3.3.0

Update to the latest version of @grafana/create-plugin (2.0.2)
- Grafana version required: >=10.0.3
Node version updated to v18

3.2.3

Update to the latest version of @grafana/create-plugin (1.12.0)

3.2.2

Update to the latest version of @grafana/create-plugin (1.10.0)
Fix incorrect plugin ID in docker-compose.yaml
Remove references to GRAFANA_API_KEY in favor of GRAFANA_ACCESS_POLICY_TOKEN

3.2.1

Update to the latest version of @grafana/create-plugin (1.9.0)
Remove references to npm in build script
Store series value in label named field.config.displayNameFromDS

3.2.0

Update to the latest version of @grafana/create-plugin (1.6.3)
- Grafana version required: >=9.5.3
Automatically build and validate plugin in validation script

3.1.3

Update to the latest version of @grafana/create-plugin (1.3.0)
Change yarn commands to npm run

3.1.2

Move README.md from base folder to src/
Update dependencies

3.1.1

Screenshots are moved to README.md

3.1.0

Screenshots are no longer packaged with the plugin
Add more and new screenshots with better descriptions
Fix bug that prevented the default gradient from being set
Don't attempt to plot data if no field names are selected
Show an error if field is not found or otherwise invalid
Show an error if maximum dew point > maximum dry bulb
Add author contact information in plugin.json
Publishing script now ensures changelog matches published version number

3.0.1

Set Viridis as the default color gradient
Add a short blurb in README.md in Troubleshooting to explain how to fix errors when upgrading to major versions

3.0.0

Migrate from a JavaScript to a TypeScript code base
Dynamically generate region & gradient selections in both the standalone app and the Grafana plugin
- This means, less code duplication, so it will be much easier to add additional regions or gradients in the future
Regions are now rendered in a blue gradient instead of a violet gradient
Tooltips now follow the mouse instead of being in predefined calculated positions
Regions, chart axes, and points are no longer rendered outside of chart boundaries
Rebuild with npx @grafana/create-plugin@1.0.0 to make sure source files and dependencies are up-to-date
Better support for long and multi-frame time series (wide time series still not implemented)
- For now, if you are using a wide time series, use the Grafana transform to convert to the long or multi-frame format
Standalone app now adds timestamps to data points by default
Minor updates in README.md to explain new ASHRAE guidelines and to update badges
Add link to official Grafana blog post in plugin.json
Add more relevant search keywords in plugin.json

2.0.1

Fixed broken badges in README.md
Fixed link to copyright notice in README.md
Removed references to plugin signing
Minor improvements to build pipeline

2.0.0

Use the new Grafana plugin builder from
```
npx @grafana/create-plugin
```
Added additional workflows for compatibility and testing the build

1.1.1

Minor updates in packaging.

Fixed instances of incorrect package name.
Updated website URL
Added plugin download URL

1.1.0

First public release in Grafana. Click here to visit the plugin's page.

Updated badges
Updated screenshots
Other small fixes in README

1.0.2

Pre-release with a few minor non-code updates.

Small edits in README and CHANGELOG

1.0.1

Pre-release with data source bug fix.

Psychart can now detect if a data source calls each series by its frame name, field name, or a concatenation of both (for example, the Static Datasource)

1.0.0

Initial release with base features.

Visualization of one data series of psychrometric properties with various field options
A robust chart editor with graph options and display options
Interactivity via hovering over data points or parts of the graph with the mouse