:py:mod:`gnome.environment.gridded_objects_base`
================================================

.. py:module:: gnome.environment.gridded_objects_base


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   gnome.environment.gridded_objects_base.Time
   gnome.environment.gridded_objects_base.Grid_U
   gnome.environment.gridded_objects_base.Grid_S
   gnome.environment.gridded_objects_base.Grid_R
   gnome.environment.gridded_objects_base.PyGrid
   gnome.environment.gridded_objects_base.Variable
   gnome.environment.gridded_objects_base.DepthBase
   gnome.environment.gridded_objects_base.L_Depth
   gnome.environment.gridded_objects_base.ROMS_Depth
   gnome.environment.gridded_objects_base.FVCOM_Depth
   gnome.environment.gridded_objects_base.Depth
   gnome.environment.gridded_objects_base.VectorVariable




.. py:class:: Time(data=(datetime.now(), ), filename=None, varname=None, tz_offset=None, origin=None, displacement=timedelta(seconds=0), *args, **kwargs)


   Bases: :py:obj:`gridded.time.Time`, :py:obj:`gnome.gnomeobject.GnomeId`

   A class for assigning a unique ID for an object

   Representation of a time axis. Provides interpolation alphas and indexing.

   :param time: Ascending list of times to use
   :type time: netCDF4.Variable or Sequence of `datetime.datetime`

   :param tz_offset: offset to compensate for time zone shifts
   :type tz_offset: `datetime.timedelta` or float or integer hours

   :param origin: shifts the time interval to begin at the time specified
   :type origin: `datetime.datetime`

   :param displacement: displacement to apply to the time data.
          Allows shifting entire time interval into future or past
   :type displacement: `datetime.timedelta`

   .. py:attribute:: _schema

      

   .. py:method:: __repr__()

      Return repr(self).


   .. py:method:: from_file(filename=None, **kwargs)
      :classmethod:



.. py:class:: Grid_U(**kwargs)


   Bases: :py:obj:`gridded.grids.Grid_U`, :py:obj:`gnome.gnomeobject.GnomeId`

   Base object for grids to share common behavior

   Init common to all Grid types. This initializer 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:attribute:: _schema

      

   .. py:method:: draw_to_plot(ax, features=None, style=None)


   .. 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:: get_cells()


   .. py:method:: get_lines()

      Returns an array of lengths, and a list of line arrays.
      The first array sequentially indexes the second array.
      When the second array is split up using the first array
      and the resulting lines are drawn, you should end up with a picture of
      the grid.


   .. py:method:: get_nodes()


   .. py:method:: get_centers()


   .. py:method:: get_metadata()



.. py:class:: Grid_S(use_masked_boundary=True, *args, **kwargs)


   Bases: :py:obj:`gnome.gnomeobject.GnomeId`, :py:obj:`gridded.grids.Grid_S`

   A class for assigning a unique ID for an object

   Init common to all Grid types. This initializer 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:property:: non_grid_variables


   .. py:attribute:: _schema

      

   .. py:method:: draw_to_plot(ax, features=None, style=None)


   .. 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:: get_cells()


   .. py:method:: get_nodes()


   .. py:method:: get_centers()


   .. py:method:: get_metadata()


   .. py:method:: get_lines()

      Returns an array of lengths, and a list of line arrays.
      The first array sequentially indexes the second array.
      When the second array is split up using the first array
      and the resulting lines are drawn, you should end up with a picture of
      the grid.



.. py:class:: Grid_R(node_lon=None, node_lat=None, grid_topology=None, node_dimensions=None, node_coordinates=None, *args, **kwargs)


   Bases: :py:obj:`gridded.grids.Grid_R`, :py:obj:`gnome.gnomeobject.GnomeId`

   Rectangular Grid

   lon and lat of the nodes are vectors

   :param node_lon=None: vector of the node longitudes
   :param node_lat=None: vector of the node latitudes
   :param grid_topology=None: ????
   :param node_dimensions=None: (should only be required for netcdf)
   :param node_coordinates=None:  ?????

   .. py:attribute:: _schema

      

   .. 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:: get_metadata()


   .. py:method:: get_nodes()


   .. py:method:: get_centers()


   .. py:method:: get_cells()


   .. py:method:: get_lines()



