Fix the phase of eight TICON constituents

[clarkbw]

TICON-4 phases eight constituents against a different equilibrium argument than the engine's, so the engine predicts them at the wrong phase. The importer now converts them, and datums are re-synthesized to match.

Each offset comes from scoring TICON's constituent against the raw GESLA-4 record at its largest gauges, with the published phase shifted by 0°, +90°, −90° and 180°. +1 is a match, −1 unrelated, −3 anti-phase.

Constituent	TICON argument − engine argument	Gauges agreeing	Largest amplitude
M3	180°	8 of 8	10.8 cm (Thevenard)
SGM (sigma1)	180°	8 of 8	4.1 cm (Anchorage)
T3	180°	7 of 8	5.0 cm (Ashland Ave)
S3	180°	17 of 20	17.5 cm (Ashland Ave)
R3	−90°	7 of 8	13.9 cm (Ashland Ave)
3L2	−90°	20 of 20	19.5 cm (Spencers Island)
2MK5	−90°	8 of 8	6.2 cm (Anchorage)
2MO5	+90°	8 of 8	3.8 cm (Puerto Madryn)

Most of the gauges that disagree are river gauges (Hedel, Gorinchem) that score near −1 at every offset. The exception is S3 at L'Isle-aux-Grues in the St. Lawrence estuary, which scores 0.66 at 0°. After conversion, every constituent scores best at 0° at its top gauges, apart from the same river gauges. S1, P1, T2, R2, S4, RHO1, 2SM2, 2MS6, 3N2 and MKS2 already score best at 0°, so they need no conversion.

Six of the eight are among the ten constituents new in TICON-4; M3 and S3 are not. The conversion happens at import (TICON_ARGUMENT_OFFSET in sources/ticon/import.ts), so the engine's IHO definitions stay as they are. NOAA's phases for M3, sigma1, 2MK5 and 2MO5 already match those definitions. The re-fit wsv and rws stations are fit against the engine's arguments and are unchanged. The TICON README has the table and the method.

Datums. The importer reused cached datums even when a station's constituents changed. HAT, LAT, LLWLT and the other harmonic datums come from synthesis, so they went stale. The importer now re-synthesizes those whenever the constituents differ from the cached file, and keeps the observed means (MHHW through MLLW), which come from the record. Re-synthesis moves HAT, LAT or LLWLT by 1 cm or more at about 2,400 stations, and by up to 39 cm (LAT at Ashland Ave).

Re-synthesis also picks up engine changes made since the datums were cached. About 120 stations move 1 cm or more beyond what the phase conversion explains. At Aiguillon-sur-Mer, LAT moves 15 cm and the phases account for 7 cm; the rest comes from the 3N2 and MKS2 lines moving in openwatersio/slackwater#365. Aiguillon has 13.5 cm of 3N2 and 5.2 cm of MKS2. One near-tideless lake gauge, Tecumseh (Lake St. Clair), had an LLWLT half a metre below MSL and now has one above it. Its tides are under a centimetre, so both values are artifacts. It joins the 19 TICON stations whose datums are already out of order on main (LAT above MLLW, HAT below MHHW, or LLWLT above MLLW), which need a separate fix.

quality.json changes only in warning text; no station changes score or acceptance.

• All 4,640 stations change only the eight phases and the synthesized datums; observed means and all other fields are unchanged
• Re-scored after conversion: every constituent scores best at 0°
• npm test (including the station tests), npm run validate:database, npm run lint, npm run test -w swift
• Release the database

Closes #239

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@slackwater/database@249

commit: db454d6

[Copilot]

🔵 Needs a closer look

Cached harmonic-only datums can survive when a new synthesis omits them.

0 open findings

What changed in this PR

Corrects eight TICON constituent phases and regenerates dependent harmonic datums.

Changes:

• Applies constituent-specific phase offsets during import.
• Re-synthesizes cached harmonic datums when constituents change.
• Regenerates 4,640 stations and quality warnings.

File	Description
sources/​ticon/​import.ts	Adds phase conversion and datum refresh logic.
sources/​ticon/​README.md	Documents offsets and validation method.
data/​ticon/​*.json (4,640 files)	Updates phases and synthesized datums.
quality.json	Refreshes resulting warning text.

🧠 Review effort: Balanced

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

[clarkbw]

you don't have to review, the only the question i have here for @bkeepers is this

Datums. The importer reused cached datums even when a station's constituents changed. HAT, LAT, LLWLT and the other harmonic datums come from synthesis, so they went stale. The importer now re-synthesizes those whenever the constituents differ from the cached file, and keeps the observed means (MHHW through MLLW), which come from the record. Re-synthesis moves HAT, LAT or LLWLT by 1 cm or more at about 2,400 stations, and by up to 39 cm (LAT at Ashland Ave).

Re-synthesis also picks up engine changes made since the datums were cached. About 120 stations move 1 cm or more beyond what the phase conversion explains. At Aiguillon-sur-Mer, LAT moves 15 cm and the phases account for 7 cm; the rest comes from the 3N2 and MKS2 lines moving in openwatersio/slackwater#365. Aiguillon has 13.5 cm of 3N2 and 5.2 cm of MKS2. One near-tideless lake gauge, Tecumseh (Lake St. Clair), had an LLWLT half a metre below MSL and now has one above it. Its tides are under a centimetre, so both values are artifacts. It joins the 19 TICON stations whose datums are already out of order on main (LAT above MLLW, HAT below MHHW, or LLWLT above MLLW), which need a separate fix.

[bkeepers]

What's the question there?

[clarkbw]

What's the question there?

The datum question is really three decisions bundled into a phase fix:

1. Scope: the PR changes datums far beyond what the title says. The phase conversion explains the move at most of the ~2,400 stations, but re-synthesis also picks up every engine change since the datums were cached — about 120 stations move ≥1 cm for reasons unrelated to Several TICON constituents are predicted at the wrong phase #239 (e.g. the 3N2/MKS2 line changes from slackwater#365; Aiguillon’s LAT moves 15 cm, of which phases explain 7). The question to bkeepers is whether a “fix eight phases” PR should also quietly refresh HAT/LAT/LLWLT against a newer engine, or whether re-synthesis belongs in its own data PR so the diff reviewer can attribute every move.
2. Frame mixing is now explicit. For datums_source: observed stations the importer keeps the observed means (MHHW…MLLW, from the record) and re-synthesizes only the harmonic extremes and chart datums, shifted into the observed MSL frame. That’s the pre-existing design, not new, but this PR is the first time the two halves can be computed at different times from different engines. Worth him confirming that’s the intended contract.
3. Known-bad values ship. Tecumseh (Lake St. Clair, sub-centimetre tides) flips its LLWLT from half a metre below MSL to above it — both artifacts — and joins 19 TICON stations already out of order on main (LAT above MLLW, HAT below MHHW, or LLWLT above MLLW). Nothing in CI gates that: validate-datums is a NOAA cross-check tool, not a CI step, and there’s no issue tracking those 20. The question is whether to merge with a follow-up filed, or hold