npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@neaps/tide-predictor

v0.1.1

Published

Tide predictor

Downloads

18

Readme

example workflow FOSSA Status codecov

Tide predictor

A Javascript tide harmonic calculator.

🚨Warning🚨

Do not use calculations from this project for navigation, or depend on them in any situation where inaccuracies could result in harm to a person or property.

Tide predictions are only as good as the harmonics data available, and these can be inconsistent and vary widely based on the accuracy of the source data and local conditions.

The tide predictions do not factor events such as storm surge, wind waves, uplift, tsunamis, or sadly, climate change. 😢

Installation

#npm
npm install @neaps/tide-prediction

# yarn
yarn add @neaps/tide-prediction

Importing

You can import the module using Ecmascript, or CommonJS. Note that the CommonJS export is transpiled, so deep debugging the module that way will be difficult.

import TidePrediction from '@neaps/tide-prediction'
const TidePrediction = require('@neaps/tide-prediction')

There are also packaged and minified versions for the browser in dist/web.

Usage

Neaps requires that you provide your own tidal harmonics information to generate a prediction.

Because many constituent datum come with multiple phases (in the case of NOAA's data, they are phase_local and phase_GMT), there is a phaseKey option for choosing which to use.

Note that, for now, Neaps will not do any timezone corrections. This means you need to pass date objects that align with whatever timezone the constituents are in.

import TidePrediction from '@neaps/tide-prediction'

const constituents = [
  {
    phase_GMT: 98.7,
    phase_local: 313.7,
    amplitude: 2.687,
    name: 'M2',
    speed: 28.984104
  }
  //....there are usually many, read the docs
]

const highLowTides = tidePrediction(constituents, {
  phaseKey: 'phase_GMT'
}).getExtremesPrediction({
  start: new Date('2019-01-01'),
  end: new Date('2019-01-10')
})

Tide prediction object

Calling tidePrediction will generate a new tide prediction object. It accepts the following arguments:

  • constituents - An array of constituent objects
  • options - An object with one of:
    • phaseKey - The name of the parameter within constituents that is considered the "phase"
    • offset - A value to add to all values predicted. This is useful if you want to, for example, offset tides by mean high water, etc.

Tide prediction methods

The returned tide prediction object has various methods. All of these return regular JavaScript objects.

High and low tide - getExtremesPrediction

Returns the predicted high and low tides between a start and end date.

const startDate = new Date()
const endDate = new Date(startDate + 3 * 24 * 60 * 60 * 1000)
const tides = tidePrediction(constituents).getExtremesPrediction({
  start: startDate,
  end: endDate,
  labels: {
    //optional human-readable labels
    high: 'High tide',
    low: 'Low tide'
  }
})

If you want predictions for a subservient station, first set the reference station in the prediction, and pass the subservient station offests to the getExtremesPrediction method:

const tides = tidePrediction(constituents).getExtremesPrediction({
  start: startDate,
  end: endDate,
  offset: {
    height_offset: {
      high: 1,
      low: 2
    },
    time_offset: {
      high: 1,
      low: 2
    }
  }
})
Options

The getExtremesPrediction accepts a single object with options:

  • start - **Required ** - The date & time to start looking for high and low tides
  • end - **Required ** - The date & time to stop looking for high and low tides
  • timeFidelity - Number of seconds accurate the time should be, defaults to 10 minutes.
  • labels - An object to define the human-readable labels for the tides
    • high - The human-readable label for high tides
    • low - The human-readable label for low tides
  • offset - The offset values if these predictions are for a subservient station
Return values

High and low tides are returned as arrays of objects:

  • time - A Javascript Date object of the time
  • level - The water level
  • high - true if this is a high tide, false if not
  • low - true if this is a low tide, false if not
  • label - The human-readable label (by default, 'High' or 'Low')

Water level at time - getWaterLevelAtTime

Gives you the predicted water level at a specific time.

const waterLevel = tidePrediction(constituents).getWaterLevelAtTime({
  time: new Date()
})
Options

The getWaterLevelAtTime accepts a single object of options:

  • time - A Javascript date object of the time for the prediction
Return values

A single object is returned with:

  • time - A Javascript date object
  • level - The predicted water level

Data definitions

Constituent definition

Tidal constituents should be an array of objects with at least:

  • name - string - The NOAA constituent name, all upper-case.
  • amplitude - float - The constituent amplitude
  • [phase] - float - The phase of the constituent. Because several services provide different phase values, you can choose which one to use when building your tide prediction.
[
  {
    name: '[constituent name]',
    amplitude: 1.3,
    phase: 1.33
  },
  {
    name: '[constituent name 2]',
    amplitude: 1.3,
    phase: 1.33
  }
]

Subservient station definitions

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.
    • 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
    • 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: {
    high: 1,
    low: 2
  },
  time_offset: {
    high: 1,
    low: 2
  }
}

Shout out

All the really hard math is based on the excellent Xtide and pytides.