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:

pip install irradpy2

For local development:

pip install -e .

Package Structure

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

Data Acquisition

Ground-based observations

Ground observation downloaders are available from irradpy2.getirrad.

from irradpy2.getirrad import download_bsrn, download_midc, download_srml

Example:

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.

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.

from irradpy2.clear_sky import TJ, Simplified_Solis, rest2v5

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

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

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

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

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:

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.

from irradpy2.csd import Ellis2018CSD

csd = Ellis2018CSD(
    observed_ghi,
    clear_sky_ghi,
)

Detection results can be visualized with:

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.

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.

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

Example:

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.

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

Example:

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:

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:

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

from irradpy2.tool import cal_metrics

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

print(metrics)

Individual metrics are also available:

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

The MBE definition used by irradpy2 is:

MBE = mean(predicted - observed)

Therefore:

• positive MBE indicates overestimation
• negative MBE indicates underestimation

Visualization

The utility module provides several plotting functions:

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

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

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:

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