Getting Started

This guide provides a quick introduction to using bsrn for quality control and clear-sky modeling.

BSRNDataset (recommended)

The simplest way to work with a BSRN archive file is through BSRNDataset, which reads the file, resolves station metadata, and exposes chainable pipeline methods:

import bsrn

ds = bsrn.BSRNDataset.from_file("data/QIQ/qiq0125.dat.gz")

ds.solpos()            # solar position + extraterrestrial
ds.clear_sky()         # clear-sky irradiance (Ineichen)
ds.qc_test()           # 6-level quality control flags
ds.qc_mask()           # optional: NaN failed irradiance, drop flags

Logical Record Selection

You can select which logical records are parsed using include_lrs. Supported selectors are "lr0100" (required), "lr0300", "lr4000", and "lr0001". Parsed LR0001 is stored on the dataset under metadata_lrs["lr0001"] and is returned by ds.get_lr("lr0001").

import bsrn

ds = bsrn.BSRNDataset.from_file(
    "data/QIQ/qiq0125.dat.gz",
    include_lrs=["lr0100", "lr0300"],
    strict=False,
)

# Query loaded logical records.
lr0100 = ds.get_lr("lr0100")
has_lr0300 = ds.has_lr("lr0300")

When to use each LR access pattern:

from bsrn.archive import LR0001, LR0100

# Use LR0100.from_file(...) / LR0001.from_file(...) when you only need one LR.
lr0100_direct = LR0100.from_file("data/QIQ/qiq0125.dat.gz")
lr0001_direct = LR0001.from_file("data/QIQ/qiq0125.dat.gz")

# Use ds.get_lr(...) when you already work with a dataset pipeline object.
ds = bsrn.BSRNDataset.from_file("data/QIQ/qiq0125.dat.gz")
lr0100_from_ds = ds.get_lr("lr0100")
lr0001_from_ds = ds.get_lr("lr0001")

Both patterns are valid. Pick one based on workflow context; there is no need to use both in the same script unless you explicitly want both views.

Functional API

All pipeline steps are also available as standalone functions, useful when working with non-BSRN data or custom DataFrames:

from bsrn.physics.geometry import add_solpos_columns
from bsrn.modeling.clear_sky import add_clearsky_columns
from bsrn.qc.wrapper import run_qc

df = add_solpos_columns(df, lat=47.80, lon=124.49, elev=170)
df = add_clearsky_columns(df, lat=47.80, lon=124.49, elev=170)
df = run_qc(df, lat=47.80, lon=124.49, elev=170)

Key Features

• Automated Quality Control: 6 levels of QC based on BSRN standards.

• Clear-sky Modeling: Support for Ineichen, McClear, and REST2.

• Clear-sky Detection: Multiple algorithms (Reno, Ineichen, etc.).

• Cloud Enhancement detection: Killinger, Yang, Gueymard.

• Irradiance Separation: Erbs, BRL, Engerer2, Yang4.