bsrn.modeling.clear_sky.add_clearsky_columns#

bsrn.modeling.clear_sky.add_clearsky_columns(df, station_code=None, lat=None, lon=None, elev=None, model='ineichen', mcclear_email=None)[source]#

Adds clear-sky radiation columns to a DataFrame based on its DatetimeIndex. 根据 DatetimeIndex 向 DataFrame 添加晴空辐射列。

Location can be given by BSRN station code or by explicit lat/lon/elev (e.g. for non-BSRN stations), consistent with the QC wrapper metadata pattern. 位置可由 BSRN 站点代码指定，或由显式的 lat/lon/elev 指定（如非 BSRN 站点），与 QC 包装的元数据约定一致。

Parameters:

  • df (pd.DataFrame) – Input data with pd.DatetimeIndex. 包含 DatetimeIndex 的输入数据。

  • station_code (str, optional) – BSRN station abbreviation. [e.g. ‘QIQ’] Used if lat/lon/elev not provided. BSRN 站点缩写。[例如 ‘QIQ’]。未提供 lat/lon/elev 时使用。

  • lat (float, optional) – Latitude. [degrees] Required for non-BSRN stations if station_code omitted. 纬度。[度]。非 BSRN 站点且未提供 station_code 时必填。

  • lon (float, optional) – Longitude. [degrees] Required for non-BSRN stations if station_code omitted. 经度。[度]。非 BSRN 站点且未提供 station_code 时必填。

  • elev (float, optional) – Elevation. [m] Required for non-BSRN stations if station_code omitted. 海拔。[米]。非 BSRN 站点且未提供 station_code 时必填。

  • model (str, default 'ineichen') – Clear-sky model to use. [‘ineichen’, ‘mcclear’, ‘rest2’, or ‘tj’] 使用的晴空模型。[ ‘ineichen’、’mcclear’、’rest2’ 或 ‘tj’]

  • mcclear_email (str, optional) – SoDa account email used when downloading McClear automatically for the ‘mcclear’ model. 当 model=’mcclear’ 时，用于自动下载 McClear 的 SoDa 账户邮箱。

Returns:

df – DataFrame with added _clear columns. 增加了 _clear 列的 DataFrame。

Return type:

pd.DataFrame

Raises:

  • ValueError – If df.index is not a DatetimeIndex. / 索引非 DatetimeIndex。

  • ValueError – If solar geometry columns are missing and the DataFrame frequency is >5 min, causing the automatic add_solpos_columns fallback to fail. 若缺少太阳几何列且聚合度大于5分钟，自动补充将失败。

  • ValueError – If neither a valid station_code nor complete (lat, lon, elev) is provided. 若既未提供有效 station_code 也未提供完整的 (lat, lon, elev)。