Metadata-Version: 2.4
Name: atmotools
Version: 1.2.13
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="https://gitlab.com/atmotools/pictures/-/raw/1be4f0f7330bbd2375edb80a34b15c02ee0268ef/logoAtmoTools_v2_small.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

**Requirements**: Python >= 3.11.10

It is strongly recommended to create a virtual environment.
In the directory that will hold the virtual environment, run:
```sh
virtualenv atmotools_env
source atmotools_env/bin/activate
```

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)

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:

```sh
pip install --editable .
```
   > **_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 atmotools.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 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](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 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](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 -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.

```sh
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.  
MicroCarb visualization tool :
![mca_visu_tool_main_window](docs/images/visu_tool_iasing.png)  
IASI-NG visualization tool :
![iasi_visu_tool_main_window](docs/images/visu_tool_microcarb.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.
