English units by default, with a metric toggle

[abkfenris]

(from #38) Needs the
agreed conversion table before it can be built — at minimum °C→°F, m→ft,
m s⁻¹→kt, and a decision on barometric pressure. Also: does the tooltip
show both units at once (as the old tool did) or only the selected one,
and does the data table and its CSV download follow the toggle or stay
metric?

[abkfenris]

Use the same conversions as the Mariner's dashboard supports, which are here: https://github.com/gulfofmaine/Neracoos-1-Buoy-App/tree/main/src/Features/Units

[abkfenris]

Findings and a plan

I went through the app and transcribed the Mariner's Dashboard conversion table from
src/Features/Units,
then prototyped the Python side against pint to check the numbers. Summary: the
conversion table is small and fully recoverable from the dashboard, pint is a good fit
for the math but not for the dataframe plumbing, and three of the four open questions
in this issue have a defensible default. One of them (the tooltip) is gated on #137.

---

1. How the dashboard actually does it

DataTypeConversion is keyed on CF standard name, with the source unit hardcoded per
entry, and dispatches to convert-units.
Default is UnitSystem.english (types.ts), so "English by default" matches the dashboard.
Roughly 100 standard names are registered; ~45 are Passthrough. The ones that actually
convert:

Dashboard class	Source → Metric / English	Standard names
Temperature	C → C / F	air_temperature, dew_point_temperature, sea_surface_temperature, sea_water_temperature
WindSpeed	m/s → m/s / knot	wind_speed, wind_speed_sc, wind_speed_ve, wind_speed_of_gust, eastward_wind, northward_wind
WindSpeedKnots	knot → m/s / knot	wind_speed_knots, wind_speed_of_gust_knots
CmsVelocity	cm/s → m/s / knot	sea_water_speed, sea_water_velocity, eastward_sea_water_velocity, northward_sea_water_velocity, wind_gust, wind_min, wind_peak
WaveHeight	m → m / ft	significant_wave_height, significant_height_of_wind_and_swell_waves(_3), sea_surface_wave_significant_height, max_wave_height, sea_water_level, surface_altitude, predicted_sea_water_level
TidalLevel	m → m / ft	sea_surface_height_above_geopotential_datum, tidal_sea_surface_height_above_mean_{higher_high_water,lower_low_water,sea_level}
AirPressureHpa	hPa → hPa / psi	barometric_pressure, air_pressure_at_sea_level, sea_level_pressure, tendency_of_air_pressure
AirPressure (bespoke)	mbar → hPa / inHg	air_pressure
Visibility	m → km / nMi	visibility_in_air, min_visibility, max_visibility
CardinalDirection	degrees → degrees / compass string	wind_from_direction, wind_direction_kvh, mean_wave_direction, sea_surface_wave_{from,to}_direction

Five things in there are worth deciding on rather than copying:

1. Pressure is internally inconsistent. air_pressure → inHg; the other four pressure
   standard names → psi. Since Clean up items v.2 Climatology #38's worked example is
   A01 Barometric Pressure,
   this is exactly the variable the decision lands on.
2. wind_gust / wind_min / wind_peak are treated as cm/s (CmsVelocity divides by
   100). Plausible for the specific ERDDAP variables behind them, but it's a hardcoded
   source unit that nothing validates.
3. Metric visibility is km, not the source m — so "metric" isn't a no-op there.
4. CardinalDirection returns a string in English mode. Fine for a dashboard readout,
   unusable as a chart value or a climatology mean.
5. pressure_tendency is a Passthrough with unit "degrees" while
   tendency_of_air_pressure converts as an absolute pressure. Neither is obviously right.

---

2. Library options

Buoy Barn hands us the real ERDDAP unit string on every reading
(ts["data_type"]["units"], e.g. degree_C), which the dashboard throws away in favour of
its hardcoded per-class source. Using it is strictly better: WindSpeed / WindSpeedKnots
/ CmsVelocity collapse into one entry, and a mismatch becomes a caught
DimensionalityError instead of a silently wrong plot.

Recommended — pint for the math, plain float64 in the frames.

pint's default registry does not parse the strings ERDDAP emits. I checked, on pint
0.25.3:

'degree_C'  -> UndefinedUnitError
'm s-1'     -> TypeError (a parser crash, not a clean error)
'psu'       -> UndefinedUnitError

cf_xarray.units exists for
exactly this — it registers a pint registry with UDUNITS/CF aliases. With it, m s-1,
m.s-1, psu, S m-1, W m-2, kg m-3, umol kg-1 all parse. It still misses
degree_C (it defines degC but not the CF spelling), so we need two @alias lines. That
was the whole gap:

import cf_xarray.units
ureg = cf_xarray.units.units
ureg.define("@alias degree_Celsius = degree_C = degrees_C")
ureg.define("@alias degree_Fahrenheit = degree_F = degrees_F")

Verified output from the prototype (rounded to 2dp, as the page already does):

standard_name	source	English	Metric
air_temperature	degree_C	[32.0, 50.0, 70.7] °F	[0.0, 10.0, 21.5] °C
wind_speed	m s-1	[1.94, 19.44] kn	[1.0, 10.0] m/s
significant_height_of_wind_and_swell_waves	m	[3.28, 8.2] ft	[1.0, 2.5] m
barometric_pressure	hPa	[29.92, 28.94] inHg	[1013.25, 980.0] hPa
visibility_in_air	m	[1.0, 5.4] nmi	[1.85, 10.0] km
sea_water_salinity	psu	[32.1] psu	[32.1] psu
turbidity	ntu (unparseable)	[3.0] ntu	[3.0] ntu

pint also gets us short-form labels for free (f"{units:~P}" → °F, kn, ft, inHg),
and delta_degC if an anomaly or a min→max range is ever added — the one place a
hand-rolled table quietly goes wrong (a 10 °C range is 18 °F, not 50 °F).

Not recommended — pint-pandas / pint-xarray dtypes end to end. I tried it. The
dtype leaks straight into serialization, which is fatal here:

df = pd.DataFrame({"t": pd.Series([0., 10.], dtype="pint[degree_C]")})
df.to_csv(index=False)   # 't\n0.0 degree_Celsius\n10.0 degree_Celsius\n'
df.to_dict("records")    # [{'t': <Quantity(0.0, 'degree_Celsius')>}]

That breaks the vega spec (marimo_inline_csv), pyarrow/vegafusion, and marimo's table
download. We'd have to .pint.magnitude before every chart and every accordion anyway, at
which point the dtype layer is pure overhead. pint-xarray is moot — xarray is a
declared dependency but nothing in the app imports it.

Other options, for the record:

• Hand-rolled table — a dict of standard_name → (factor, offset, label), ~70 lines,
  zero new deps. Genuinely viable given how small the table is. Costs: hardcoded source
  units (same weakness as the dashboard), no dimensionality check, offset temperature by
  hand, and no answer for delta units later.
• cf-units (UDUNITS2 bindings, what Iris uses) —
  parses every ERDDAP string natively with no alias patching. Costs a compiled UDUNITS2
  dependency and has no pandas story, so we'd be writing the same magnitude-extraction glue
  with a heavier dep.
• unyt / astropy.units — both work; neither has pint's pandas/xarray ecosystem
  position, and astropy is a very large dependency for six conversions.

Deps to add: pint and cf_xarray (both conda-forge noarch). Worth confirming they solve
cleanly against the pinned numpy <2.5.2 when we pixi add.

---

3. Where the code changes

Nothing above climatology.py needs to move. Two useful properties keep this small:

• mean, min and max all commute with an affine conversion
  (mean(aX + b) == a·mean(X) + b — confirmed numerically in the prototype). So we convert
  the display frames after core.climatology() and core.year_series(), not the raw
  observations. Flipping the toggle then costs nothing: no ERDDAP refetch, no
  period_means, no filter_means, and the threshold histogram (a count) is untouched.
• The unit only reaches the chart through the y-axis title
  (climatology.py:365) and the column names, so the data table and its CSV follow for free
  if we rename columns.

File	Change
pyproject.toml	add pint, cf_xarray; relock
units.py (new)	registry + aliases, TARGETS table, convert(values, source, standard_name, system), label(). Pure functions over arrays — no marimo, no altair, testable like climatology_core.py
climatology.py	toggle in the existing mo.hstack; convert clim_df + df_year; unit into the y-axis title and the Mean/Min/Max (…) column names
tests/unit/test_units.py (new)	table-driven; the dashboard ships ~100 .spec.ts files we can port assertions from
tests/e2e/test_climatology.py	toggling changes the axis label and the URL
README.md	short note

Toggle: mo.ui.radio(options=["English", "Metric"], inline=True), persisted as
?units= through the existing common.query_param_default path. Write the param
on change only, like the existing dropdowns — eagerly seeding a default would break
test_western_maine_shelf_air, which asserts an exact URL.

Unparseable or unlisted units fall through to the source value and the source label — the
prototype handles ntu, degrees_true and a bogus unit that way. Worth a
monitoring.report(..., level="warning") on the dimensionality mismatch case only (a
real bug: Buoy Barn says one thing, our table says another); silent passthrough for genuinely
unknown units, which are just chemistry.

by_platform.py and by_standard_name.py are a separate, larger job: both use the unit
string as a melted-frame column name and Altair encoding field
(by_platform.py:176-193, by_standard_name.py:169), and by_platform groups its subplots
by unit. Converting there means the grouping key changes with the toggle. I'd keep #144
scoped to climatology and file a follow-up.

Rough size: ~200 lines of new code, ~150 of tests, plus the relock.

---

4. The four decisions

Barometric pressure — recommend inHg. psi is not a meteorological unit and looks like
an oversight on the dashboard (it applies to four standard names while air_pressure, with
a bespoke class, uses inHg). inHg is what NWS marine products use. At 2dp it gives ~0.34 mb
resolution, which is fine for a climatology. Alternative worth naming: mb in both systems,
since mb is what mariners read off a barometer face anyway — but that breaks the "toggle
does something" expectation. Whichever way this goes, the dashboard should probably be made
to match, as a separate issue over there.

Tooltip — this is blocked on #137, not on a units decision. Worth being explicit: the
climatology chart has no tooltip encodings at all today. area, mean and line
encode only x/y/y2, and the only tooltip= anywhere in the app is on the layered logo
(common.py:353). So "both units at once, as the old tool did" is not a small addition to
an existing tooltip — it requires the shared-hover layer #137 describes (pivot transform +
transparent rule). My recommendation: build #137 first, then both-units is genuinely one
transform_calculate per field on top of it, and matching the old tool is cheap enough to
just do. If #144 needs to ship before #137, ship it with axis and table only and leave the
tooltip to #137.

