@neaps/tide-predictor 0.0.4

package/src/__mocks__/secondary-station.js

@@ -0,0 +1,11 @@
+export default {
+  reference_station: '',
+  height_offset: {
+    high: 1,
+    low: 2
+  },
+  time_offset: {
+    high: 1,
+    low: 2
+  }
+}

package/src/__tests__/index.js

@@ -0,0 +1,81 @@
+import mockConstituents from '../__mocks__/constituents'
+import tidePrediction from '../index.js'
+
+const startDate = new Date()
+startDate.setFullYear(2019)
+startDate.setMonth(8)
+startDate.setDate(1)
+startDate.setHours(0)
+startDate.setMinutes(0)
+startDate.setSeconds(0)
+startDate.setMilliseconds(0)
+
+const endDate = new Date()
+endDate.setFullYear(2019)
+endDate.setMonth(8)
+endDate.setDate(1)
+endDate.setHours(6)
+endDate.setMinutes(0)
+endDate.setSeconds(0)
+endDate.setMilliseconds(0)
+
+describe('Tidal station', () => {
+  test('it is created correctly', () => {
+    let stationCreated = true
+
+    try {
+      tidePrediction(mockConstituents)
+    } catch (e) {
+      stationCreated = false
+    }
+    expect(stationCreated).toBeTruthy()
+
+    try {
+      tidePrediction(mockConstituents)
+    } catch (e) {
+      stationCreated = false
+    }
+    expect(stationCreated).toBeTruthy()
+  })
+
+  test('it predicts the tides in a timeline', () => {
+    const results = tidePrediction(mockConstituents).getTimelinePrediction({
+      start: startDate,
+      end: endDate,
+    })
+    expect(results[0].level).toBeCloseTo(-1.34712509, 3)
+    expect(results.pop().level).toBeCloseTo(2.85263589, 3)
+  })
+
+  test('it predicts the tidal extremes', () => {
+    const results = tidePrediction(mockConstituents).getExtremesPrediction({
+      start: startDate,
+      end: endDate,
+    })
+    expect(results[0].level).toBeCloseTo(-1.565033, 4)
+  })
+
+  test('it predicts the tidal extremes with high fidelity', () => {
+    const results = tidePrediction(mockConstituents).getExtremesPrediction({
+      start: startDate,
+      end: endDate,
+      timeFidelity: 60,
+    })
+    expect(results[0].level).toBeCloseTo(-1.565389, 4)
+  })
+
+  test('it fetches a single water level', () => {
+    const result = tidePrediction(mockConstituents).getWaterLevelAtTime({
+      time: startDate,
+    })
+    expect(result.level).toBeCloseTo(-1.34712509, 4)
+  })
+
+  test('it adds offset phases', () => {
+    const results = tidePrediction(mockConstituents, {
+      offset: 3,
+    }).getExtremesPrediction({ start: startDate, end: endDate })
+
+    expect(results[0].level).toBeCloseTo(1.43496678, 4)
+  })
+})

package/src/__tests__/noaa.js

