Metadata-Version: 2.3
Name: netcdf2dataframe
Version: 0.1.1
Summary: Small utility to transform netCDF files into (Geo)DataFrames
License: GPL-3.0-or-later
Keywords: climatology,oceanography
Author: Thomas Grandjean
Author-email: thomas.grandjean@developpement-durable.gouv.fr
Maintainer: Thomas Grandjean
Maintainer-email: thomas.grandjean@developpement-durable.gouv.fr
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Requires-Dist: geopandas (>=1.0.1,<2.0.0)
Requires-Dist: importlib-metadata (>=8.6.1,<9.0.0)
Requires-Dist: netcdf4 (>=1.7.2,<2.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Project-URL: Bug Tracker, https://github.com/tgrandje/netcdf-to-geodataframe/issues
Project-URL: Homepage, https://github.com/tgrandje/french-cities/
Description-Content-Type: text/markdown

# netcdf2dataframe
This repo contains a small utility used to transform netCDF files to geopandas.GeoDataFrames.

# Why netcdf2dataframe?

⚠️ This project was initiated due to the need of colleagues. It's considered a work in
progress !

# Installation

`pip install netcdf2dataframe`

# Basic usage

```
from netcdf2dataframe import netcdf2dataframe
path = "IMERG_total_precipitation_day_0.5x0.5_global_2021_v6.0.nc"
df = netcdf2dataframe(path, "pr")
```

Note that this module may end up crashing your machine, as DataFrames are not 
RAM-efficient objects (compared to the netCDF format). But sometimes, this is
what you may need...

Full docstring:

```
netcdf2dataframe(path: str, target: str = 'pr', dropna: bool = True) -> geopandas.geodataframe.GeoDataFrame
    Picks a netCDF file and extracts one variable ("target") on the form of
    a GeoDataFrame.
    
    Parameters
    ----------
    path : str
        Path to netCDF file
    target : str
        Target variable. Should be any of the available variables, excepting
        the latitude, longitude or time. Please look the INFO log to now more
        on the available variables.
        Note that available variables are displayed in the log (info level).
    dropna : bool, optional
        If True, the GeoDataFrame will not contain missing values, hence
        being more frugal (less RAM consumption). The default is True.
    
    Returns
    -------
    gpd.GeoDataFrame
        GeoDataFrame of the extracted values
    
    Example
    -------
    >>> df = netcdf2dataframe(
            "IMERG_total_precipitation_day_0.5x0.5_global_2021_v6.0.nc,
            "pr",
            )
    >>> df.head()
    
             pr   time_val                      geometry
    0  0.000000 2021-01-01  POINT (-179.74998 -78.24999)
    1  0.382080 2021-01-01  POINT (-177.24998 -78.24999)
    2  1.625944 2021-01-01  POINT (-176.74998 -78.24999)
    3  1.772459 2021-01-01  POINT (-176.24998 -78.24999)
    4  1.412688 2021-01-01  POINT (-175.74998 -78.24999)
```

## Support
In case of bugs, please open an issue [on the repo](https://github.com/tgrandje/netcdf-to-geodataframe/issues).

## Contribution
Any help is welcome.

This project is managed with poetry and tested with pytest. It uses black formatting with 79 characters.

## Author
Thomas GRANDJEAN (DREAL Hauts-de-France, service Information, Développement Durable et Évaluation Environnementale, pôle Promotion de la Connaissance).

## Licence
GPL-3.0-or-later

## Project Status
Development.
