:py:mod:`gnome.environment.wind` ================================ .. py:module:: gnome.environment.wind .. autoapi-nested-parse:: module contains objects that contain weather related data. For example, the Wind object defines the Wind conditions for the spill Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: gnome.environment.wind.MagnitudeDirectionTuple gnome.environment.wind.Wind Functions ~~~~~~~~~ .. autoapisummary:: gnome.environment.wind.constant_wind gnome.environment.wind.wind_from_values Attributes ~~~~~~~~~~ .. autoapisummary:: gnome.environment.wind.PointWind .. py:class:: MagnitudeDirectionTuple(*arg, **kw) Bases: :py:obj:`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 :class:`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 :attr:`colander.drop`, the node will be dropped from schema serialization. If not provided, the node will be serialized to :attr:`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 :attr:`colander.required`, indicating that it is considered 'required'. When ``missing`` is :attr:`colander.required`, the ``required`` computed attribute will be ``True``. When ``missing`` is :attr:`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 :class:`colander.interfaces.Preparer` interface. - ``validator``: Optional validator for this node. It should be an object that implements the :class:`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. .. py:attribute:: speed .. py:attribute:: direction .. py:class:: 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: :py:obj:`gnome.utilities.timeseries.Timeseries`, :py:obj:`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. :param timeseries=None: :param units=None: :param filename=None: :param coord_sys='r-theta': :param latitude=None: :param longitude=None: :param speed_uncertainty_scale=0.0: :param extrapolation_is_allowed=False: .. py:property:: time .. py: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 .. py:property:: data_start The start time of the valid data for this wind timeseries .. py:property:: data_stop The stop time of the valid data for this wind timeseries .. py:property:: units define units in which wind data is input/output .. py:attribute:: _ref_as :value: 'wind' .. py:attribute:: _gnome_unit :value: 'm/s' .. py:attribute:: _schema .. py:attribute:: valid_vel_units .. py:method:: update_from_dict(dict_, refs=None) .. py:method:: _check_units(units) Checks the user provided units are in list Wind.valid_vel_units .. py:method:: __repr__() Return repr(self). .. py:method:: new_set_timeseries(value, coord_sys) .. py:method:: _convert_units(data, coord_sys, from_unit, to_unit) method to convert units for the 'value' stored in the date/time value pair .. py:method:: _write_timeseries_to_zip(saveloc, ts_name) use a StringIO type of file descriptor and write directly to zipfile .. py:method:: _write_timeseries_to_file(datafile) write timeseries data to file .. py:method:: _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 .. py:method:: 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' :param datetime: [optional] datetime object or list of datetime objects for which the value is desired :type datetime: datetime object :param units: [optional] outputs data in these units. Default is to output data without unit conversion :type units: string. Uses the nucos module. :param coord_sys: output coordinate system for the times series: either 'r-theta' or 'uv' :type coord_sys: either string or integer value defined by basic_types.ts_format.* (see cy_basic_types.pyx) :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 .. py:method:: 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. :param datetime_value_2d: timeseries of wind data defined in a numpy array :type datetime_value_2d: numpy array of dtype basic_types.datetime_value_2d :param units: units associated with the data. Valid units defined in Wind.valid_vel_units list :param coord_sys: output coordinate system for the times series, as defined by basic_types.format. :type coord_sys: either string or integer value defined by basic_types.format.* (see cy_basic_types.pyx) .. py:method:: 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) :param time: the time(s) you want the data for :type time: datetime object or sequence of datetime objects. .. note:: It invokes get_wind_data(..) function .. py:method:: 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. :param 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. :param time: Datetime of the time to be queried :param coord_sys: String describing the coordinate system. .. py:method:: 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. .. py:method:: __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 .. py:method:: validate() only issues warning - object is always valid .. py:data:: PointWind .. py:function:: constant_wind(speed, direction, units='m/s') utility to create a constant wind "timeseries" :param speed: speed of wind :param direction: direction -- direction wind is from (degrees True) :param 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. .. py:function:: wind_from_values(values, units='m/s') Creates a Wind object directly from data. :param values: list of (datetime, speed, direction) tuples :param 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.