Metadata-Version: 2.2
Name: odb4py
Version: 1.3.4rc1
Summary: odb4py is a Python interface for ECMWF ODB1 databases, developed at the Royal Meteorological Institute of Belgium (RMI).
Keywords: RMI,KMI,observation,ODB,meteorology,python,database,extension,C
Author-Email: Idir Dehmous <idehmous@meteo.be>
Maintainer: Idir Dehmous - Royal Meteorological Institute of Belgium
License: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Project-URL: Homepage, https://github.com/idirdehmous/odb4py
Project-URL: Source, https://github.com/idirdehmous/odb4py
Project-URL: Documentation, https://odb4py.readthedocs.io
Requires-Python: >=3.9
Description-Content-Type: text/markdown

[![PyPI version](https://img.shields.io/pypi/v/odb4py.svg)](https://pypi.org/project/odb4py/)
[![Documentation Status](https://readthedocs.org/projects/odb4py/badge/?version=latest)](https://odb4py.readthedocs.io)
![Python](https://img.shields.io/pypi/pyversions/odb4py)

# odb4py 1.3.4rc1 release

## Description

**odb4py** (*Observation DataBase FOR PYthon*) is a C/Python interface to read and query ECMWF ODB1 databases.<br>
It provides high-performance access to ODB data through a native C backend, with seamless integration into the Python scientific ecosystem.<br>
The package embeds a customized version of the ECMWF ODB software [odb_api_bundle-0.18.1-Source](https://confluence.ecmwf.int) and is distributed as **manylinux wheels**, requiring no external ODB installation.

---

## Features

- Native C backend based on ECMWF ODB1
- Support for IFS and ARPEGE ODB databases
- SQL-like query interface
- Fast data access with [NumPy/C API](https://numpy.org/doc/2.1/reference/c-api/index.html) and pandas integration
- No runtime dependency on system ODB libraries and binaries
- Conversion to other formats : ODB2 ,NetcDF and SQLITE

---

## Installation

The **odb4py** package can be installed from PyPI using `pip`:

```bash
pip install odb4py  
```
## Quick start  
```python 
 
from odb4py import core      # The extension core
from odb4py import utils     # The helpers module


# Create a connction  
conn = core.odb_open( database  = "/path/to/ODB")   # ECMA or CCMA 

# Select lat/lon and obsvalue
sql_query="SELECT degrees(lat), degrees(lon) , obsvalue FROM hdr, body"

# Parse the query 
p=utils.SqlParser ("/path/to/ODB")

nf  =p.get_nfunc    ( sql_query )
sql =p.clean_string ( sql_query )


# Get the data as a Python dictionary 
data = conn.odb_dict( database  ="/path/to/ODB" ,   #  ODB path
                       sql_query= sql           ,   #  SQL query              
                       nfunc    = nf       )        #  Number of functions in the query
print(data)
```
For more documentation, please refer to the [Official Documentation](https://odb4py.readthedocs.io/en/latest/).

## Requirements
Python ≥ 3.9 <br>
NumPy  ≥ 2.0 <br>
Linux system (manylinux2014 compatible)

### Optional  <br>
pyodc  ≥ 1.6.0 <br>

## Scientific context
ODB (Observation DataBase) is a column-oriented database format developed at ECMWF
and widely used in numerical weather prediction systems such as IFS,ARPEGE and NWP limited are models<br>

**odb4py** is primarily designed for:<br>
- Meteorologists and atmospheric scientists (especially within the ACCORD consortium)<br>
- Operational and research environments
- Post-processing and diagnostic workflows
- The current package version focuses on read-only access and data extraction for scientific analysis.


## License
Apache License, Version 2.0. [See LICENSE for details ](https://www.apache.org/licenses/LICENSE-2.0).


odb4py incorporates components derived from the ECMWF ODB software.

The original source code has been modified to:
- Expose functionality through a Python interface
- Reduce the runtime footprint
- Enable portable binary wheel distribution

All original copyrights remain with ECMWF.

## Acknowledgements
- This project incorporates and is derived from the ECMWF ODB software. <br/>
ODB was developed at the European Centre for Medium-Range Weather Forecasts (ECMWF)
by [S. Saarinen et al](https://www.ecmwf.int/sites/default/files/elibrary/2004/76278-ifs-documentation-cy36r1-part-i-observation-processing_1.pdf). All rights to the original ODB software remains with ECMWF and their respective owners.
- The author would like S. Martinez from Météo France for to provide ARPEGE global model ODB samples. The latters have been used to evaluate the performance of the package.
- The author would also like to thank 'M.O Ait Meziane' for testing odb4py and providing valuable feedback.
