gnome.environment.wind

module contains objects that contain weather related data. For example, the Wind object defines the Wind conditions for the spill

Module Contents

Classes

MagnitudeDirectionTuple	Fundamental building block of schemas.
Wind	Provides a "point wind" -- uniform wind over all space

Functions

constant_wind(speed, direction[, units])	utility to create a constant wind "timeseries"
wind_from_values(values[, units])	Creates a Wind object directly from data.

Attributes

PointWind

class gnome.environment.wind.MagnitudeDirectionTuple(*arg, **kw)

Bases: gnome.persist.DefaultTupleSchema

Fundamental building block of schemas.

The constructor accepts these positional arguments:

• typ: The ‘type’ for this node. It should be an instance of a class that implements the colander.interfaces.Type interface. If typ is not passed, a call to the schema_type() method on this class is made to get a default type. (When subclassing, schema_type() should be overridden to provide a reasonable default type).

• *children: a sequence of subnodes. If the subnodes of this node are not known at construction time, they can later be added via the add method.

The constructor accepts these keyword arguments:

• name: The name of this node.

• typ: The ‘type’ for this node can optionally be passed in as a keyword argument. See the documentation for the positional arg above.

• default: The default serialization value for this node when not set. If default is colander.drop, the node will be dropped from schema serialization. If not provided, the node will be serialized to colander.null.

• missing: The default deserialization value for this node. If it is not provided, the missing value of this node will be the special marker value colander.required, indicating that it is considered ‘required’. When missing is colander.required, the required computed attribute will be True. When missing is colander.drop, the node is dropped from the schema if it isn’t set during deserialization.

• missing_msg: Optional error message to be used if the value is required and missing.

• preparer: Optional preparer for this node. It should be an object that implements the colander.interfaces.Preparer interface.

• validator: Optional validator for this node. It should be an object that implements the colander.interfaces.Validator interface.

• after_bind: A callback which is called after a clone of this node has ‘bound’ all of its values successfully. This callback is useful for performing arbitrary actions to the cloned node, or direct children of the cloned node (such as removing or adding children) at bind time. A ‘binding’ is the result of an execution of the bind method of the clone’s prototype node, or one of the parents of the clone’s prototype nodes. The deepest nodes in the node tree are bound first, so the after_bind methods of the deepest nodes are called before the shallowest. The after_bind callback should accept two values: node and kw. node will be a clone of the bound node object, kw will be the set of keywords passed to the bind method.

• title: The title of this node. Defaults to a titleization of the name (underscores replaced with empty strings and the first letter of every resulting word capitalized). The title is used by higher-level systems (not by Colander itself).

• description: The description for this node. Defaults to '' (the empty string). The description is used by higher-level systems (not by Colander itself).

• widget: The ‘widget’ for this node. Defaults to None. The widget attribute is not interpreted by Colander itself, it is only meaningful to higher-level systems such as Deform.

• insert_before: if supplied, it names a sibling defined by a superclass for its parent node; the current node will be inserted before the named node. It is not useful unless a mapping schema is inherited from another mapping schema, and you need to control the ordering of the resulting nodes.

Arbitrary keyword arguments remaining will be attached to the node object unmolested.

speed

direction

class gnome.environment.wind.Wind(timeseries=None, units=None, filename=None, coord_sys='r-theta', latitude=None, longitude=None, speed_uncertainty_scale=0.0, extrapolation_is_allowed=False, **kwargs)

Bases: gnome.utilities.timeseries.Timeseries, gnome.environment.environment.Environment

Provides a “point wind” – uniform wind over all space

Create a uniform Wind object, representing a time series of wind at a single location, applied over all space.

Parameters:

• timeseries=None –

• units=None –

• filename=None –

• coord_sys='r-theta' –

• latitude=None –

• longitude=None –

• speed_uncertainty_scale=0.0 –

• extrapolation_is_allowed=False –

property time

property timeseries

returns entire timeseries in ‘r-theta’ coordinate system in the units in which the data was entered or as specified by units attribute

property data_start

The start time of the valid data for this wind timeseries

property data_stop

The stop time of the valid data for this wind timeseries

property units

define units in which wind data is input/output

_ref_as = 'wind'

_gnome_unit = 'm/s'

_schema

valid_vel_units

update_from_dict(dict_, refs=None)

_check_units(units)

Checks the user provided units are in list Wind.valid_vel_units

__repr__()

Return repr(self).

new_set_timeseries(value, coord_sys)

_convert_units(data, coord_sys, from_unit, to_unit)

method to convert units for the ‘value’ stored in the date/time value pair

_write_timeseries_to_zip(saveloc, ts_name)