Data table and CSV — recommend they follow the toggle, with the unit in the column
header (Mean (2000 - 2024) (°F)). #38 lists "only metric in the data table" as a
complaint about the old tool, not as behaviour to preserve, and unit-bearing headers make a
downloaded CSV self-describing either way. Alternative if anyone wants archival stability:
emit both columns. I'd avoid "table always metric" — it reintroduces the thing being
complained about.

Direction (not asked, but it falls out of the table) — recommend numeric degrees in both
systems. The dashboard renders a compass string in English mode, which can't be averaged
or plotted, and climatology.py:398 already special-cases "direction" in standard_name to
drop the min/max band. Ties into #141.

---

5. Open questions

• I couldn't reach buoybarn.neracoos.org from this sandbox to enumerate which standard
  names are actually visibility=climatology. That's a one-liner locally and it would let us
  trim TARGETS to what's reachable and confirm the real spelling of every units string.
  Everything above assumes degree_C (what the test fixtures use) plus the m s-1 family.
• Should the unit preference persist across pages? The sidebar links are plain hrefs with no
  query string, so it wouldn't today. Out of scope for English units by default, with a metric toggle #144, but it's the kind of thing that
  reads as a bug once by_platform gets the toggle too.

Happy to start on units.py and the tests once the pressure and table/CSV calls are made —
those two are all that block the climatology-scoped version.

---

Generated by Claude Code