@oceanmetrics/engine 0.0.0-stage → 0.1.0

package/src/sqlTemplates.ts

@@ -0,0 +1,8 @@
+// generated by scripts/sql-templates.mjs from sql/*.sql: do not edit (edit the .sql, then run the script)
+export const TEMPLATES: Readonly<Record<string, string>> = {
+  last_step: "-- the masked cells of the **last** time step in the slab, for the map layer.\n--   {{expr}}  the value expression over the slab alias `s` (e.g. s.\"CRW_SST\", or\n--             (s.\"analysed_sst\" - 273.15) to convert Kelvin to Celsius)\n--   {{slab}}  the registered griddap file (parquet) or view\n--   {{mask}}  the mask table: latitude, longitude, weight (0,1]\n-- one row per cell: the mask's own latitude/longitude (so the squares land on the dataset grid), the\n-- area weight and the value. cells with no data on that step are kept with a NULL value, so the map\n-- draws the hole instead of moving the neighbouring squares. the join is the same exact equality on\n-- ROUND(x, 3) as stats_daily.sql (float32 axis vs float64 mask).\nWITH joined AS (\n  SELECT\n    s.\"time\"     AS time,\n    m.latitude   AS latitude,\n    m.longitude  AS longitude,\n    m.weight     AS weight,\n    {{expr}}     AS value\n  FROM {{slab}} s\n  JOIN {{mask}} m\n    ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)\n    AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)\n)\nSELECT\n  -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there\n  make_timestamp(epoch_ms(time) * 1000)::DATE AS date,\n  latitude,\n  longitude,\n  weight,\n  value\nFROM joined\nWHERE time = (SELECT max(time) FROM joined)\nORDER BY latitude, longitude\n",
+  points_tabledap: "-- one row per masked sampling station, for the map layer of a tabledap run.\n--   {{expr}}  the value expression over the slab alias `s`\n--   {{slab}}  the registered tabledap file (parquet) or view\n--   {{mask}}  the station table: latitude, longitude\n-- a tabledap window holds many casts at the same position and many depths per cast, so the map\n-- shows each **station**: its mean value over the window, the number of measurements behind it and\n-- the last time it was sampled.\nSELECT\n  m.latitude                                             AS latitude,\n  m.longitude                                            AS longitude,\n  1.0                                                    AS weight,\n  avg({{expr}})                                          AS value,\n  count({{expr}})                                        AS n,\n  make_timestamp(epoch_ms(max(s.\"time\")) * 1000)::DATE   AS date\nFROM {{slab}} s\nJOIN {{mask}} m\n  ON  ROUND(s.latitude::DOUBLE,  5) = ROUND(m.latitude::DOUBLE,  5)\n  AND ROUND(s.longitude::DOUBLE, 5) = ROUND(m.longitude::DOUBLE, 5)\nWHERE {{expr}} IS NOT NULL\nGROUP BY 1, 2\nORDER BY 1, 2\n",
+  stats_categorical: "-- per date x class composition for one place from a categorical ERDDAP griddap slab (seascapeR's\n-- sum_ss_grds_to_ts(): how much of the place is in each class on each date).\n--   {{expr}}  the class expression over the slab alias `s` (e.g. s.\"CLASS\"); cast to BIGINT here\n--   {{slab}}  the registered griddap file (parquet) or view\n--   {{mask}}  the mask table: latitude, longitude, weight (0,1]\n-- `fraction` is area-weighted (partial boundary cells count for their overlap) and sums to exactly 1\n-- over the classes of a date; `percent_cells` is the unweighted cell count share.\n-- the join is the same exact equality on ROUND(x, 3) as stats_daily.sql (float32 axis vs float64 mask).\nWITH cells AS (\n  SELECT\n    -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there\n    make_timestamp(epoch_ms(s.\"time\") * 1000)::DATE AS date,\n    CAST({{expr}} AS BIGINT)                        AS class,\n    m.weight                                        AS weight\n  FROM {{slab}} s\n  JOIN {{mask}} m\n    ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)\n    AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)\n  WHERE {{expr}} IS NOT NULL\n),\ntotals AS (\n  SELECT date, count(*) AS n_total, sum(weight) AS weight_total\n  FROM cells\n  GROUP BY 1\n)\nSELECT\n  c.date                                    AS date,\n  c.class                                   AS class,\n  count(*)                                  AS n,\n  sum(c.weight)                             AS weight,\n  sum(c.weight) / any_value(t.weight_total) AS fraction,\n  100.0 * count(*) / any_value(t.n_total)   AS percent_cells\nFROM cells c\nJOIN totals t USING (date)\nGROUP BY c.date, c.class\nORDER BY 1, 2\n",
+  stats_daily: "-- daily key statistics for one place from an ERDDAP griddap slab.\n--   {{expr}}  the value expression over the slab alias `s` (e.g. s.\"CRW_SST\", or\n--             (s.\"analysed_sst\" - 273.15) to convert Kelvin to Celsius)\n--   {{slab}}  the registered griddap file (parquet) or view\n--   {{mask}}  the mask table: latitude, longitude, weight (0,1]\n-- the join is an exact equality on ROUND(x, 3): the ERDDAP axis is float32 in the parquet and float64\n-- in the JS mask, so 21.375 arrives as 21.374999... on one side; rounding to the grid's 3 decimals\n-- (0.05 spacing) makes the two match without a tolerance join.\nSELECT\n  -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there\n  make_timestamp(epoch_ms(s.\"time\") * 1000)::DATE   AS date,\n  count({{expr}})                                  AS n,\n  avg({{expr}})                                    AS mean,\n  sum({{expr}} * m.weight) / sum(m.weight)         AS mean_wt,\n  stddev_samp({{expr}})                            AS sd,\n  min({{expr}})                                    AS min,\n  max({{expr}})                                    AS max,\n  quantile_cont({{expr}}, 0.10)                    AS p10,\n  quantile_cont({{expr}}, 0.90)                    AS p90,\n  sum(m.weight)                                     AS weight_sum\nFROM {{slab}} s\nJOIN {{mask}} m\n  ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)\n  AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)\nWHERE {{expr}} IS NOT NULL\nGROUP BY 1\nORDER BY 1\n",
+  stats_tabledap: "-- monthly key statistics for one place from an ERDDAP **tabledap** slab (point samples).\n--   {{expr}}  the value expression over the slab alias `s` (e.g. s.\"measurement_value\")\n--   {{slab}}  the registered tabledap file (parquet) or view\n--   {{mask}}  the station table: latitude, longitude (weight is 1 — a point is in or out)\n-- tabledap points are sparse and irregular, so the roll-up is by **month**, not by day: a CalCOFI\n-- quarterly cruise gives a handful of days a year, and a daily grouping would be mostly empty.\n-- `n_casts` counts the distinct sampling events (time x position) behind the n measurements, since\n-- one cast contributes many depths.\n-- the join is an exact equality on ROUND(x, 5): the station positions come back out of DuckDB, go\n-- through the JS point-in-polygon mask and come back in, so five decimals (~1 m) is exact here.\nWITH pts AS (\n  SELECT\n    -- utc, via epoch_ms because duckdb-wasm ships without icu: TIMESTAMPTZ::DATE is unimplemented there\n    make_timestamp(epoch_ms(s.\"time\") * 1000) AS ts,\n    s.longitude::DOUBLE                       AS longitude,\n    s.latitude::DOUBLE                        AS latitude,\n    {{expr}}                                  AS value\n  FROM {{slab}} s\n  JOIN {{mask}} m\n    ON  ROUND(s.latitude::DOUBLE,  5) = ROUND(m.latitude::DOUBLE,  5)\n    AND ROUND(s.longitude::DOUBLE, 5) = ROUND(m.longitude::DOUBLE, 5)\n  WHERE {{expr}} IS NOT NULL\n)\nSELECT\n  date_trunc('month', ts)::DATE                  AS date,\n  count(value)                                   AS n,\n  count(DISTINCT (ts, longitude, latitude))      AS n_casts,\n  avg(value)                                     AS mean,\n  stddev_samp(value)                             AS sd,\n  min(value)                                     AS min,\n  max(value)                                     AS max,\n  quantile_cont(value, 0.10)                     AS p10,\n  quantile_cont(value, 0.90)                     AS p90\nFROM pts\nGROUP BY 1\nORDER BY 1\n",
+}

