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 Attributes ---------- .. autoapisummary:: gnome.environment.wind.PointWind gnome.environment.wind.cardinal_directions Classes ------- .. autoapisummary:: gnome.environment.wind.MagnitudeDirectionTuple gnome.environment.wind.Wind Functions --------- .. autoapisummary:: gnome.environment.wind.constant_wind gnome.environment.wind.wind_from_values gnome.environment.wind.read_ossm_format Module Contents --------------- .. 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, timezone_offset=None, **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. If ``filename`` is specified, then the data will be read from a file. otherwise, all the other attributes must be set. :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: :param timezone_offset: .. py:attribute:: valid_vel_units .. py:attribute:: updated_at .. py:attribute:: source_id .. py:attribute:: longitude :value: None .. py:attribute:: latitude :value: None .. py:attribute:: description .. py:attribute:: speed_uncertainty_scale :value: 0.0 .. py:attribute:: extrapolation_is_allowed :value: False .. py:method:: from_file(filename, format=None) :classmethod: create an object from a file. currently only the OSSM format is supported :param filename: Path to the data file :type PathLike: :param format: File format of data -- only 'ossm' currently supported. If None: it will attempt to auto-detect the format. :type format: str .. py:method:: update_from_dict(dict_, refs=None) .. 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:method:: new_set_timeseries(value, coord_sys) .. 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: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, *, units=None, extrapolate=None, coord_sys='uv', _auto_align=True, **kwargs) 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:: 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 (Point Wind) directly from data. :param values: list of (datetime, speed, direction) tuples :param units: speed units - defaults to "m/s" Any speed unit defined in nucos is acceptable (e.g. knot, mph) Direction is the where the wind is coming from in degrees from North :returns: A :py:class:`gnome.environment.wind.Wind` object that can be used for a wind mover, etc. .. py:data:: cardinal_directions .. py:function:: read_ossm_format(filename) Read any of the three OSSM formats: 3 line header 4 line header -- preferred 5 line header :returns: Times, data, name, timezone offset, timezone, units.