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.

Installation

Users are recommended to install tfv-get-tools into a dedicated conda environment. The package is available via the Python Package Index (PyPI) or Conda Forge.

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

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

To install tfv-get-tools using pip:

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:

    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
• Copernicus Marine: Copernicus Marine Service
• FES tidal models: AVISO+

Quick Start

tfv-get-tools installs four command line tools:

GetAtmos
GetOcean
GetWave
GetTide

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

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

Download ERA5 atmospheric data:

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:

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

Extract tidal data from FES2022 using a boundary nodestring shapefile:

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:

# 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):

python -m tfv_get_tools.cli.atmos_cli [args...]

Python API

The package can also be used directly from 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:

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 for details. Wave Data:

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
  • Copernicus Marine: Copernicus Marine Service
  • FES Tidal Models: AVISO+ (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 through the Copernicus Climate Change Service.
• NOAA CFSR: Data provided by the National Oceanic and Atmospheric Administration National Centers for Environmental Information.
• BARRA2: Data provided by the Australian Bureau of Meteorology.
• HYCOM: Ocean data supplied by the HYCOM consortium.
• Copernicus Marine: Ocean and wave data provided by the Copernicus Marine Environment Monitoring Service.
• CSIRO CAWCR: Wave data provided by the Commonwealth Scientific and Industrial Research Organisation.
• ECMWF ERA5 wave: Wave data provided by the European Centre for Medium-Range Weather Forecasts through the Copernicus Climate Change Service.
• FES tidal models: Tidal data provided by AVISO+ and the FES development team.
• PyTMD: Tidal analysis and prediction provided by PyTMD.

Support

For support contact TUFLOW Support.

Development and Publishing Workflow

For local development, testing, release publishing, and conda feedstock updates, see RELEASE.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.