Metadata-Version: 2.4
Name: atmotools
Version: 1.2.9
Summary: AtmoTools SA package
Author-email: contact <antonin.zabukovec@cnes.fr>
License-Expression: Apache-2.0
Project-URL: Homepage, https://gitlab.cnes.fr/toolboxsa/toolbox
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==2.1.3
Requires-Dist: pandas==2.2.3
Requires-Dist: plotly==6.1.1
Requires-Dist: dash==4.1.0
Requires-Dist: rasterio==1.4.4
Requires-Dist: rioxarray==0.19.0
Requires-Dist: xarray==2024.10.0
Requires-Dist: scipy==1.14.1
Requires-Dist: h5py==3.15.1
Requires-Dist: pyproj==3.7.2
Requires-Dist: matplotlib==3.9.2
Requires-Dist: geoviews==1.15.1
Requires-Dist: holoviews==1.22.1
Requires-Dist: bokeh==3.8.2
Requires-Dist: texttable==1.7.0
Requires-Dist: netCDF4==1.7.2
Requires-Dist: pyhdf==0.11.6
Requires-Dist: basemap==2.0.0
Dynamic: license-file

<div align="center">

<!-- ![logo_atmotools](docs/images/logoAtmoTools.png)  -->
<img src="docs/images/logo_atmotools.png" height="200" />

**AtmoTools : A toolkit for atmospheric sounding data visualization.**

[![pypi](https://img.shields.io/pypi/v/atmotools?color=%2334D058&label=pypi)](https://pypi.org/project/atmotools/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/atmotools)
](https://pypi.org/project/atmotools/)
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-orange.svg)](CONTRIBUTING.md)
[![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
![Python >=3.11.10](https://img.shields.io/badge/python-3.11.10%2B-blue)

# 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.
</div>

# 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

You can install **AtmoTools** by running the following command :

```sh
pip install atmotools
```

If you have difficulties using the previous command, run the following command :
```sh
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](https://gitlab.cnes.fr/toolboxsa/toolbox/-/blob/develop/CNES_installation.md?ref_type=heads)

Else, you can install **AtmoTools** in "editable" mode :

```sh
pip install --editable atmotools
```
   > **_NOTE :_** The "editable" mode allows to imediatly update files modifications 

Please read this [guide](docs/doc_developer_guide.md) 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.

```py
import utils.hdf_netcdf_tools as hdfu

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

**Describe a file**
```py
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**
```py
var = rdr.get_var(<VAR_PATH>)
```
Get information on a variable
```py
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](docs/doc_reader_writer.md) and the [example](examples/hdf_netcdf_reader_example.ipynb).

### Writer

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

```py
import 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](examples/hdf_netcdf_writer_example.ipynb) and the [documentation](docs/doc_reader_writer.md)

**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:

```py
import 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](examples/hdf_netcdf_writer_modify_example.ipynb) and the [documentation](docs/doc_reader_writer.md)

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

```sh
atmotools.microcarb.app
```
You can now use the tool by navigating to http://127.0.0.1:8051/ via your preferred browser.

```sh
atmotools.iasi_ng.app -rad <path_to_rad_file>.nc
```
You can now use the tool by navigating to http://127.0.0.1:8052/ via your preferred browser.


These commands launch the following apps.  
MicroCarb visualization tool :
![mca_visu_tool_main_window](docs/images/mca_app_page1.png)  
IASI-NG visualization tool :
![iasi_visu_tool_main_window](docs/images/app_demo.png)

For more information on what these apps can do, how to launch them, and how they work, please refer to the documentation.
- [MicroCarb documentation](docs/doc_vis_microcarb.md)   
- [IASI-NG documentation](docs/doc_vis_iasing.md) 

# License

**AtmoTools** is licensed under permissive [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). Please refer to the [LICENSE](LICENSE) file for more details.

# Support

# Contributing
We welcome contributions! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get involved, including coding standards and submission processes.
