unox

Use machine learning to make predictions of NOₓ and other atmospheric species.

This is an application of the U-net deep learning model for North American NOₓ emission estimates using the tensorflow Python package.

model_diagram

Documentation

Setup guides, example usage, and API reference are available on Read the Docs.

Installation

This package is available for installation with pip. It is recommended to install unox in a virtual environment, such as one created with venv or conda.

(venv_name) $ pip install unox

Currently, the version of Python required for unox depends on what you want to do. The analysis and plotting functionality is written for Python 3.9.21, while the GPU functionality to run the model is written for Python 3.12.4. See the installation guide for details and instructions on how to get set up developing the code.

Requirements

There are two different sets of requirements, one for the analysis / plotting environment and one for the GPU environment. For the analysis / plotting environment, dependencies are tracked using the poetry dependency manager and the current specified version dependencies are listed under [tool.poetry.dependencies] in the pyproject.toml file. For the GPU environment, a summary of the requirements is given in the table below:

Package	Version
Python	3.12.4
Xarray	2024.3.0
NetCDF4	1.7.2
TensorFlow	2.17.0
Keras	3.10.0
CUDA	12.6

Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

The unox package was created by Mikhail Schee. It is licensed under the terms of the MIT license.

Credits

The U-net model is based on Tailong He’s repository for Chinese NOₓ emissions [1].
Initial transition from China region to North America by Evelyn MacDonald.
Initial adaptation to make estimates for CO by Daniel Sequeira.
Documentation, converting .npy to .nc files, and ensemble runs by Mikhail Schee.
The unox package was based off the py-pkgs-cookiecutter template using cookiecutter.
Package structure, documentation, and continuous integration based on the Python Packages open source book by Tomas Beuzen & Tiffany Timbers

Source of data

Training stage 1 involves TCR-2 surface NO₂ concentrations and NOₓ emissions. Both could be found from the JPL TCR-2 website. Last access was on 12 March 2025.
Training stage 2 involves in situ daily NO₂ measurements from the United States Environmental Protection Agency (EPA). Canadian data is planned to be added in the future.
Both stages require meteorological fields from ERA5 on single levels and on pressure levels.
Scripts for downloading ERA5 data and creating Unet input files and more information about the input file format are in the datafiles/ directory. Data are currently stored on animus-c.

Reference