pyedautils

pyedautils#

Python Energy Data Analysis Utilities – a pip-installable library of compact utility functions for analyzing and visualizing energy and comfort time-series data.

Features#

  • Data I/O – Save and load DataFrames in CSV, pickle, compressed pickle, and JSON formats with automatic directory creation, timing, and file-size logging.

  • Data quality – Gap, stuck-value and range-outlier detection, interval inference, ok/warning/critical quality flags, and missing-value visualizations.

  • Thermal comfort – SIA 180:2014 adaptive comfort boundary curves, summer-half-year filter, overheating hours and KPIs (Minergie / SIA 180 limits), and the comfort-compass distribution of temperature/humidity states.

  • Psychrometrics – Moist-air state calculations (dew point, wet bulb, enthalpy, density, pressure from altitude) and air-handling processes (heating, cooling, humidification, mixing, heat recovery) for the Mollier h,x-diagram.

  • Energy signature – Proposed Energy Signature (Eriksson et al. 2020): balance temperature, heat loss coefficient, and domestic hot water / circulation demand from hourly data.

  • Unit conversion – SI ↔ IP conversions for temperature, humidity ratio, enthalpy, pressure, flow, power, density and more, including whole moist-air states.

  • Degree days & climate correction – Swiss heating degree days HGT 20/12, accumulated temperature differences ATD (SIA 380), cooling degree days, reference climatology, SIA-380-style normalization of heating energy, fixed-base degree-day regression (ASHRAE Guideline 14 metrics) and the BFE GT&S method.

  • Geocoding & coordinates – Address geocoding (Nominatim), WGS84-to-Swiss-LV95 conversion, altitude lookup via opentopodata.org and geo.admin.ch, Swiss postal code resolution, and Haversine distance calculation.

  • Plotting – Plotly- and D3-based visualizations:

    • daily profiles (seasons x weekdays grid with median lines and quantile bands), median-week and calendar heatmaps

    • energy signature (simple and PES), seasonal plots (overlapping, miniplots, before/after, polar) and density by season

    • comfort plots: SIA 180 comfort, Mollier h,x-diagram (incl. a fast interactive variant), comfort compass, comfort donuts, overheating time series and bar chart, temperature/humidity time series

    • statistical plots: sum frequency (duration curve), STL decomposition, time series, distribution, boxplot, outliers, correlation, scatter, autocorrelation

    • heating/cooling gradient boxplots and solar-influence dual-axis plot

    • degree days vs. reference and degree-day regression

  • Data preparation

    • Season detection – Astronomical (ephem-based equinox/solstice) or meteorological seasons, for both hemispheres and with custom labels.

    • Solar position – Sun elevation and azimuth for a location and time, as a single value or vectorized over a pandas Series/DatetimeIndex.

    • Gradients – Heating and cooling gradients (K/h) of a time series, classified by direction and season.

    • Solar influence – Detect direct solar influence on a sensor (radiation-vs-excess-temperature correlation, orientation hint, steep-rise events).

    • Reshape – Per-id resampling of long-format sensor data, IQR outlier removal, and long-to-wide pivoting.

  • Swiss weather data

    • MeteoSwiss – Download of historical and recent measurements (10-minute, hourly, daily) from the MeteoSwiss open data portal by station or Swiss postal code, current measurements of all automatic stations, and the nearest station for a sensor type within an altitude tolerance.

    • Agrometeo.ch – Station list, nearest station for a sensor type, and download of hourly temperature, global radiation, humidity and rain data by station or Swiss postal code.

    • Swiss open data – Monthly degree-day series of the BFE (population-weighted, since 1980) and the Stadt Zürich (since 1864).

Quick start#

from pyedautils.data_prep.season import get_season
from datetime import datetime

season = get_season(datetime(2024, 7, 15))
print(season)  # "Summer"

New to the h,x diagram or the comfort compass? The guides explain how to read the h,x diagram correctly, what the comfort zone means, how to save energy and how to read the comfort compass.

Learning Python for energy and comfort data? The online book EDAP: Energy Data Analysis with Python walks through loading, cleaning and plotting real building data step by step, using pyedautils.

See the Installation page for setup instructions and the API Reference for detailed documentation of each module.