helioqc 0.1.0__tar.gz

helioqc-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# Test / tooling
+.tox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Secrets and local artefacts
+.env
+tmp/
+
+# Notebook outputs
+.ipynb_checkpoints/
+*.png

helioqc-0.1.0/LICENSE

@@ -0,0 +1 @@
+TBD — License text to be added.

helioqc-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.3
+Name: helioqc
+Version: 0.1.0
+Summary: Visual quality-control diagnostics for solar irradiance measurements (HelioQC multipanel).
+Author-email: Mines Paris - PSL <TBD@mines-paris.psl.eu>
+License: TBD — License text to be added.
+Keywords: irradiance,photovoltaic,quality-control,solar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: click<9,>=8.1
+Requires-Dist: ipykernel>=7.3.0
+Requires-Dist: jupyter>=1.1.1
+Requires-Dist: matplotlib<4,>=3.8
+Requires-Dist: netcdf4>=1.7.3
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: pandas<3,>=2.0
+Requires-Dist: pvlib<1,>=0.11
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: sg2<3,>=2.3
+Requires-Dist: tqdm<5,>=4.66
+Requires-Dist: xarray>=2025.6.1
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: netcdf4<2,>=1.6; extra == 'dev'
+Requires-Dist: pkginfo<2,>=1.12; extra == 'dev'
+Requires-Dist: pytest-mock<4,>=3.14; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: tox-uv<2,>=1; extra == 'dev'
+Requires-Dist: tox<5,>=4.19; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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:** <TBD>
+
+**License:** <TBD> (see [LICENSE](LICENSE))
+
+**Authors:** Mines Paris - PSL — <TBD>
+
+## Installation
+
+```bash
+pip install helioqc
+```
+
+For a local checkout:
+
+```bash
+pip install -e .
+```
+
+## Prerequisites
+
+1. **CAMS radiation service** — register at [soda-pro CAMS Radiation Service](https://www.soda-pro.com/web-services/radiation/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`](.env.sample) to `.env` and set your credentials:
+
+```bash
+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
+
+```python
+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="you@example.com",
+)
+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
+
+```bash
+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 you@example.com \
+  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
+
+```bash
+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](demo.ipynb) for a minimal workflow: fetch data from the Thredds server, attach metadata, and call `visual_qc()`.

helioqc-0.1.0/README.md

@@ -0,0 +1,127 @@
+# 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:** <TBD>
+
+**License:** <TBD> (see [LICENSE](LICENSE))
+
+**Authors:** Mines Paris - PSL — <TBD>
+
+## Installation
+
+```bash
+pip install helioqc
+```
+
+For a local checkout:
+
+```bash
+pip install -e .
+```
+
+## Prerequisites
+
+1. **CAMS radiation service** — register at [soda-pro CAMS Radiation Service](https://www.soda-pro.com/web-services/radiation/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`](.env.sample) to `.env` and set your credentials:
+
+```bash
+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
+
+```python
+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="you@example.com",
+)
+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
+
+```bash
+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 you@example.com \
+  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
+
+```bash
+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](demo.ipynb) for a minimal workflow: fetch data from the Thredds server, attach metadata, and call `visual_qc()`.

helioqc-0.1.0/helioqc/__init__.py

@@ -0,0 +1,6 @@
+"""HelioQC: visual quality-control diagnostics for solar irradiance measurements."""
+
+from helioqc.api import visual_qc
+
+__all__ = ["visual_qc"]
+__version__ = "0.1.0"

helioqc-0.1.0/helioqc/api.py

@@ -0,0 +1,114 @@
+"""Public HelioQC API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+from helioqc.config import (
+    load_env,
+    resolve_cams_email,
+    resolve_google_api_key,
+    resolve_metadata,
+)
+from helioqc.diagnostic import compute_plots
+from helioqc.io import ensure_utc_index, normalize_irradiance_columns
+from helioqc.log import configure_logging, get_logger
+from helioqc.pipeline import prepare_qc_dataframe
+
+import matplotlib.pyplot as plt
+
+if TYPE_CHECKING:
+    import matplotlib.figure
+
+logger = get_logger()
+
+
+def visual_qc(
+    input_df: pd.DataFrame,
+    latitude: float | None = None,
+    longitude: float | None = None,
+    elevation: float | None = None,
+    cams_email: str | None = None,
+    google_api_key: str | None = None,
+    climate: str | None = None,
+    country: str | None = None,
+    station: str | None = None,
+    station_id: str | None = None,
+    source: str | None = None,
+    show_axis_nr: bool = False,
+    no_cache: bool = False,
+) -> matplotlib.figure.Figure:
+    """Run the HelioQC diagnostic multipanel on irradiance measurements.
+
+    Parameters
+    ----------
+    input_df
+        DataFrame with a DatetimeIndex and columns ``GHI``, ``DHI`` or ``DIF``,
+        ``BNI`` or ``DNI`` (W/m²). Timestamps without timezone are assumed UTC.
+        Filter the time range before calling this function.
+        Location metadata may be stored in ``input_df.attrs``.
+
+    latitude, longitude, elevation
+        Station coordinates. May be provided in ``input_df.attrs``
+
+    cams_email
+        Email registered with the CAMS radiation service.
+        Falls back to ``CAMS_EMAIL`` env var.
+
+    google_api_key
+        Google Static Maps API key. Falls back to ``GOOGLE_API_KEY`` env var.
+        Map thunmbnails are skipped if missing
+
+    climate, country, station, station_id, source
+        Optional station metadata for display panels.
+
+    show_axis_nr
+        Annotate subplot panel labels when True.
+
+    no_cache
+        When True, bypass the on-disk cache for CAMS and Google Static Maps.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The HelioQC multipanel figure (shown once in Jupyter when returned).
+    """
+    load_env()
+    configure_logging()
+    logger.info("Starting HelioQC visual QC...")
+    df = ensure_utc_index(normalize_irradiance_columns(input_df))
+
+    metadata = resolve_metadata(
+        input_df,
+        latitude=latitude,
+        longitude=longitude,
+        elevation=elevation,
+        climate=climate,
+        country=country,
+        station=station,
+        station_id=station_id,
+        source=source,
+    )
+    email = resolve_cams_email(cams_email)
+    maps_key = resolve_google_api_key(google_api_key)
+
+    qc_df, metadata = prepare_qc_dataframe(
+        df,
+        metadata,
+        cams_email=email,
+        no_cache=no_cache,
+    )
+    logger.info("Generating multipanel figure...")
+    with plt.ioff():
+        fig = compute_plots(
+            qc_df,
+            metadata,
+            showAxisNr=show_axis_nr,
+            google_api_key=maps_key,
+            no_cache=no_cache,
+        )
+    plt.close(fig)
+    logger.info("HelioQC visual QC complete")
+    return fig