libwx

package module
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 9, 2026 License: MIT Imports: 2 Imported by: 0

README

github.com/cdzombak/libwx

Go Reference

This package primarily provides some weather/atmospheric-related calculations. It also provides types for these calculations to traffic, helping to reduce the chance of mixing up units.

For example, these types prevent accidentally using a Celsius temperature as a Fahrenheit temperature:

Custom types allow your IDE/build to prevent accidental unit confusion.

Documentation: pkg.go.dev/github.com/cdzombak/libwx

Installation

go get github.com/cdzombak/libwx

Usage

Dew point calculation

DewPointF() and DewPointC() calculate the dew point, given a temperature and relative humidity.

Indoor humidity recommendation

IndoorHumidityRecommendationF() and IndoorHumidityRecommendationC() provide a recommended maximum indoor humidity percentage for the given outdoor temperature.

Wind chill calculation

WindChillF() and WindChillC() calculate the wind chill, given the outdoor temperature and wind speed.

The wind chill formula works given temperatures less than 50ºF and wind speeds greater than 3 mph. To calculate wind chill but return an error if the input is outside this range, use WindChillFWithValidation() and WindChillCWithValidation(). These functions return ErrInputRange if the input is out of the formula's input range.

Wet bulb temperature calculation

WetBulbF() and WetBulbC() calculate the wet bulb temperature, given the dry bulb temperature and relative humidity.

This formula is taken from "Wet-Bulb Temperature from Relative Humidity and Air Temperature" (Roland Stull, Journal of Applied Meteorology and Climatology, 2011) and assumes standard sea level pressure.

WetBulbFAtPressure() and WetBulbCAtPressure() additionally accept the barometric pressure (as PressureMb), making them usable at elevations above sea level. This formula is taken from "Direct Calculation of Thermodynamic Wet-Bulb Temperature as a Function of Pressure and Elevation" (Sadeghi et al., Journal of Atmospheric and Oceanic Technology, 2013).

These functions accept temperatures from -17°C to 40°C, relative humidity from 5-99%, and pressures from 585 to 1100 millibars. The paper validates the formula over the first two ranges, but only for pressures between 585 millibars (its 4500 m elevation limit) and standard sea level pressure, 1013.25 millibars. Pressures above sea level are accepted so that ordinary high-pressure readings do not error; the formula is well-behaved there, but the paper does not validate it. The constants MinWetBulbPressureMb and MaxWetBulbPressureMb are provided for clients who want to clamp pressure inputs to the accepted range.

These functions return ErrInputRange if the input is out of the formula's input range.

Heat index calculation

HeatIndexFWithValidation() and HeatIndexCWithValidation() calculate the heat index, given a temperature and relative humidity.

Heat index warning levels

HeatIndexWarningF() and HeatIndexWarningC() provide a warning level based on the heat index. These warning levels are based on the NOAA's heat index table:

  • HeatIndexWarningNone indicates the heat index does not warrant elevated caution.
  • HeatIndexWarningCaution indicates fatigue is possible with prolonged exposure and activity. Continuing activity could result in heat cramps.
  • HeatIndexWarningExtremeCaution indicates heat cramps and heat exhaustion are possible. Continuing activity could result in heat stroke.
  • HeatIndexWarningDanger indicates heat cramps and heat exhaustion are likely; heat stroke is probable with continued activity.
  • HeatIndexWarningExtremeDanger indicates heat stroke is imminent.
Direction statistical calculations

Three functions are provided that perform circular statistics on a slice of Degree values:

  • AvgDirectionDeg calculates the circular mean of the given set of angles (in degrees).
  • WeightedAvgDirectionDeg calculates the weighted circular mean of the given set of angles (in degrees).
  • StdDevDirectionDeg calculates the circular standard deviation of the given set of angles (in degrees).
  • WeightedStdDevDirectionDeg calculates the weighted circular standard deviation of the given set of angles (in degrees).

These can be used to calculate the average and standard deviation of a set of wind directions, for example.

Note that variance == (standard deviation)^2, but standard deviation of a dataset is in the dataset's units (degrees, in this case). Variance of this dataset would have the unit degrees^2.

Compass direction to cardinal direction string