@@ -0,0 +1,92 @@
+import fs from 'fs'
+import fetch from 'node-fetch'
+import tidePrediction from '..'
+
+// Create a directory for test cache
+if (!fs.existsSync('./.test-cache')) {
+  fs.mkdirSync('./.test-cache')
+}
+
+const stations = ['9413450', '9411340', '2695535', '8761724', '8410140']
+
+const getStation = (station, callback) => {
+  const filePath = `./.test-cache/${station}.json`
+  if (fs.existsSync(filePath)) {
+    fs.readFile(filePath, (err, data) => {
+      if (err) {
+        throw new Error('Cannot access test cache')
+      }
+      callback(JSON.parse(data))
+    })
+    return
+  }
+  const stationData = {}
+  fetch(
+    `https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations/${station}/harcon.json?units=metric`
+  )
+    .then((response) => {
+      return response.json()
+    })
+    .then((harmonics) => {
+      stationData.harmonics = harmonics
+      return fetch(
+        `https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?date=recent&station=${station}&product=predictions&datum=MTL&time_zone=gmt&units=metric&format=json`
+      )
+    })
+    .then((response) => {
+      return response.json()
+    })
+    .then((levels) => {
+      stationData.levels = levels
+      return fetch(
+        `https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations/${station}/datums.json?units=metric`
+      )
+    })
+    .then((response) => {
+      return response.json()
+    })
+    .then((info) => {
+      stationData.info = info
+      fs.writeFile(filePath, JSON.stringify(stationData), (error) => {
+        if (error) {
+          throw new Error('Cannot write to test cache')
+        }
+        callback(stationData)
+      })
+    })
+}
+
+describe('Results compare to NOAA', () => {
+  stations.forEach((station) => {
+    test(`it compares with station ${station}`, (done) => {
+      getStation(station, ({ harmonics, levels, info }) => {
+        let mtl = 0
+        let mllw = 0
+        info.datums.forEach((datum) => {
+          if (datum.name === 'MTL') {
+            mtl = datum.value
+          }
+          if (datum.name === 'MLLW') {
+            mllw = datum.value
+          }
+        })
+        const tideStation = tidePrediction(
+          harmonics.HarmonicConstituents,
+          mtl - mllw
+        )
+        levels.predictions.forEach((prediction) => {
+          const neapsPrediction = tideStation.getWaterLevelAtTime({
+            time: new Date(prediction.t),
+          })
+          expect(parseFloat(prediction.v)).toBeGreaterThanOrEqual(
+            neapsPrediction.level - 0.5
+          )
+          expect(parseFloat(prediction.v)).toBeLessThanOrEqual(
+            neapsPrediction.level + 0.5
+          )
+        })
+        done()
+      })
+    })
+  })
+})

package/src/astronomy/__tests__/coefficients.js

@@ -0,0 +1,12 @@
+import coefficients, { sexagesimalToDecimal } from '../coefficients'
+
+describe('astronomy coefficients', () => {
+  test('converts a sexagesimal angle into decimal degrees', () => {
+    expect(sexagesimalToDecimal(10, 10, 10, 10, 10)).toBe(10.169447225)
+    expect(sexagesimalToDecimal(10)).toBe(10)
+  })
+
+  test('calculates terrestrial oliquity coefficients rewritten to T', () => {
+    expect(coefficients.terrestrialObliquity[1]).toBe(-0.013002583333333335)
+  })
+})

package/src/astronomy/__tests__/index.js

