Methods

DriftCast methods

This page documents the operational data flow used by DriftCast: where each dataset originates, how a requested time window is selected, how trajectories and wave spectra are calculated, and how the published products are displayed. All times are UTC.

Because this file lives in the site’s content directory, it is also a normal Markdown note in the Obsidian vault and can be edited there.

System overview

DriftCast has three main parts:

1. The advisor site submits virtual-trajectory and live-buoy requests to the buoy-case-api Cloudflare Worker.
2. Requests and completed web products are exchanged through the drift-data Cloudflare R2 bucket.
3. Yuki downloads or reads the required environmental data, calculates trajectories and spectra, writes versioned JSON/GeoJSON products, and publishes them to R2.

The browser only plots published products. It does not calculate trajectories or reconstruct directional spectra itself.

R2 organization

Product	R2 key
Pending virtual cases	requests/pending/<case-id>.json
Processing, completed, or failed cases	requests/<status>/<case-id>.json
Public trajectory index	trajectories/index.json
Trajectory metadata	trajectories/runs/<trajectory-id>/metadata.json
Trajectory geometry	trajectories/runs/<trajectory-id>/trajectory.geojson
Sampled forcing	trajectories/runs/<trajectory-id>/forcing_timeseries.json
Gridded forcing for map overlays	trajectories/runs/<trajectory-id>/forcing_fields.json
Live-buoy index	live_buoy_tracking/north_pacific/index.json
Live-buoy observations and embedded spectra	live_buoy_tracking/north_pacific/buoys/<buoy-id>/observations.json
Basin ECMWF plotting snapshot	live_buoy_tracking/north_pacific/wind.json
Basin current and wave snapshots	live_buoy_tracking/north_pacific/currents.json and waves.json

Virtual-case selection

A case specifies a release latitude, longitude, UTC start time, duration, and wind source. Durations must be whole hours between 1 and 120 hours. The requested interval must lie inside the published availability of every required forcing component unless partial output is explicitly allowed.

When a case is edited, its case ID is retained and its revision is incremented. Yuki replaces that case’s published trajectory variants after the new calculation finishes. Completed cases are reconciled with trajectory IDs of the form trj_request_<case-id>_<forcing-variant>.

The availability graphic is derived from the actual temporal extents of the source files. Selecting ECMWF or Copernicus changes the wind interval shown in that graphic. A named variable is not treated as available unless the published product contains finite values for it.

Environmental forcing

Ocean currents

Ocean-current velocity comes from the Copernicus Marine global physics analysis and forecast product GLOBAL_ANALYSISFORECAST_PHY_001_024, dataset cmems_mod_glo_phy_anfc_merged-uv_PT1H-i.

The required source variables are:

• uo: eastward current, normalized to u_current in m s⁻¹
• vo: northward current, normalized to v_current in m s⁻¹

Waves and Stokes drift

Wave forcing comes from Copernicus Marine product GLOBAL_ANALYSISFORECAST_WAV_001_027, dataset cmems_mod_glo_wav_anfc_0.083deg_PT3H-i.

The downloaded variables are:

• VSDX and VSDY: eastward and northward surface Stokes drift
• VHM0: significant wave height
• VMDR: mean wave direction
• VTM10: mean wave period
• VTPK: peak wave period

Only VSDX and VSDY affect the Stokes-enabled trajectory. The remaining variables are published for context and plotting.

Atmospheric wind

Each request selects ecmwf or copernicus in request.forcing.wind_source. If the field is absent in a legacy request, Yuki currently defaults to ECMWF.

ECMWF wind is built from archived IFS operational forecast GRIB files. The required 10 m components are u10 and v10, normalized as:

• eastward_wind, m s⁻¹
• northward_wind, m s⁻¹

Accumulated ewss and nsss, when present, are differenced over their forecast interval and normalized as eastward and northward stress in N m⁻². Stress is optional and does not enter the windage calculation.

Yuki’s current ECMWF integration input is:

data/processed/ecmwf/wind_forecast/latest/ecmwf_wind_pacific_basin_latest.nc

