truewinds code

truewinds.legacy module

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

truewinds.legacy.full(crse=None, cspd=None, wdir=None, zlr=None, hd=None, adir=None, wspd=None, tdir=None, tspd=None, *args, **kwargs)[source]

truewinds.legacy.missing_values(crse=None, cspd=None, wdir=None, hd=None, wspd=None, tdir=None, tspd=None, wmis=None, *args, **kwargs)[source]

truewinds.legacy.truerr(crse=None, cspd=None, hd=None, wdir=None, wspd=None, wmis=None, nw=None, nwpm=None, nwam=None, nwf=None, *args, **kwargs)[source]

truewinds.legacy.truew(crse=None, cspd=None, wdir=None, zlr=0.0, hd=None, wspd=None, wmis=[-1111.0, -9999.0, 1111.0, 9999.0, 5555.0])[source]

truewinds.legacy.truewinds(sel=None, crse=None, cspd=None, wdir=None, zlr=None, hd=None, wspd=None, wmis=None)[source]

truewinds.truewinds module

Compute the apparent wind direction from the true heading, relative wind direction, and zero line reference.

Parameters:

hdg – The true heading of the vessel or platform in degrees.
rwd – The relative wind direction in degrees.
zlr – The clockwise angle between the bow of the platform and the anemometer reference line in degrees.

Returns:

The apparent wind direction in degrees.

Compute true wind direction and true wind speed from a moving reference frame, such as a vessel or mobile platform.

This function is a vectorized adaptation of the original True Winds Python code written by Mylene Remigio and is based on the work of Smith et al. 1999. To use the original code, please use the legacy module.

Parameters:

cog – Course over ground in degrees. Most often derived from a NMEA0183 VTG message.
sog – Speed over ground. Most often derived from a NMEA0183 VTG message. Units for speed over ground much match relative wind speed (rws) units.
hdg – The true heading of the vessel or platform in degrees. Most often derived from a NMEA0183 HDG message.
rwd – Relative wind direction in degrees from which the wind is blowing. Derived from an anemometer on the platform.
rws – Relative wind speed in the same units as speed over ground (sog). Derived from an anemometer on the platform.
zlr – The clockwise angle between the bow of the platform and the anemometer reference line in degrees. Default is 0.0 degrees.
return_flags – If True, flags are returned with the true wind dictionary.

Returns:

A dictionary containing true wind direction and true wind speed

Compute the u and v components of the true wind vector.

Parameters:

true_wind_direction – True wind direction in degrees.
true_wind_speed – True wind speed in the same units as the speed.

Returns:

A tuple containing the u and v components of the true wind vector.

truewinds.magdec module

truewinds.magdec.dt2dy(dt: datetime) → float[source]: Convert a Pyton datetime object to a float value that represents the decimal year. :param dt: A datetime.datetime object. :return: A float value representing the decimal year.

truewinds.magdec.estimate_magnetic_declination(time: datetime, latitude: float, longitude: float, altitude: float = 0.0, high_resolution: bool = False)[source]

Estimate the magnetic declination at a given time and position using the PyGeomag package.

For data older than 2010, the default coefficients are used.

Parameters:

time – The input time as a datetime object.
latitude – The latitude of the measurement location in degrees.
longitude – The longitude of the measurement location in degrees.
altitude – The altitude of the measurement location in meters. Default is 0.0 m.
high_resolution – If True, use the high-resolution model. Currently, this is only available for time inputs from 2025 onward.

Returns:

The estimated magnetic declination in degrees for the given inputs.

truewinds.qaqc module

class truewinds.qaqc.FLAG[source]

Bases: object

BAD: int = 4

MISSING_VALUE: int = 9

NOT_EVALUATED: int = 0

OK: int = 1

PROBABLY_BAD: int = 3

PROBABLY_OK: int = 2

class truewinds.qaqc.FillValue[source]

Bases: object

COG: float = -1111.0

HEADING: float = 5555.0

SOG: float = -9999.0

WIND_DIR: float = 1111.0

WIND_SPEED: float = 9999.0

truewinds.qaqc.check_zlr(zlr: float) → None[source]

Verify that the zero line reference (zlr) is a valid value. If the input zlr is impossible (value less than 0 or greater than 360), then a ValueError is raised.

Parameters:: zlr – A floating point value representing the zero line reference in degrees.
Returns:: None

truewinds.qaqc.flag_direction(direction: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | int | float) → array[source]: Flag a direction value, in degrees, if it exceeds the gross range of 0 to 360 degrees. :param direction: An array-like object containing direction values in degrees. :return: A numpy array of flags where 1 indicates OK and 4 indicates BAD.

Flag a speed value, in user defined units, if it is less than 0 or exceeds the operator-defined limits.

Parameters:

speed – An array-like object containing speed values.
operator_min – If supplied, values between 0 and the operator_min will be flagged as PROBABLY_OK.
operator_max – If supplied, values exceeding the operator_max will be flagged as PROBABLY_OK.

Returns:

A numpy array of flags where 1 indicates OK, 2 indicates PROBABLY_OK, and 4 indicates BAD.

truewinds.core module

Convert degrees to radians.

Parameters:: degrees – The angle in degrees.
Returns:: Radians.

Convert kilometers per hour to meters per second.

Parameters:: kmph – Speed in kilometers per hour.
Returns:: Speed in meters per second.

Convert knots to meters per second.

Parameters:: knots – Speed in knots.
Returns:: Speed in meters per second.

Convert radians to degrees.

Parameters:: radians – The angle in radians.
Returns:: Degrees.