DirectionStr returns a string representation of the given compass direction (in degrees).

Distance types & conversions

The following distance types are provided:

Each type provides methods to convert to the other types (e.g. NauticalMile.Meters()). An Unwrap() method also exists to get the raw value as a float64.

Humidity types

The RelHumidity type is an integer type representing a relative humidity percentage from 0-100, inclusive. A clamping method and function for this range are provided.

An Unwrap() method also exists to get the raw value as an int; UnwrapFloat64() returns the value as a float64.

Absolute humidity type and conversions

The AbsHumidity type represents absolute humidity in grams per cubic meter (g/m³).

An Unwrap() method also exists to get the raw value as a float64.

Absolute and relative humidity conversions

AbsHumidityFromRelF() and AbsHumidityFromRelC() calculate absolute humidity from relative humidity and temperature.

RelHumidityFromAbsF() and RelHumidityFromAbsC() calculate relative humidity from absolute humidity and temperature.

These conversions use the Antoine equation for water vapor pressure and assume standard atmospheric pressure. The calculations are valid for temperatures from -20°C to 100°C (-4°F to 212°F).

Pressure types and conversions

The following pressure types are provided:

Each type provides methods to convert to the other type (e.g. PressureInHg.Mb()). An Unwrap() method also exists to get the raw value as a float64.

Speed types and conversions

The following speed types are provided:

Each type provides methods to convert to the other types (e.g. SpeedKnots.Mph()). An Unwrap() method also exists to get the raw value as a float64.

Temperature types and conversions

The following temperature types are provided:

Each type provides methods to convert to the other type (e.g. TempF.C()). An Unwrap() method also exists to get the raw value as a float64.

Direction types

The following direction type is provided:

Utilities: Comparisons

Finally, libwx provides some utility functions for comparing float64 and int values:

The *Compare(…) functions return:

  • -1 if a < b
  • 0 if a == b
  • 1 if a > b

For float64 comparisons functions that accept a tolerance, convenience tolerance constants are provided:

ToleranceExact = float64(0.0)
Tolerance0     = float64(1.0)
Tolerance1     = float64(0.1)
Tolerance01    = float64(0.01)
Tolerance001   = float64(0.001)
Curried float64 comparisons

When making repeated comparisons with the same tolerance, having to pass the tolerance each time is tedious and increases room for human error. To help with this, curried versions of Float64Compare() and Float64Equal() are provided. These return a comparison function with the specified tolerance baked-in:

For example:

package main

import (
	wx "github.com/cdzombak/libwx"
)

function main() {
	equalityChecker := wx.CurriedFloat64Equal(Tolerance1)

	equalityChecker(1.0, 1.11) // => false
	equalityChecker(1.0, 1.01) // => true
}

License

MIT; see LICENSE in this repo.

Author

Chris Dzombak

Documentation

Index

Constants

View Source 
const (
	ToleranceExact = float64(0.0)
	Tolerance0     = float64(1.0)
	Tolerance1     = float64(0.1)
	Tolerance01    = float64(0.01)
	Tolerance001   = float64(0.001)
	Tolerace1      = Tolerance1 // deprecated; wasa a typo in a previous release
)
View Source 
const (
	// MinWetBulbPressureMb is the minimum barometric pressure supported by
	// WetBulbFAtPressure and WetBulbCAtPressure.
	MinWetBulbPressureMb = PressureMb(585.0)

	// MaxWetBulbPressureMb is the maximum barometric pressure supported by
	// WetBulbFAtPressure and WetBulbCAtPressure.
	MaxWetBulbPressureMb = PressureMb(1100.0)
)
View Source 
const (
	// HeatIndexWarningNone indicates the heat index does not warrant elevated caution.
	HeatIndexWarningNone = iota
	// HeatIndexWarningCaution indicates fatigue is possible with prolonged exposure and activity. Continuing activity could result in heat cramps.
	HeatIndexWarningCaution
	// HeatIndexWarningExtremeCaution indicates heat cramps and heat exhaustion are possible. Continuing activity could result in heat stroke.
	HeatIndexWarningExtremeCaution
	// HeatIndexWarningDanger indicates heat cramps and heat exhaustion are likely; heat stroke is probable with continued activity.
	HeatIndexWarningDanger
	// HeatIndexWarningExtremeDanger indicates heat stroke is imminent.
	HeatIndexWarningExtremeDanger
)