@@ -0,0 +1,96 @@
+import astro, {
+  polynomial,
+  derivativePolynomial,
+  JD,
+  T,
+  _I,
+  _xi,
+  _nu,
+  _nup,
+  _nupp
+} from '../index'
+
+const sampleTime = new Date()
+sampleTime.setFullYear(2019)
+sampleTime.setMonth(9)
+sampleTime.setDate(4)
+sampleTime.setHours(10)
+sampleTime.setMinutes(15)
+sampleTime.setSeconds(40)
+sampleTime.setMilliseconds(10)
+
+describe('astronomy', () => {
+  test('complete astronomic calculation', () => {
+    const result = astro(sampleTime)
+    expect(result.s.value).toBeCloseTo(258.23871057233191, 4)
+    expect(result.s.speed).toBeCloseTo(0.54901651929993922, 4)
+
+    expect(result.pp.value).toBeCloseTo(283.27697979858613, 4)
+    expect(result.pp.speed).toBeCloseTo(1.9612154426341654e-6, 4)
+
+    expect(result.h.value).toBeCloseTo(192.82639897760328, 4)
+    expect(result.h.speed).toBeCloseTo(0.041068640143510367, 4)
+
+    expect(result.xi.value).toBeCloseTo(11.989946298635664, 4)
+    expect(result.xi.speed).toBeNull()
+
+    expect(result.I.value).toBeCloseTo(22.811296275568843, 4)
+    expect(result.I.speed).toBeNull()
+
+    expect(result.P.value).toBeCloseTo(155.24265065565865, 4)
+    expect(result.P.speed).toBeNull()
+
+    expect(result.nupp.value).toBeCloseTo(8.8162480626605451, 4)
+    expect(result.nupp.speed).toBeNull()
+
+    expect(result.nu.value).toBeCloseTo(13.028571777192044, 4)
+    expect(result.nu.speed).toBeNull()
+
+    expect(result['T+h-s'].value).toBeCloseTo(268.50435506200392, 4)
+    expect(result['T+h-s'].speed).toBeCloseTo(14.492052120843571, 4)
+
+    expect(result.omega.value).toBeCloseTo(23.436722306067253, 4)
+    expect(result.omega.speed).toBeCloseTo(-1.4832917321024327e-8, 4)
+  })
+
+  test('evaluates a polynomial', () => {
+    expect(polynomial([1, 2, 3], 3)).toBe(34)
+  })
+
+  test('evaluates derivative polynomials', () => {
+    expect(derivativePolynomial([1, 2, 3], 3)).toBe(20)
+  })
+
+  test('evaluates Meeus formula 7.1 (JD) correctly', () => {
+    sampleTime.setMonth(9)
+    expect(JD(sampleTime)).toBeCloseTo(2458760.92755, 2)
+    // Months of less than 2 go back a year
+    sampleTime.setMonth(0)
+    expect(JD(sampleTime)).toBeCloseTo(2458487.92755, 2)
+  })
+
+  test('evaluates Meeus formula 11.1 (T) correctly', () => {
+    sampleTime.setMonth(9)
+    expect(T(sampleTime)).toBeCloseTo(0.19756132, 2)
+  })
+
+  test('evaluates value for _I correctly', () => {
+    expect(_I(4, 10, 5)).toBeCloseTo(14.9918364991, 4)
+  })
+
+  test('evaluates value for _xi correctly', () => {
+    expect(_xi(4, 3, 10)).toBeCloseTo(0.911946348144, 4)
+  })
+
+  test('evaluates value for _nu correctly', () => {
+    expect(_nu(10, 4, 5)).toBeCloseTo(4.45767377718, 4)
+  })
+
+  test('evaluates value for _nup correctly', () => {
+    expect(_nup(10, 4, 5)).toBeCloseTo(2.13580480226, 4)
+  })
+
+  test('evaluates value for _nupp correctly', () => {
+    expect(_nupp(10, 4, 5)).toBeCloseTo(1.1146589591, 4)
+  })
+})

package/src/astronomy/coefficients.js

@@ -0,0 +1,72 @@
+// Convert a sexagesimal angle into decimal degrees
+const sexagesimalToDecimal = (degrees, arcmins, arcsecs, mas, muas) => {
+  arcmins = typeof arcmins !== 'undefined' ? arcmins : 0
+  arcsecs = typeof arcsecs !== 'undefined' ? arcsecs : 0
+  mas = typeof mas !== 'undefined' ? mas : 0
+  muas = typeof muas !== 'undefined' ? muas : 0
+
+  return (
+    degrees +
+    arcmins / 60.0 +
+    arcsecs / (60.0 * 60.0) +
+    mas / (60.0 * 60.0 * 1e3) +
+    muas / (60.0 * 60.0 * 1e6)
+  )
+}
+
+const coefficients = {
+  // Meeus formula 21.3
+  terrestrialObliquity: [
+    sexagesimalToDecimal(23, 26, 21.448),
+    -sexagesimalToDecimal(0, 0, 4680.93),
+    -sexagesimalToDecimal(0, 0, 1.55),
+    sexagesimalToDecimal(0, 0, 1999.25),
+    -sexagesimalToDecimal(0, 0, 51.38),
+    -sexagesimalToDecimal(0, 0, 249.67),
+    -sexagesimalToDecimal(0, 0, 39.05),
+    sexagesimalToDecimal(0, 0, 7.12),
+    sexagesimalToDecimal(0, 0, 27.87),
+    sexagesimalToDecimal(0, 0, 5.79),
+    sexagesimalToDecimal(0, 0, 2.45),
+  ].map((number, index) => {
+    return number * Math.pow(1e-2, index)
+  }),
+
+  solarPerigee: [
+    280.46645 - 357.5291,
+    36000.76932 - 35999.0503,
+    0.0003032 + 0.0001559,
+    0.00000048,
+  ],
+
+  solarLongitude: [280.46645, 36000.76983, 0.0003032],
+
+  lunarInclination: [5.145],
+
+  lunarLongitude: [
+    218.3164591,
+    481267.88134236,
+    -0.0013268,
+    1 / 538841.0 - 1 / 65194000.0,
+  ],
+
+  lunarNode: [
+    125.044555,
+    -1934.1361849,
+    0.0020762,
+    1 / 467410.0,
+    -1 / 60616000.0,
+  ],
+
+  lunarPerigee: [
+    83.353243,
+    4069.0137111,
+    -0.0103238,
+    -1 / 80053.0,
+    1 / 18999000.0,
+  ],
+}
+
+export default coefficients
+
+export { sexagesimalToDecimal }

