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()`.