Variables

View Source 
var ErrInputRange = errors.New("one or more input values are outside the calculation's supported range")
View Source 
var ErrMismatchedInputLength = errors.New("input slices must be the same length")

Functions

func CurriedFloat64Compare added in v1.0.0 

func CurriedFloat64Compare(tolerance float64) func(float64, float64) int

func CurriedFloat64Equal added in v1.0.0 

func CurriedFloat64Equal(tolerance float64) func(float64, float64) bool

func DirectionStr added in v1.3.0 

func DirectionStr(deg Degree, precision DirectionStrPrecision) string

DirectionStr returns a string representation of the given compass direction (in degrees). Given DirectionStrPrecision1, it returns a cardinal direction (N, E, S, W). Given DirectionStrPrecision2, it returns a primary intercardinal direction (N, NE, E, SE, S, SW, W, NW). Given DirectionStrPrecision3, it returns a secondary intercardinal direction (N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW).

func Float64Compare added in v1.0.0 

func Float64Compare(a, b, tolerance float64) int

func Float64Equal added in v1.0.0 

func Float64Equal(a, b, tolerance float64) bool

func IntCompare added in v1.0.0 

func IntCompare(a, b int) int

Types

type AbsHumidity added in v1.4.0 

type AbsHumidity float64

func AbsHumidityFromRelC added in v1.4.0 

func AbsHumidityFromRelC(temp TempC, rh RelHumidity) AbsHumidity

func AbsHumidityFromRelF added in v1.4.0 

func AbsHumidityFromRelF(temp TempF, rh RelHumidity) AbsHumidity

func (AbsHumidity) Unwrap added in v1.4.0 

func (ah AbsHumidity) Unwrap() float64

type Degree added in v1.3.0 

type Degree float64

Degree represents direction in (angular) degrees.

func AvgDirectionDeg added in v1.3.0 

func AvgDirectionDeg(degrees []Degree) Degree

AvgDirectionDeg calculates the circular mean of the given set of angles (in degrees). This is useful to find e.g. the average wind direction.

func ClampedDegree added in v1.3.0 

func ClampedDegree(d float64) Degree

ClampedDegree returns a Degree from the given value, guaranteed to be within 0 < d <= 360.

func StdDevDirectionDeg added in v1.3.0 

func StdDevDirectionDeg(degrees []Degree) Degree

StdDevDirectionDeg calculates the circular standard deviation of the given set of angles (in degrees). This is useful to find e.g. the variability of wind direction.

func WeightedAvgDirectionDeg added in v1.3.0 

func WeightedAvgDirectionDeg(degrees []Degree, weights []float64) (Degree, error)

WeightedAvgDirectionDeg calculates the weighted circular mean of the given set of angles (in degrees). This is useful to find e.g. the average wind direction, weighted by wind speed.

func WeightedStdDevDirectionDeg added in v1.3.0 

func WeightedStdDevDirectionDeg(degrees []Degree, weights []float64) (Degree, error)

WeightedStdDevDirectionDeg calculates the circular standard deviation of the given set of angles (in degrees). This is useful to find e.g. the variability of wind direction, weighted by wind speed.

func (Degree) Clamped added in v1.3.0 

func (d Degree) Clamped() Degree

Clamped returns an angular direction in degrees guaranteed to be within 0 < d <= 360.

func (Degree) Unwrap added in v1.3.0 

func (d Degree) Unwrap() float64

type DirectionStrPrecision added in v1.3.0 

type DirectionStrPrecision int
const (
	DirectionStrPrecision1 DirectionStrPrecision = 1
	DirectionStrPrecision2 DirectionStrPrecision = 2
	DirectionStrPrecision3 DirectionStrPrecision = 3
)

type HeatIndexWarning added in v1.1.0 

type HeatIndexWarning int

func HeatIndexWarningC added in v1.1.0 

func HeatIndexWarningC(heatIndex TempC) HeatIndexWarning

HeatIndexWarningC returns a heat index warning level for the given heat index temperature (in Celsius) per https://en.wikipedia.org/wiki/Heat_index#Table_of_values captured on 2024-07-17.

func HeatIndexWarningF added in v1.1.0 

func HeatIndexWarningF(heatIndex TempF) HeatIndexWarning

HeatIndexWarningF returns a heat index warning level for the given heat index temperature (in Fahrenheit) per https://en.wikipedia.org/wiki/Heat_index#Table_of_values captured on 2024-07-17.

type Km added in v1.0.0 

type Km float64

Km represents distance in kilometers.

func (Km) Meters added in v1.0.1 

func (km Km) Meters() Meter

Meters returns the distance in meters.

func (Km) Miles added in v1.0.0 

func (km Km) Miles() Mile

Miles returns the distance in miles.

func (Km) NauticalMiles added in v1.0.0 

func (km Km) NauticalMiles() NauticalMile

NauticalMiles returns the distance in nautical miles.

func (Km) Unwrap added in v1.0.0 

func (km Km) Unwrap() float64

type Meter added in v1.0.1 

type Meter float64

Meter represents distance in meters.

func (Meter) Km added in v1.0.1 

func (m Meter) Km() Km

Km returns the distance in kilometers.

func (Meter) Miles added in v1.0.1 

func (m Meter) Miles() Mile

Miles returns the distance in miles.

func (Meter) NauticalMiles added in v1.0.1 

func (m Meter) NauticalMiles() NauticalMile

NauticalMiles returns the distance in nautical miles.

func (Meter) Unwrap added in v1.0.1 

func (m Meter) Unwrap() float64

type Mile added in v1.0.0 

type Mile float64

Mile represents distance in miles.

func (Mile) Km added in v1.0.0 

func (mi Mile) Km() Km

Km returns the distance in kilometers.

func (Mile) Meters added in v1.0.1 

func (mi Mile) Meters() Meter

Meters returns the distance in meters.

func (Mile) NauticalMiles added in v1.0.0 

func (mi Mile) NauticalMiles() NauticalMile

NauticalMiles returns the distance in nautical miles.

func (Mile) Unwrap added in v1.0.0 

func (mi Mile) Unwrap() float64

type NauticalMile added in v1.0.0 

type NauticalMile float64

NauticalMile represents distance in nautical miles.

func (NauticalMile) Km added in v1.0.0 

func (nm NauticalMile) Km() Km

Km returns the distance in kilometers.

func (NauticalMile) Meters added in v1.0.1 

func (nm NauticalMile) Meters() Meter

Meters returns the distance in meters.

func (NauticalMile) Miles added in v1.0.0 

func (nm NauticalMile) Miles() Mile

Miles returns the distance in miles.

func (NauticalMile) Unwrap added in v1.0.0 

func (nm NauticalMile) Unwrap() float64

type PressureInHg 

type PressureInHg float64

PressureInHg represents barometric pressure in inches of mercury.

func (PressureInHg) Mb added in v1.0.0 

func (p PressureInHg) Mb() PressureMb

Mb converts pressure in inches of mercury to millibars.

func (PressureInHg) Unwrap added in v1.0.0 

func (p PressureInHg) Unwrap() float64

type PressureMb 

type PressureMb float64

PressureMb represents barometric pressure in millibars.

func (PressureMb) InHg added in v1.0.0 

func (p PressureMb) InHg() PressureInHg

InHg converts pressure in millibars to inches of mercury.

func (PressureMb) Unwrap added in v1.0.0 

func (p PressureMb) Unwrap() float64

type RelHumidity 

type RelHumidity int

RelHumidity represents a relative humidity percentage (0-100, inclusive).

func ClampedRelHumidity added in v1.0.0 

func ClampedRelHumidity(rh int) RelHumidity

ClampedRelHumidity returns a RelHumidity from the given integer, guaranteed to be within the valid 0-100 (inclusive) range.

func IndoorHumidityRecommendationC 

func IndoorHumidityRecommendationC(outdoorT TempC) RelHumidity

IndoorHumidityRecommendationC returns the maximum recommended indoor relative humidity percentage for the given outdoor temperature (in degrees C).

func IndoorHumidityRecommendationF 

