Unit mapping

Every OG1 variable has a canonical units spelling, set in config/OG1_variable_attributes.yaml (for example mS cm-1 for conductivity, m s-1 for velocities, degree_Celsius for temperature). A basestation file may label the same quantity differently (S/m, cm/s, degrees_Celsius), so the converter resolves each source spelling to the canonical one through the shared units tables (seagliderOG1.vocabularies.UNITS) and applies a factor where the units differ in size. An unknown spelling is refused (UnitsError) rather than written with a wrong or unchecked label.

What the converter does to a variable’s units, in order:

  • unchanged — the source is already the OG1 spelling; nothing happens.

  • relabel — the same quantity in a different spelling (degrees_Celsius → degree_Celsius); the units string is rewritten to the canonical one, the values are unchanged (factor 1).

  • convert — the units differ in size (S/m → mS cm-1, ×10; cm/s → m s-1, ×0.01); the values are multiplied by the factor and original_units records the source label.

  • label correction — the basestation label is wrong for the magnitude the values hold (g/m^3 for kg m⁻³ density); corrected before conversion, recorded in original_units and comment (see What the conversion does).

  • no source units — the source variable has no units; the OG1 label is adopted unchanged.

  • wrong-quantity — the source is a different quantity from the OG1 variable (per-mass versus per-volume oxygen); the mapping is removed and the variable passes through under its basestation name, with a drop recommendation on the conversion page.

Where to add or change a unit

The unit definitions below are package-level: they live in the package and apply to every file of a given basestation version, so adding one needs a change to seagliderOG1 and a release. (The tables further down are the data these produce, not where you change it.) The factor itself is applied in seagliderOG1._convert from the (canonical, factor) that vocabularies.UNITS resolves, so adding a row is all a new spelling needs — no code change.

  • A wrong label — a basestation units string that is wrong for the magnitude the values hold (density written g/m^3 for kg m⁻³ values; glide_angle written cm/s for degrees): add a row keyed by the basestation variable to OG1_unit_corrections.yaml.

  • An accepted spelling and its factor — a source spelling that resolves to a canonical one (S/m → mS cm-1, ×10; cm/s → m s-1, ×0.01; micrograms/liter → mg m-3, ×1): add a row to the UNITS view in vocabularies.py. The view layers the package rows over the shared family tables in reports/_vendored/units_tables.py, which are vendored byte-for-byte from ctdcast — edit those upstream and re-vendor, not here.

  • The canonical units of an OG1 variable (the target spelling a source resolves to): the variable’s units in OG1_variable_attributes.yaml.

  • Which basestation variable maps to which OG1 variable (add a mapping, or remove a wrong-quantity one so the source passes through under its own name): OG1_variable_names.yaml.

Mission-level, in your own mission.yaml with no change to the package:

  • Leave a variable out whose units you cannot use (for example one that is refused, or a wrong-quantity pass-through): list it under drop_variables (see mission.yaml reference).

  • Correct a wrong label on one variable with a unit_corrections: block keyed by the basestation variable name: to is the label to write, from is the label as written (null for an unlabelled source). It is applied before conversion, in origin terms, and layered over the package OG1_unit_corrections.yaml so a mission entry wins on a shared key. Use it for a one-off mislabel on this mission; the package file carries the systematic, cross-mission defects. The to spelling must be one the OG1 target resolves (an alias in UNITS or the target’s own units) — a genuinely new spelling is still a package-level change above. A fleet-wide overlay (the reserved local_config key) is not yet available.

The tables below are regenerated on every docs build from the two bundled samples (sg005, basestation 2.8; sg271, basestation 3.0.6), so they always match the code.