.. 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:: 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:: DepthBase(name=None, surface_index=-1, bottom_index=0, default_surface_boundary_condition='extrapolate', default_bottom_boundary_conditon='mask', **kwargs)


   Bases: :py:obj:`gridded.depth.DepthBase`, :py:obj:`gnome.gnomeobject.GnomeId`

   A class for assigning a unique ID for an object

   :param surface_index: array index of 'highest' level (closest to sea level)

   :param bottom_index: array index of 'lowest' level (closest to seafloor)

   .. py:attribute:: _schema

      

   .. py:attribute:: _default_component_types

      

   .. 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:class:: L_Depth(terms=None, **kwargs)


   Bases: :py:obj:`gridded.depth.L_Depth`, :py:obj:`gnome.gnomeobject.GnomeId`

   A class for assigning a unique ID for an object

   :param surface_index: array index of 'highest' level (closest to sea level)

   :param bottom_index: array index of 'lowest' level (closest to seafloor)

   .. py:attribute:: _schema

      

   .. py:attribute:: _default_component_types

      

   .. 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:class:: ROMS_Depth(name=None, time=None, grid=None, bathymetry=None, zeta=None, terms=None, vtransform=2, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', **kwargs)


   Bases: :py:obj:`gridded.depth.ROMS_Depth`, :py:obj:`gnome.gnomeobject.GnomeId`

   Sigma coordinate depth object for ROMS style output

   :param name: Human readable name
   :type name: string

   :param time: time axis of the object
   :type time: gridded.time.Time or derivative

   :param grid: x/y grid representation
   :type grid: gridded.grids.GridBase or derivative

   :param bathymetry: variable object representing seafloor
   :type bathymetry: gridded.variable.Variable or derivative

   :param zeta: variable object representing free-surface
   :type zeta: gridded.variable.Variable or derivative

   :param terms: remaining terms in dictionary layout
   :type terms: dictionary of string key to numeric value
   See S_Depth.default_names, sans bathymetry and zeta

   :param vtransform: S-coordinate transform type. 1 = Old, 2 = New
   :type vtransform: int (default 2)

   :param surface_boundary_condition: Determines how to handle points above the surface
   :type surface_boundary_condition: string ('extrapolate' or 'mask')

   :param bottom_boundary_condition: Determines how to handle points below the seafloor
   :type bottom_boundary_condition: string ('extrapolate' or 'mask')

   .. py:attribute:: _schema

      

   .. py:attribute:: _default_component_types

      

   .. 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:class:: FVCOM_Depth(name=None, time=None, grid=None, bathymetry=None, zeta=None, terms=None, vtransform=2, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', **kwargs)


   Bases: :py:obj:`gridded.depth.FVCOM_Depth`, :py:obj:`gnome.gnomeobject.GnomeId`

   Represents the ocean s-coordinates as implemented by ROMS,
   It may or may not be useful for other systems.

   :param name: Human readable name
   :type name: string

   :param time: time axis of the object
   :type time: gridded.time.Time or derivative

   :param grid: x/y grid representation
   :type grid: gridded.grids.GridBase or derivative

   :param bathymetry: variable object representing seafloor
   :type bathymetry: gridded.variable.Variable or derivative

   :param zeta: variable object representing free-surface
   :type zeta: gridded.variable.Variable or derivative

   :param terms: remaining terms in dictionary layout
   :type terms: dictionary of string key to numeric value
   See S_Depth.default_names, sans bathymetry and zeta

   :param vtransform: S-coordinate transform type. 1 = Old, 2 = New
   :type vtransform: int (default 2)

   :param surface_boundary_condition: Determines how to handle points above the surface
   :type surface_boundary_condition: string ('extrapolate' or 'mask')

   :param bottom_boundary_condition: Determines how to handle points below the seafloor
   :type bottom_boundary_condition: string ('extrapolate' or 'mask')

   .. py:attribute:: _schema

      

   .. py:attribute:: _default_component_types

      

   .. 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:class:: Depth


   Bases: :py:obj:`gridded.depth.Depth`

   Factory class that generates depth objects.

   Also handles common loading and parsing operations

   .. py:attribute:: ld_types

      

   .. py:attribute:: sd_types

      

   .. py:attribute:: surf_types

      


.. 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: