Data Access¶
The hindcast data is available through three interfaces depending on your workflow.
Marine Energy Atlas¶
The Marine Energy Atlas provides a point-and-click interface for exploring time- and depth-averaged current speed and power density across all five hindcast domains. Use it for initial site screening before downloading time series data.
See the Atlas guide for usage instructions.
Python Library and CLI¶
The us-marine-energy-resource Python library (which includes the us-tidal CLI) can query tidal hindcast data by point, transect, or area, with built-in tools to visualize and analyze the results.
Install¶
uv (faster resolver, recommended):
pip (may be slow — pip’s dependency resolver backtracks extensively on this package’s transitive dependencies):
Python Quick Start¶
import us_marine_energy_resource.tidal_hindcast as tidal
# Fetch the full hindcast time series for the nearest grid point.
# Data is downloaded from S3 and cached locally on first call.
df = tidal.get_data_at_point(lat=60.73, lon=-151.43)
# Plot velocity exceedance curves across all depth layers.
fig, stats = tidal.plot_velocity_exceedance(df)
# Plot the joint probability distribution at a single depth layer.
fig = tidal.generate_tidal_joint_probability(df, sigma_layer=4)
us-tidal CLI Reference¶
The us-tidal command line tool is included with the library install. It supports point, transect, bounding box, and polygon queries without writing Python.
Usage: us-tidal [OPTIONS] [LOCATION]
Query and download modeled tidal current data from the U.S. DOE H2O High Resolution Tidal Hindcast — FVCOM simulations
covering five U.S. coastal regions: Cook Inlet AK, Aleutian Islands AK, Salish Sea WA, Piscataqua River NH, and
Western Passage ME.
A point query returns the mesh face containing the coordinate. Area and transect queries return all faces whose
triangles geometrically intersect the specified geometry. Each matched face downloads as a full-year, hourly or
half-hourly time series of current speed, direction, and kinetic power density at 10 depth layers (sea surface to
seafloor).
Dataset citation: https://mhkdr.openei.org/submissions/632
Documentation: https://github.com/US-Marine-Energy-Resource/us-marine-energy-resource-python
AWS S3 browser: https://data.openei.org/s3_viewer?bucket=marine-energy-data&prefix=us-tidal%2F
Provide exactly one geometry input: a positional lat,lon for
a point query, or one of --coord, --bbox, --file,
or --wkt for area queries.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ location [LOCATION] Point as lat,lon (e.g. 60.73,-151.43). │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --coord -c TEXT Transect waypoint as lat,lon. Repeat for multi-segment lines. │
│ --bbox TEXT Bounding box as lat_min,lon_min,lat_max,lon_max. │
│ --file -f PATH Polygon from a GeoJSON file. Draw one at https://geojson.io/next/. │
│ --wkt TEXT Polygon as a WKT POLYGON string or path to a .wkt file. │
│ --output-dir -o PATH Copy downloaded parquet files to this directory. │
│ --csv Export downloaded data as CSV files. Written to --output-dir if set, otherwise │
│ to the current directory. │
│ --dry-run Show size estimate without downloading. │
│ --max-size-mb FLOAT Abort if uncached data to download exceeds this limit (MB). 0 = no limit. │
│ [env var: US_TIDAL_MAX_SIZE_MB] │
│ [default: 500.0] │
│ --max-distance-km FLOAT Reject if nearest face is farther than this (km). Point queries only. │
│ --config PATH Path to config file (default: ~/.us_tidal.toml). │
│ --aws-profile TEXT Override AWS profile from config. │
│ --cache-dir PATH Override local cache directory from config. │
│ --use-hpc Use HPC local filesystem instead of S3. │
│ --hpc-base-path TEXT Override HPC dataset root path from config. │
│ --clear-cache Clear the local cache before running. │
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or customize the │
│ installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Dataset Info ───────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --info Show dataset metadata, schema, and statistics without downloading. Reads only the │
│ parquet footer (fast range requests). │
│ --info-speed Show speed category info only (implies --info). │
│ --info-direction Show direction category info only (implies --info). │
│ --info-power Show power density category info only (implies --info). │
│ --info-depth Show depth/water-level category info only (implies --info). │
│ --layer INTEGER Sigma layer for --info statistics (0=surface, 9=near-bed). Repeat to select │
│ multiple layers. │
│ --depth FLOAT Select the sigma layer nearest to this depth (m from surface) for --info │
│ statistics. Approximate — uses footer depth stats. │
│ --depth-avg Average --info statistics across all sigma layers. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Examples
us-tidal 60.73,-151.43 Point query
us-tidal --coord 60.7,-151.4 --coord 60.9,-151.2 Transect
us-tidal --bbox 60.7,-151.5,60.9,-151.2 Bounding box
us-tidal --file study_area.geojson Polygon from file
us-tidal --wkt "POLYGON((-151.5 60.7,...))" Polygon from WKT
us-tidal 60.73,-151.43 --dry-run Size estimate
us-tidal 60.73,-151.43 --info Dataset info (no download)
us-tidal 60.73,-151.43 --info-speed Speed category only
us-tidal 60.73,-151.43 --info --layer 3 Layer 3 stats
us-tidal 60.73,-151.43 --info --depth 15.0 Layer nearest 15 m
us-tidal 60.73,-151.43 --info --depth-avg Average all layers
us-tidal --bbox 60.7,-151.5,60.9,-151.2 --info Aggregate area info
us-tidal 60.73,-151.43 --output-dir ./data Save parquet files
us-tidal 60.73,-151.43 --csv Export CSV to current dir
us-tidal 60.73,-151.43 --csv --output-dir ./data Export CSV to ./data
Config file (~/.us_tidal.toml) sets defaults for AWS, cache, and HPC options.
Point Query¶
mer tidal accepts a positional lat,lon argument. Start with
--dry-run to check the size before committing to a download.
face_id 00126601
location AK_cook_inlet
latitude 60.7298317
longitude -151.4297485
distance 0.00 km (containing cell)
file AK_cook_inlet/v1.0.0/b1_vap_by_point_partition/lat_deg=60/lon_deg=…
s3 s3://marine-energy-data/us-tidal/AK_cook_inlet/v1.0.0/b1_vap_by_po…
url https://marine-energy-data.s3.us-west-2.amazonaws.com/us-tidal/AK_…
Files matched 1
Total size 3.6 MB
Already cached 3.6 MB
To download 0.0 MB
On first run the file is fetched from S3. Subsequent calls read from the local cache with no network traffic.
#### Area Query
`--bbox` takes `lat_min,lon_min,lat_max,lon_max`. Use `--dry-run` first
because bbox queries can match thousands of faces.
``` bash
mer tidal --bbox 60.725,-151.445,60.735,-151.425 --dry-run
Matched 103 faces · AK_cook_inlet
face_id location lat lon dist_km
────────────────────────────────────────────────────────────
00127584 AK_cook_inlet 60.72406 -151.4444 0.0
00126347 AK_cook_inlet 60.73291 -151.43512 0.0
00127215 AK_cook_inlet 60.72453 -151.42508 0.0
00127216 AK_cook_inlet 60.72458 -151.42688 0.0
00127220 AK_cook_inlet 60.72469 -151.43073 0.0
00127219 AK_cook_inlet 60.72481 -151.43262 0.0
00127383 AK_cook_inlet 60.72487 -151.43976 0.0
00127585 AK_cook_inlet 60.7249 -151.4458 0.0
00127382 AK_cook_inlet 60.72509 -151.44177 0.0
00127380 AK_cook_inlet 60.72521 -151.43649 0.0
00127007 AK_cook_inlet 60.72524 -151.42371 0.0
00127217 AK_cook_inlet 60.72542 -151.42734 0.0
00127381 AK_cook_inlet 60.72544 -151.43842 0.0
00127218 AK_cook_inlet 60.72548 -151.42923 0.0
00127200 AK_cook_inlet 60.7257 -151.43311 0.0
00127201 AK_cook_inlet 60.72588 -151.43506 0.0
00127384 AK_cook_inlet 60.7259 -151.4422 0.0
00127006 AK_cook_inlet 60.7261 -151.42401 0.0
00127387 AK_cook_inlet 60.72612 -151.44556 0.0
00127008 AK_cook_inlet 60.72623 -151.42584 0.0
… and 83 more
Files matched 103
Total size ~367.3 MB
Already cached 3.6 MB
To download ~363.7 MB
#### Transect Query
`--coord` defines a waypoint. Repeat it to build a multi-segment path.
All faces whose triangles geometrically intersect the path are returned.
``` bash
mer tidal --coord 60.72,-151.43 --coord 60.75,-151.44 --dry-run
Matched 39 faces · AK_cook_inlet
face_id location lat lon dist_km
────────────────────────────────────────────────────────────
00127818 AK_cook_inlet 60.72053 -151.43036 0.0
00127621 AK_cook_inlet 60.72163 -151.43011 0.0
00127622 AK_cook_inlet 60.72207 -151.43176 0.0
00127423 AK_cook_inlet 60.72301 -151.43188 0.0
00127422 AK_cook_inlet 60.72375 -151.43024 0.0
00127220 AK_cook_inlet 60.72469 -151.43073 0.0
00127219 AK_cook_inlet 60.72481 -151.43262 0.0
00127200 AK_cook_inlet 60.7257 -151.43311 0.0
00127012 AK_cook_inlet 60.72645 -151.43164 0.0
00126992 AK_cook_inlet 60.72733 -151.43219 0.0
00126807 AK_cook_inlet 60.72812 -151.43073 0.0
00126788 AK_cook_inlet 60.72897 -151.43127 0.0
00126787 AK_cook_inlet 60.72909 -151.43335 0.0
00126764 AK_cook_inlet 60.73 -151.43396 0.0
00126581 AK_cook_inlet 60.73064 -151.43268 0.0
00126558 AK_cook_inlet 60.73155 -151.43317 0.0
00126557 AK_cook_inlet 60.7319 -151.43494 0.0
00126345 AK_cook_inlet 60.73349 -151.43335 0.0
00126347 AK_cook_inlet 60.73291 -151.43512 0.0
00126128 AK_cook_inlet 60.7345 -151.43329 0.0
… and 19 more
Files matched 39
Total size ~139.1 MB
Already cached 0.0 MB
To download ~139.1 MB
``` bash
Export Options¶
``` bash
Direct API Downloads¶
Tidal hindcast data is accessible via multiple functions that can be
used independently of the plotting functions. This allows users to
access the underlying data at specific points, along lines, or within
rectangular areas. This downloads data to a local cache directory and
returns the path to the downloaded files, which can be loaded and
analyzed with the load_parquet and prepare_dataframe functions in
the analysis module.
tidal._state is initialized lazily on the first get_data_at_point()
call; call that once to populate the shared cache and manifest before
accessing _state directly.
``` python from us_marine_energy_resource import tidal_hindcast as tidal from us_marine_energy_resource.analysis import load_parquet, prepare_dataframe
For full documentation see the library README.
Bulk Access (HSDS and AWS S3)¶
For bulk downloads or programmatic access to the raw parquet files, the data is available via HSDS and AWS S3.
Dataset citation: [@mhkdr_tidal_hindcast_submission]