gnome.environment.gridded_objects_base ====================================== .. py:module:: gnome.environment.gridded_objects_base 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 Module Contents --------------- .. py:class:: Time(data=None, filename=None, varname=None, tz_offset=None, new_tz_offset=None, tz_offset_name='', origin=None, displacement=None, *args, **kwargs) Bases: :py:obj:`gridded.time.Time`, :py:obj:`gnome.gnomeobject.GnomeId` Object to represent a time axis in a Variable. Representation of a time axis. Provides interpolation alphas and indexing. :param data: Ascending list of times to use :type data: Sequence of `datetime.datetime` objects. :param filename=None: name of file data was loaded from -- informational only :param varname=None: name of variable in data file -- informational only :param tz_offset=None: Timezone offset of the data. If not provided it will be NOne ("Naive") e.g. offset is not known. Use zero for UTC. :type tz_offset: float or integer hours :param new_tz_offset: Timezone offset desired -- from the offset specified by tz_offset. :type new_tz_offset: float or integer hours :param tz_offset_name="": name for the time zone offset, if desired. example: "Pacific Daylight Time" NOTE: only informational -- it's up to you to have the tz_offset correct. :type tz_offset_name: str. :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:method:: from_netCDF(*args, **kwargs) :classmethod: Construct a Time object from a netcdf file. By default, this will attempt to discover the data variable to use. If the file is not standards conforming, you can specify the time variable name, or another variable, for which you want the corresponding times. :param filename=None: name of netcdf file :param dataset=None: netcdf dataset object (only one of filename or dataset should be specified) :param varname=None: Name of the time variable. :param datavar=None: A netcdf variable or name of netcdf variable for which you want the corresponding time object. It will try to find the time variable that corresponds to the passed in variable. :param tz_offset=None: Timezone offset from UTC the data are in, in hours. If None: offset will be read from file, if present. If no offset is specified in the file, UTC (tz_offset=0) will be assumed. If 'Naive', then no offset will be assigned. :type tz_offset: Number in hours. :param new_tz_offset=None: New Timezone offset from UTC desired in hours. Data will be shifted to the new offset. If tz_offset is set to Naive, then this will fail. (It can't be changed without knowing what it was to begin with) :type new_tz_offset: Number in hours. :param tz_offset_name="": name for the time zone offset, if desired. example: "Pacific Daylight Time" NOTE: only informational -- it's up to you to have the tz_offset correct. :type tz_offset_name: str. .. py:method:: from_file(filename=None, **kwargs) :classmethod: .. py:class:: Grid_U(*args, **kwargs) Bases: :py:obj:`gridded.grids.Grid_U`, :py:obj:`gnome.gnomeobject.GnomeId` Object to represent a triangle unstructured grid in a Variable. It is not recommended to use the __init__ directly, use .from_netCDF instead See gridded.pyugrid.ugrid.UGrid for full __init__ documentation .. py:method:: from_netCDF(filename=None, dataset=None, data_file=None, grid_file=None, grid_topology=None, *args, **kwargs) :classmethod: :param filename: File containing a grid :type filename: string or list of string :param dataset: Takes precedence over filename, if provided. :type dataset: netCDF4.Dataset :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 See https://ugrid-conventions.github.io/ugrid-conventions/#2d-triangular-mesh-topology :returns: Instance of Grid_U .. py:method:: draw_to_plot(ax, features=None, style=None) .. py:method:: to_dict(json_=None) Returns a dictionary representation of this object. Uses the schema to determine which attributes are put into the dictionary. No extra processing is done to each attribute. They are presented as is. The ``json_`` parameter is ignored in this base class. 'save' is passed in when the schema is saving the object. This allows an override of this function to do any custom stuff necessary to prepare for saving. .. 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() returns a Nx3x2 array. N = number of cells, 3 = nodes of each triangle, 2 = (lon, lat) [[[lon1, lat1], [lon2, lat2], [lon3, lat3]], ...] .. 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() returns a Nx2 array of nodes. N = number of nodes, 2 = (lon, lat) .. py:method:: get_centers() returns a Nx2 array of centers. N = number of centers, 2 = (lon, lat) .. py:method:: get_metadata() .. py:class:: Grid_S(use_masked_boundary=True, *args, **kwargs) Bases: :py:obj:`gridded.grids.Grid_S`, :py:obj:`gnome.gnomeobject.GnomeId` Object to represent a structured quad grid in a Variable. It is not recommended to use the __init__ directly, use .from_netCDF instead See gridded.pyugrid.sgrid.SGrid for full __init__ documentation .. py:method:: from_netCDF(*args, **kwargs) :classmethod: .. py:property:: non_grid_variables .. py:method:: draw_to_plot(ax, features=None, style=None) .. py:method:: to_dict(json_=None) Returns a dictionary representation of this object. Uses the schema to determine which attributes are put into the dictionary. No extra processing is done to each attribute. They are presented as is. The ``json_`` parameter is ignored in this base class. 'save' is passed in when the schema is saving the object. This allows an override of this function to do any custom stuff necessary to prepare for saving. .. 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() returns a Nx4x2 array. N = number of cells, 4 = nodes of each quad, 2 = (lon, lat) Only returns the cells that are not masked by node_mask [[[lon1, lat1], [lon2, lat2], [lon3, lat3], [lon4, lat4]], ...] .. 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(*args, **kwargs) Bases: :py:obj:`gridded.grids.Grid_R`, :py:obj:`gnome.gnomeobject.GnomeId` Rectangular Grid lon and lat of the nodes are vectors It is not recommended to use the __init__ directly, use .from_netCDF instead See gridded.pyugrid.sgrid.SGrid for full __init__ documentation .. 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:class:: Variable(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs) Bases: :py:obj:`gridded.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 :value: [] .. py:attribute:: cf_names :value: [] .. py:property:: extrapolation_is_allowed .. 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 used in subclasses, so 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, extrapolate=None, unmask=True, **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. 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. :: [[Lon1, Lat1, Z1], [Lon2, Lat2, Z2], [Lon3, Lat3, Z3], ...] :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:property:: data_start .. py:property:: data_stop .. 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: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: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: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: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, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs) Bases: :py:obj:`gridded.VectorVariable`, :py:obj:`gnome.environment.environment.Environment` 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:: extrapolation_is_allowed .. 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 :type filename: string :param dataset: Instance of open Dataset :type dataset: netCDF4.Dataset :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 grid_topology: Description of the relationship between grid attributes and variable names. :type grid_topology: {string : string, ...} :param grid: Grid that the data corresponds with :type grid: pysgrid or pyugrid :param varnames: Names of the variables in the data source file :type varnames: [] of string. Order of the names in the list would be order of vector components :param time: Time axis of the data :type time: [] of datetime.datetime, netCDF4 Variable, or Time object :param name: Name of property :type name: string :param units: Units :type units: string .. py:method:: from_netCDF(*args, **kwargs) :classmethod: Allows one-function initialization of a VectorVariable from a file. :param filename: Default data source. Parameters below take precedence :type filename: string :param dataset: Instance of open Dataset :type dataset: netCDF4.Dataset :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 grid_topology: Description of the relationship between grid attributes and variable names. :type grid_topology: {string : string, ...} :param grid: Grid that the data corresponds with :type grid: pysgrid or pyugrid :param varnames: Names of the variables in the data source file :type varnames: [] of string. Order of the names in the list would be order of vector components :param time: Time axis of the data :type time: [] of datetime.datetime, netCDF4 Variable, or Time object :param name: Name of property :type name: string :param units: Units :type units: string .. 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, extrapolate=None, unmask=True, **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 (2, time_slices, len_linearized_data) .. py:method:: get_metadata() .. py:property:: data_start .. py:property:: data_stop .. 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