The Copernicus alternative uses the global near-real-time wind product WIND_GLO_PHY_L4_NRT_012_004, dataset cmems_obs-wind_glo_phy_nrt_l4_0.125deg_PT1H, from Yuki’s data/raw/copernicus/wind_stress/wind_stress_*.nc files.

The basin-level R2 wind.json object is a plotting snapshot. The trajectory calculation uses the selected NetCDF source on Yuki, after which sampled and gridded results are published with the trajectory.

Trajectory calculation

DriftCast publishes three forcing variants when their inputs are available:

Variant	Horizontal velocity
Current	surface ocean current
Current + Stokes	surface current + surface Stokes drift
Current + Stokes + windage	surface current + Stokes drift + windage

Windage is calculated component-by-component using a fixed Spotter slip fraction of 0.012:

$$u_{windage}=0.012u_{10},v_{windage}=0.012v_{10}.$$

The full velocity is therefore

$${\mathbf{u}}_{trajectory}={\mathbf{u}}_{current}+{\mathbf{u}}_{Stokes}+0.012{\mathbf{u}}_{10}.$$

Positions are advanced with an Euler-forward integration. The current operational output interval is 60 minutes. Source values are sampled with nearest-neighbor time and horizontal-grid selection. Longitudes are normalized to the Pacific-domain convention before sampling.

If the requested time lies outside a required source extent, the nearest source cell is masked, or the point leaves the source domain, that component is marked missing. A variant may consequently be published as partial and terminate at its last valid point. A zero-length windage trajectory means no valid wind existed at its release time; it is not interpreted as a stationary windage result.

Live-buoy observations

Live observations originate from public Sofar Spotter records. Published observations include time, latitude, longitude, available bulk-wave values, and available wind values. A moored buoy retains its complete time series even though DriftCast does not draw its small GPS scatter as a drifting trajectory.

For a requested history window, the product records both the requested range and the range actually available. If only a subset is valid, the returned notification states both intervals and the browser displays only the published subset. Buoy-specific display limits can be applied when the source contains records outside a verified deployment interval. For example, the currently verified Suruga Bay directional-spectrum interval is August 6–9, 2026.

Directional wave spectra

When a Spotter observation contains frequency bins, bin widths, variance density, and Fourier directional coefficients (a1, b1, a2, and b2), Yuki reconstructs directional spectra using two methods:

• truncated Fourier reconstruction
• maximum entropy method (MEM)

The published product contains the one-dimensional variance-density spectrum, a 5° directional grid, and a frequency-by-direction power matrix for each method. The browser does not interpolate spectra between observations.

For live buoys, the main time slider contains only timestamps with a valid directional spectrum. The small previous and next controls step through every raw observation; a raw observation without a spectrum displays an explicit unavailable message.

The 1D plot uses logarithmic frequency and power axes. The 2D polar plot uses coming-from direction azimuthally and a logarithmic frequency radius. Spectral power and all environmental raster variables use the sequential BuPu color map.

Map overlays

Map-layer choices are built from the selected trajectory’s sampled and gridded forcing products. Vector layers are offered for currents, Stokes drift, wind, wind stress, and directional wave quantities when their required component variables contain finite values. Unavailable layers remain disabled rather than opening an empty overlay.

For an ECMWF trajectory, atmospheric overlays are taken from the ECMWF product; for a Copernicus trajectory, only the Copernicus atmospheric field is offered. A trajectory calculated with one wind source cannot plot the other source as its case wind field.

Interpretation and limitations

• Forecast skill is limited by the source models, their update cadence, and their spatial resolution.
• Nearest-neighbor sampling does not resolve sub-grid coastal structure.
• Nearshore masked cells can stop otherwise valid trajectories.
• The 1.2% windage coefficient is a fixed operational assumption, not an object-specific calibration.
• A moored buoy’s GPS scatter should not be interpreted as modeled drift.
• Partial publication means at least one requested variant or interval lacked forcing; the completed variants remain valid within their reported coverage.

This note should be updated whenever a source dataset, coefficient, interpolation method, output cadence, or R2 product contract changes.