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.
Files changed (74) hide show
  1. tfv_get_tools-0.2.0/PKG-INFO +286 -0
  2. tfv_get_tools-0.2.0/README.md +242 -0
  3. tfv_get_tools-0.2.0/pyproject.toml +77 -0
  4. tfv_get_tools-0.2.0/setup.cfg +4 -0
  5. tfv_get_tools-0.2.0/src/tfv_get_tools/__init__.py +4 -0
  6. tfv_get_tools-0.2.0/src/tfv_get_tools/_standard_attrs.py +107 -0
  7. tfv_get_tools-0.2.0/src/tfv_get_tools/atmos.py +167 -0
  8. tfv_get_tools-0.2.0/src/tfv_get_tools/cli/_cli_base.py +173 -0
  9. tfv_get_tools-0.2.0/src/tfv_get_tools/cli/atmos_cli.py +192 -0
  10. tfv_get_tools-0.2.0/src/tfv_get_tools/cli/ocean_cli.py +204 -0
  11. tfv_get_tools-0.2.0/src/tfv_get_tools/cli/tide_cli.py +118 -0
  12. tfv_get_tools-0.2.0/src/tfv_get_tools/cli/wave_cli.py +183 -0
  13. tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/__init__.py +3 -0
  14. tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/_atmos.py +230 -0
  15. tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/_fvc.py +218 -0
  16. tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/_ocean.py +171 -0
  17. tfv_get_tools-0.2.0/src/tfv_get_tools/fvc/_tide.py +195 -0
  18. tfv_get_tools-0.2.0/src/tfv_get_tools/ocean.py +170 -0
  19. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/__init__.py +0 -0
  20. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/_custom_conversions.py +34 -0
  21. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/_downloader.py +566 -0
  22. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/_merger.py +520 -0
  23. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/_utilities.py +255 -0
  24. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/barra2.py +209 -0
  25. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/barra2_c2.yaml +52 -0
  26. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/barra2_r2.yaml +85 -0
  27. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/barra2_re2.yaml +70 -0
  28. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/cfsr.yaml +68 -0
  29. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/era5.yaml +77 -0
  30. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfgs/era5_gcp.yaml +77 -0
  31. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/cfsr.py +207 -0
  32. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/era5.py +20 -0
  33. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/atmos/era5_gcp.py +20 -0
  34. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/cfgs/copernicus_blk.yaml +64 -0
  35. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/cfgs/copernicus_glo.yaml +67 -0
  36. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/cfgs/copernicus_nws.yaml +62 -0
  37. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/cfgs/hycom.yaml +73 -0
  38. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/copernicus_ocean.py +457 -0
  39. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/ocean/hycom.py +611 -0
  40. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cawcr.py +166 -0
  41. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_aus_10m.yaml +39 -0
  42. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_aus_4m.yaml +39 -0
  43. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_glob_24m.yaml +39 -0
  44. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_pac_10m.yaml +39 -0
  45. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/cawcr_pac_4m.yaml +39 -0
  46. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/copernicus_glo.yaml +56 -0
  47. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/copernicus_nws.yaml +51 -0
  48. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/era5.yaml +48 -0
  49. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/cfgs/era5_gcp.yaml +48 -0
  50. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/copernicus_wave.py +38 -0
  51. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/era5.py +232 -0
  52. tfv_get_tools-0.2.0/src/tfv_get_tools/providers/wave/era5_gcp.py +169 -0
  53. tfv_get_tools-0.2.0/src/tfv_get_tools/tide/__init__.py +2 -0
  54. tfv_get_tools-0.2.0/src/tfv_get_tools/tide/_nodestring.py +214 -0
  55. tfv_get_tools-0.2.0/src/tfv_get_tools/tide/_tidal_base.py +568 -0
  56. tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/_tfv_bc.py +78 -0
  57. tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/horizontal_padding.py +89 -0
  58. tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/land_masking.py +93 -0
  59. tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/parsers.py +44 -0
  60. tfv_get_tools-0.2.0/src/tfv_get_tools/utilities/warnings.py +38 -0
  61. tfv_get_tools-0.2.0/src/tfv_get_tools/wave.py +179 -0
  62. tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/PKG-INFO +286 -0
  63. tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/SOURCES.txt +72 -0
  64. tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/dependency_links.txt +1 -0
  65. tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/entry_points.txt +5 -0
  66. tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/requires.txt +24 -0
  67. tfv_get_tools-0.2.0/src/tfv_get_tools.egg-info/top_level.txt +1 -0
  68. tfv_get_tools-0.2.0/tests/test_all_downloaders.py +215 -0
  69. tfv_get_tools-0.2.0/tests/test_cli_get_atmos.py +369 -0
  70. tfv_get_tools-0.2.0/tests/test_downloader.py +182 -0
  71. tfv_get_tools-0.2.0/tests/test_era5_merger.py +618 -0
  72. tfv_get_tools-0.2.0/tests/test_frontend_python_api.py +402 -0
  73. tfv_get_tools-0.2.0/tests/test_mergers.py +495 -0
  74. 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
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
52
+ [![Project Status: Active](https://img.shields.io/badge/Project%20Status-Active-green.svg)](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
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
+ [![Project Status: Active](https://img.shields.io/badge/Project%20Status-Active-green.svg)](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?$'
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ from tfv_get_tools.ocean import DownloadOcean, MergeOcean
2
+ from tfv_get_tools.wave import DownloadWave, MergeWave
3
+ from tfv_get_tools.atmos import DownloadAtmos, MergeAtmos
4
+ from tfv_get_tools.tide._tidal_base import ExtractTide