func IndoorHumidityRecommendationF(outdoorT TempF) RelHumidity

IndoorHumidityRecommendationF returns the maximum recommended indoor relative humidity percentage for the given outdoor temperature (in degrees F).

func RelHumidityFromAbsC added in v1.4.0 

func RelHumidityFromAbsC(temp TempC, ah AbsHumidity) RelHumidity

func RelHumidityFromAbsF added in v1.4.0 

func RelHumidityFromAbsF(temp TempF, ah AbsHumidity) RelHumidity

func (RelHumidity) Clamped added in v1.0.0 

func (rh RelHumidity) Clamped() RelHumidity

Clamped returns a relative humidity guaranteed to be within the valid 0-100 (inclusive) range.

func (RelHumidity) Unwrap added in v1.0.0 

func (rh RelHumidity) Unwrap() int

func (RelHumidity) UnwrapFloat64 added in v1.1.0 

func (rh RelHumidity) UnwrapFloat64() float64

type SpeedKmH added in v1.0.0 

type SpeedKmH float64

SpeedKmH represents speed in kilometers per hour.

func (SpeedKmH) Knots added in v1.0.0 

func (s SpeedKmH) Knots() SpeedKnots

Knots returns the speed in knots.

func (SpeedKmH) Mph added in v1.0.0 

func (s SpeedKmH) Mph() SpeedMph

Mph returns the speed in miles per hour.

func (SpeedKmH) Unwrap added in v1.0.0 

func (s SpeedKmH) Unwrap() float64

type SpeedKnots added in v1.0.0 

type SpeedKnots float64

SpeedKnots represents speed in knots.

func (SpeedKnots) KmH added in v1.0.0 

func (s SpeedKnots) KmH() SpeedKmH

KmH returns the speed in kilometers per hour.

func (SpeedKnots) Mph added in v1.0.0 

func (s SpeedKnots) Mph() SpeedMph

Mph returns the speed in miles per hour.

func (SpeedKnots) Unwrap added in v1.0.0 

func (s SpeedKnots) Unwrap() float64

type SpeedMph added in v1.0.0 

type SpeedMph float64

SpeedMph represents speed (e.g. wind speed) in miles per hour.

func (SpeedMph) KmH added in v1.0.0 

func (s SpeedMph) KmH() SpeedKmH

KmH returns the speed in kilometers per hour.

func (SpeedMph) Knots added in v1.0.0 

func (s SpeedMph) Knots() SpeedKnots

Knots returns the speed in knots.

func (SpeedMph) Unwrap added in v1.0.0 

func (s SpeedMph) Unwrap() float64

type TempC 

type TempC float64

TempC represents a temperature in degrees Celsius.

func DewPointC 

func DewPointC(t TempC, rh RelHumidity) TempC

DewPointC calculates the dew point given the current temperature (in Celsius) and relative humidity percentage (an integer 0-100, *not* a float 0.0-1.0).

func HeatIndexC added in v1.1.0 

func HeatIndexC(temp TempC, rh RelHumidity) TempC

HeatIndexC is deprecated; use HeatIndexCWithValidation

func HeatIndexCWithValidation added in v1.2.0 

func HeatIndexCWithValidation(temp TempC, rh RelHumidity) (TempC, error)

HeatIndexCWithValidation calculates the heat index for the given temperature (in Celsius) and relative humidity percentage.

func WetBulbC added in v1.1.0 

func WetBulbC(temp TempC, rh RelHumidity) (TempC, error)

WetBulbC calculates the wet bulb temperature (in Celsius) given a dry bulb temperature (in Celsius) and relative humidity percentage. If the given temperature or relative humidity are outside the supported range, ErrInputRange is returned. See: https://journals.ametsoc.org/view/journals/apme/50/11/jamc-d-11-0143.1.xml

func WetBulbCAtPressure added in v1.5.0 

func WetBulbCAtPressure(temp TempC, rh RelHumidity, pressure PressureMb) (TempC, error)