use a StringIO type of file descriptor and write directly to zipfile

_write_timeseries_to_file(datafile)

write timeseries data to file

_write_timeseries_to_fd(fd)

Takes a general file descriptor as input and writes data to it.

Writes the “OSSM format” with the full header

get_wind_data(datetime=None, units=None, coord_sys='r-theta')

Returns the timeseries in the requested coordinate system. If datetime=None, then the original timeseries that was entered is returned. If datetime is a list containing datetime objects, then the value for each of those date times is determined by the underlying C++ object and the timeseries is returned.

The output coordinate system is defined by the strings ‘r-theta’, ‘uv’

Parameters:

• datetime (datetime object) – [optional] datetime object or list of datetime objects for which the value is desired

• units (string. Uses the nucos module.) – [optional] outputs data in these units. Default is to output data without unit conversion

• coord_sys (either string or integer value defined by basic_types.ts_format.* (see cy_basic_types.pyx)) – output coordinate system for the times series: either ‘r-theta’ or ‘uv’

Returns:

numpy array containing dtype=basic_types.datetime_value_2d. Contains user specified datetime and the corresponding values in user specified ts_format

Note

Invokes self._convert_units() to do the unit conversion. Override this method to define the derived object’s unit conversion functionality

todo: return data in appropriate significant digits

set_wind_data(wind_data, units, coord_sys='r-theta')

Sets the timeseries of the Wind object to the new value given by a numpy array. The coordinate system for the input data defaults to basic_types.format.magnitude_direction but can be changed by the user. Units are also required with the data.

Parameters:

• datetime_value_2d (numpy array of dtype basic_types.datetime_value_2d) – timeseries of wind data defined in a numpy array

• units – units associated with the data. Valid units defined in Wind.valid_vel_units list

• coord_sys (either string or integer value defined by basic_types.format.* (see cy_basic_types.pyx)) – output coordinate system for the times series, as defined by basic_types.format.

get_value(time)

Return the value at specified time and location. Wind timeseries are independent of location; however, a gridded datafile may require location so this interface may get refactored if it needs to support different types of wind data. It returns the data in SI units (m/s) in ‘r-theta’ coordinate system (speed, direction)

Parameters:

time (datetime object or sequence of datetime objects.) – the time(s) you want the data for

Note

It invokes get_wind_data(..) function

at(points, time, coord_sys='uv', units=None, extrapolate=False, _auto_align=True)

Returns the value of the wind at the specified points at the specified time. Valid coordinate systems include ‘r-theta’, ‘r’, ‘theta’, ‘uv’, ‘u’ or ‘v’. This function is for API compatibility with the new environment objects.

Parameters:

• points – Nx2 or Nx3 array of positions (lon, lat, [z]). This may be None: this is a spatially independent wind - value is the same for all points.

• time – Datetime of the time to be queried

• coord_sys – String describing the coordinate system.

set_speed_uncertainty(up_or_down=None)

This function shifts the wind speed values in our time series based on a single parameter Rayleigh distribution method, and scaled by a value in the range [0.0 … 0.5]. This range represents a plus-or-minus percent of uncertainty that the distribution function should calculate

For each wind value in our time series:

• We assume it to be the average speed for that sample time

• We calculate its respective Rayleigh distribution mode (sigma).

• We determine either an upper percent uncertainty or a lower percent uncertainty based on a passed in parameter.

• Using the Rayleigh Quantile method and our calculated percent, we determine the wind speed that is just at or above the fractional area under the Probability distribution.

• We assign the wind speed to its new calculated value.

Since we are irreversibly changing the wind speed values, we should probably do this only once.

__eq__(other)

invoke super to check equality for all ‘save’ parameters. Also invoke __eq__ for Timeseries object to check equality of timeseries. Super is not used in any of the __eq__ methods

validate()

only issues warning - object is always valid

gnome.environment.wind.PointWind

gnome.environment.wind.constant_wind(speed, direction, units='m/s')

utility to create a constant wind “timeseries”

Parameters:

• speed – speed of wind

• direction – direction – direction wind is from (degrees True)

• unit='m/s' – units for speed, as a string, i.e. “knots”, “m/s”, “cm/s”, etc.

Note

The time for a constant wind timeseries is irrelevant. This function simply sets it to datetime.now() accurate to hours.

gnome.environment.wind.wind_from_values(values, units='m/s')

Creates a Wind object directly from data.

Parameters:

• values – list of (datetime, speed, direction) tuples

• units='m/s' – speed units.

Direction is the where the wind is coming from in degrees from North

Returns:

A Wind timeseries object that can be used for a wind mover, etc.