Metadata-Version: 2.4
Name: irradpy2
Version: 1.0.3
Summary: Multi-source solar irradiance data acquisition, modeling, separation, and forecasting toolkit.
License-Expression: MIT
Keywords: solar irradiance,meteorological data,data acquisition,clear-sky modeling,clear-sky detection,irradiance separation,solar forecasting
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: requests
Requires-Dist: pytz
Requires-Dist: scikit-learn
Requires-Dist: torch
Dynamic: license-file

# irradpy2

`irradpy2` is a Python package for solar irradiance data acquisition, processing, modeling, separation, forecasting, and evaluation.

The package provides a consistent interface for working with ground-based observations, gridded meteorological data, clear-sky irradiance models, clear-sky detection methods, irradiance separation models, and forecasting methods.

## Features

- Download ground-based solar irradiance observations
- Download gridded and reanalysis meteorological data
- Prepare multi-source data for irradiance analysis
- Run clear-sky irradiance models
- Detect clear-sky periods
- Estimate diffuse and direct irradiance components
- Forecast global horizontal irradiance
- Calculate common evaluation metrics
- Visualize model and observation results

## Installation

After the package is released on PyPI:

```bash
pip install irradpy2
```

For local development:

```bash
pip install -e .
```

## Package Structure

```text
irradpy2
├── clear_sky
├── csd
├── forecast
├── getgridded
├── getirrad
├── separation
└── tool.py
```

| Module | Description |
|---|---|
| `getirrad` | Download ground-based solar irradiance observations |
| `getgridded` | Download gridded and reanalysis meteorological data |
| `clear_sky` | Calculate clear-sky GHI, DNI, and DHI |
| `csd` | Detect clear-sky periods |
| `separation` | Separate GHI into diffuse and direct components |
| `forecast` | Forecast global horizontal irradiance |
| `tool` | Data processing, evaluation, and visualization utilities |

## Data Acquisition

### Ground-based observations

Ground observation downloaders are available from `irradpy2.getirrad`.

```python
from irradpy2.getirrad import download_bsrn, download_midc, download_srml
```

Example:

```python
from irradpy2.getirrad import download_bsrn

download_bsrn(
    site="CAB",
    begin="2025-01-01",
    end="2025-12-31",
    username="your_bsrn_username",
    password="your_bsrn_password",
    save_path="cab_2025.csv",
)
```

### Gridded meteorological data

Gridded and reanalysis downloaders are available from `irradpy2.getgridded`.

```python
from irradpy2.getgridded import download_merra2, download_era5, download_cams
```

Some data sources require external accounts or API credentials:

- BSRN account for BSRN data
- NASA Earthdata account for MERRA-2 data
- Copernicus ADS credentials for CAMS data

## Clear-Sky Irradiance Models

The `clear_sky` module provides models for estimating clear-sky GHI, DNI, and DHI.

```python
from irradpy2.clear_sky import TJ, Simplified_Solis, rest2v5
```

The models use NumPy arrays or pandas Series as inputs and return irradiance components.

```python
ghi_clear, dni_clear, dhi_clear = TJ(sza, datetime)
```

```python
ghi_clear, dni_clear, dhi_clear = Simplified_Solis(
    sza,
    datetime,
    press,
    aod700,
    wv,
)
```

```python
ghi_clear, dni_clear, dhi_clear = rest2v5(
    sza,
    datetime,
    press,
    albedo,
    ang_alpha,
    ang_beta,
    ozone,
    NO2,
    wv,
)
```

## Preparing Clear-Sky Model Inputs

`prepare_clearsky` prepares a combined dataset from ground observations and MERRA-2 auxiliary data.

It performs the following operations:

- identifies time columns
- builds a complete time index
- aligns ground and MERRA-2 data
- interpolates meteorological variables
- converts atmospheric variables
- calculates the solar zenith angle

```python
from irradpy2.tool import read_csv, prepare_clearsky

ground_data = read_csv("ground_data.csv")
merra2_data = read_csv("merra2_data.csv")

data = prepare_clearsky(
    ground_data,
    merra2_data,
    latitude=39.742,
    longitude=-105.18,
    begin="2023-01-01",
    end="2023-01-01",
)
```

Common output columns include:

```text
UTC
ghi
dni
dhi
sza
press
albedo
wv
aod700
ang_alpha
ang_beta
ozone_input
```

The `sza` column produced by `prepare_clearsky` is expressed in radians for use by the clear-sky models.

