cerra-benchmarking

A repository for the CERRA benchmarking study to demonstrate how to download datasets from BrightHub and the workflow to perform a long term correlation for reanalysis datasets with site data. This repo contains example code, data references, and a workflow to compare perform long term correlation using the brightwind library methodology.

Getting started

Clone this repository:

git clone https://github.com/brightwindanalysis/cerra-benchmarking.git
cd cerra-benchmarking

What this repo is for

• Demonstrating the CERRA benchmarking workflow with reanalysis and site data.
• Comparing three reanalysis datasets: CERRA, ERA5, and MERRA-2.
• Computing correlations between each reanalysis dataset and site measurements.
• Using the methodology described in the brightwind library notes for reanalysis benchmarking and correlation analysis.

Repository layout

• data/CERRA/ - CERRA reanalysis dataset files downloaded and saved here as pkl files
• data/ERA5/ - ERA5 reanalysis dataset files downloaded and saved here as pkl files
• data/MERRA-2/ - MERRA-2 reanalysis dataset files downloaded and saved here as pkl files
• data/SiteData/ - cleaned measured datasets saved here as csv files
• notebooks/analysis_notebook.ipynb - example analysis notebook
• outputs/ - results and output files from the demonstrated workflow

Install brightwind

Full installation guidance, including a Windows step-by-step guide, is in the official brightwind docs.

Option 1: Create a new venv environment

python -m venv .venv

On Windows:

.\.venv\Scripts\Activate.ps1

On macOS/Linux:

source .venv/bin/activate

Install brightwind and required packages:

pip install --upgrade pip
pip install brightwind notebook

If you prefer JupyterLab, install it instead of or in addition to notebook:

pip install jupyterlab

Install this repository in editable mode

From the repo root:

pip install -e .

This makes cerra_benchmarking importable from notebooks and scripts without manual sys.path changes.

Option 2: Create a new conda environment

conda create -n cerra-benchmarking python=3.11 -y
conda activate cerra-benchmarking
pip install --upgrade pip
pip install brightwind notebook
pip install -e .

BrightHub account and data access

Downloading reanalysis and site data in this workflow requires a free BrightHub account. BrightHub is the data platform used by Brightwind; the brightwind library accesses it directly via the BrightHub API.

Create an account

Sign up for a free account at brighthub.io using either:

• Email and password — enter your email, set a password, and verify via the confirmation link sent to your inbox
• Microsoft SSO — sign in with your work Microsoft account

Free accounts give access to all reanalysis datasets and open-source datasets on BrightHub.

API credentials

Once you have an account, follow the BrightHub Python user guide — Accessing data via the BrightHub API for instructions on authenticating with your credentials within the brightwind library.

Note: Keep your BrightHub credentials out of version control. Do not hardcode usernames or passwords in notebooks or scripts — use environment variables or a local config file that is listed in .gitignore.

Run the benchmarking workflow

Use the provided notebook notebooks/analysis_notebook.ipynb to:

1. Download reanalysis data from ERA5, MERRA-2 and CERRA using the brightwind library.
2. Download an example open access mast dataset
3. Apply cleaning, calibrations and adjustments to the mast data.
4. Compute correlations for each reanalysis dataset versus the site observations.
5. Compare results across the three datasets.

Correlation methodology

Following the brightwind library methodology as described in the official brightwind notes:

• compute correlation metrics for each dataset pair
• compare the three reanalysis results to evaluate relative performance

This repo is designed to work with that methodology by providing the example data structure and analysis template.