tfv-get-tools 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tfv_get_tools-0.2.0/PKG-INFO +286 -0
- tfv_get_tools-0.2.0/README.md +242 -0
- tfv_get_tools-0.2.0/pyproject.toml +77 -0
- tfv_get_tools-0.2.0/setup.cfg +4 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/__init__.py +4 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/_standard_attrs.py +107 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/atmos.py +167 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/cli/_cli_base.py +173 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/cli/atmos_cli.py +192 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/cli/ocean_cli.py +204 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/cli/tide_cli.py +118 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/cli/wave_cli.py +183 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/__init__.py +3 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/_atmos.py +230 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/_fvc.py +218 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/_ocean.py +171 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/_tide.py +195 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/ocean.py +170 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/__init__.py +0 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/_custom_conversions.py +34 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/_downloader.py +566 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/_merger.py +520 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/_utilities.py +255 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/barra2.py +209 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/barra2_c2.yaml +52 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/barra2_r2.yaml +85 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/barra2_re2.yaml +70 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/cfsr.yaml +68 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/era5.yaml +77 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/era5_gcp.yaml +77 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfsr.py +207 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/era5.py +20 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/era5_gcp.py +20 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/cfgs/copernicus_blk.yaml +64 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/cfgs/copernicus_glo.yaml +67 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/cfgs/copernicus_nws.yaml +62 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/cfgs/hycom.yaml +73 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/copernicus_ocean.py +457 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/hycom.py +611 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cawcr.py +166 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_aus_10m.yaml +39 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_aus_4m.yaml +39 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_glob_24m.yaml +39 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_pac_10m.yaml +39 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_pac_4m.yaml +39 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/copernicus_glo.yaml +56 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/copernicus_nws.yaml +51 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/era5.yaml +48 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/era5_gcp.yaml +48 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/copernicus_wave.py +38 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/era5.py +232 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/era5_gcp.py +169 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/tide/__init__.py +2 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/tide/_nodestring.py +214 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/tide/_tidal_base.py +568 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/_tfv_bc.py +78 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/horizontal_padding.py +89 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/land_masking.py +93 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/parsers.py +44 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/warnings.py +38 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools/wave.py +179 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/PKG-INFO +286 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/SOURCES.txt +72 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/dependency_links.txt +1 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/entry_points.txt +5 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/requires.txt +24 -0
- tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/top_level.txt +1 -0
- tfv_get_tools-0.2.0/tests/test_all_downloaders.py +215 -0
- tfv_get_tools-0.2.0/tests/test_cli_get_atmos.py +369 -0
- tfv_get_tools-0.2.0/tests/test_downloader.py +182 -0
- tfv_get_tools-0.2.0/tests/test_era5_merger.py +618 -0
- tfv_get_tools-0.2.0/tests/test_frontend_python_api.py +402 -0
- tfv_get_tools-0.2.0/tests/test_mergers.py +495 -0
- tfv_get_tools-0.2.0/tests/test_tide_extraction.py +1084 -0
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: tfv_get_tools
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Tool for downloading and processing data for TUFLOW FV modelling
|
|
5
|
+
Author-email: Alex Waterhouse <alex.waterhouse@apac.bmt.org>, Mitchell Smith <mitchell.smith@apac.bmt.org>, TUFLOW Support <support@tuflow.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools
|
|
8
|
+
Project-URL: Repository, https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools
|
|
9
|
+
Project-URL: Issues, https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools/issues
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Requires-Python: <3.14,>=3.9
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
Requires-Dist: netCDF4>=1.6.2
|
|
22
|
+
Requires-Dist: tqdm>=4.65.0
|
|
23
|
+
Requires-Dist: xarray>=2023.1.0
|
|
24
|
+
Requires-Dist: scipy>=1.10.0
|
|
25
|
+
Requires-Dist: pyproj>=3.5.0
|
|
26
|
+
Requires-Dist: siphon>=0.9
|
|
27
|
+
Requires-Dist: cdsapi>=0.7.0
|
|
28
|
+
Requires-Dist: copernicusmarine>=1.2.3
|
|
29
|
+
Requires-Dist: bottleneck>=1.3.5
|
|
30
|
+
Requires-Dist: pyTMD>=2.1.5
|
|
31
|
+
Requires-Dist: shapely>=2.0.6
|
|
32
|
+
Requires-Dist: geopandas>=1.0.1
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: ipython>=8.6.0; extra == "dev"
|
|
35
|
+
Requires-Dist: notebook>=6.5.2; extra == "dev"
|
|
36
|
+
Requires-Dist: ipykernel>=6.17.1; extra == "dev"
|
|
37
|
+
Requires-Dist: dask>=2022.11.0; extra == "dev"
|
|
38
|
+
Requires-Dist: black>=22.12.0; extra == "dev"
|
|
39
|
+
Requires-Dist: matplotlib>=3.7.0; extra == "dev"
|
|
40
|
+
Requires-Dist: sphinx>=7.3.7; extra == "dev"
|
|
41
|
+
Requires-Dist: recommonmark>=0.7.1; extra == "dev"
|
|
42
|
+
Requires-Dist: sphinx-markdown-builder>=0.6.6; extra == "dev"
|
|
43
|
+
Requires-Dist: pyprojroot; extra == "dev"
|
|
44
|
+
|
|
45
|
+
# TFV Get Tools
|
|
46
|
+
|
|
47
|
+
> **⚠️ Beta Package** - This is a beta release. Features may change and improvements are ongoing. Please report any issues to support@tuflow.com.
|
|
48
|
+
|
|
49
|
+
**Tools to assist with downloading and processing meteorological and ocean data to use with TUFLOW FV**
|
|
50
|
+
|
|
51
|
+
[](https://opensource.org/licenses/MIT)
|
|
52
|
+
[](https://github.com/your-repo/tfv-get-tools)
|
|
53
|
+
|
|
54
|
+
## Overview
|
|
55
|
+
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
### Supported Data Sources
|
|
59
|
+
|
|
60
|
+
**Atmospheric Data:**
|
|
61
|
+
- [ECMWF ERA5](https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5) (Default - registration required, see [CDS API](https://cds.climate.copernicus.eu/api-how-to))
|
|
62
|
+
- [NOAA CFSR](https://www.ncei.noaa.gov/data/climate-forecast-system/) (Climate Forecast System Reanalysis)
|
|
63
|
+
- [BARRA2](http://www.bom.gov.au/research/projects/reanalysis/) (Australian Bureau of Meteorology)
|
|
64
|
+
|
|
65
|
+
**Ocean Data:**
|
|
66
|
+
- [HYCOM](https://www.hycom.org/) (Naval Research Laboratory - Global Ocean Forecast System)
|
|
67
|
+
- [Copernicus Marine](https://marine.copernicus.eu/) Global and NWS (registration required, see [Copernicus Marine Service](https://marine.copernicus.eu/))
|
|
68
|
+
|
|
69
|
+
**Wave Data:**
|
|
70
|
+
- [CSIRO CAWCR](https://data.csiro.au/collection/csiro:39819) (glob_24m, aus_10m, aus_4m, pac_10m, pac_4m)
|
|
71
|
+
- [Copernicus Marine](https://marine.copernicus.eu/) Global and NWS
|
|
72
|
+
- [ECMWF ERA5](https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5) (registration required, see [CDS API](https://cds.climate.copernicus.eu/api-how-to))
|
|
73
|
+
|
|
74
|
+
**Tidal Data:**
|
|
75
|
+
- [FES2014](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html) (AVISO+ Finite Element Solution 2014)
|
|
76
|
+
- [FES2022](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html) (AVISO+ Finite Element Solution 2022)
|
|
77
|
+
|
|
78
|
+
## Installation
|
|
79
|
+
|
|
80
|
+
### Conda/Mamba (Recommended)
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
# Create a new environment, if required.
|
|
84
|
+
conda create -n tfv python=3.9
|
|
85
|
+
conda activate tfv
|
|
86
|
+
|
|
87
|
+
# Install the package
|
|
88
|
+
conda install -c conda-forge tfv-get-tools
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Pip
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
pip install tfv-get-tools
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Quick Start
|
|
98
|
+
|
|
99
|
+
### Command Line Interface
|
|
100
|
+
|
|
101
|
+
The package provides command-line tools for downloading and processing data:
|
|
102
|
+
|
|
103
|
+
**Ocean Data Example:**
|
|
104
|
+
```bash
|
|
105
|
+
# Download HYCOM data for January 2011 in southeast Queensland
|
|
106
|
+
GetOcean A 2011-01-01 2011-02-01 153 156 -29 -24
|
|
107
|
+
|
|
108
|
+
# Download with custom options (top 20m, 3-hourly data, custom prefix)
|
|
109
|
+
GetOcean A -p raw_data -pf SEQ_HYCOM -ts 3 -z 0 20 2011-01-01 2011-02-01 153 156 -29 -24
|
|
110
|
+
|
|
111
|
+
# Merge downloaded files
|
|
112
|
+
GetOcean B -i raw_data -o output -rp 28350 -tz 8 -ltz AWST -n merged_hycom.nc
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Atmospheric Data Example:**
|
|
116
|
+
```bash
|
|
117
|
+
# Download ERA5 atmospheric data
|
|
118
|
+
GetAtmos A 2011-01-01 2011-02-01 152 154 -28 -26
|
|
119
|
+
|
|
120
|
+
# Merge with reprojection and timezone conversion
|
|
121
|
+
GetAtmos B -i raw_data -o output -rp 7856 -tz 10 -ltz AEST
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Tidal Data Example:**
|
|
125
|
+
```bash
|
|
126
|
+
# Extract tidal data using a boundary nodestring shapefile
|
|
127
|
+
GetTide output/tide_data.nc 2011-01-01 2012-01-01 boundaries/nodestring.shp path/to/fes2022/
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Python API
|
|
131
|
+
|
|
132
|
+
**Ocean Data:**
|
|
133
|
+
```python
|
|
134
|
+
from tfv_get_tools import DownloadOcean, MergeOcean
|
|
135
|
+
|
|
136
|
+
# Download HYCOM data
|
|
137
|
+
result = DownloadOcean(
|
|
138
|
+
start_date='2011-01-01',
|
|
139
|
+
end_date='2011-02-01',
|
|
140
|
+
xlims=(153, 156),
|
|
141
|
+
ylims=(-29, -24),
|
|
142
|
+
out_path='./raw_data',
|
|
143
|
+
source='HYCOM',
|
|
144
|
+
time_interval=24
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
# Merge downloaded files
|
|
148
|
+
MergeOcean(
|
|
149
|
+
in_path='./raw_data',
|
|
150
|
+
out_path='./output',
|
|
151
|
+
source='HYCOM',
|
|
152
|
+
reproject=28350,
|
|
153
|
+
local_tz=(8, 'AWST')
|
|
154
|
+
)
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
**Atmospheric Data:**
|
|
158
|
+
```python
|
|
159
|
+
from tfv_get_tools import DownloadAtmos, MergeAtmos
|
|
160
|
+
|
|
161
|
+
# Download BARRA2 data
|
|
162
|
+
result = DownloadAtmos(
|
|
163
|
+
start_date='2020-01-01',
|
|
164
|
+
end_date='2020-02-01',
|
|
165
|
+
xlims=(152.72, 153.78),
|
|
166
|
+
ylims=(-27.49, -25.39),
|
|
167
|
+
out_path='./raw_data',
|
|
168
|
+
source='BARRA2',
|
|
169
|
+
model='C2'
|
|
170
|
+
)
|
|
171
|
+
|
|
172
|
+
# Merge with reprojection to GDA2020 MGA56
|
|
173
|
+
MergeAtmos(
|
|
174
|
+
in_path='./raw_data',
|
|
175
|
+
out_path='./output',
|
|
176
|
+
source='BARRA2',
|
|
177
|
+
model='C2',
|
|
178
|
+
reproject=7856,
|
|
179
|
+
local_tz=(10.0, 'AEST')
|
|
180
|
+
)
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
**Tidal Data:**
|
|
184
|
+
```python
|
|
185
|
+
from pathlib import Path
|
|
186
|
+
from tfv_get_tools.tide import ExtractTide
|
|
187
|
+
|
|
188
|
+
# Basic tidal extraction
|
|
189
|
+
ExtractTide(
|
|
190
|
+
start_date='2011-01-01',
|
|
191
|
+
end_date='2012-01-01',
|
|
192
|
+
filename='tide_data.nc',
|
|
193
|
+
out_path='./output',
|
|
194
|
+
freq='15min',
|
|
195
|
+
shapefile='boundaries/nodestring.shv'
|
|
196
|
+
)
|
|
197
|
+
|
|
198
|
+
# Advanced usage with constituent caching
|
|
199
|
+
from tfv_get_tools.tide import load_nodestring_shapefile, process_nodestring_gdf, get_constituents
|
|
200
|
+
|
|
201
|
+
# Load and process boundary shapefile
|
|
202
|
+
gdf = load_nodestring_shapefile('boundaries/nodestring.shp', process_ids=[1])
|
|
203
|
+
coordinates = process_nodestring_gdf(gdf, spacing=5000)
|
|
204
|
+
|
|
205
|
+
# Extract constituents once (slow first time, fast afterwards)
|
|
206
|
+
constituents = get_constituents(
|
|
207
|
+
coordinates,
|
|
208
|
+
source='FES2022',
|
|
209
|
+
save_cons='boundary_constituents.pkl'
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
# Use cached constituents for faster extraction
|
|
213
|
+
ExtractTide(
|
|
214
|
+
start_date='2011-01-01',
|
|
215
|
+
end_date='2012-01-01',
|
|
216
|
+
filename='tide_data.nc',
|
|
217
|
+
out_path='./output',
|
|
218
|
+
freq='15min',
|
|
219
|
+
constituents='boundary_constituents.pkl'
|
|
220
|
+
)
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Requirements
|
|
224
|
+
|
|
225
|
+
- Python 3.9+
|
|
226
|
+
- Internet connection for data downloads
|
|
227
|
+
- Registration required for some data sources:
|
|
228
|
+
- **ERA5**: [Copernicus Climate Data Store (CDS) API](https://cds.climate.copernicus.eu/api-how-to)
|
|
229
|
+
- **Copernicus Marine**: [Copernicus Marine Service](https://marine.copernicus.eu/)
|
|
230
|
+
- **FES Tidal Models**: [AVISO+](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html) (for tidal constituent files)
|
|
231
|
+
|
|
232
|
+
## Data Credits and Acknowledgements
|
|
233
|
+
|
|
234
|
+
This package utilises data from multiple authoritative sources. Please ensure appropriate attribution when using this data:
|
|
235
|
+
|
|
236
|
+
### Atmospheric Data
|
|
237
|
+
- **ECMWF ERA5**: Data provided by the [European Centre for Medium-Range Weather Forecasts (ECMWF)](https://www.ecmwf.int/) through the Copernicus Climate Change Service (C3S). Please acknowledge: "Contains modified Copernicus Climate Change Service information [2025]".
|
|
238
|
+
- **NOAA CFSR**: Data provided by the [National Oceanic and Atmospheric Administration (NOAA)](https://www.noaa.gov/) National Centers for Environmental Information.
|
|
239
|
+
- **BARRA2**: Data provided by the [Australian Bureau of Meteorology](http://www.bom.gov.au/).
|
|
240
|
+
|
|
241
|
+
### Ocean Data
|
|
242
|
+
- **HYCOM**: All ocean data is supplied by the [HYCOM consortium](https://www.hycom.org/). Please refer to the [HYCOM data acknowledgement and disclaimer](https://www.hycom.org/publications/acknowledgements/hycom-data).
|
|
243
|
+
- **Copernicus Marine**: Ocean and wave data provided by the [Copernicus Marine Environment Monitoring Service (CMEMS)](https://marine.copernicus.eu/).
|
|
244
|
+
|
|
245
|
+
### Wave Data
|
|
246
|
+
- **CSIRO CAWCR**: Wave data provided by the [Commonwealth Scientific and Industrial Research Organisation (CSIRO)](https://www.csiro.au/) Centre for Australian Weather and Climate Research.
|
|
247
|
+
- **Copernicus Marine**: Wave data provided by the [Copernicus Marine Environment Monitoring Service (CMEMS)](https://marine.copernicus.eu/).
|
|
248
|
+
|
|
249
|
+
### Tidal Data
|
|
250
|
+
- **FES Tidal Models**: Tidal data provided by [AVISO+](https://www.aviso.altimetry.fr/) and the FES development team. FES2014 and FES2022 are products of Noveltis, Legos, and CLS, with support from CNES.
|
|
251
|
+
- **PyTMD**: This package utilises the [PyTMD](https://github.com/tsutterley/pyTMD) Python package for tidal analysis and prediction, developed by Tyler Sutterley.
|
|
252
|
+
|
|
253
|
+
## Support
|
|
254
|
+
|
|
255
|
+
For questions, bug reports, or feature requests:
|
|
256
|
+
- 📧 **Email**: support@tuflow.com
|
|
257
|
+
- 🐛 **Issues**: Submit via the project repository
|
|
258
|
+
- 📖 **Documentation**: [Link to documentation] (if available)
|
|
259
|
+
|
|
260
|
+
## Contributing
|
|
261
|
+
|
|
262
|
+
Contributions are welcome! Please follow these steps:
|
|
263
|
+
|
|
264
|
+
1. Fork the repository
|
|
265
|
+
2. Create a feature branch from `main`
|
|
266
|
+
3. Make your changes with appropriate tests
|
|
267
|
+
4. Submit a pull request
|
|
268
|
+
5. Email support@tuflow.com to notify the development team
|
|
269
|
+
|
|
270
|
+
Please ensure your code follows the project's coding standards and includes appropriate documentation.
|
|
271
|
+
|
|
272
|
+
## License
|
|
273
|
+
|
|
274
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
275
|
+
|
|
276
|
+
## Authors
|
|
277
|
+
|
|
278
|
+
Developed by [BMT](https://www.bmt.org/), 2025
|
|
279
|
+
|
|
280
|
+
## Project Status
|
|
281
|
+
|
|
282
|
+
**Active** - This project is actively maintained and in use. For update requests or feature suggestions, please email support@tuflow.com.
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
*Last updated: July 2025*
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
# TFV Get Tools
|
|
2
|
+
|
|
3
|
+
> **⚠️ Beta Package** - This is a beta release. Features may change and improvements are ongoing. Please report any issues to support@tuflow.com.
|
|
4
|
+
|
|
5
|
+
**Tools to assist with downloading and processing meteorological and ocean data to use with TUFLOW FV**
|
|
6
|
+
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
[](https://github.com/your-repo/tfv-get-tools)
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
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.
|
|
13
|
+
|
|
14
|
+
### Supported Data Sources
|
|
15
|
+
|
|
16
|
+
**Atmospheric Data:**
|
|
17
|
+
- [ECMWF ERA5](https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5) (Default - registration required, see [CDS API](https://cds.climate.copernicus.eu/api-how-to))
|
|
18
|
+
- [NOAA CFSR](https://www.ncei.noaa.gov/data/climate-forecast-system/) (Climate Forecast System Reanalysis)
|
|
19
|
+
- [BARRA2](http://www.bom.gov.au/research/projects/reanalysis/) (Australian Bureau of Meteorology)
|
|
20
|
+
|
|
21
|
+
**Ocean Data:**
|
|
22
|
+
- [HYCOM](https://www.hycom.org/) (Naval Research Laboratory - Global Ocean Forecast System)
|
|
23
|
+
- [Copernicus Marine](https://marine.copernicus.eu/) Global and NWS (registration required, see [Copernicus Marine Service](https://marine.copernicus.eu/))
|
|
24
|
+
|
|
25
|
+
**Wave Data:**
|
|
26
|
+
- [CSIRO CAWCR](https://data.csiro.au/collection/csiro:39819) (glob_24m, aus_10m, aus_4m, pac_10m, pac_4m)
|
|
27
|
+
- [Copernicus Marine](https://marine.copernicus.eu/) Global and NWS
|
|
28
|
+
- [ECMWF ERA5](https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5) (registration required, see [CDS API](https://cds.climate.copernicus.eu/api-how-to))
|
|
29
|
+
|
|
30
|
+
**Tidal Data:**
|
|
31
|
+
- [FES2014](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html) (AVISO+ Finite Element Solution 2014)
|
|
32
|
+
- [FES2022](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html) (AVISO+ Finite Element Solution 2022)
|
|
33
|
+
|
|
34
|
+
## Installation
|
|
35
|
+
|
|
36
|
+
### Conda/Mamba (Recommended)
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
# Create a new environment, if required.
|
|
40
|
+
conda create -n tfv python=3.9
|
|
41
|
+
conda activate tfv
|
|
42
|
+
|
|
43
|
+
# Install the package
|
|
44
|
+
conda install -c conda-forge tfv-get-tools
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Pip
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install tfv-get-tools
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Quick Start
|
|
54
|
+
|
|
55
|
+
### Command Line Interface
|
|
56
|
+
|
|
57
|
+
The package provides command-line tools for downloading and processing data:
|
|
58
|
+
|
|
59
|
+
**Ocean Data Example:**
|
|
60
|
+
```bash
|
|
61
|
+
# Download HYCOM data for January 2011 in southeast Queensland
|
|
62
|
+
GetOcean A 2011-01-01 2011-02-01 153 156 -29 -24
|
|
63
|
+
|
|
64
|
+
# Download with custom options (top 20m, 3-hourly data, custom prefix)
|
|
65
|
+
GetOcean A -p raw_data -pf SEQ_HYCOM -ts 3 -z 0 20 2011-01-01 2011-02-01 153 156 -29 -24
|
|
66
|
+
|
|
67
|
+
# Merge downloaded files
|
|
68
|
+
GetOcean B -i raw_data -o output -rp 28350 -tz 8 -ltz AWST -n merged_hycom.nc
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**Atmospheric Data Example:**
|
|
72
|
+
```bash
|
|
73
|
+
# Download ERA5 atmospheric data
|
|
74
|
+
GetAtmos A 2011-01-01 2011-02-01 152 154 -28 -26
|
|
75
|
+
|
|
76
|
+
# Merge with reprojection and timezone conversion
|
|
77
|
+
GetAtmos B -i raw_data -o output -rp 7856 -tz 10 -ltz AEST
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
**Tidal Data Example:**
|
|
81
|
+
```bash
|
|
82
|
+
# Extract tidal data using a boundary nodestring shapefile
|
|
83
|
+
GetTide output/tide_data.nc 2011-01-01 2012-01-01 boundaries/nodestring.shp path/to/fes2022/
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Python API
|
|
87
|
+
|
|
88
|
+
**Ocean Data:**
|
|
89
|
+
```python
|
|
90
|
+
from tfv_get_tools import DownloadOcean, MergeOcean
|
|
91
|
+
|
|
92
|
+
# Download HYCOM data
|
|
93
|
+
result = DownloadOcean(
|
|
94
|
+
start_date='2011-01-01',
|
|
95
|
+
end_date='2011-02-01',
|
|
96
|
+
xlims=(153, 156),
|
|
97
|
+
ylims=(-29, -24),
|
|
98
|
+
out_path='./raw_data',
|
|
99
|
+
source='HYCOM',
|
|
100
|
+
time_interval=24
|
|
101
|
+
)
|
|
102
|
+
|
|
103
|
+
# Merge downloaded files
|
|
104
|
+
MergeOcean(
|
|
105
|
+
in_path='./raw_data',
|
|
106
|
+
out_path='./output',
|
|
107
|
+
source='HYCOM',
|
|
108
|
+
reproject=28350,
|
|
109
|
+
local_tz=(8, 'AWST')
|
|
110
|
+
)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
**Atmospheric Data:**
|
|
114
|
+
```python
|
|
115
|
+
from tfv_get_tools import DownloadAtmos, MergeAtmos
|
|
116
|
+
|
|
117
|
+
# Download BARRA2 data
|
|
118
|
+
result = DownloadAtmos(
|
|
119
|
+
start_date='2020-01-01',
|
|
120
|
+
end_date='2020-02-01',
|
|
121
|
+
xlims=(152.72, 153.78),
|
|
122
|
+
ylims=(-27.49, -25.39),
|
|
123
|
+
out_path='./raw_data',
|
|
124
|
+
source='BARRA2',
|
|
125
|
+
model='C2'
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
# Merge with reprojection to GDA2020 MGA56
|
|
129
|
+
MergeAtmos(
|
|
130
|
+
in_path='./raw_data',
|
|
131
|
+
out_path='./output',
|
|
132
|
+
source='BARRA2',
|
|
133
|
+
model='C2',
|
|
134
|
+
reproject=7856,
|
|
135
|
+
local_tz=(10.0, 'AEST')
|
|
136
|
+
)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
**Tidal Data:**
|
|
140
|
+
```python
|
|
141
|
+
from pathlib import Path
|
|
142
|
+
from tfv_get_tools.tide import ExtractTide
|
|
143
|
+
|
|
144
|
+
# Basic tidal extraction
|
|
145
|
+
ExtractTide(
|
|
146
|
+
start_date='2011-01-01',
|
|
147
|
+
end_date='2012-01-01',
|
|
148
|
+
filename='tide_data.nc',
|
|
149
|
+
out_path='./output',
|
|
150
|
+
freq='15min',
|
|
151
|
+
shapefile='boundaries/nodestring.shv'
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
# Advanced usage with constituent caching
|
|
155
|
+
from tfv_get_tools.tide import load_nodestring_shapefile, process_nodestring_gdf, get_constituents
|
|
156
|
+
|
|
157
|
+
# Load and process boundary shapefile
|
|
158
|
+
gdf = load_nodestring_shapefile('boundaries/nodestring.shp', process_ids=[1])
|
|
159
|
+
coordinates = process_nodestring_gdf(gdf, spacing=5000)
|
|
160
|
+
|
|
161
|
+
# Extract constituents once (slow first time, fast afterwards)
|
|
162
|
+
constituents = get_constituents(
|
|
163
|
+
coordinates,
|
|
164
|
+
source='FES2022',
|
|
165
|
+
save_cons='boundary_constituents.pkl'
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
# Use cached constituents for faster extraction
|
|
169
|
+
ExtractTide(
|
|
170
|
+
start_date='2011-01-01',
|
|
171
|
+
end_date='2012-01-01',
|
|
172
|
+
filename='tide_data.nc',
|
|
173
|
+
out_path='./output',
|
|
174
|
+
freq='15min',
|
|
175
|
+
constituents='boundary_constituents.pkl'
|
|
176
|
+
)
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Requirements
|
|
180
|
+
|
|
181
|
+
- Python 3.9+
|
|
182
|
+
- Internet connection for data downloads
|
|
183
|
+
- Registration required for some data sources:
|
|
184
|
+
- **ERA5**: [Copernicus Climate Data Store (CDS) API](https://cds.climate.copernicus.eu/api-how-to)
|
|
185
|
+
- **Copernicus Marine**: [Copernicus Marine Service](https://marine.copernicus.eu/)
|
|
186
|
+
- **FES Tidal Models**: [AVISO+](https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html) (for tidal constituent files)
|
|
187
|
+
|
|
188
|
+
## Data Credits and Acknowledgements
|
|
189
|
+
|
|
190
|
+
This package utilises data from multiple authoritative sources. Please ensure appropriate attribution when using this data:
|
|
191
|
+
|
|
192
|
+
### Atmospheric Data
|
|
193
|
+
- **ECMWF ERA5**: Data provided by the [European Centre for Medium-Range Weather Forecasts (ECMWF)](https://www.ecmwf.int/) through the Copernicus Climate Change Service (C3S). Please acknowledge: "Contains modified Copernicus Climate Change Service information [2025]".
|
|
194
|
+
- **NOAA CFSR**: Data provided by the [National Oceanic and Atmospheric Administration (NOAA)](https://www.noaa.gov/) National Centers for Environmental Information.
|
|
195
|
+
- **BARRA2**: Data provided by the [Australian Bureau of Meteorology](http://www.bom.gov.au/).
|
|
196
|
+
|
|
197
|
+
### Ocean Data
|
|
198
|
+
- **HYCOM**: All ocean data is supplied by the [HYCOM consortium](https://www.hycom.org/). Please refer to the [HYCOM data acknowledgement and disclaimer](https://www.hycom.org/publications/acknowledgements/hycom-data).
|
|
199
|
+
- **Copernicus Marine**: Ocean and wave data provided by the [Copernicus Marine Environment Monitoring Service (CMEMS)](https://marine.copernicus.eu/).
|
|
200
|
+
|
|
201
|
+
### Wave Data
|
|
202
|
+
- **CSIRO CAWCR**: Wave data provided by the [Commonwealth Scientific and Industrial Research Organisation (CSIRO)](https://www.csiro.au/) Centre for Australian Weather and Climate Research.
|
|
203
|
+
- **Copernicus Marine**: Wave data provided by the [Copernicus Marine Environment Monitoring Service (CMEMS)](https://marine.copernicus.eu/).
|
|
204
|
+
|
|
205
|
+
### Tidal Data
|
|
206
|
+
- **FES Tidal Models**: Tidal data provided by [AVISO+](https://www.aviso.altimetry.fr/) and the FES development team. FES2014 and FES2022 are products of Noveltis, Legos, and CLS, with support from CNES.
|
|
207
|
+
- **PyTMD**: This package utilises the [PyTMD](https://github.com/tsutterley/pyTMD) Python package for tidal analysis and prediction, developed by Tyler Sutterley.
|
|
208
|
+
|
|
209
|
+
## Support
|
|
210
|
+
|
|
211
|
+
For questions, bug reports, or feature requests:
|
|
212
|
+
- 📧 **Email**: support@tuflow.com
|
|
213
|
+
- 🐛 **Issues**: Submit via the project repository
|
|
214
|
+
- 📖 **Documentation**: [Link to documentation] (if available)
|
|
215
|
+
|
|
216
|
+
## Contributing
|
|
217
|
+
|
|
218
|
+
Contributions are welcome! Please follow these steps:
|
|
219
|
+
|
|
220
|
+
1. Fork the repository
|
|
221
|
+
2. Create a feature branch from `main`
|
|
222
|
+
3. Make your changes with appropriate tests
|
|
223
|
+
4. Submit a pull request
|
|
224
|
+
5. Email support@tuflow.com to notify the development team
|
|
225
|
+
|
|
226
|
+
Please ensure your code follows the project's coding standards and includes appropriate documentation.
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
231
|
+
|
|
232
|
+
## Authors
|
|
233
|
+
|
|
234
|
+
Developed by [BMT](https://www.bmt.org/), 2025
|
|
235
|
+
|
|
236
|
+
## Project Status
|
|
237
|
+
|
|
238
|
+
**Active** - This project is actively maintained and in use. For update requests or feature suggestions, please email support@tuflow.com.
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
*Last updated: July 2025*
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "tfv_get_tools"
|
|
3
|
+
version = "0.2.0"
|
|
4
|
+
description = "Tool for downloading and processing data for TUFLOW FV modelling"
|
|
5
|
+
authors = [
|
|
6
|
+
{ name = "Alex Waterhouse", email = "alex.waterhouse@apac.bmt.org" },
|
|
7
|
+
{ name = "Mitchell Smith", email = "mitchell.smith@apac.bmt.org" },
|
|
8
|
+
{ name = "TUFLOW Support", email = "support@tuflow.com" },
|
|
9
|
+
]
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
readme = "README.md"
|
|
12
|
+
requires-python = ">=3.9,<3.14"
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 3 - Alpha",
|
|
15
|
+
"Intended Audience :: Science/Research",
|
|
16
|
+
"License :: OSI Approved :: MIT License",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.9",
|
|
19
|
+
"Programming Language :: Python :: 3.10",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
]
|
|
24
|
+
dependencies = [
|
|
25
|
+
"netCDF4>=1.6.2",
|
|
26
|
+
"tqdm>=4.65.0",
|
|
27
|
+
"xarray>=2023.1.0",
|
|
28
|
+
"scipy>=1.10.0",
|
|
29
|
+
"pyproj>=3.5.0",
|
|
30
|
+
"siphon>=0.9",
|
|
31
|
+
"cdsapi>=0.7.0",
|
|
32
|
+
"copernicusmarine>=1.2.3",
|
|
33
|
+
"bottleneck>=1.3.5",
|
|
34
|
+
"pyTMD>=2.1.5",
|
|
35
|
+
"shapely >= 2.0.6",
|
|
36
|
+
"geopandas >= 1.0.1",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[project.optional-dependencies]
|
|
40
|
+
dev = [
|
|
41
|
+
"ipython>=8.6.0",
|
|
42
|
+
"notebook>=6.5.2",
|
|
43
|
+
"ipykernel>=6.17.1",
|
|
44
|
+
"dask>=2022.11.0",
|
|
45
|
+
"black>=22.12.0",
|
|
46
|
+
"matplotlib>=3.7.0",
|
|
47
|
+
"sphinx>=7.3.7",
|
|
48
|
+
"recommonmark>=0.7.1",
|
|
49
|
+
"sphinx-markdown-builder>=0.6.6",
|
|
50
|
+
"pyprojroot",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[project.urls]
|
|
54
|
+
Homepage = "https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools"
|
|
55
|
+
Repository = "https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools"
|
|
56
|
+
Issues = "https://gitlab.com/tuflow-user-group/tuflow-fv/data-pre-processing/tfv-get-tools/issues"
|
|
57
|
+
|
|
58
|
+
[build-system]
|
|
59
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
60
|
+
build-backend = "setuptools.build_meta"
|
|
61
|
+
|
|
62
|
+
[project.scripts]
|
|
63
|
+
GetAtmos = "tfv_get_tools.cli.atmos_cli:entry"
|
|
64
|
+
GetOcean = "tfv_get_tools.cli.ocean_cli:entry"
|
|
65
|
+
GetWave = "tfv_get_tools.cli.wave_cli:entry"
|
|
66
|
+
GetTide = "tfv_get_tools.cli.tide_cli:entry"
|
|
67
|
+
|
|
68
|
+
[tool.setuptools.packages.find]
|
|
69
|
+
where = ["src"]
|
|
70
|
+
|
|
71
|
+
[tool.setuptools.package-data]
|
|
72
|
+
tfv_get_tools = ["**/*.yaml", "**/*.yml"]
|
|
73
|
+
|
|
74
|
+
[tool.black]
|
|
75
|
+
line-length = 88
|
|
76
|
+
target-version = ['py39']
|
|
77
|
+
include = '\.pyi?$'
|