Atmospheric Datasets Comparison (ADC) Toolbox is aimed to have a set of tools that allows users to compare atmospheric composition datasets from different sources. Currently, it is possible to compare:

• Forecast data from CAMS model vs. L2 near real-time and offline data from TROPOMI (NO₂, O₃, CO, SO₂, HCHO), IASI (O₃, CO, SO₂) and GOME-2 (NO₂, O₃, SO₂, HCHO) sensors.
• Reanalysis monthly data from CAMS model vs. L3 monthly data from TROPOMI (NO₂), IASI (O₃, CO) and GOME-2 (NO₂) sensors.

A full explanation of the initial version of this software and its theoretical background can be read in Research Gate.

Users can install the software in their desktop by following the steps described in Requirements. A case study was created to show the usability of the toolbox for deriving long-term trends in air pollution.

ADC Toolbox facilitates the retrieval of all the datasets presented in Table 1, since the dates they became available to the public. As an exception, the retrieval of IASI L2 data is currently available only since May 14, 2019.

Table 1. Temporal availability (start date - end date) by data source.

The temporal availability of each dataset differs from others. CAMS forecasts became available in 2015 and the reanalysis datasets are accessible since 2003. Besides, the satellites that carry the instruments were launched in different years. Sentinel 5-P was launched in 2017, whereas Metop-A, the first European polar-orbiting satellite, was launched in 2006 and de-orbited in 2021. Metop-B and Metop-C have been operational since 2012 and 2018, respectively.

The needed packages to run this software can be found in requirements.txt. The virtual environment environment.yml was generated to simplify the installation process, users just need to clone the project, create the environment and activate it with:

$ conda config --set channel_priority false
$ conda env create -f environment.yml
$ conda activate ADC Toolbox

If this takes too long, they can manually create it instead (recommended):

$ conda create --name ADC Toolbox
$ conda activate ADC Toolbox
$ conda install -c conda-forge/label/cartopy_dev cartopy
$ pip install -r requirements.txt

To download data from CAMS, users will need to create an account, get the ADS API key, create a file with the name keys.txt under the folder data, and write their API key in one line.

It is important to know that this code only runs in Linux operative systems due to the fact that CAMS model data must be downloaded in GRIB format. This can only be done using ecCodes, a package developed by ECMWF that is only available for Linux. In order to install this library, refer to this installation guide for clear instructions.

Lately, there have been problems retrieving the data from NACIS Natural Earth to generate the maps. It has also been found out that there are compatibility issues between the libraries Cartopy and Shapely. It is recommended that Shapely is reinstalled after installing Cartopy and that the maps data are downloaded manually with the following commands:

!pip install cartopy
!pip uninstall -y shapely
!pip install shapely --no-binary shapely
!wget https://raw.githubusercontent.com/SciTools/cartopy/master/tools/cartopy_feature_download.py
!python cartopy_feature_download.py physical
!python cartopy_feature_download.py cultural

In case users want to see the distribution of the components by countries, they will need a Google API Key, Client User ID and Secret. The library Geocoder is used to get the data from Google, but it also allows the users of the ADC Toolbox to use other APIs to do reverse geocoding (retrieving location information by coordinates). In the function scatter_plot, they will find the following line. You can rewrite as they wish. The list of providers can be found in Geocoder's Github repository.

>>> merge_df['Country'] = merge_df.apply(lambda row: geocoder.google([row['latitude'], row['longitude']], 
                                                     method = 'reverse', key = google_api_key).country_long, 
                                                     axis = 1)

If they do not want to edit anything and prefer to run the code using Google API, then they should edit the file keys.txt under the folder data, and write three lines, under their ADS API key. They should contain, in this order, the Google API Key, Client User ID and Secret. They can get their credentials in Google Cloud Platform.

├── README.md                               <- Details about project
├── LICENSE                                 <- Details about license
├── apt.txt                                 <- Details about requirements (apt-get)
├── requirements.txt                        <- Details about requirements (pip)
├── environment.yml                         <- Details about virtual environment
├── data                                    <- Folder where datasets are stored
│   │
│   └── cams                                <- Folder where CAMS datasets are stored
│       │
│       ├── 137-levels-definition.csv       <- Details about CAMS L137 levels
│       └── 60-levels-definition.csv        <- Details about CAMS L60 levels
│
├── functions                               <- Folder that contains all functions
│   │
│   ├── functions_general.ipynb             <- Functions that apply to all datasets
│   ├── functions_cams.ipynb                <- Functions that apply to CAMS datasets
│   ├── functions_iasi.ipynb                <- Functions that apply to IASI datasets
│   ├── functions_tropomi.ipynb             <- Functions that apply to TROPOMI datasets
│   └── functions_gome.ipynb                <- Functions that apply to GOME-2 datasets
│
├── report                                  <- Folder where the images of the README.md are stored
│
├── thesis                                  <- Folder for case study (master's thesis)
│
├── trainings                               <- Folder for trainings material 
│   │
│   └── 2021-12-atmospheric-composition     <- 3rd EUMETSAT/ESA/ECMWF Joint Training in AC
│     │
│     ├── images                            <- Folder where the images of the training are stored
│     ├── data-comparison-practical.ipynb   <- Data comparison practical
│     └── keys-example.txt                  <- File format example of keys.txt (hidden)
│
├── main_cams_gome_L2.ipynb                 <- Comparison between CAMS and GOME-2 L2 datasets
├── main_cams_gome_L3.ipynb                 <- Comparison between CAMS and GOME-2 L3 datasets
├── main_cams_iasi_L2.ipynb                 <- Comparison between CAMS and IASI L2 datasets
├── main_cams_iasi_L3.ipynb                 <- Comparison between CAMS and IASI L3 datasets
├── main_cams_tropomi_L2.ipynb              <- Comparison between CAMS and TROPOMI L2 datasets
└── main_cams_tropomi_L3.ipynb              <- Comparison between CAMS and TROPOMI L3 datasets

• ADS: CAMS global atmospheric composition forecasts
• ADS: CAMS global greenhouse gas reanalysis (EGG4) monthly averaged fields
• S5-P hub: TROPOMI datasets (L2)
• TEMIS: TROPOMI and GOME-2 datasets (L3)
• AERIS Portal: IASI datasets (L2 and L3)
• AC SAF: GOME-2 datasets (L2 and L3)

• TROPOMI user manual
• TROPOMI NO₂ product manual
• TROPOMI CO product manual
• SENTINEL API documentation
• Xarray API reference

• Supporting functions from LTPy training course
• CAMS model vertical resolution and configuration

If you are interested in the ADC toolbox and would like it to have other functionalities or datasets, you can write your feedback in this form. Thank you very much!

Alba Vilanova Cortezón
Research Engineer at Barcelona Supercomputing Center
BEng in Mechanical Engineering at University of Lleida and Inha University
MSc in Geospatial Technologies at NOVA University of Lisbon, WWU Münster and UJI
GitHub: @albavilanova
LinkedIn: @albavilanova
Website: https://albavilanova.es/