WetBulbCAtPressure calculates the wet bulb temperature (in Celsius) given a dry bulb temperature (in Celsius), relative humidity percentage, and barometric pressure (in millibars). The supported input ranges are -17 to 40 degrees C, 5-99% relative humidity, and MinWetBulbPressureMb to MaxWetBulbPressureMb (inclusive); if the input is outside these ranges, ErrInputRange is returned. The formula is taken from "Direct Calculation of Thermodynamic Wet-Bulb Temperature as a Function of Pressure and Elevation" (Sadeghi et al., Journal of Atmospheric and Oceanic Technology, 2013). Its stated accuracy is within 0.65 degrees C, with the largest errors occurring at high temperatures combined with very low or very high relative humidity. See: https://journals.ametsoc.org/view/journals/atot/30/8/jtech-d-12-00191_1.xml

func WindChillC 

func WindChillC(temp TempC, windSpeed SpeedMph) TempC

WindChillC calculates the wind chill for the given temperature (in Celsius) and wind speed (in miles/hour). If wind speed is less than 3 mph, or temperature is over 10 degrees C, the given temperature is returned - the formula works below 10 degrees C and above 3 mph.

func WindChillCWithValidation added in v1.1.0 

func WindChillCWithValidation(temp TempC, windSpeed SpeedMph) (TempC, error)

WindChillCWithValidation calculates the wind chill for the given temperature (in Celsius) and wind speed (in miles/hour). If wind speed or temperature are outside the supported range, ErrInputRange is returned.

func (TempC) F added in v1.0.0 

func (t TempC) F() TempF

F converts Celsius temperature to Fahrenheit.

func (TempC) Unwrap added in v1.0.0 

func (t TempC) Unwrap() float64

type TempF 

type TempF float64

TempF represents a temperature in degrees Fahrenheit.

func DewPointF 

func DewPointF(t TempF, rh RelHumidity) TempF

DewPointF calculates the dew point given the current temperature (in Fahrenheit) and relative humidity percentage (an integer 0-100, *not* a float 0.0-1.0).

func HeatIndexF added in v1.1.0 

func HeatIndexF(temp TempF, rh RelHumidity) TempF

HeatIndexF is deprecated; use HeatIndexFWithValidation

func HeatIndexFWithValidation added in v1.2.0 

func HeatIndexFWithValidation(temp TempF, rh RelHumidity) (TempF, error)

HeatIndexFWithValidation calculates the heat index for the given temperature (in Fahrenheit) and relative humidity percentage.

func WetBulbF added in v1.1.0 

func WetBulbF(temp TempF, rh RelHumidity) (TempF, error)

WetBulbF calculates the wet bulb temperature (in Fahrenheit) given a dry bulb temperature (in Fahrenheit) and relative humidity percentage. If the given temperature or relative humidity are outside the supported range, ErrInputRange is returned. See: https://journals.ametsoc.org/view/journals/apme/50/11/jamc-d-11-0143.1.xml

func WetBulbFAtPressure added in v1.5.0 

func WetBulbFAtPressure(temp TempF, rh RelHumidity, pressure PressureMb) (TempF, error)

WetBulbFAtPressure calculates the wet bulb temperature (in Fahrenheit) given a dry bulb temperature (in Fahrenheit), relative humidity percentage, and barometric pressure (in millibars). If the given temperature, relative humidity, or pressure are outside the supported range, ErrInputRange is returned. See: https://journals.ametsoc.org/view/journals/atot/30/8/jtech-d-12-00191_1.xml

func WindChillF 

func WindChillF(t TempF, windSpeed SpeedMph) TempF

WindChillF calculates the wind chill for the given temperature (in Fahrenheit) and wind speed (in miles/hour). If wind speed is less than 3 mph, or temperature is over 50 degrees F, the given temperature is returned - the formula works below 50 degrees F and above 3 mph.

func WindChillFWithValidation added in v1.1.0 

func WindChillFWithValidation(t TempF, windSpeed SpeedMph) (TempF, error)

WindChillFWithValidation calculates the wind chill for the given temperature (in Fahrenheit) and wind speed (in miles/hour). If wind speed or temperature are outside the supported range, ErrInputRange is returned.

func (TempF) C added in v1.0.0 

func (t TempF) C() TempC

C converts Fahrenheit temperature to Celsius.

func (TempF) Unwrap added in v1.0.0 

func (t TempF) Unwrap() float64

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.