## Clear-Sky Detection

Clear-sky detection methods are available from `irradpy2.csd`.

```python
from irradpy2.csd import Ellis2018CSD

csd = Ellis2018CSD(
    observed_ghi,
    clear_sky_ghi,
)
```

Detection results can be visualized with:

```python
from irradpy2.tool import plot_csd

plot_csd(
    data,
    ghi_col="ghi",
    clear_col="ghi_clear",
    csd_col="csd",
)
```

## Irradiance Separation

Irradiance separation methods estimate diffuse and direct irradiance components from GHI.

```python
from irradpy2.separation import engerer2

kd, dhi, dni = engerer2(
    ghi,
    datetime,
    latitude,
    longitude,
    averaging_period=1,
)
```

The separation results can be evaluated against observed DHI and DNI using the functions in `irradpy2.tool`.

## GHI Forecasting

Forecasting methods are available from `irradpy2.forecast`.

```python
from irradpy2.forecast import (
    forecast_persistence,
    forecast_arima,
    forecast_rnn,
    forecast_lstm,
    forecast_informer,
)
```

Example:

```python
from irradpy2.forecast import forecast_lstm

ori_data, pre_data = forecast_lstm(
    datetime,
    ghi,
    seq_len=72,
    horizon=6,
    epochs=10,
    batch_size=64,
)
```

The forecasting functions return the original and predicted GHI data with their corresponding timestamps.

## Data Processing Tools

Common time-series utilities are provided in `irradpy2.tool`.

```python
from irradpy2.tool import (
    read_csv,
    select_series,
    resample_series,
    merge_series,
    merge_columns,
)
```

Example:

```python
from irradpy2.tool import read_csv, resample_series

data = read_csv("irradiance.csv")

hourly_data = resample_series(
    data,
    time_col="UTC",
    cols=["ghi"],
    freq="1h",
    agg="mean",
    lower_limit=0,
)
```

Multiple time-series datasets can be aligned using:

```python
from irradpy2.tool import merge_series

merged_data = merge_series(
    [ground_data, merra2_data, cams_data],
    time_col="UTC",
    dropna=True,
)
```

## Solar Geometry

The solar zenith angle can be calculated using:

```python
from irradpy2.tool import cal_zen

data = cal_zen(
    data,
    latitude=39.742,
    longitude=-105.18,
    time_col="UTC",
    zen_col="zen",
)
```

`cal_zen` returns the solar zenith angle in degrees.

## Evaluation Metrics

The package provides the following evaluation metrics:

- Mean Squared Error
- Root Mean Squared Error
- Mean Absolute Error
- Mean Bias Error
- Coefficient of Determination

```python
from irradpy2.tool import cal_metrics

metrics = cal_metrics(
    data,
    obs_col="ghi",
    pred_col="ghi_pred",
)

print(metrics)
```

Individual metrics are also available:

```python
from irradpy2.tool import cal_mse, cal_rmse, cal_mae, cal_mbe, cal_r2
```

The MBE definition used by `irradpy2` is:

```text
MBE = mean(predicted - observed)
```

Therefore:

- positive MBE indicates overestimation
- negative MBE indicates underestimation

## Visualization

The utility module provides several plotting functions:

```python
from irradpy2.tool import (
    plot_columns,
    plot_clearsky,
    plot_csd,
    plot_series,
)
```

For example, observed and predicted GHI can be compared using:

```python
from irradpy2.tool import plot_series

plot_series(
    data,
    obs_col="ghi",
    pred_col="ghi_pred",
    obs_label="Observed GHI",
    pred_label="Predicted GHI",
    title="GHI Forecast",
    ylabel=r"GHI [W m$^{-2}$]",
)
```

## Data Conventions

The package generally follows these conventions:

| Variable | Meaning | Typical unit |
|---|---|---|
| `UTC` | UTC timestamp | datetime |
| `ghi` | Global horizontal irradiance | W m⁻² |
| `dni` | Direct normal irradiance | W m⁻² |
| `dhi` | Diffuse horizontal irradiance | W m⁻² |
| `zen` | Solar zenith angle | degree |
| `sza` | Solar zenith angle used by clear-sky models | radian |
| `press` | Atmospheric pressure | hPa or mb |
| `wv` | Precipitable water | model-dependent |
| `aod700` | Aerosol optical depth at 700 nm | dimensionless |
| `albedo` | Surface albedo | dimensionless |

Source datasets may use different time-column names. The utility functions support common names including:
