WIP: add support for subordinate stations

Author: bkeepers

packages/neaps/package.json

@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "@neaps/tide-predictor": "^0.1.1",
-    "@neaps/tide-stations": "github:neaps/tide-database",
+    "@neaps/tide-stations": "github:neaps/tide-database#subordinate",
     "geolib": "^3.3.4"
   }
 }

packages/neaps/src/index.ts

@@ -95,23 +95,30 @@ export function findStation(query: string) {
 }
 
 export function useStation(station: Station, distance?: number) {
+  // If subordinate station, use the reference station for datums and constituents
+  let reference = station
+  if (station.type === 'subordinate') {
+    reference = findStation(station.offsets?.reference || '')
+  }
+  const { datums, harmonic_constituents } = reference
+
   // Use MLLW as the default datum if available
-  const defaultDatum = 'MLLW' in station.datums ? 'MLLW' : undefined
+  const defaultDatum = 'MLLW' in datums ? 'MLLW' : undefined
 
   function getPredictor({ datum = defaultDatum }: DatumOption = {}) {
     let offset = 0
 
     if (datum) {
-      const datumOffset = station.datums?.[datum]
-      const mslOffset = station.datums?.['MSL']
+      const datumOffset = datums?.[datum]
+      const mslOffset = datums?.['MSL']
 
-      if (!datumOffset) {
+      if (typeof datumOffset !== 'number') {
         throw new Error(
-          `Station ${station.id} missing ${datum} datum. Available datums: ${Object.keys(station.datums || {}).join(', ')}`
+          `Station ${station.id} missing ${datum} datum. Available datums: ${Object.keys(datums || {}).join(', ')}`
         )
       }
 
-      if (!mslOffset) {
+      if (typeof mslOffset !== 'number') {
         throw new Error(
           `Station ${station.id} missing MSL datum, so predictions can't be given in ${datum}.`
         )
@@ -120,7 +127,7 @@ export function useStation(station: Station, distance?: number) {
       offset = mslOffset - datumOffset
     }
 
-    return tidePredictor(station.harmonic_constituents, {
+    return tidePredictor(harmonic_constituents, {
       phaseKey: 'phase_UTC',
       offset
     })
@@ -129,20 +136,31 @@ export function useStation(station: Station, distance?: number) {
   return {
     ...station,
     distance,
+    datums,
+    harmonic_constituents,
     defaultDatum,
     getExtremesPrediction({ datum = defaultDatum, ...input }: ExtremesOptions) {
       return {
         datum,
         distance,
         station,
-        extremes: getPredictor({ datum }).getExtremesPrediction(input)
+        extremes: getPredictor({ datum }).getExtremesPrediction({
+          ...input,
+          offsets: station.offsets
+        })
       }
     },
 
     getTimelinePrediction({
       datum = defaultDatum,
       ...params
     }: TimelineOptions) {
+      if (station.type === 'subordinate') {
+        throw new Error(
+          `Timeline predictions are not supported for subordinate stations.`
+        )
+      }
+
       return {
         datum,
         station,
@@ -151,6 +169,12 @@ export function useStation(station: Station, distance?: number) {
     },
 
     getWaterLevelAtTime({ time, datum = defaultDatum }: WaterLevelOptions) {
+      if (station.type === 'subordinate') {
+        throw new Error(
+          `Water level predictions are not supported for subordinate stations.`
+        )
+      }
+
       return {
         datum,
         station,

packages/neaps/test/index.test.ts

@@ -13,23 +13,43 @@ import { describe, test, expect } from 'vitest'
 // predictions for a station in a non-UTC timezone without this.
 process.env.TZ = 'UTC'
 
+expect.extend({
+  toBeWithin(received, expected, delta) {
+    const diff = Math.abs(received - expected)
+    const pass = diff <= delta
+    return {
+      pass,
+      message: () =>
+        `expected ${received} to be within ±${delta} of ${expected}, but was ${diff}`
+    }
+  }
+})
+
+interface CustomMatchers<R = unknown> {
+  toBeWithin: (expected: number, delta: number) => R
+}
+
+declare module 'vitest' {
+  interface Matchers<T = any> extends CustomMatchers<T> {}
+}
+
 describe('getExtremesPrediction', () => {
   test('gets extremes from nearest station', () => {
     const prediction = getExtremesPrediction({
-      lat: 26.7,
+      lat: 26.772,
       lon: -80.05,
       start: new Date('2025-12-18T00:00:00-05:00'),
       end: new Date('2025-12-19T00:00:00-05:00'),
-      timeFidelity: 6,
+      timeFidelity: 60,
       datum: 'MLLW'
     })
 
-    expect(prediction.station.id).toEqual('us-fl-port-of-west-palm-beach')
+    expect(prediction.station.id).toEqual('us-fl-port-of-palm-beach')
     expect(prediction.datum).toBe('MLLW')
 
     const { extremes } = prediction
     expect(extremes.length).toBe(4)
-    expect(extremes[0].time).toEqual(new Date('2025-12-18T05:29:48.000Z'))
+    expect(extremes[0].time).toEqual(new Date('2025-12-18T05:30:00.000Z'))
     expect(extremes[0].level).toBeCloseTo(0.02, 2)
     expect(extremes[0].high).toBe(false)
     expect(extremes[0].low).toBe(true)
@@ -40,13 +60,13 @@ describe('getExtremesPrediction', () => {
 describe('getTimelinePrediction', () => {
   test('gets timeline from nearest station', () => {
     const timeline = getTimelinePrediction({
-      lat: 26.7,
+      lat: 26.772,
       lon: -80.05,
       start: new Date('2025-12-19T00:00:00-05:00'),
       end: new Date('2025-12-19T01:00:00-05:00')
     })
 
-    expect(timeline.station.id).toEqual('us-fl-port-of-west-palm-beach')
+    expect(timeline.station.id).toEqual('us-fl-port-of-palm-beach')
     expect(timeline.datum).toBe('MLLW')
     expect(timeline.timeline.length).toBe(7) // Every 10 minutes for 1 hour = 7 points
   })
@@ -55,13 +75,13 @@ describe('getTimelinePrediction', () => {
 describe('getWaterLevelAtTime', () => {
   test('gets water level at specific time from nearest station', () => {
     const prediction = getWaterLevelAtTime({
-      lat: 26.7,
+      lat: 26.772,
       lon: -80.05,
       time: new Date('2025-12-19T00:30:00-05:00'),
       datum: 'MSL'
     })
 
-    expect(prediction.station.id).toEqual('us-fl-port-of-west-palm-beach')
+    expect(prediction.station.id).toEqual('us-fl-port-of-palm-beach')
     expect(prediction.datum).toBe('MSL')
     expect(prediction.time).toEqual(new Date('2025-12-19T05:30:00.000Z'))
     expect(typeof prediction.level).toBe('number')
@@ -73,27 +93,88 @@ describe('for a specific station', () => {
 
   describe('getExtremesPrediction', () => {
     test('can return extremes from station', () => {
-      const station = nearestStation({ lat: 26.7, lon: -80.05 })
+      const station = nearestStation({ lat: 26.772, lon: -80.05 })
 
       const start = new Date('2025-12-17T00:00:00-05:00')
       const end = new Date('2025-12-18T05:00:00-05:00')
 
       const { extremes: predictions } = station.getExtremesPrediction({
         start,
         end,
-        timeFidelity: 6,
+        timeFidelity: 60,
         datum: 'MLLW'
       })
 
       expect(predictions.length).toBe(4)
-      expect(predictions[0].time).toEqual(new Date('2025-12-17T11:23:06.000Z'))
+      expect(predictions[0].time).toEqual(new Date('2025-12-17T11:23:00.000Z'))
       expect(predictions[0].level).toBeCloseTo(0.9, 1)
       expect(predictions[0].high).toBe(true)
       expect(predictions[0].low).toBe(false)
       expect(predictions[0].label).toBe('High')
     })
   })
 
+  describe('for a subordinate station', () => {
+    const station = findStation('9411189')
+
+    test('gets datums and harmonic_constituents from reference station', () => {
+      expect(station.type).toBe('subordinate')
+      expect(station.datums).toBeDefined()
+      expect(station.datums).toEqual(findStation('9410660').datums)
+      expect(station.harmonic_constituents).toBeDefined()
+      expect(station.harmonic_constituents).toEqual(
+        findStation('9410660').harmonic_constituents
+      )
+      expect(station.defaultDatum).toBe('MLLW')
+    })
+
+    describe('getExtremesPrediction', () => {
+      test('returns adjusted predictions', async () => {
+        const bigtime = stations
+          .filter((s) => s.type === 'subordinate')
+          .sort(
+            (a, b) =>
+              Math.abs(a.offsets?.height.high) -
+              Math.abs(b.offsets?.height.high)
+          )
+          .reverse()
+
+        console.log(bigtime[0])
+
+        const station = useStation(bigtime[0])
+
+        const start = new Date('2025-12-17T00:00:00Z')
+        const end = new Date('2025-12-19T00:00:00Z')
+
+        const prediction = station.getExtremesPrediction({
+          start,
+          end,
+          timeFidelity: 60,
+          datum: 'MLLW'
+        })
+
+        console.log(prediction.extremes)
+
+        // https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?format=json&product=predictions&units=metric&time_zone=gmt&station=TEC4769&begin_date=2025-12-17&end_date=2025-12-18&interval=hilo&datum=MLLW
+        const noaa = [
+          { t: '2025-12-17T01:44:00Z', v: -0.091, type: 'L' },
+          { t: '2025-12-17T08:50:00Z', v: 0.75, type: 'H' },
+          { t: '2025-12-18T02:15:00Z', v: -0.13, type: 'L' },
+          { t: '2025-12-18T09:24:00Z', v: 0.754, type: 'H' }
+        ]
+
+        noaa.forEach((expected, index) => {
+          const actual = prediction.extremes[index]
+          expect(actual.time).toBeWithin(
+            new Date(expected.t),
+            25 * 60 * 1000 /* min */
+          )
+          expect(actual.level).toBeWithin(expected.v, 0.04 /* m */)
+        })
+      })
+    })
+  })
+
   describe('getTimelinePrediction', () => {
     test('gets timeline', () => {
       const prediction = station.getTimelinePrediction({
@@ -119,20 +200,14 @@ describe('for a specific station', () => {
 })
 
 describe('nearestStation', () => {
-  test('finds the nearest station', () => {
-    const station = nearestStation({ lat: 26.7, lon: -80.05 })
-    expect(station.source.id).toBe('8722588')
-    expect(station.latitude).toBeCloseTo(26.77)
-    expect(station.longitude).toBeCloseTo(-80.0517)
-  })
   ;[
-    { lat: 26.7, lon: -80.05 },
-    { lat: 26.7, lng: -80.05 },
-    { latitude: 26.7, longitude: -80.05 }
+    { lat: 26.772, lon: -80.052 },
+    { lat: 26.772, lng: -80.052 },
+    { latitude: 26.772, longitude: -80.052 }
   ].forEach((position) => {
     test(`finds station with ${Object.keys(position).join('/')}`, () => {
       const station = nearestStation(position)
-      expect(station.id).toEqual('us-fl-port-of-west-palm-beach')
+      expect(station.source.id).toBe('8722588')
     })
   })
 })
@@ -143,9 +218,9 @@ describe('findStation', () => {
   })
 
   test('finds station by id', () => {
-    const station = findStation('us-fl-ankona-indian-river')
+    const station = findStation('us-ma-boston')
     expect(station).toBeDefined()
-    expect(station.id).toBe('us-fl-ankona-indian-river')
+    expect(station.id).toBe('us-ma-boston')
     expect(station.getExtremesPrediction).toBeDefined()
   })
 
@@ -159,7 +234,7 @@ describe('findStation', () => {
 
 describe('datum', () => {
   test('defaults to MLLW datum', () => {
-    const station = findStation('us-fl-ankona-indian-river')
+    const station = findStation('8722274')
     const extremes = station.getExtremesPrediction({
       start: new Date('2025-12-17T00:00:00Z'),
       end: new Date('2025-12-18T00:00:00Z')
@@ -168,7 +243,7 @@ describe('datum', () => {
   })
 
   test('accepts datum option', () => {
-    const station = findStation('us-fl-ankona-indian-river')
+    const station = findStation('8722274')
     const extremes = station.getExtremesPrediction({
       start: new Date('2025-12-17T00:00:00Z'),
       end: new Date('2025-12-18T00:00:00Z'),
@@ -191,21 +266,26 @@ describe('datum', () => {
   test('throws error when missing MSL datum', () => {
     // Find station without MSL but with other datums
     const station = stations.find(
-      (s) => !('MSL' in s.datums) && Object.keys(s.datums).length > 0
+      (s) =>
+        s.type === 'reference' &&
+        !('MSL' in s.datums) &&
+        Object.keys(s.datums).length > 0
     )
     if (!station) expect.fail('No station without MSL datum found')
     expect(() => {
       useStation(station).getExtremesPrediction({
         start: new Date('2025-12-17T00:00:00Z'),
         end: new Date('2025-12-18T00:00:00Z'),
-        datum: 'NAVD88'
+        datum: Object.keys(station.datums)[0]
       })
     }).toThrow(/missing MSL/)
   })
 
   test('does not apply datums when non available', () => {
     // Find a station with no datums
-    const station = stations.find((s) => Object.entries(s.datums).length === 0)
+    const station = stations.find(
+      (s) => s.type === 'reference' && Object.entries(s.datums).length === 0
+    )
     if (!station) expect.fail('No station without datums found')
     const extremes = useStation(station).getExtremesPrediction({
       start: new Date('2025-12-17T00:00:00Z'),

packages/tide-predictor/README.md

@@ -179,20 +179,20 @@ Tidal constituents should be an array of objects with at least:
 
 Some stations do not have defined harmonic data, but do have published offets and a reference station. These include the offsets in time or amplitude of the high and low tides. Subservient station definitions are objects that include:
 
-- `height_offset` - **object** - An object of height offets, in the same units as the reference station.
+- `height` - **object** - An object of height offets, in the same units as the reference station.
   - `high` - **float** - The offset to be added to high tide (can be negative)
   - `low` - **float** - The offset to be added to low tide (can be negative)
-- `time_offset` - **object** - An object of time offets, in number of minutes
+- `time` - **object** - An object of time offets, in number of minutes
   - `high` - **float** - The number of minutes to add to high tide times (can be negative)
   - `low` - **float** - The number of minutes to add to low tide times (can be negative)
 
 ```
 {
-  height_offset: {
+  height: {
     high: 1,
     low: 2
   },
-  time_offset: {
+  time: {
     high: 1,
     low: 2
   }