helioqc 0.1.0

Visual quality-control diagnostics for solar irradiance measurements (HelioQC multipanel).

HelioQC

HelioQC produces a unified multipanel visual diagnostic for solar irradiance quality control (GHI, DNI, DIF). It complements automated QC tests by revealing characteristic signatures of measurement anomalies across several coordinated views.

DOI:

License: (see LICENSE)

Authors: Mines Paris - PSL —

Installation

pip install helioqc

For a local checkout:

pip install -e .

Prerequisites

1. CAMS radiation service — register at soda-pro CAMS Radiation Service, then provide your email as CAMS_EMAIL or cams_email=.
2. Google Static Maps API (optional) — set GOOGLE_API_KEY for station map thumbnails. When absent, maps are skipped with a warning.

Copy .env.sample to .env and set your credentials:

cp .env.sample .env
# edit .env — CAMS_EMAIL is required

Integration tests and local runs read from .env at the project root.

Input data format

visual_qc expects a pandas.DataFrame with:

• a UTC DatetimeIndex (naive timestamps are assumed to be UTC)
• columns GHI, DHI or DIF, BNI or DNI (W/m²)

Filter the time range in Python before calling visual_qc (e.g. df.loc["2021-01-01":"2025-12-31"]).

Optional station metadata may be attached to input_df.attrs (e.g. after reading a NetCDF file):

attrs key	Description
latitude	Station latitude (°)
longitude	Station longitude (°)
elevation	Station elevation (m)
ClimateType	Köppen-Geiger code
Country	Country name
station	Station name
ID	Station identifier
source	Measurement network

latitude, longitude, and elevation are required unless passed explicitly.

Python API

from helioqc import visual_qc
import pandas as pd

df = pd.read_csv("measurements.csv", parse_dates=["time"], index_col="time")
df.index = df.index.tz_localize("UTC")

fig = visual_qc(
    df,
    latitude=36.624,
    longitude=-116.019,
    elevation=1007,
    climate="BWh",
    country="United States",
    station="Desert Rock, Nevada",
    station_id="DRA",
    source="SURFRAD",
    cams_email="[e-mail]",
)
fig.savefig("helioqc_output.png", dpi=150, bbox_inches="tight")

visual_qc synopsis

visual_qc(input_df, *, latitude, longitude, elevation, cams_email, ...) → matplotlib.figure.Figure

Returns a matplotlib Figure displayed automatically in Jupyter notebooks.

Command-line interface

helioqc \
  --latitude 36.624 --longitude -116.019 --elevation 1007 \
  --climate BWh --country "United States" \
  --station "Desert Rock, Nevada" --station-id DRA --source SURFRAD \
  --cams-email [e-mail] \
  data/surfrad_dra_2025.csv.zip output.png

.csv, .csv.gz, and .csv.zip inputs are supported. By default the CLI analysis window spans the last five years of data ending at the dataset maximum (--start-date / --end-date to override).

Additional options: --time-col, --time-format, --timezone, --ghi-col, --dni-col (falls back to BNI), --dif-col (falls back to DHI), --start-date, --end-date.

Sample data

The repository includes one year of SURFRAD Desert Rock (DRA) measurements:

data/surfrad_dra_2025.csv.zip

Station metadata (latitude, climate, …) is passed as function/CLI parameters — see the API and CLI examples above.

Tests

make test       # e2e (CAMS mocked) + unit tests
make test-unit  # fast wiring tests only

End-to-end tests call sg2/SRTM/plotting for real (CAMS mocked) and write JPEG artefacts to tmp/test_api.jpg and tmp/test_cli.jpg.

Demo notebook

See demo.ipynb for a minimal workflow: fetch data from the Thredds server, attach metadata, and call visual_qc().