Sea breeze detection

This repository has code that is intended to detect sea breezes from numerical weather model output. The code relies on packages including xarray/dask, scipy, metpy, scikit-image, pyproj and pandas (see requirements).

Contents:

• Code structure
  • Pre-processing model data
  • Sea breeze diagnostics
  • Object identification and filtering
• Examples
  • Local example
  • On the gadi HPC system
• Requirements
• Contributing
• Citing
• WxSysLib

Code structure

The code is organised into three sequential steps:

1. Pre-processing model data
2. Calculating sea breeze diagnostics
3. Object identification and filtering

Pre-processing model data

These are functions for loading and pre-processing model data, and can be found in load_model_data. This includes loading temperature, moisture, wind, and static variables from four different model datasets hosted on the NCI data catalog (requires the code to be run locally on the NCI system). There is also a function that finds the angle of dominant coastline orientation from a land-sea mask (get_coastline_angle_kernel). This is important for finding the onshore component of the wind that is used in most sea breeze diagnostics (with thanks to Ewan Short for developing this method and code with input from Jarrah Harrison-Lofthouse).

Sea breeze diagnostics

These are functions for calculating sea breeze diagnostics, and can be found in sea_breeze_funcs. There are currently three key diagnostics:

• Kinematic moisture frontogenesis (kinematic_frontogenesis)
• Sea breeze index (calc_sbi)
• Fuzzy logic algorithm (fuzzy_function_combine)

Details on each diagnostic can be found in the relevant docstrings. For the fuzzy logic algoirithm, hourly changes in wind, temperature, and moisture need to be first calculated using the hourly_change function within sea_breeze_funcs. It is recommended to calculate hourly changes for the entire period of interest, as the algorithm needs to find percentiles of the distribution of each hourly change.

Sea breeze filtering

These functions convert the sea breeze diagnostics to a binary mask of candidate sea breeze objects, which are then refined by applying several filters of known sea breeze characteristics. Functions can be found in sea_breeze_filters. There are several filters that can be applied in filter_3d (see docstring). Output from filter_3d is a binary dataset of sea breeze objects. The filter.py script can be used to drive the filtering processing

For calculating the threshold to mask with, the percentile function can be used prior to the filtering. That way, the percentile threshold can be taken from a distribution over a longer period (say, several months) than the filtering period (say, a single day).

Notes

• For km-scale data, large amounts of memory may be required for diagnostic calculation and model pre-processing.

• In practice, diagnostics should be saved to disk, and reloaded for filtering. This is because each is a computationally heavy task, especially for km-scale model data. The zarr format is used for saving output for efficiency.

• There are a variety of settings in the filtering script, and it is noted that the land_sea_temperature_filter currently causes significant slowdown due to radial searching around sea breeze objects.

Examples

Local example

An example notebook demonstrating these three steps using ERA5 data is available here, with sample ERA5 data provided in the example_data directory.

On the gadi HPC system

An example notebook demonstrating these three steps using AUS2200 data is available here. This example is intended to run on the Australian NCI Gadi supercomputer, with access to the ACCESS-NRI conda environment on xp65 and AUS2200 on the bs94 project.

Requirements

The code was devloped on the analysis3-25.06 conda environment through the xp65 NCI project. This code builds on the following packages:

• cartopy 0.24.0
• dask 2025.5.1
• metpy 1.7.0
• numpy 1.26.4
• pandas 2.2.3
• pyproj 3.6.1
• scikit-image 0.25.2
• scipy 1.15.2
• xarray 2025.4.0
• netCDF4 1.7.2
• zarr 2.18.7

For running the local example, a minimum working environment can be build using conda:

conda create -n sea_breeze_env -c conda-forge cartopy=0.24.0 dask=2025.5.1 metpy=1.7.0 numpy=1.26.4 pandas=2.2.3 pyproj=3.6.1 scikit-image=0.25.2 scipy=1.15.2 xarray=2025.4.0 netCDF4=1.7.2 zarr=2.18.7

In addition, for loading ERA5 data hosted on the NCI within the load_model_data.py module, the following packages are required:

• access-nri-intake 1.2.3

Contributing

If would like to make changes to improve this code, please reach out or make an issue!

Citing

WxSysLib

This code was developed with funding from the ARC Centre of Excellence for 21st Century Weather. The code is also available in the Centre's WxSysLib repository. However, the version provided here should be considered the most up to date.