:py:mod:`gnome.environment` =========================== .. py:module:: gnome.environment .. autoapi-nested-parse:: environment module Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 environment/index.rst environment_objects/index.rst grid/index.rst gridcur/index.rst gridded_objects_base/index.rst names/index.rst running_average/index.rst tide/index.rst timeseries_objects_base/index.rst water/index.rst waves/index.rst wind/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: gnome.environment.Environment gnome.environment.WindTS gnome.environment.GridCurrent gnome.environment.GridWind gnome.environment.IceVelocity gnome.environment.IceConcentration gnome.environment.GridTemperature gnome.environment.IceAwareCurrent gnome.environment.IceAwareWind gnome.environment.TemperatureTS gnome.environment.FileGridCurrent gnome.environment.SteadyUniformCurrent gnome.environment.Water gnome.environment.Waves gnome.environment.Tide gnome.environment.Wind gnome.environment.RunningAverage gnome.environment.TimeseriesData gnome.environment.TimeseriesVector gnome.environment.PyGrid gnome.environment.VectorVariable gnome.environment.Variable gnome.environment.Grid Functions ~~~~~~~~~ .. autoapisummary:: gnome.environment.env_from_netCDF gnome.environment.ice_env_from_netCDF gnome.environment.from_gridcur gnome.environment.constant_wind gnome.environment.wind_from_values Attributes ~~~~~~~~~~ .. autoapisummary:: gnome.environment.base_classes gnome.environment.helper_functions gnome.environment.env_objs gnome.environment.schemas gnome.environment.ts_property gnome.environment.__all__ .. py:class:: Environment(make_default_refs=True, **kwargs) Bases: :py:obj:`gnome.gnomeobject.GnomeId` A base class for all classes in environment module. This is primarily to define a dtype such that the OrderedCollection defined in the Model object requires it. base class for environment objects :param name=None: .. py:property:: data_start :abstractmethod: .. py:property:: data_stop :abstractmethod: .. py:attribute:: _subclasses :value: [] .. py:attribute:: _ref_as :value: 'environment' .. py:attribute:: __metaclass__ .. py:method:: at(points, time, units=None) :abstractmethod: Find the value of the property at positions P at time T :param points: Coordinates to be queried (lon, lat, depth) :type points: Nx3 numpy array :param time: The time at which to query these points (T) :type time: datetime.datetime object :param units=None: units the values will be returned in (or converted to) if None, the default units for the environment type will be used. :type units: string such as ('m/s', 'knots', etc) :param extrapolate=False: if True, extrapolation will be supported :type extrapolate: boolean (True or False) :return: returns a Nx2 or Nx3 array of interpolated values :rtype: Nx2 or Nx3 numpy array of values .. py:method:: prepare_for_model_run(model_time) Override this method if a derived environment class needs to perform any actions prior to a model run .. py:method:: prepare_for_model_step(model_time) Override this method if a derived environment class needs to perform any actions prior to a model run .. py:method:: post_model_run() Override this method if a derived environment class needs to perform any actions after a model run is complete (StopIteration triggered) .. py:function:: env_from_netCDF(filename=None, dataset=None, grid_file=None, data_file=None, _cls_list=None, **kwargs) Returns a list of instances of environment objects that can be produced from a file or dataset. These instances will be created with a common underlying grid, and will interconnect when possible. For example, if an IceAwareWind can find an existing IceConcentration, it will use it instead of instantiating another. This function tries ALL gridded types by default. This means if a particular subclass of object is possible to be built, it is likely that all it's parents will be built and included as well. If you wish to limit the types of environment objects that will be used, pass a list of the types using "_cls_list" kwarg .. py:function:: ice_env_from_netCDF(filename=None, **kwargs) A short function to generate a list of all the 'ice_aware' classes for use in env_from_netCDF (this excludes GridCurrent, GridWind, GridTemperature, etc.) .. py:class:: WindTS(name=None, units=None, time=None, variables=None, **kwargs) Bases: :py:obj:`VelocityTS`, :py:obj:`gnome.environment.environment.Environment` Base class for multiple data sources aligned along the same single time dimension A class that represents a vector natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time. :param name: Name of the Property :type name: string :param units: Unit of the underlying data :type units: string :param time: Time axis of the data :type time: [] of datetime.datetime, netCDF4.Variable, or Time object :param variables: component data arrays :type variables: [] of TimeseriesData or numpy.array (Max len=2) .. py:attribute:: _ref_as :value: 'wind' .. py:method:: constant_wind(name='Constant Wind', speed=None, direction=None, units='m/s') :classmethod: :param speed: speed of wind :param direction: direction -- degrees True, direction wind is from (degrees True) :param unit='m/s': units for speed, as a string, i.e. "knots", "m/s", "cm/s", etc. .. py:class:: GridCurrent(angle=None, **kwargs) Bases: :py:obj:`VelocityGrid`, :py:obj:`gnome.environment.environment.Environment` GridCurrent is VelocityGrid that adds specific stuff for currents: - Information about how to find currents in netCDF file - Ability to apply an angle adjustment of grid-aligned currents - overloading the memorization to memoize the angle-adjusted current. - add a get_data_vectors() provides magnitude, direction -- used to draw the currents in a GUI loading code for netcdf files for gridded currents, and an interpolation (`.at`), function that provides caching :param angle: scalar field of cell rotation angles (for rotated/distorted grids) .. py:attribute:: _ref_as :value: 'current' .. py:attribute:: _gnome_unit :value: 'm/s' .. py:attribute:: default_names .. py:attribute:: cf_names .. py:method:: at(points, time, *args, **kwargs) Find the value of the property at positions P at time T :param points: Coordinates to be queried (P) :type points: Nx2 or Nx3 array of double :param time: The time at which to query these points (T) :type time: datetime.datetime object :param units: units the values will be returned in (or converted to) :type units: string such as ('m/s', 'knots', etc) :param extrapolate: if True, extrapolation will be supported :type extrapolate: boolean (True or False) :return: returns a Nx2 array of interpolated values :rtype: double .. py:class:: GridWind(wet_dry_mask=None, *args, **kwargs) Bases: :py:obj:`VelocityGrid`, :py:obj:`gnome.environment.environment.Environment` Gridded winds -- usually from netcdf files from meteorological models. This will most often be initialized from netcdf files as: wind = GridWind.from_netCDF(filename="a/path/to/a/netcdf_file.nc") filename can be: * An already open netCDF4 Dataset * A single path to a netcdf file * A list of paths to a set of netcdf files with timeseries :param angle: scalar field of cell rotation angles (for rotated/distorted grids) .. py:attribute:: _ref_as :value: 'wind' .. py:attribute:: _gnome_unit :value: 'm/s' .. py:attribute:: default_names .. py:attribute:: cf_names .. py:method:: at(points, time, coord_sys='uv', _auto_align=True, **kwargs) Find the value of the property at positions P at time T :param points: Coordinates to be queried (P) :type points: Nx2 array of double :param time: The time at which to query these points (T) :type time: datetime.datetime object :param depth: Specifies the depth level of the variable :type depth: integer :param units: units the values will be returned in (or converted to) :type units: string such as ('m/s', 'knots', etc) :param extrapolate: if True, extrapolation will be supported :type extrapolate: boolean (True or False) :param coord_sys: String describing the coordinate system to be used. :type coord_sys: string, one of ('uv','u','v','r-theta','r','theta') :return: returns a Nx2 array of interpolated values :rtype: double .. py:method:: transform_result(value, coord_sys) .. py:method:: get_start_time() .. py:method:: get_end_time() .. py:class:: IceVelocity(angle=None, **kwargs) Bases: :py:obj:`VelocityGrid`, :py:obj:`gnome.environment.environment.Environment` A class for assigning a unique ID for an object :param angle: scalar field of cell rotation angles (for rotated/distorted grids) .. py:attribute:: _ref_as :value: ['ice_velocity', 'ice_aware'] .. py:attribute:: _gnome_unit :value: 'm/s' .. py:attribute:: default_names .. py:attribute:: cf_names .. py:class:: IceConcentration(*args, **kwargs) Bases: :py:obj:`gnome.environment.gridded_objects_base.Variable`, :py:obj:`gnome.environment.environment.Environment` Variable object: represents a field of values associated with the grid. Abstractly, it is usually a scalar physical property such a temperature, salinity that varies over a the domain of the model. This more or less maps to a variable in a netcdf file, but does not have to come form a netcdf file, and this provides and abstraction where the user can access the value in world coordinates, interpolated from the grid. It holds a reference to its own grid object, and its data. This class represents a value defined on a grid :param name: Name :type name: string :param units: Units :type units: string :param time: Time axis of the data :type time: list of `datetime.datetime`, netCDF4 Variable, or Time object :param data: Underlying data source :type data: array-like object such as netCDF4.Variable or numpy.ndarray :param grid: Grid that the data corresponds with :type grid: Grid object (pysgrid or pyugrid or ) :param data_file: Name of data source file :type data_file: string :param grid_file: Name of grid source file :type grid_file: string :param varname: Name of the variable in the data source file :type varname: string :param fill_value: the fill value used for undefined data :param location: location on the grid -- possible values depend on the grid type :type location: str :param attributes: attributes associated with the Variable (analogous to netcdf variable attributes) :type attributes: dict .. py:attribute:: _ref_as :value: ['ice_concentration', 'ice_aware'] .. py:attribute:: default_names .. py:attribute:: cf_names .. py:attribute:: _gnome_unit :value: 'fraction' .. py:class:: GridTemperature(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs) Bases: :py:obj:`gnome.environment.gridded_objects_base.Variable`, :py:obj:`gnome.environment.environment.Environment` Variable object: represents a field of values associated with the grid. Abstractly, it is usually a scalar physical property such a temperature, salinity that varies over a the domain of the model. This more or less maps to a variable in a netcdf file, but does not have to come form a netcdf file, and this provides and abstraction where the user can access the value in world coordinates, interpolated from the grid. It holds a reference to its own grid object, and its data. This class represents a value defined on a grid :param name: Name :type name: string :param units: Units :type units: string :param time: Time axis of the data :type time: list of `datetime.datetime`, netCDF4 Variable, or Time object :param data: Underlying data source :type data: array-like object such as netCDF4.Variable or numpy.ndarray :param grid: Grid that the data corresponds with :type grid: Grid object (pysgrid or pyugrid or ) :param data_file: Name of data source file :type data_file: string :param grid_file: Name of grid source file :type grid_file: string :param varname: Name of the variable in the data source file :type varname: string :param fill_value: the fill value used for undefined data :param location: location on the grid -- possible values depend on the grid type :type location: str :param attributes: attributes associated with the Variable (analogous to netcdf variable attributes) :type attributes: dict .. py:attribute:: default_names .. py:attribute:: cf_names .. py:attribute:: _gnome_unit :value: 'K' .. py:attribute:: _default_unit_type :value: 'Temperature' .. py:class:: IceAwareCurrent(ice_velocity=None, ice_concentration=None, *args, **kwargs) Bases: :py:obj:`GridCurrent` IceAwareCurrent is a GridCurrent that modulates the usual water velocity field using ice velocity and concentration information. While under 20% ice coverage, queries will return water velocity. Between 20% and 80% coverage, queries will interpolate linearly between water and ice velocity Above 80% coverage, queries will return the ice velocity. :param ice_velocity: VectorVariable representing surface ice velocity :type ice_velocity: VectorVariable or compatible object :param ice_concentration: Variable representing surface ice concentration :type ice_concentration: Variable or compatible object .. py:attribute:: _ref_as :value: ['current', 'ice_aware'] .. py:attribute:: _req_refs .. py:attribute:: _schema .. py:method:: from_netCDF(*args, **kwargs) :classmethod: create a new VectorVariable object from a netcdf file See init_from_netcdf for signature .. py:method:: init_from_netCDF(ice_file=None, ice_concentration=None, ice_velocity=None, *args, **kwargs) Allows one-function initialization of a VectorVariable from a file. :param filename: Default data source. Parameters below take precedence :param varnames: Names of the variables in the data source file :param grid_topology: Description of the relationship between grid attributes and variable names. :param name: Name of property :param units: Units :param time: Time axis of the data :param data: Underlying data source :param grid: Grid that the data corresponds with :param dataset: Instance of open Dataset :param data_file: Name of data source file :param grid_file: Name of grid source file :type filename: string :type varnames: [] of string :type grid_topology: {string : string, ...} :type name: string :type units: string :type time: [] of datetime.datetime, netCDF4 Variable, or Time object :type data: netCDF4.Variable or numpy.array :type grid: pysgrid or pyugrid :type dataset: netCDF4.Dataset :type data_file: string :type grid_file: string .. py:method:: at(points, time, *args, **kwargs) Find the value of the property at positions P at time T :param points: Coordinates to be queried (P) :type points: Nx2 or Nx3 array of double :param time: The time at which to query these points (T) :type time: datetime.datetime object :param units: units the values will be returned in (or converted to) :type units: string such as ('m/s', 'knots', etc) :param extrapolate: if True, extrapolation will be supported :type extrapolate: boolean (True or False) :return: returns a Nx2 array of interpolated values :rtype: double .. py:class:: IceAwareWind(ice_concentration=None, *args, **kwargs) Bases: :py:obj:`GridWind` Gridded winds -- usually from netcdf files from meteorological models. This will most often be initialized from netcdf files as: wind = GridWind.from_netCDF(filename="a/path/to/a/netcdf_file.nc") filename can be: * An already open netCDF4 Dataset * A single path to a netcdf file * A list of paths to a set of netcdf files with timeseries :param angle: scalar field of cell rotation angles (for rotated/distorted grids) .. py:attribute:: _ref_as :value: ['wind', 'ice_aware'] .. py:attribute:: _req_refs .. py:attribute:: _schema .. py:method:: from_netCDF(ice_concentration=None, ice_velocity=None, **kwargs) :classmethod: create a new VectorVariable object from a netcdf file See init_from_netcdf for signature .. py:method:: at(points, time, min_val=0, *args, **kwargs) Find the value of the property at positions P at time T :param points: Coordinates to be queried (P) :type points: Nx2 array of double :param time: The time at which to query these points (T) :type time: datetime.datetime object :param depth: Specifies the depth level of the variable :type depth: integer :param units: units the values will be returned in (or converted to) :type units: string such as ('m/s', 'knots', etc) :param extrapolate: if True, extrapolation will be supported :type extrapolate: boolean (True or False) :param coord_sys: String describing the coordinate system to be used. :type coord_sys: string, one of ('uv','u','v','r-theta','r','theta') :return: returns a Nx2 array of interpolated values :rtype: double .. py:class:: TemperatureTS(name=None, units='K', time=None, data=None, **kwargs) Bases: :py:obj:`gnome.environment.timeseries_objects_base.TimeseriesData`, :py:obj:`gnome.environment.environment.Environment` Base class for data with a single dimension: time A class that represents a natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time. EnvProp is the base class, and returns only a single value regardless of the time. :param name: Name :type name: string :param units: Units :type units: string :param time: Time axis of the data :type time: [] of datetime.datetime, netCDF4.Variable, or Time object :param data: Value of the property :type data: array-like .. py:attribute:: _gnome_unit :value: 'K' .. py:method:: constant_temperature(name='Constant Temperature', temperature=None, units='K') :classmethod: .. py:class:: FileGridCurrent(filename=None, extrapolation_is_allowed=False, *args, **kwargs) Bases: :py:obj:`GridCurrent` class that presents an interface for GridCurrent loaded from files of various formats Done as a class to provide a Schema for the persistence system And to provide a simple interface to making a current from a file. :param angle: scalar field of cell rotation angles (for rotated/distorted grids) .. py:attribute:: _schema .. py:method:: init_from_gridcur(filename, extrapolation_is_allowed, **kwargs) Wrapper for external initalize function .. py:method:: new_from_dict(serial_dict) :classmethod: creates a new object from dictionary This is base implementation and can be over-ridden by classes using this mixin .. py:class:: SteadyUniformCurrent(speed, direction, units='m/s', name='Steady Uniform Current') Bases: :py:obj:`gnome.environment.environment.Environment` Simple current: the same at all time and places Create a steady, uniform current (same at all time and places) :param speed: speed of the current :param direction: direction of the current (direction to, not from), in degrees from north :param units="m/s": units of speed: defaults to "m/s" :param name="Steady Uniform Current": optional name for the current .. py:property:: speed .. py:property:: direction .. py:property:: u .. py:property:: v .. py:attribute:: _ref_as :value: 'current' .. py:attribute:: _schema .. py:attribute:: data_start .. py:attribute:: data_stop .. py:method:: __repr__() Return repr(self). .. py:method:: _set_uv() .. py:method:: at(points, time, units=None) Find the value of the property at positions of points at time T :param points: will be ignored :param time: will be ignored :param units='m/s': units the values will be returned in (or converted to) if None, the default units for the environment type will be used. :type units: string such as ('m/s', 'knots', etc) :return: returns an Nx2 arrary is points is Nx2, Nx3 is points is Nx3 .. py:function:: from_gridcur(filename, extrapolation_is_allowed=False, **kwargs) factory function to make a GridCurrent from a gridcur file :param filename: name (full path) of the gridcur file to load :param extrapolation_is_allowed=False: passes other keyword arguments on to GridCurrent initilizer .. py:class:: Water(temperature=300.0, salinity=35.0, sediment=0.005, wave_height=None, fetch=None, units=None, name='Water', **kwargs) Bases: :py:obj:`gnome.environment.environment.Environment` Define the environmental conditions for a spill, like water_temperature, Single values for all all time and space Defined in a Serializable class since user will need to set/get some of these properties through the client Includes attributes with a Environment interface: Temperature Salinity Sediment WaveHeight Example: water.Temperature.at(points, time, unit) Assume units are SI for all properties. 'units' attribute assumes SI by default. This can be changed, but initialization takes SI. Units is dict, with some subset of these keys:: { 'temperature': 'K', 'salinity': 'psu', 'sediment': 'kg/m^3', 'wave_height': 'm', 'fetch': 'm', } So to set units of temperature to F: ``units = {'temperature': 'F'}`` .. py:property:: data_start The Water object doesn't directly manage a time series of data, so it will not have a data range. We will just return an infinite range for Water. .. py:property:: data_stop .. py:property:: density return the density based on water salinity and temperature. The salinity is in 'psu'; it is not being converted to absolute salinity units - for our purposes, this is sufficient. Using gsw.rho() internally which expects salinity in absolute units. .. py:property:: units .. py:attribute:: _ref_as :value: 'water' .. py:attribute:: _field_descr .. py:attribute:: _schema .. py:attribute:: _units_type .. py:attribute:: _gnome_units .. py:attribute:: __str__ .. py:method:: __repr__() Return repr(self). .. py:method:: get(attr, unit=None) return value in desired unit. If None, then return the value in SI units. The user_unit are given in 'units' attribute and each attribute carries the value in as given in these user_units. .. py:method:: set(attr, value, unit) provide a corresponding set method that requires value and units The attributes can be directly set. This function just sets the desired property and also updates the units dict .. py:method:: _get_density(salinity, temp, temp_units) :staticmethod: use lru cache so we don't recompute if temp is not changing .. py:method:: _convert_sediment_units(from_, to) used internally to convert to/from sediment units. .. py:class:: Waves(wind=None, water=None, **kwargs) Bases: :py:obj:`gnome.environment.environment.Environment` class to compute the wave height for a time series At the moment, it only does a single point, non spatially variable, but may be extended in the future wind and water must be set before running the model; however, these can be set after object construction :param wind: A wind object to get the wind speed. This should be a moving average wind object. :type wind: A Wind type, or equivelent :param water: water properties, specifically fetch and wave height :type water: environment.Water object. .. note:: must take ``**kwargs`` since base class supports more inputs like 'name'. The new_from_dict() alternate constructor will invoke __init__ will arguments that supported by baseclass .. py:property:: data_start The Waves object doesn't directly manage a time series of data, so it will not have a data range itself. But it depends upon a Wind and a Water object. The Water won't have a data range either, but the Wind will. So its data range will be that of the Wind it is associated with. .. py:property:: data_stop .. py:attribute:: _ref_as :value: 'waves' .. py:attribute:: _req_refs :value: ['wind', 'water'] .. py:attribute:: _schema .. py:method:: validate() All pygnome objects should be able to validate themselves. Many py_gnome objects reference other objects like wind, water, waves. These may not be defined when object is created so they can be None at construction time; however, they should reference valid objects when running in the model. If make_default_refs is True, then object is valid because the model will set these up at runtime. To raise an exception for missing references at runtime, directly call validate_refs(level='error') 'wind', 'water', 'waves' attributes also have special meaning. An object containing this attribute references the corresponding object. Logs warnings: :returns: a tuple of length two containing: (a list of messages that were logged, isvalid bool) If any references are missing and make_default_refs is False, object is not valid .. note: validate() only logs warnings since it designed to be used to validate before running model. To log these as errors during model run, invoke validate_refs() directly. .. py:method:: get_value(points, time) return the rms wave height, peak period and percent wave breaking at a given time. Does not currently support location-variable waves. :param time: the time you want the wave data for :type time: datetime.datetime object :returns: wave_height, peak_period, whitecap_fraction, dissipation_energy Units: wave_height: meters (RMS height) peak_period: seconds whitecap_fraction: unit-less fraction dissipation_energy: not sure!! # fixme! .. py:method:: get_wind_speed(points, model_time, coord_sys='r', fill_value=1.0) Wrapper for the weatherers so they can extrapolate .. py:method:: get_emulsification_wind(points, time) Return the right wind for the wave climate If a wave height was specified, then you need the greater of the real or pseudo wind. If not, then you need the actual wind. The idea here is that if there is a low wind, but the user specified waves, we really want emulsification that makes sense for the waves. But if the actual wind is stronger than that for the wave height give, we should use the actual wind. fixme: I'm not sure this is right -- if we stick with the wave energy given by the user for dispersion, why not for emulsification? .. py:method:: compute_H(U) .. py:method:: pseudo_wind(H) .. py:method:: whitecap_fraction(U) .. py:method:: mean_wave_period(U) .. py:method:: peak_wave_period(points, time) :param time: the time you want the wave data for :type time: datetime.datetime object :returns: peak wave period (s) .. py:method:: dissipative_wave_energy(H) .. py:method:: energy_dissipation_rate(H, U) c_ub = 100 = dimensionless empirical coefficient to correct for non-Law-of-the-Wall results (Umlauf and Burchard, 2003) u_c = water friction velocity (m/s) sqrt(rho_air / rho_w) * u_a ~ .03 * u_a u_a = air friction velocity (m/s) z_0 = surface roughness (m) (Taylor and Yelland) c_p = peak wave speed for Pierson-Moskowitz spectrum w_p = peak angular frequency for Pierson-Moskowitz spectrum (1/s) TODO: This implementation should be in a utility function. It should not be part of the Waves management object itself. .. py:class:: Tide(filename, yeardata=os.path.join(os.path.dirname(gnome.__file__), 'data', 'yeardata'), scale_factor=None, **kwargs) Bases: :py:obj:`gnome.environment.environment.Environment` todo: baseclass called ScaleTimeseries (or something like that) ScaleCurrent Define the tide for a spill Currently, this internally defines and uses the CyShioTime object, which is a cython wrapper around the C++ Shio object Tide information can be obtained from a filename or set as a timeseries (timeseries is NOT TESTED YET) It requires one of the following to initialize: 1. 'timeseries' assumed to be in 'uv' format (NOT TESTED/IMPLEMENTED OR USED YET) 2. a 'filename' containing a header that defines units amongst other meta data :param timeseries: numpy array containing tide data :type timeseries: numpy.ndarray with dtype=datetime_value_1d :param units: units associated with the timeseries data. If 'filename' is given, then units are read in from the filename. unit conversion - NOT IMPLEMENTED YET :type units=None: (Optional) string, for example: 'knot', 'meter per second', 'mile per hour' etc :param filename: path to a long wind filename from which to read wind data :param yeardata='gnome/data/yeardata/': path to yeardata used for Shio data. .. py:property:: extrapolation_is_allowed .. py:property:: data_start .. py:property:: data_stop .. py:property:: yeardata .. py:attribute:: _ref_as :value: 'tide' .. py:attribute:: _schema .. py:attribute:: scale_factor .. py:method:: _obj_to_create(filename) open file, read a few lines to determine if it is an ossm file or a shio file .. 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: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. .. py:class:: RunningAverage(wind=None, timeseries=None, past_hours_to_average=3, **kwargs) Bases: :py:obj:`gnome.environment.environment.Environment` Defines a running average time series for a wind or tide Initializes a running average object from a wind and past hours to average If no wind is given, timeseries gets initialized as:: timeseries = np.zeros((1,), dtype=basic_types.datetime_value_2d) (note: probably should be an error) All other keywords are optional. Optional parameters (kwargs): :param past_hours_to_average=3: duration of time average window Units are always 'mps' .. py:property:: past_hours_to_average .. py:property:: timeseries .. py:attribute:: _schema .. py:method:: __repr__() Return repr(self). .. py:method:: __str__() Return str(self). .. py:method:: _convert_to_time_value_pair(datetime_value_2d) fmt datetime_value_2d so it is a numpy array with dtype=basic_types.time_value_pair as the C++ code expects .. py:method:: get_timeseries(datetime=None) Returns the timeseries in the requested format. If datetime=None, then the original timeseries that was entered is returned. If datetime is a list containing datetime objects, then the wind value for each of those date times is determined by the underlying CyOSSMTime object and the timeseries is returned. The output format 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 :returns: numpy array containing dtype=basic_types.datetime_value_2d. Contains user specified datetime and the corresponding values in 'm/s' and 'uv' format .. py:method:: prepare_for_model_run(model_time) Make sure we are up to date with the referenced time series .. py:method:: prepare_for_model_step(model_time) Make sure we are up to date with the referenced time series .. py:method:: create_running_average_timeseries(past_hours_to_average, model_time=0) Creates the timeseries of the RunningAverage object :param past_hours_to_average: amount of data to use in the averaging .. py:method:: get_value(time) Return the value at specified time and location. 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 data. It assumes the data in SI units (m/s) and 'uv' format .. note:: It invokes get_timeseries(..) function .. py:class:: TimeseriesData(data=None, time=None, units=None, extrapolate=True, *args, **kwargs) Bases: :py:obj:`gnome.gnomeobject.GnomeId` Base class for data with a single dimension: time A class that represents a natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time. EnvProp is the base class, and returns only a single value regardless of the time. :param name: Name :type name: string :param units: Units :type units: string :param time: Time axis of the data :type time: [] of datetime.datetime, netCDF4.Variable, or Time object :param data: Value of the property :type data: array-like .. py:property:: timeseries Creates a representation of the time series :rtype: list of (datetime, double) tuples .. py:property:: data .. py:property:: time .. py:attribute:: _schema .. py:attribute:: _gnome_unit .. py:method:: constant(name=None, units=None, data=None) :classmethod: .. py:method:: at(points, time, units=None, extrapolate=None, auto_align=True, **kwargs) Interpolates this property to the given points at the given time with the units specified. :param points: A Nx2 array of lon,lat points :param time: A datetime object. May be None; if this is so, the variable is assumed to be gridded but time-invariant :param units: The units that the result would be converted to .. py:method:: in_units(unit) Returns a full cpy of this property in the units specified. WARNING: This will cpy the data of the original property! :param units: Units to convert to :type units: string :return: Copy of self converted to new units :rtype: Same as self .. py:method:: is_constant() .. py:class:: TimeseriesVector(variables=None, time=None, units=None, *args, **kwargs) Bases: :py:obj:`gnome.gnomeobject.GnomeId` Base class for multiple data sources aligned along the same single time dimension A class that represents a vector natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time. :param name: Name of the Property :type name: string :param units: Unit of the underlying data :type units: string :param time: Time axis of the data :type time: [] of datetime.datetime, netCDF4.Variable, or Time object :param variables: component data arrays :type variables: [] of TimeseriesData or numpy.array (Max len=2) .. py:property:: time Time axis of data. I :rtype: gnome.environment.property.Time .. py:property:: units Units of underlying data :rtype: string .. py:property:: varnames Names of underlying variables :rtype: [] of strings .. py:attribute:: _schema .. py:attribute:: _gnome_unit .. py:method:: _check_consistency() :abstractmethod: Checks that the attributes of each GriddedProp in varlist are the same as the GridVectorProp .. py:method:: at(points, time, units=None, *args, **kwargs) Find the value of the property at positions P at time T TODO: What are the argument names for time and time level really? :param points: Coordinates to be queried (P) :type points: Nx2 array of double :param time: The time at which to query these points (T) :type time: datetime.datetime object :param time: Specifies the time level of the variable :type time: integer :param units: units the values will be returned in (or converted to) :type units: string such as ('m/s', 'knots', etc) :param extrapolate: if True, extrapolation will be supported :type extrapolate: boolean (True or False) :return: returns a Nx2 array of interpolated values :rtype: double .. py:class:: PyGrid Bases: :py:obj:`gridded.grids.Grid` Factory class that generates grid objects. Also handles common loading and parsing operations Init common to all Grid types. This constructor will take all the kwargs of both pyugrid.UGrid and pysgrid.SGrid. See their documentation for details :param filename: Name of the file this grid was constructed from, if available. .. py:method:: from_netCDF(*args, **kwargs) :staticmethod: :param filename: File containing a grid :param dataset: Takes precedence over filename, if provided. :param grid_type: Must be provided if Dataset does not have a 'grid_type' attribute, or valid topology variable :param grid_topology: A dictionary mapping of grid attribute to variable name. Takes precedence over discovered attributes :param kwargs: All kwargs to SGrid, UGrid, or RGrid are valid, and take precedence over all. :returns: Instance of Grid_U, Grid_S, or Grid_R .. py:method:: new_from_dict(dict_) :staticmethod: .. py:method:: _get_grid_type(*args, **kwargs) :staticmethod: .. py:class:: VectorVariable(extrapolation_is_allowed=False, *args, **kwargs) Bases: :py:obj:`gridded.VectorVariable`, :py:obj:`gnome.gnomeobject.GnomeId` A class for assigning a unique ID for an object .. py:property:: extrapolation_is_allowed .. py:property:: data_start .. py:property:: data_stop .. py:attribute:: _schema .. py:attribute:: _default_component_types .. py:attribute:: _gnome_unit .. py:method:: __repr__() Return repr(self). .. py:method:: init_from_netCDF(filename=None, varnames=None, grid_topology=None, name=None, units=None, time=None, time_origin=None, grid=None, depth=None, data_file=None, grid_file=None, dataset=None, load_all=False, variables=None, **kwargs) Allows one-function initialization of a VectorVariable from a file. :param filename: Default data source. Parameters below take precedence :param varnames: Names of the variables in the data source file :param grid_topology: Description of the relationship between grid attributes and variable names. :param name: Name of property :param units: Units :param time: Time axis of the data :param data: Underlying data source :param grid: Grid that the data corresponds with :param dataset: Instance of open Dataset :param data_file: Name of data source file :param grid_file: Name of grid source file :type filename: string :type varnames: [] of string :type grid_topology: {string : string, ...} :type name: string :type units: string :type time: [] of datetime.datetime, netCDF4 Variable, or Time object :type data: netCDF4.Variable or numpy.array :type grid: pysgrid or pyugrid :type dataset: netCDF4.Dataset :type data_file: string :type grid_file: string .. py:method:: from_netCDF(*args, **kwargs) :classmethod: create a new VectorVariable object from a netcdf file See init_from_netcdf for signature .. py:method:: new_from_dict(dict_, **kwargs) :classmethod: creates a new object from dictionary This is base implementation and can be over-ridden by classes using this mixin .. py:method:: constant(values, name=None, units=None) :classmethod: Sets a VectorVariable up to represent a constant vector field. The result will return a constant value for all times and places. :param values: vector of values :type values: array-like .. py:method:: at(points, time, units=None, *args, **kwargs) Find the value of the property at positions P at time T :param points: Cartesian coordinates to be queried (P). Lon, Lat required, Depth (Z) is optional Coordinates must be organized as a 2D array or list, one coordinate per row or list element. :: [[Lon1, Lat1, Z1], [Lon2, Lat2, Z2], [Lon3, Lat3, Z3], ...] Failure to provide point data in this format may cause unexpected behavior If you wish to provide point data using separate longitude and latitude arrays, use the `lons=` and `lats=` kwargs. :type points: Nx3 array of double :param time: The time at which to query these points (T) :type time: `datetime.datetime` object :param units: units the values will be returned in (or converted to) :type units: string such as ('m/s', 'knots', etc) :param extrapolate: if True, extrapolation will be supported :type extrapolate: boolean (default False) :param unmask: if True and return array is a masked array, returns filled array :type unmask: boolean (default False) :param zero_ref: Specifies whether the zero datum moves with zeta or not. Only applicable if depth dimension is present with full sigma layers :type zero_ref: string 'absolute' or 'relative' :param lons: 1D iterable of longitude values. This is ignored if points is provided :type lons: iterable :param lats 1D iterable of latitude values. This is ignored if points is provided :type lons: iterable :return: NxM array of interpolated values N = len(points) M = len(self.variables) :rtype: np.array or np.ma.MaskedArray If time is out of bounds of the time series, and extrapolate is False, a gridded.time.OutOfTimeRangeError is raised. .. py:method:: get_grid_lines() .. py:method:: get_data_vectors() return array of shape (time_slices, len_linearized_data,2) first is magnitude, second is direction .. py:method:: get_metadata() .. py:method:: save(saveloc='.', refs=None, overwrite=True) Save the variable object to a netcdf file. :param filepath: path to file you want o save to. or a writable netCDF4 Dataset An existing one If a path, an existing file will be clobbered. :type filepath: string Follows the convention established by the netcdf UGRID working group: http://ugrid-conventions.github.io/ugrid-conventions .. py:method:: _get_shared_vars(*sh_args) :classmethod: .. py:class:: Variable(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs) Bases: :py:obj:`gridded.Variable`, :py:obj:`gnome.gnomeobject.GnomeId` Variable object: represents a field of values associated with the grid. Abstractly, it is usually a scalar physical property such a temperature, salinity that varies over a the domain of the model. This more or less maps to a variable in a netcdf file, but does not have to come form a netcdf file, and this provides and abstraction where the user can access the value in world coordinates, interpolated from the grid. It holds a reference to its own grid object, and its data. This class represents a value defined on a grid :param name: Name :type name: string :param units: Units :type units: string :param time: Time axis of the data :type time: list of `datetime.datetime`, netCDF4 Variable, or Time object :param data: Underlying data source :type data: array-like object such as netCDF4.Variable or numpy.ndarray :param grid: Grid that the data corresponds with :type grid: Grid object (pysgrid or pyugrid or ) :param data_file: Name of data source file :type data_file: string :param grid_file: Name of grid source file :type grid_file: string :param varname: Name of the variable in the data source file :type varname: string :param fill_value: the fill value used for undefined data :param location: location on the grid -- possible values depend on the grid type :type location: str :param attributes: attributes associated with the Variable (analogous to netcdf variable attributes) :type attributes: dict .. py:property:: extrapolation_is_allowed .. py:property:: data_start .. py:property:: data_stop .. py:attribute:: _schema .. py:attribute:: default_names :value: [] .. py:attribute:: cf_names :value: [] .. py:attribute:: _default_component_types .. py:attribute:: _gnome_unit .. py:method:: __repr__() Return repr(self). .. py:method:: init_from_netCDF(filename=None, dataset=None, data_file=None, grid_file=None, varname=None, grid_topology=None, name=None, units=None, time=None, time_origin=None, grid=None, depth_index=None, depth=None, location=None, load_all=False, fill_value=0, **kwargs) Initialize a Variable from a netcdf file. This is use in subclasses, to it can be done after object creation :param filename: Default data source. Has lowest priority. If dataset, grid_file, or data_file are provided, this function uses them first :type filename: string :param varname: Explicit name of the data in the data source file. Equivalent to the key used to look the item up directly eg 'ds["lon_u"]' for a netCDF4 Dataset. :type varname: string :param grid_topology: Description of the relationship between grid attributes and variable names that hold the grid. :type grid_topology: {string : string, ...} :param name: Name of this object (GNome Object name) :type name: string :param units: string such as 'm/s' :type units: string :param time: Time axis of the data. May be a constructed ``gridded.Time`` object, or collection of datetime.datetime objects :type time: [] of datetime.datetime, netCDF4 Variable, or Time object :param data: Underlying data object. May be any array-like, including netCDF4 Variable, etc :type data: netCDF4.Variable or numpy.array :param grid: Grid that the data corresponds to :type grid: pysgrid or pyugrid :param location: The feature where the data aligns with the grid. e.g. "node", "face" :type location: string :param depth: Depth axis object from ``gridded.depth`` :type depth: Depth, S_Depth or L_Depth :param dataset: Instance of open netCDF4.Dataset :type dataset: netCDF4.Dataset :param data_file: Name of data source file, if data and grid files are separate :type data_file: string :param grid_file: Name of grid source file, if data and grid files are separate :type grid_file: string :param extrapolation_is_allowed: .. py:method:: from_netCDF(*args, **kwargs) :classmethod: create a new variable object from a netcdf file See init_from_netcdf for signature .. py:method:: at(points, time, units=None, *args, **kwargs) Find the value of the property at positions P at time T :param points: Cartesian coordinates to be queried (P). Lon, Lat required, Depth (Z) is optional Coordinates must be organized as a 2D array or list, one coordinate per row or list element. ``[[Lon1, Lat1, Z1],`` ``[Lon2, Lat2, Z2],`` ``[Lon3, Lat3, Z3],`` ``...]`` Failure to provide point data in this format may cause unexpected behavior If you wish to provide point data using separate longitude and latitude arrays, use the `lons=` and `lats=` kwargs. :type points: Nx3 array of double :param time: The time at which to query these points (T) :type time: datetime.datetime object :param units: units the values will be returned in (or converted to) :type units: string such as ('m/s', 'knots', etc) :param extrapolate: if True, extrapolation will be supported :type extrapolate: boolean (default False) :param unmask: if True and return array is a masked array, returns filled array :type unmask: boolean (default False) :param surface_boundary_condition: specifies how to evaluate points above the depth interval :type surface_boundary_condition: string ('extrapolate' or 'mask', default 'extrapolate') :param bottom_boundary_condition: specifies how to evaluate points below the depth interval :type bottom_boundary_condition: string ('extrapolate' or 'mask', default 'extrapolate') :param lons: 1D iterable of longitude values. This is ignored if points is provided :type lons: iterable :param lats 1D iterable of latitude values. This is ignored if points is provided :type lons: iterable :return: returns a Nx1 array of interpolated values :rtype: double If time is out of bounds of the time series, and extrapolate is False, a gridded.time.OutOfTimeRangeError is raised. .. py:method:: new_from_dict(dict_) :classmethod: creates a new object from dictionary This is base implementation and can be over-ridden by classes using this mixin .. py:method:: constant(value, **kwargs) :classmethod: .. py:method:: save(saveloc='.', refs=None, overwrite=True) Save object state as json to user specified saveloc :param saveloc: A directory, file path, open zipfile.ZipFile, or None. If a directory, it will place the zip file there, overwriting if specified. If a file path, it will write the file there as follows: If the file does not exist, it will create the zip archive there. If the saveloc is a zip file or ``zipfile.Zipfile`` object and overwrite is False, it will append there. Otherwise, it will overwrite the file if allowed. If set to None, this function will instead return an open ``zipfile.Zipfile`` object linked to a temporary file. The zip file will be named [object.name].zip if a directory is specified :param refs: dictionary of references to objects :param overwrite: If True, overwrites the file at the saveloc :returns (obj_json, saveloc, refs): ``obj_json`` is the json that is written to this object's file in the zipfile. For example if saving a Model named Model1, obj_json will contain the contents of the Model1.json in the save file. ``saveloc`` will be the string path passed in EXCEPT if None was passed in. In this case, it will be an open ``zipfile.ZipFile`` based on a temporary file. ``refs`` will be a dict containing all the objects that were saved in the save file, keyed by object id. It will also contain the reference to the object that called ``.save`` itself. .. py:class:: Grid(filename, topology_file=None, grid_type=1, extrapolate=False, time_offset=0, **kwargs) Bases: :py:obj:`gnome.environment.environment.Environment` Defines a grid for a current or wind Initializes a grid object from a file and a grid type. Maybe allow a grid to be passed in eventually, otherwise filename required All other keywords are optional. Optional parameters (kwargs): :param grid_type: default is 1 - regular grid (eventually figure this out from file) .. py:property:: grid_type .. py:attribute:: _schema .. py:attribute:: extrapolate .. py:attribute:: time_offset .. py:method:: __repr__() Return repr(self). .. py:method:: __str__() Return str(self). .. py:method:: prepare_for_model_run(model_time) Not sure we need to do anything here .. py:method:: prepare_for_model_step(model_time) Make sure we have the right data loaded .. py:method:: get_value(time, location) Return the value at specified time and location. .. py:method:: get_values(model_time, positions, velocities) Return the values for the given positions .. py:method:: serialize(json_='webapi') Returns a json serialization of this object ("webapi" mode only) .. py:method:: deserialize(json_) :classmethod: classmethod takes json structure as input, deserializes it using a colander schema then invokes the new_from_dict method to create an instance of the object described by the json schema. We also need to accept sparse json objects, in which case we will not treat them, but just send them back. .. py:data:: base_classes .. py:data:: helper_functions .. py:data:: env_objs .. py:data:: schemas .. py:data:: ts_property .. py:data:: __all__