Metadata-Version: 2.4
Name: tfv_get_tools
Version: 0.2.9
Summary: Tool for downloading and processing data for TUFLOW FV modelling
Author-email: TUFLOW Support <support@tuflow.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools
Project-URL: Repository, https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools
Project-URL: Issues, https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT 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
Requires-Python: <3.14,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: netCDF4>=1.6.2
Requires-Dist: tqdm>=4.65.0
Requires-Dist: xarray>=2023.1.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: pyproj>=3.5.0
Requires-Dist: siphon>=0.9
Requires-Dist: cdsapi>=0.7.0
Requires-Dist: copernicusmarine>=1.2.3
Requires-Dist: bottleneck>=1.3.5
Requires-Dist: pyTMD<3,>=2.1.7
Requires-Dist: shapely>=2.0.6
Requires-Dist: geopandas>=1.0.1
Requires-Dist: pandas<=2.3.3
Provides-Extra: dev
Requires-Dist: ipython>=8.6.0; extra == "dev"
Requires-Dist: notebook>=6.5.2; extra == "dev"
Requires-Dist: ipykernel>=6.17.1; extra == "dev"
Requires-Dist: dask>=2022.11.0; extra == "dev"
Requires-Dist: cftime; extra == "dev"
Requires-Dist: pydap; extra == "dev"
Requires-Dist: toolz; extra == "dev"
Requires-Dist: black>=22.12.0; extra == "dev"
Requires-Dist: matplotlib>=3.7.0; extra == "dev"
Requires-Dist: sphinx>=7.3.7; extra == "dev"
Requires-Dist: recommonmark>=0.7.1; extra == "dev"
Requires-Dist: sphinx-markdown-builder>=0.6.6; extra == "dev"
Requires-Dist: pyprojroot; extra == "dev"
Dynamic: license-file

# TFV Get Tools

tfv-get-tools provides command line tools and Python helpers for downloading and processing meteorological, ocean, wave, and tidal data for use with [TUFLOW FV](https://www.tuflow.com/Tuflow%20FV.aspx).

## Installation

Users are recommended to install tfv-get-tools into a dedicated conda environment. The package is available via the Python Package Index ([PyPI](https://pypi.org/project/tfv-get-tools/)) or [Conda Forge](https://anaconda.org/conda-forge/tfv-get-tools).

To install tfv-get-tools from the conda command line tool:

```cmd
conda install -c conda-forge tfv-get-tools
```

To install tfv-get-tools using pip:

```cmd
python -m pip install tfv-get-tools
```

*Note: The latest version has been built and tested on Python 3.9 to 3.13*.

### Dependencies

The tfv-get-tools package depends on the following core packages:

```text
    netCDF4>=1.6.2
    tqdm>=4.65.0
    xarray>=2023.1.0
    scipy>=1.10.0
    pyproj>=3.5.0
    siphon>=0.9
    cdsapi>=0.7.0
    copernicusmarine>=1.2.3
    bottleneck>=1.3.5
    pyTMD>=2.1.7,<3
    shapely>=2.0.6
    geopandas>=1.0.1
    pandas<=2.3.3
```

These will be automatically installed or updated as part of the tfv-get-tools installation.

## Supported Data Sources

tfv-get-tools supports the following data source families:

- Atmospheric data: ECMWF ERA5, NOAA CFSR, and BARRA2.
- Ocean data: HYCOM and Copernicus Marine.
- Wave data: CSIRO CAWCR, Copernicus Marine, and ECMWF ERA5.
- Tidal data: FES2014 and FES2022.

Registration or local data access is required for some sources:

- ERA5: [Copernicus Climate Data Store API](https://cds.climate.copernicus.eu/api-how-to)
- Copernicus Marine: [Copernicus Marine Service](https://marine.copernicus.eu/)
- FES tidal models: [AVISO+](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html)

## Quick Start

tfv-get-tools installs four command line tools:

```cmd
GetAtmos
GetOcean
GetWave
GetTide
```

Download HYCOM ocean data for January 2011 on the east coast of Australia:

```cmd
GetOcean A 2011-01-01 2011-02-01 153 154 -29 -28
```

Download ERA5 atmospheric data:

```cmd
GetAtmos A -p raw_data 2010-03-01 2010-04-01 153 154 -29 -28
```

Merge downloaded atmospheric files and convert the time coordinate to AEST:

```cmd
GetAtmos B -i raw_data -o output -rp 28356 -tz 10 -ltz AEST
```

Extract tidal data from FES2022 using a boundary nodestring shapefile:

```cmd
GetTide output/tide_data.nc 2010-03-01 2010-04-01 nodestrings/2d_ns_Open_Boundary_001_L.shp -s FES2022_extrapolated fes2022b/ocean_tide_extrapolated
```

**Wave Data Example:**
```bash
# Download CACWR wave data with options (output directory path (-p))
GetWave A -p raw_data 2018-08-01 2018-09-01 149 162 -31 -22

# Merge downloaded files with options (input directory (-i), output directory (-o), reprojected to EPSG:28356 (-rp), timezone conversion (-tz) and timezone attribute metadata (-ltz))
GetWave B -i raw_data -o output -rp 28356 -tz 10 -ltz AEST
```

Note: if your IT environment prevents you from running executables like the GetAtmos CLI tool, you can achieve the same by running (using GetAtmos as an example):
```cmd
python -m tfv_get_tools.cli.atmos_cli [args...]
```

## Python API

The package can also be used directly from Python:

```python
from tfv_get_tools import DownloadAtmos, DownloadOcean, MergeAtmos, MergeOcean

DownloadOcean(
    start_date="2011-01-01",
    end_date="2011-02-01",
    xlims=(153, 154),
    ylims=(-29, -28),
    out_path="./raw_data",
    source="HYCOM",
    time_interval=24,
)

MergeOcean(
    in_path="./raw_data",
    out_path="./output",
    source="HYCOM",
    local_tz=(10, "AEST"),
    fname="HYCOM_20110101_20110201_AEST.nc",
)

DownloadAtmos(
    start_date="2022-12-01",
    end_date="2023-01-01",
    xlims=(153, 154),
    ylims=(-29, -28),
    out_path="./raw_data",
    source="BARRA2",
    model="C2",
)

MergeAtmos(
    in_path="./raw_data",
    out_path="./output",
    fname="BARRA2_C2_20221201_20230101_EPSG7856_AEST.nc",
    source="BARRA2",
    model="C2",
    reproject=7856,
    local_tz=(10.0, "AEST"),
)
```

Tidal extraction is available through `tfv_get_tools.tide`:

```python
from tfv_get_tools.tide import ExtractTide
ExtractTide(
    time_start="2023-01-01",
    time_end="2023-02-01",
    model_dir="./fes2022b/ocean_tide_extrapolated",
    source="FES2022_extrapolated",
    fname="GOC_FES2022_extrapolated_20230101_20230201.nc",
    out_path="./output",
    freq="15min",
    shapefile="./2d_ns_Open_Boundary_001_L.shp",
)
```

GetTide supports multiple FES tide models and each model requires a specific local directory structure. See the [TUFLOW FV Get Tide wiki page](https://fvwiki.tuflow.com/TUFLOW_FV_Get_Tide#Mandatory_FES_Folder_Structure) for details.
**Wave Data:**
```python
from tfv_get_tools import DownloadWave, MergeWave

# Download Copernicus Global data
DownloadWave(
        start_date="2018-08-01",
        end_date="2018-11-30",
        xlims=(149, 162),
        ylims=(-31, -22),
        source="COPERNICUS",
        model="GLO",
        out_path="./raw_data",
)

# Merge downloaded files
MergeWave(
        in_path="./raw_data",
        out_path="./output",
        source="COPERNICUS",
        model="GLO",
        fname="Copernicus_GLO_wave_20180801_20181130.nc",
)
```

## Requirements

- Python 3.9+
- Internet connection for data downloads
- Registration required for some data sources:
    - **ERA5**: [Copernicus Climate Data Store (CDS) API](https://cds.climate.copernicus.eu/api-how-to)
    - **Copernicus Marine**: [Copernicus Marine Service](https://marine.copernicus.eu/)
    - **FES Tidal Models**: [AVISO+](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html) (for tidal constituent files)

## Data Credits and Acknowledgements

This package uses data from multiple authoritative sources. Please ensure appropriate attribution when using downloaded or processed data:

- ECMWF ERA5: Data provided by the [European Centre for Medium-Range Weather Forecasts](https://www.ecmwf.int/) through the Copernicus Climate Change Service.
- NOAA CFSR: Data provided by the [National Oceanic and Atmospheric Administration](https://www.noaa.gov/) National Centers for Environmental Information.
- BARRA2: Data provided by the [Australian Bureau of Meteorology](http://www.bom.gov.au/).
- HYCOM: Ocean data supplied by the [HYCOM consortium](https://www.hycom.org/).
- Copernicus Marine: Ocean and wave data provided by the [Copernicus Marine Environment Monitoring Service](https://marine.copernicus.eu/).
- CSIRO CAWCR: Wave data provided by the [Commonwealth Scientific and Industrial Research Organisation](https://www.csiro.au/).
- ECMWF ERA5 wave: Wave data provided by the [European Centre for Medium-Range Weather Forecasts](https://www.ecmwf.int/) through the Copernicus Climate Change Service.
- FES tidal models: Tidal data provided by [AVISO+](https://www.aviso.altimetry.fr/) and the FES development team.
- PyTMD: Tidal analysis and prediction provided by [PyTMD](https://github.com/tsutterley/pyTMD).

## Support

For support contact [TUFLOW Support](mailto:support@tuflow.com).

## Development and Publishing Workflow

For local development, testing, release publishing, and conda feedstock updates, see [RELEASE.md](RELEASE.md).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