package/src/astronomy/constants.js

@@ -0,0 +1,4 @@
+const d2r = Math.PI / 180.0
+const r2d = 180.0 / Math.PI
+
+export { d2r, r2d }

package/src/astronomy/index.js

@@ -0,0 +1,201 @@
+import { d2r, r2d } from './constants'
+import coefficients from './coefficients'
+
+// Evaluates a polynomial at argument
+const polynomial = (coefficients, argument) => {
+  const result = []
+  coefficients.forEach((coefficient, index) => {
+    result.push(coefficient * Math.pow(argument, index))
+  })
+  return result.reduce((a, b) => {
+    return a + b
+  })
+}
+
+// Evaluates a derivative polynomial at argument
+const derivativePolynomial = (coefficients, argument) => {
+  const result = []
+  coefficients.forEach((coefficient, index) => {
+    result.push(coefficient * index * Math.pow(argument, index - 1))
+  })
+  return result.reduce((a, b) => {
+    return a + b
+  })
+}
+
+// Meeus formula 11.1
+const T = (t) => {
+  return (JD(t) - 2451545.0) / 36525
+}
+
+// Meeus formula 7.1
+const JD = (t) => {
+  let Y = t.getFullYear()
+  let M = t.getMonth() + 1
+  const D =
+    t.getDate() +
+    t.getHours() / 24.0 +
+    t.getMinutes() / (24.0 * 60.0) +
+    t.getSeconds() / (24.0 * 60.0 * 60.0) +
+    t.getMilliseconds() / (24.0 * 60.0 * 60.0 * 1e6)
+  if (M <= 2) {
+    Y = Y - 1
+    M = M + 12
+  }
+  const A = Math.floor(Y / 100.0)
+  const B = 2 - A + Math.floor(A / 4.0)
+  return (
+    Math.floor(365.25 * (Y + 4716)) +
+    Math.floor(30.6001 * (M + 1)) +
+    D +
+    B -
+    1524.5
+  )
+}
+
+/**
+ * @todo - What's  with the array returned from the arccos?
+ * @param {*} N
+ * @param {*} i
+ * @param {*} omega
+ */
+const _I = (N, i, omega) => {
+  N = d2r * N
+  i = d2r * i
+  omega = d2r * omega
+  const cosI =
+    Math.cos(i) * Math.cos(omega) - Math.sin(i) * Math.sin(omega) * Math.cos(N)
+  return r2d * Math.acos(cosI)
+}
+
+const _xi = (N, i, omega) => {
+  N = d2r * N
+  i = d2r * i
+  omega = d2r * omega
+  let e1 =
+    (Math.cos(0.5 * (omega - i)) / Math.cos(0.5 * (omega + i))) *
+    Math.tan(0.5 * N)
+  let e2 =
+    (Math.sin(0.5 * (omega - i)) / Math.sin(0.5 * (omega + i))) *
+    Math.tan(0.5 * N)
+  e1 = Math.atan(e1)
+  e2 = Math.atan(e2)
+  e1 = e1 - 0.5 * N
+  e2 = e2 - 0.5 * N
+  return -(e1 + e2) * r2d
+}
+
+const _nu = (N, i, omega) => {
+  N = d2r * N
+  i = d2r * i
+  omega = d2r * omega
+  let e1 =
+    (Math.cos(0.5 * (omega - i)) / Math.cos(0.5 * (omega + i))) *
+    Math.tan(0.5 * N)
+  let e2 =
+    (Math.sin(0.5 * (omega - i)) / Math.sin(0.5 * (omega + i))) *
+    Math.tan(0.5 * N)
+  e1 = Math.atan(e1)
+  e2 = Math.atan(e2)
+  e1 = e1 - 0.5 * N
+  e2 = e2 - 0.5 * N
+  return (e1 - e2) * r2d
+}
+
+// Schureman equation 224
+const _nup = (N, i, omega) => {
+  const I = d2r * _I(N, i, omega)
+  const nu = d2r * _nu(N, i, omega)
+  return (
+    r2d *
+    Math.atan(
+      (Math.sin(2 * I) * Math.sin(nu)) /
+        (Math.sin(2 * I) * Math.cos(nu) + 0.3347)
+    )
+  )
+}
+
+// Schureman equation 232
+const _nupp = (N, i, omega) => {
+  const I = d2r * _I(N, i, omega)
+  const nu = d2r * _nu(N, i, omega)
+  const tan2nupp =
+    (Math.sin(I) ** 2 * Math.sin(2 * nu)) /
+    (Math.sin(I) ** 2 * Math.cos(2 * nu) + 0.0727)
+  return r2d * 0.5 * Math.atan(tan2nupp)
+}
+
+const modulus = (a, b) => {
+  return ((a % b) + b) % b
+}
+
+const astro = (time) => {
+  const result = {}
+  const polynomials = {
+    s: coefficients.lunarLongitude,
+    h: coefficients.solarLongitude,
+    p: coefficients.lunarPerigee,
+    N: coefficients.lunarNode,
+    pp: coefficients.solarPerigee,
+    90: [90.0],
+    omega: coefficients.terrestrialObliquity,
+    i: coefficients.lunarInclination,
+  }
+
+  // Polynomials are in T, that is Julian Centuries; we want our speeds to be
+  // in the more convenient unit of degrees per hour.
+  const dTdHour = 1 / (24 * 365.25 * 100)
+  Object.keys(polynomials).forEach((name) => {
+    result[name] = {
+      value: modulus(polynomial(polynomials[name], T(time)), 360.0),
+      speed: derivativePolynomial(polynomials[name], T(time)) * dTdHour,
+    }
+  })
+
+  // Some other parameters defined by Schureman which are dependent on the
+  // parameters N, i, omega for use in node factor calculations. We don't need
+  // their speeds.
+  const functions = {
+    I: _I,
+    xi: _xi,
+    nu: _nu,
+    nup: _nup,
+    nupp: _nupp,
+  }
+  Object.keys(functions).forEach((name) => {
+    const functionCall = functions[name]
+    result[name] = {
+      value: modulus(
+        functionCall(result.N.value, result.i.value, result.omega.value),
+        360.0
+      ),
+      speed: null,
+    }
+  })
+
+  // We don't work directly with the T (hours) parameter, instead our spanning
+  // set for equilibrium arguments #is given by T+h-s, s, h, p, N, pp, 90.
+  // This is in line with convention.
+  const hour = {
+    value: (JD(time) - Math.floor(JD(time))) * 360.0,
+    speed: 15.0,
+  }
+
+  result['T+h-s'] = {
+    value: hour.value + result.h.value - result.s.value,
+    speed: hour.speed + result.h.speed - result.s.speed,
+  }
+
+  // It is convenient to calculate Schureman's P here since several node
+  // factors need it, although it could be argued that these
+  // (along with I, xi, nu etc) belong somewhere else.
+  result.P = {
+    value: result.p.value - (result.xi.value % 360.0),
+    speed: null,
+  }
+
+  return result
+}
+
+export default astro
+export { polynomial, derivativePolynomial, T, JD, _I, _xi, _nu, _nup, _nupp }