gnome.environment.gridded_objects_base¶

Classes¶

`Time`	A class for assigning a unique ID for an object
`Grid_U`	Base object for grids to share common behavior
`Grid_S`	Base object for grids to share common behavior
`Grid_R`	Rectangular Grid
`PyGrid`	Factory class that generates grid objects. Also handles common
`Variable`	Variable object: represents a field of values associated with the grid.
`DepthBase`	A class for assigning a unique ID for an object
`L_Depth`	A class for assigning a unique ID for an object
`ROMS_Depth`	Sigma coordinate depth object for ROMS style output
`FVCOM_Depth`	Represents the ocean s-coordinates as implemented by ROMS,
`Depth`	Factory class that generates depth objects.
`VectorVariable`	A base class for all classes in environment module.

Module Contents¶

class gnome.environment.gridded_objects_base.Time(data=None, filename=None, varname=None, tz_offset=None, new_tz_offset=None, tz_offset_name='', origin=None, displacement=None, *args, **kwargs)¶

Bases: gridded.time.Time, gnome.gnomeobject.GnomeId

A class for assigning a unique ID for an object

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

Parameters:

data (Sequence of datetime.datetime objects.) – Ascending list of times to use
filename=None – name of file data was loaded from – informational only
varname=None – name of variable in data file – informational only
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.
new_tz_offset (float or integer hours) – Timezone offset desired – from the offset specified by tz_offset.
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.
origin (datetime.datetime) – shifts the time interval to begin at the time specified
displacement (datetime.timedelta) – displacement to apply to the time data. Allows shifting entire time interval into future or past

classmethod from_file(filename=None, **kwargs)¶

class gnome.environment.gridded_objects_base.Grid_U(filename=None, *args, **kwargs)¶

Bases: gridded.grids.Grid_U, 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

Parameters:: filename – Name of the file this grid was constructed from, if available.

draw_to_plot(ax, features=None, style=None)¶

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

get_cells()¶

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.

get_nodes()¶

get_centers()¶

get_metadata()¶

class gnome.environment.gridded_objects_base.Grid_S(use_masked_boundary=True, *args, **kwargs)¶

Bases: gridded.grids.Grid_S, 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

Parameters:: filename – Name of the file this grid was constructed from, if available.

property non_grid_variables¶

draw_to_plot(ax, features=None, style=None)¶

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

get_cells()¶

get_nodes()¶

get_centers()¶

get_metadata()¶

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.

class gnome.environment.gridded_objects_base.Grid_R(node_lon=None, node_lat=None, grid_topology=None, node_dimensions=None, node_coordinates=None, *args, **kwargs)¶

Bases: gridded.grids.Grid_R, gnome.gnomeobject.GnomeId

Rectangular Grid

lon and lat of the nodes are vectors

Parameters:

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

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

get_metadata()¶

get_nodes()¶

get_centers()¶

get_cells()¶

get_lines()¶

class gnome.environment.gridded_objects_base.PyGrid¶

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

Parameters:: filename – Name of the file this grid was constructed from, if available.

static from_netCDF(*args, **kwargs)¶

Parameters:

filename – File containing a grid
dataset – Takes precedence over filename, if provided.
grid_type – Must be provided if Dataset does not have a ‘grid_type’ attribute, or valid topology variable
grid_topology – A dictionary mapping of grid attribute to variable name. Takes precedence over discovered attributes
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

static new_from_dict(dict_)¶

class gnome.environment.gridded_objects_base.Variable(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs)¶

Bases: gridded.Variable, 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

Parameters:

name (string) – Name
units (string) – Units
time (list of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data
data (array-like object such as netCDF4.Variable or numpy.ndarray) – Underlying data source
grid (Grid object (pysgrid or pyugrid or )) – Grid that the data corresponds with
data_file (string) – Name of data source file
grid_file (string) – Name of grid source file
varname (string) – Name of the variable in the data source file
fill_value – the fill value used for undefined data
location (str) – location on the grid – possible values depend on the grid type
attributes (dict) – attributes associated with the Variable (analogous to netcdf variable attributes)

default_names = []¶

cf_names = []¶

property extrapolation_is_allowed¶

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

Parameters:

filename (string) – Default data source. Has lowest priority. If dataset, grid_file, or data_file are provided, this function uses them first
varname (string) – 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.
grid_topology ({string : string, ...}) – Description of the relationship between grid attributes and variable names that hold the grid.
name (string) – Name of this object (GNome Object name)
units (string) – string such as ‘m/s’
time ([] of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data. May be a constructed gridded.Time object, or collection of datetime.datetime objects
data (netCDF4.Variable or numpy.array) – Underlying data object. May be any array-like, including netCDF4 Variable, etc
grid (pysgrid or pyugrid) – Grid that the data corresponds to
location (string) – The feature where the data aligns with the grid. e.g. “node”, “face”
depth (Depth, S_Depth or L_Depth) – Depth axis object from gridded.depth
dataset (netCDF4.Dataset) – Instance of open netCDF4.Dataset
data_file (string) – Name of data source file, if data and grid files are separate
grid_file (string) – Name of grid source file, if data and grid files are separate
extrapolation_is_allowed

classmethod from_netCDF(*args, **kwargs)¶

create a new variable object from a netcdf file

See init_from_netcdf for signature

at(points, time, *, units=None, extrapolate=None, unmask=True, **kwargs)¶

Find the value of the property at positions P at time T

Parameters:

points (Nx3 array of double) – 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.
time (datetime.datetime object) – The time at which to query these points (T)
units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)
extrapolate (boolean (default False)) – if True, extrapolation will be supported
unmask (boolean (default False)) – if True and return array is a masked array, returns filled array
surface_boundary_condition (string ('extrapolate' or 'mask', default 'extrapolate')) – specifies how to evaluate points above the depth interval
bottom_boundary_condition (string ('extrapolate' or 'mask', default 'extrapolate')) – specifies how to evaluate points below the depth interval
lons (iterable) – 1D iterable of longitude values. This is ignored if points is provided

:param lats 1D iterable of latitude values. This is ignored if points is provided :type lons: iterable

Returns:: returns a Nx1 array of interpolated values
Return type:: double

If time is out of bounds of the time series, and extrapolate is False, a gridded.time.OutOfTimeRangeError is raised.

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

classmethod constant(value, **kwargs)¶

property data_start¶

property data_stop¶

save(saveloc='.', refs=None, overwrite=True)¶

Save object state as json to user specified saveloc

Parameters:

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
refs – dictionary of references to objects
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.

class gnome.environment.gridded_objects_base.DepthBase(name=None, surface_index=-1, bottom_index=0, default_surface_boundary_condition='extrapolate', default_bottom_boundary_conditon='mask', **kwargs)¶

Bases: gridded.depth.DepthBase, gnome.gnomeobject.GnomeId

A class for assigning a unique ID for an object

Parameters:

surface_index – array index of ‘highest’ level (closest to sea level)
bottom_index – array index of ‘lowest’ level (closest to seafloor)

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

class gnome.environment.gridded_objects_base.L_Depth(terms=None, **kwargs)¶

Bases: gridded.depth.L_Depth, gnome.gnomeobject.GnomeId

A class for assigning a unique ID for an object

Parameters:

surface_index – array index of ‘highest’ level (closest to sea level)
bottom_index – array index of ‘lowest’ level (closest to seafloor)

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

class gnome.environment.gridded_objects_base.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: gridded.depth.ROMS_Depth, gnome.gnomeobject.GnomeId

Sigma coordinate depth object for ROMS style output

Parameters:

name (string) – Human readable name
time (gridded.time.Time or derivative) – time axis of the object
grid (gridded.grids.GridBase or derivative) – x/y grid representation
bathymetry (gridded.variable.Variable or derivative) – variable object representing seafloor
zeta (gridded.variable.Variable or derivative) – variable object representing free-surface
terms (dictionary of string key to numeric value) – remaining terms in dictionary layout

See S_Depth.default_names, sans bathymetry and zeta

Parameters:

vtransform (int (default 2)) – S-coordinate transform type. 1 = Old, 2 = New
surface_boundary_condition (string ('extrapolate' or 'mask')) – Determines how to handle points above the surface
bottom_boundary_condition (string ('extrapolate' or 'mask')) – Determines how to handle points below the seafloor

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

class gnome.environment.gridded_objects_base.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: gridded.depth.FVCOM_Depth, gnome.gnomeobject.GnomeId

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

Parameters:

name (string) – Human readable name
time (gridded.time.Time or derivative) – time axis of the object
grid (gridded.grids.GridBase or derivative) – x/y grid representation
bathymetry (gridded.variable.Variable or derivative) – variable object representing seafloor
zeta (gridded.variable.Variable or derivative) – variable object representing free-surface
terms (dictionary of string key to numeric value) – remaining terms in dictionary layout

See S_Depth.default_names, sans bathymetry and zeta

Parameters:

vtransform (int (default 2)) – S-coordinate transform type. 1 = Old, 2 = New
surface_boundary_condition (string ('extrapolate' or 'mask')) – Determines how to handle points above the surface
bottom_boundary_condition (string ('extrapolate' or 'mask')) – Determines how to handle points below the seafloor

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

class gnome.environment.gridded_objects_base.Depth¶

Bases: gridded.depth.Depth

Factory class that generates depth objects.

Also handles common loading and parsing operations

ld_types¶

sd_types¶

surf_types¶

class gnome.environment.gridded_objects_base.VectorVariable(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs)¶

Bases: gridded.VectorVariable, 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

Parameters:: name=None

property extrapolation_is_allowed¶

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.

Parameters:

filename (string) – Default data source. Parameters below take precedence
dataset (netCDF4.Dataset) – Instance of open Dataset
data_file (string) – Name of data source file
grid_file (string) – Name of grid source file
grid_topology ({string : string, ...}) – Description of the relationship between grid attributes and variable names.
grid (pysgrid or pyugrid) – Grid that the data corresponds with
varnames ([] of string. Order of the names in the list would be order of vector components) – Names of the variables in the data source file
time ([] of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data
name (string) – Name of property
units (string) – Units

classmethod from_netCDF(*args, **kwargs)¶

Allows one-function initialization of a VectorVariable from a file.

Parameters:

filename (string) – Default data source. Parameters below take precedence
dataset (netCDF4.Dataset) – Instance of open Dataset
data_file (string) – Name of data source file
grid_file (string) – Name of grid source file
grid_topology ({string : string, ...}) – Description of the relationship between grid attributes and variable names.
grid (pysgrid or pyugrid) – Grid that the data corresponds with
varnames ([] of string. Order of the names in the list would be order of vector components) – Names of the variables in the data source file
time ([] of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data
name (string) – Name of property
units (string) – Units

classmethod new_from_dict(dict_, **kwargs)¶

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin

classmethod constant(values, name=None, units=None)¶

Sets a VectorVariable up to represent a constant vector field. The result will return a constant value for all times and places.

Parameters:: values (array-like) – vector of values

at(points, time, *, units=None, extrapolate=None, unmask=True, **kwargs)¶

Find the value of the property at positions P at time T

Parameters:

points (Nx3 array of double) –
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.
time (datetime.datetime object) – The time at which to query these points (T)
units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)
extrapolate (boolean (default False)) – if True, extrapolation will be supported
unmask (boolean (default False)) – if True and return array is a masked array, returns filled array
zero_ref (string 'absolute' or 'relative') – Specifies whether the zero datum moves with zeta or not. Only applicable if depth dimension is present with full sigma layers
lons (iterable) – 1D iterable of longitude values. This is ignored if points is provided

:param lats 1D iterable of latitude values. This is ignored if points is provided :type lons: iterable

Returns:: NxM array of interpolated values N = len(points) M = len(self.variables)
Return type:: 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.

get_grid_lines()¶

get_data_vectors()¶: return array of shape (time_slices, len_linearized_data,2) first is magnitude, second is direction

get_metadata()¶

property data_start¶

property data_stop¶

save(saveloc='.', refs=None, overwrite=True)¶

Save the variable object to a netcdf file.

Parameters:: filepath (string) – 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.

Follows the convention established by the netcdf UGRID working group:

http://ugrid-conventions.github.io/ugrid-conventions