package/src/wkb.ts

@@ -0,0 +1,81 @@
+// WKB -> GeoJSON, just enough for the gazetteer: (Multi)Point, (Multi)LineString, (Multi)Polygon and
+// GeometryCollection. DuckDB-WASM has no spatial extension, so the `geometry` column of
+// places.parquet (WKB MULTIPOLYGON, already split at +-180) is decoded here in JS instead.
+//
+// Both byte orders are handled, plus the two common type-code dialects:
+//   ISO WKB : type + 1000 (Z), + 2000 (M), + 3000 (ZM)
+//   EWKB    : high bits 0x80000000 (Z), 0x40000000 (M), 0x20000000 (SRID follows the type)
+// Z/M ordinates are read and dropped: GeoJSON here is 2-D on purpose (gridMask only wants x, y).
+import type { Geometry, GeometryCollection, LineString, MultiLineString, MultiPoint, MultiPolygon, Point, Polygon } from 'geojson'
+
+interface Cursor { view: DataView; off: number; le: boolean }
+
+const u32 = (c: Cursor) => { const v = c.view.getUint32(c.off, c.le); c.off += 4; return v }
+const f64 = (c: Cursor) => { const v = c.view.getFloat64(c.off, c.le); c.off += 8; return v }
+
+/** byte order + type code of the geometry at the cursor; leaves the cursor after the header. */
+function header(c: Cursor): { type: number; dims: number } {
+  const order = c.view.getUint8(c.off); c.off += 1
+  if (order !== 0 && order !== 1) throw new Error(`WKB: bad byte order ${order} at ${c.off - 1}`)
+  c.le = order === 1
+  const raw = u32(c)
+  const ewkbZ = (raw & 0x80000000) !== 0
+  const ewkbM = (raw & 0x40000000) !== 0
+  const srid  = (raw & 0x20000000) !== 0
+  const base  = raw & 0x0fffffff
+  const iso   = Math.floor(base / 1000)          // 0 = XY, 1 = Z, 2 = M, 3 = ZM
+  const type  = base % 1000
+  if (srid) u32(c)                                // skip the SRID
+  const dims = 2 + (ewkbZ ? 1 : 0) + (ewkbM ? 1 : 0) + (iso === 1 || iso === 2 ? 1 : iso === 3 ? 2 : 0)
+  return { type, dims }
+}
+
+const point = (c: Cursor, dims: number): number[] => {
+  const xy = [f64(c), f64(c)]
+  for (let i = 2; i < dims; i++) f64(c)           // drop Z / M
+  return xy
+}
+const ring = (c: Cursor, dims: number): number[][] => {
+  const n = u32(c), out: number[][] = new Array(n)
+  for (let i = 0; i < n; i++) out[i] = point(c, dims)
+  return out
+}
+const rings = (c: Cursor, dims: number): number[][][] => {
+  const n = u32(c), out: number[][][] = new Array(n)
+  for (let i = 0; i < n; i++) out[i] = ring(c, dims)
+  return out
+}
+
+function geometry(c: Cursor): Geometry {
+  const { type, dims } = header(c)
+  switch (type) {
+    case 1: return { type: 'Point',      coordinates: point(c, dims) } as Point
+    case 2: return { type: 'LineString', coordinates: ring(c, dims)  } as LineString
+    case 3: return { type: 'Polygon',    coordinates: rings(c, dims) } as Polygon
+    case 4: case 5: case 6: case 7: {
+      const n = u32(c)
+      const parts: Geometry[] = new Array(n)
+      for (let i = 0; i < n; i++) parts[i] = geometry(c)  // each part carries its own header
+      if (type === 7) return { type: 'GeometryCollection', geometries: parts } as GeometryCollection
+      if (type === 4) return { type: 'MultiPoint',      coordinates: parts.map((p) => (p as Point).coordinates) } as MultiPoint
+      if (type === 5) return { type: 'MultiLineString', coordinates: parts.map((p) => (p as LineString).coordinates) } as MultiLineString
+      return { type: 'MultiPolygon', coordinates: parts.map((p) => (p as Polygon).coordinates) } as MultiPolygon
+    }
+    default: throw new Error(`WKB: unsupported geometry type ${type}`)
+  }
+}
+
+/** decode one WKB (or EWKB) geometry to GeoJSON, 2-D. */
+export function wkbToGeoJSON(bytes: Uint8Array | ArrayBuffer): Geometry {
+  const u    = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+  const view = new DataView(u.buffer, u.byteOffset, u.byteLength)
+  return geometry({ view, off: 0, le: true })
+}
+
+/** every Polygon of a geometry, as a MultiPolygon-style coordinate array. */
+export function polygonCoordinates(g: Geometry): number[][][][] {
+  if (g.type === 'Polygon')            return [g.coordinates]
+  if (g.type === 'MultiPolygon')       return g.coordinates
+  if (g.type === 'GeometryCollection') return g.geometries.flatMap(polygonCoordinates)
+  return []
+}