tfv-get-tools 0.2.6

Tool for downloading and processing data for TUFLOW FV modelling

TFV Get Tools

⚠️ Beta Package - This is a beta release. Features may change and improvements are ongoing. Please report any issues to [e-mail].

Tools to assist with downloading and processing meteorological and ocean data to use with TUFLOW FV

Overview

TFV Get Tools is a Python package that simplifies the process of downloading and processing meteorological and ocean data for use with TUFLOW FV models. The tool supports extraction of tidal data, atmospheric conditions, ocean physics, and wave data from various authoritative sources.

Supported Data Sources

Atmospheric Data:

• ECMWF ERA5 (Atmos Default - registration required, see CDS API)
• NOAA CFSR (Climate Forecast System Reanalysis)
• BARRA2 (Australian Bureau of Meteorology)

Ocean Data:

• HYCOM (Ocean Default Naval Research Laboratory - Global Ocean Forecast System)
• Copernicus Marine Global and NWS (registration required, see Copernicus Marine Service)

Wave Data:

• CSIRO CAWCR (Wave Default glob_24m, aus_10m, aus_4m, pac_10m, pac_4m)
• Copernicus Marine Global and NWS
• ECMWF ERA5 (registration required, see CDS API)

Tidal Data:

• FES2014 (AVISO+ Finite Element Solution 2014)
• FES2022 (Tide Default AVISO+ Finite Element Solution 2022)

Installation

Conda/Mamba (Recommended)

# Create a new environment, if required. 
conda create -n tfv python=3.9
conda activate tfv

# Install the package
conda install -c conda-forge tfv-get-tools

Pip

pip install tfv-get-tools

Quick Start

Command Line Interface

The package provides command-line tools for downloading and processing data:

Ocean Data Example:

# Download HYCOM data for January 2011 on the east coast of Australia
GetOcean A 2011-01-01 2011-02-01 153 154 -29 -28

# Download with options (output directory path (-p), custom filename prefix (-pf) 3-hourly data (-ts), top 20 m (-z))
GetOcean A -p raw_data -pf studysite -ts 3 -z 0 20 2011-01-01 2011-02-01 153 154 -29 -28

# Merge downloaded files with options (input directory (-i), output directory (-o), timezone conversion (-tz), timezone attribute metadata (-ltz) and custom filename (-f))
GetOcean B -i raw_data -o output -tz 10 -ltz AEST -f merged_hycom.nc

Atmospheric Data Example:

# Download ERA5 atmospheric data with options (output directory path (-p))
GetAtmos A -p raw_data 2010-03-01 2010-04-01 153 154 -29 -28

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

Tidal Data Example:

# Extract tidal data from FES2022 extrapolated ocean tide 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
# Get Tide supports multiple FES tide models and each requires a specific directory structure. Refer to the wiki: (https://fvwiki.tuflow.com/TUFLOW_FV_Get_Tide_draft#Mandatory_FES_Folder_Structure)

Python API

Ocean Data:

from tfv_get_tools import DownloadOcean, MergeOcean

# Download HYCOM data
result = 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
)

# Merge downloaded files and shift time +10h with timezone attribute set to 'AEST'
MergeOcean(
    in_path='./raw_data',
    out_path='./output',
    source='HYCOM', 
    local_tz=(10, 'AEST'),
	fname= 'HYCOM_20110101_20110201_AEST.nc',
)

Atmospheric Data:

from tfv_get_tools import DownloadAtmos, MergeAtmos

# Download BARRA2 data
result = 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'
)

# Merge downloaded files, reproject to GDA2020 MGA56, and shift time +10h with timezone attribute set to 'AEST'
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 Data:

from pathlib import Path
from tfv_get_tools.tide import ExtractTide

# User input
t_start = '2023-01-01'
t_end = '2023-02-01'
fes_dir = './fes2022b/ocean_tide_extrapolated' # Get Tide supports multiple FES tide models and each requires a specific directory structure. Refer to the wiki: (https://fvwiki.tuflow.com/TUFLOW_FV_Get_Tide_draft#Mandatory_FES_Folder_Structure)
output_dir = './output'
shp_file = './2d_ns_Open_Boundary_001_L.shp'
output_name = 'GOC_FES2022_extrapolated_20230101_20230125.nc'
model = 'FES2022_extrapolated'

# Basic tidal extraction
ExtractTide(
    time_start=t_start,
    time_end=t_end,
    model_dir=fes_dir,
    source=model,
    fname=output_name,
    out_path=output_dir,
    freq='15min',
    shapefile=shp_file,
)

# Advanced usage with constituent caching
from tfv_get_tools.tide import load_nodestring_shapefile, process_nodestring_gdf, get_constituents

# Load and process boundary shapefile
gdf = load_nodestring_shapefile(shp_file)
coordinates = process_nodestring_gdf(gdf, spacing=2500)

# Extract constituents once (slow first time, fast afterwards)
constituents = get_constituents(
    coordinates,
    model_dir=fes_dir,
    source=model,
    save_cons='boundary_constituents.pkl',
)

# Use cached constituents for faster extraction
ExtractTide(
    time_start=t_start,
    time_end=t_end,
    fname=output_name,
    out_path=output_dir,
    freq='15min',
    constituents='boundary_constituents.pkl',
)

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 utilises data from multiple authoritative sources. Please ensure appropriate attribution when using this data:

Atmospheric Data

• ECMWF ERA5: Data provided by the European Centre for Medium-Range Weather Forecasts (ECMWF) through the Copernicus Climate Change Service (C3S). Please acknowledge: "Contains modified Copernicus Climate Change Service information [2025]".
• NOAA CFSR: Data provided by the National Oceanic and Atmospheric Administration (NOAA) National Centers for Environmental Information.
• BARRA2: Data provided by the Australian Bureau of Meteorology.

Ocean Data

• HYCOM: All ocean data is supplied by the HYCOM consortium. Please refer to the HYCOM data acknowledgement and disclaimer.
• Copernicus Marine: Ocean and wave data provided by the Copernicus Marine Environment Monitoring Service (CMEMS).

Wave Data

• CSIRO CAWCR: Wave data provided by the Commonwealth Scientific and Industrial Research Organisation (CSIRO) Centre for Australian Weather and Climate Research.
• Copernicus Marine: Wave data provided by the Copernicus Marine Environment Monitoring Service (CMEMS).

Tidal Data

• FES Tidal Models: Tidal data provided by AVISO+ and the FES development team. FES2014 and FES2022 are products of Noveltis, Legos, and CLS, with support from CNES.
• PyTMD: This package utilises the PyTMD Python package for tidal analysis and prediction, developed by Tyler Sutterley.

Support

For questions, bug reports, or feature requests:

• 📧 Email: [e-mail]
• 🐛 Issues: Submit via the project repository

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch from main
3. Make your changes with appropriate tests
4. Submit a pull request
5. Email [e-mail] to notify the development team

Please ensure your code follows the project's coding standards and includes appropriate documentation.

License

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

Authors

Developed by TUFLOW, 2026

Project Status

Active - This project is actively maintained and in use. For update requests or feature suggestions, please email [e-mail].

---

Last updated: January 2026