dazhiyang/bsrn-nsrdb-conus

---
language: en
license: mit
configs:
- config_name: bil
data_files:
- split: bil
path: bil/*.parquet
- config_name: bon
data_files:
- split: bon
path: bon/*.parquet
- config_name: bos
data_files:
- split: bos
path: bos/*.parquet
- config_name: dra
data_files:
- split: dra
path: dra/*.parquet
- config_name: e13
data_files:
- split: e13
path: e13/*.parquet
- config_name: fpe
data_files:
- split: fpe
path: fpe/*.parquet
- config_name: gcr
data_files:
- split: gcr
path: gcr/*.parquet
- config_name: gim
data_files:
- split: gim
path: gim/*.parquet
- config_name: lrc
data_files:
- split: lrc
path: lrc/*.parquet
- config_name: psu
data_files:
- split: psu
path: psu/*.parquet
- config_name: sxf
data_files:
- split: sxf
path: sxf/*.parquet
tags:
- solar
- radiation
- nsrdb
- bsrn
pretty_name: BSRN NSRDB PSM v4 conus
---

<!-- This file is uploaded as the Hugging Face dataset README; keep content user-facing (no internal maintainer or upload-only notes). -->

# BSRN NSRDB PSM v4 conus

Point-extracted [NSRDB (National Solar Radiation Database)](https://nsrdb.nrel.gov/) PSM v4 (conus variant) data for [Baseline Surface Radiation Network (BSRN)](https://bsrn.awi.de/) stations.

## Dataset Description

Each file contains 5-minute NSRDB variables at a single BSRN station location. **Extraction is performed via the NREL NSRDB API (NLR)**. The `conus` variant (v4.0.0) provides **2 km spatial resolution** and covers the Contiguous United States using GOES-East and GOES-West satellite data from **2018 to 2024**.

### File Structure

Station folders use the **lowercase** BSRN three-letter code (e.g. `bil`).

```
{station}/
{station}{MM}{YY}_nsrdb_conus.parquet # One file per month
```

Example:

- `bil/bil0119_nsrdb_conus.parquet` — BIL, January 2019

### Variables

| Column | Description | Units |
|--------|----------------------------------|---------------|
| ghi_nsrdb | Global Horizontal Irradiance | W/m² |
| bni_nsrdb | Beam Normal Irradiance (DNI) | W/m² |
| dhi_nsrdb | Diffuse Horizontal Irradiance | W/m² |

- **Index**: UTC `DatetimeIndex` (5-minute resolution).
- **Time coverage**: NSRDB PSM v4 `conus` variant spans 2018–2024.

## Usage

### Load from Hugging Face

```python
from huggingface_hub import hf_hub_download
import pandas as pd

# Download a single file; path is {station}/{station}{MM}{YY}_nsrdb_conus.parquet
path = hf_hub_download(
repo_id="dazhiyang/bsrn-nsrdb-conus",
filename="bil/bil0119_nsrdb_conus.parquet",
repo_type="dataset",
)
df = pd.read_parquet(path)
# df has DatetimeIndex (UTC) and columns: ghi_nsrdb, bni_nsrdb, dhi_nsrdb
```

### Use with bsrn package

The `bsrn` package can fetch NSRDB data from Hugging Face **into RAM** (no disk cache) automatically.

```python
from bsrn.io.nsrdb import add_nsrdb_columns

# Add NSRDB columns to an existing BSRN DataFrame
df = add_nsrdb_columns(df, station_code="BIL", variant="conus")
```

## Data Sources

- **NSRDB**: [NREL National Solar Radiation Database](https://nsrdb.nrel.gov/)
- **API**: [NREL Developer Network (NLR)](https://developer.nrel.gov/)
- **Station inventory**: BSRN FTP

## References

1. Sengupta, M., Xie, Y., Lopez, A., Habte, A., Maclaurin, G., & Shelby, J. (2018). The national solar radiation data base (NSRDB). *Renewable and Sustainable Energy Reviews*, 89, 51-60.

2. Xie, Y., Yang, J., Sengupta, M., Liu, Y., & Zhou, X. (2022). Improving the prediction of DNI with physics-based representation of all-sky circumsolar radiation. *Solar Energy*, 231, 758-766.

3. Xie, Y., Sengupta, M., Yang, J., Buster, G., Benton, B., Habte, A., & Liu, Y. (2023). Integration of a physics-based direct normal irradiance (DNI) model to enhance the National Solar Radiation Database (NSRDB). *Solar energy*, 266, 112195.

4. Xie, Y., Sengupta, M., & Dudhia, J. (2016). A Fast All-sky Radiation Model for Solar applications (FARMS): Algorithm and performance evaluation. *Solar Energy*, 135, 435-445.

## Citation

If you use this dataset, please cite the references above and the **bsrn** package: [dazhiyang/bsrn](https://github.com/dazhiyang/bsrn).

## License

NSRDB data is provided by NREL and is subject to their [Data Usage Policy](https://nsrdb.nrel.gov/about/data-usage).