AtmoTools : A toolkit for atmospheric sounding data visualization.

Overview

AtmoTools is an open-source Python package that provides a wrapper for HDF4, HDF5 and NetCDF files and visualization tools for atmospheric sounding data.

Contacts

Antonin ZABUKOVEC : antonin.zabukove@cnes.fr
Sarah GUIBERT : sarah.guibert@cnes.fr

Features

• Reader for HDF5, HDF4 and NetCDF files
• Writer for NetCDF
• Atmospheric sounding data visualizations

Quick Start

Installation

Requirements: Python >= 3.11.10

It is strongly recommended to create a virtual environment. In the directory that will hold the virtual environment, run:

virtualenv atmotools_env
source atmotools_env/bin/activate

You can install AtmoTools by running the following command :

pip install atmotools

If you have difficulties using the previous command, run the following command :

pip install atmotools==<VERSION> --index-url https://pypi.org/simple

Requirements

• Python >= 3.10.11

Developer installation

For an installation from the git repository follow this documentation

Then you can install AtmoTools in "editable" mode :

If it hasn't already been done, navigate to the project folder and then run the following command:

pip install --editable .

NOTE : The "editable" mode allows to imediatly update files modifications

Please read this guide for developer best practices and specific AtmoTools practices.

Run AtmoTools

Reader

Atmotools includes the possibility to create a reader from any HDF5, NetCDF or HDF4 file path.

import atmotools.utils.hdf_netcdf_tools as hdfu

filepath = <YOUR_FILE_PATH>.nc / .h5 / .hdf
rdr = hdfu.createReader(filepath)

Describe a file

rdr.describe_file()
rdr.describe_all_vars()

• describe_file() : describes the file as a whole, as a table (without the variables attributes) or as a tree (with the variables attributes)
• describe_all_vars() : describes all of the variables of a file (or of a group if its path is given as an argument), as a json-like dictionary.

Get a variable

var = rdr.get_var(<VAR_PATH>)

NOTE : VAR_PATH is accesible with reader.describe_file().
VAR_PATH example : group/subgroup/var_name

Get information on a variable

var.describe()
var.get_data()
var.get_mean(axis)

• describe() : describe the variable
• get_data() : get the data of a variable
• get_mean(axis) : returns the mean of a variable data along the specified axis

For more information on what this reader can do and how it works, please refer to the documentation and the example.

Writer

Create a file
It is also possible to create a file thanks to the writer. For example, to write a nc file_path:

import atmotools.utils.hdf_netcdf_tools as hdfu

filepath = <YOUR_FILE_PATH>.nc
nc_writer = hdfu.Hdf5Netcdf4Writer(file_path = file_path,
                                    mode = "w",
                                    extension = ".nc")

The writer has all the same features as the reader, with some added features, like creating groups, variables, attributes, etc.
To find more detail on the writer and what it can be used for, please refer to the example and the documentation

Modify the content of a NetCDF/HDF5/HDF4 file

With the writer, it is also possible to modify the data of an already existing file. For example for a nc file_path:

import atmotools.utils.hdf_netcdf_tools as hdfu

filepath = <YOUR_FILE_PATH>.nc
nc_writer = hdfu.Hdf5Netcdf4Writer(file_path = file_path,
                                    mode = "a",
                                    extension = ".nc")

To find more detail on the writer and what it can be used for, please refer to the example and the documentation

Interactive Visualization tools

Atmotools includes visualization tools for MicroCarb and IASI-NG , which can be launched respectively with the commands :

atmotools.microcarb.app -l1b <file_path_l1b>.nc -l1c <file_path_l1c>.nc -isrf <file_path_isrf>.nc -eng <file_path_eng>.nc -l2 <file_path_l2>.nc

NOTE : It is completely possible to select multiple files for each type (L1B, L1C, ISRF, ENG, L2), or to provide a path for only one of the types. Some products have restricted access. Consequently, some features of the tool may be disabled.

You can now use the tool by navigating to http://127.0.0.1:8051/ via your preferred browser.

atmotools.iasi_ng.app -rad <path_to_rad_file>.nc -eng <path_to_eng_file>.nc -ods <path_to_ods_file>.nc

NOTE : It is entirely possible to select multiple files for each type (ENG, RAD, ODS), or to provide a path for only one of the types. Some products have restricted access. Consequently, some features of the tool may be disabled.

You can now use the tool by navigating to http://127.0.0.1:8052/ via your preferred browser.

If you need to change de port number then acces to the config parameters with the following commands :
atmotools.iasi_ng.config
atmotools.microcarb.config
These commands open the config file with vim. Press i to editate the file, :w to save it and :q to quit.

These commands launch the following apps.
IASI-NG visualization tool : MicroCarb visualization tool :

For more information on what these apps can do, how to launch them, and how they work, please refer to the documentation.

• MicroCarb documentation
• IASI-NG documentation

License

AtmoTools is licensed under permissive Apache License 2.0. Please refer to the LICENSE file for more details.

Support

Contributing

We welcome contributions! Please read our Contributing Guidelines for details on how to get involved, including coding standards and submission processes.