gridded package

Subpackages

Submodules

gridded.depth module

class gridded.depth.Depth[source]

Bases: object

Factory class that generates depth objects. Also handles common loading and parsing operations

static from_netCDF(filename=None, dataset=None, data_file=None, grid_file=None, depth_type=None, varname=None, topology=None, _default_types=(('level', <class 'gridded.depth.L_Depth'>), ('sigma', <class 'gridded.depth.S_Depth'>), ('surface', <class 'gridded.depth.DepthBase'>)), **kwargs)[source]
Parameters

  • filename (string or list of string) – File containing a depth

  • dataset (netCDF4.Dataset) – Takes precedence over filename, if provided.

  • depth_type (string) – Must be provided if autodetection is not possible. See Depth.ld_names, Depth.sd_names, and Depth.surf_names for the expected values for this argument

Returns

Instance of L_Depth or S_Depth

ld_names = ['level', 'levels', 'L_Depth', 'depth_levelsdepth_level']
sd_names = ['sigma']
surf_names = ['surface', 'surface only', 'surf', 'none']
static surface_only(*args, **kwargs)[source]

If instantiated directly, this will always return a DepthBase It is assumed index -1 is the surface index

class gridded.depth.DepthBase(surface_index=None, bottom_index=None, **kwargs)[source]

Bases: object

classmethod from_netCDF(surface_index=-1, **kwargs)[source]
interpolation_alphas(points, time, data_shape, extrapolate=False, _hash=None, **kwargs)[source]

Returns the weights (alphas) required for interpolation

The base class implementation only supports surface values: it returns the surface index and 0.0 for the alpha

This is the expected outcome for the case where all points are on the surface.

class gridded.depth.L_Depth(name=None, terms=None, surface_index=None, bottom_index=None, default_surface_boundary_condition='extrapolate', default_bottom_boundary_conditon='mask', **kwargs)[source]

Bases: DepthBase

cf_names = {'depth': 'depth'}
default_names = {'depth': ['depth', 'depth_levels']}
default_terms = [('depth_levels', 'depth')]
classmethod from_netCDF(filename=None, dataset=None, name=None, topology=None, terms=None, surface_index=None, bottom_index=None, **kwargs)[source]
interpolation_alphas(points, time=None, data_shape=None, surface_boundary_condition=None, bottom_boundary_condition=None, *args, **kwargs)[source]

Returns a pair of values. The 1st value is an array of the depth indices of all the particles. The 2nd value is an array of the interpolation alphas for the particles between their depth index and depth_index+1. If both values are None, then all particles are on the surface layer.

class gridded.depth.S_Depth(name=None, time=None, grid=None, bathymetry=None, zeta=None, terms=None, vtransform=2, positive_down=True, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', **kwargs)[source]

Bases: DepthBase

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

cf_names = {'Cs_r': ['S-coordinate stretching curves at RHO-points'], 'Cs_w': ['S-coordinate stretching curves at W-points'], 'bathymetry': ['bathymetry at RHO-points', 'Final bathymetry at RHO-points'], 'hc': ['S-coordinate parameter, critical depth'], 's_rho': ['S-coordinate at RHO-points'], 's_w': ['S-coordinate at W-points'], 'zeta': ['free-surface']}
compute_coordinates(rho_or_w)[source]

Uses zeta, bathymetry, and the s-coordinate terms to produce the time-dependent coordinate variable.

Returns

numpy array of s-coordinates

default_names = {'Cs_r': ['Cs_r'], 'Cs_w': ['Cs_w'], 'bathymetry': ['h'], 'hc': ['hc'], 's_rho': ['s_rho'], 's_w': ['s_w'], 'zeta': ['zeta']}
classmethod from_netCDF(filename=None, varnames=None, grid_topology=None, name=None, time=None, grid=None, dataset=None, data_file=None, grid_file=None, bathymetry=None, zeta=None, terms=None, vtransform=2, positive_down=True, **kwargs)[source]
Parameters

  • filename (str or list[str]) – A string or ordered list of string of netCDF filename(s)

  • varnames (dict) –

    Direct mapping of component name to netCDF variable name. Use this if auto detection fails. Partial definition is allowable. Unspecified terms will use the value in .default_names:

    {'Cs_r': 'Cs_r',
 'Cs_w': Cs_w',
 's_rho': 's_rho'),
 's_w': 's_w',
 'bathymetry': 'h',
 'hc': 'hc'),
 'zeta': 'zeta')
 }

  • name (str) – Human-readable name for this object

  • time (gridded.time.Time or subclass) – Time dimension (for zeta)

  • grid (subclass of gridded.grids.GridBase) – X-Y dmension (for bathymetry & zeta)

get_section(time, coord='w', x_coord=None, y_coord=None, vtransform=2)[source]

Returns a section of the z-level space in time. All s-levels are returned in the data. By providing a x_coord or y_coord you can get cross sections in the direction specified, or both for the level depths at a single point.

get_transect(points, time, rho_or_w='w', _hash=None, **kwargs)[source]
Parameters

  • points (numpy array of shape (n, 3)) – array of points to interpolate to

  • time (datetime.datetime) – time to interpolate to

  • rho_or_w (string) – ‘rho’ or ‘w’ to interpolate to rho or w points

Returns

numpy array of shape (n, num_w_levels) of interpolated values

interpolation_alphas(points, time, data_shape, surface_boundary_condition=None, bottom_boundary_condition=None, _hash=None, extrapolate=False, **kwargs)[source]

Returns a pair of arrays. The 1st array is of the depth indices of all the points. The 2nd value is an array of the interpolation alphas for the points between their depth index and depth_index+1.

If a depth is between coordinate N and N+1, the index will be N. If a depth is exactly on a coordinate, the index will be N.

Any points that are ‘off grid’ will be subject to the boundary conditions ‘mask’ or ‘extrapolate’. ‘mask’ will mask the index and the alpha of the point. ‘extrapolate’ will set the index to the surface or bottom index, and the alpha to 0 or 1 depending on the orientation of the layers

property num_r_levels
property num_w_levels

gridded.gridded module

gridded module:

This module defines the gridded.Dataset – The core class that encapsulates the gridded data model

class gridded.gridded.Dataset(ncfile=None, grid=None, variables=None, grid_topology=None, attributes=None)[source]

Bases: object

An object that represent an entire complete dataset – a collection of Variables and the Grid that they are stored on.

get_variables_by_attribute(attr, value)[source]

return the variables that have attributes that fit the defined input

Parameters

  • attr – the name of the attribute you want to match

  • value – the value of the attribute you want to match

fixme: make this a bit more flexible, more like the netCDF4 version

property info

Information about the Dataset object

save(filename, format='netcdf4')[source]

save the dataset to a file

Parameters

  • filename – full path to file to save to.

  • format – format to save – ‘netcdf3’ or ‘netcdf4’ are the only options at this point.

gridded.grids module

class gridded.grids.Grid[source]

Bases: object

Factory class that generates grid objects. Also handles common loading and parsing operations

static from_netCDF(filename=None, dataset=None, grid_type=None, grid_topology=None, _default_types=(('ugrid', <class 'gridded.grids.Grid_U'>), ('sgrid', <class 'gridded.grids.Grid_S'>), ('rgrid', <class 'gridded.grids.Grid_R'>)), *args, **kwargs)[source]
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

class gridded.grids.GridBase(filename=None, *args, **kwargs)[source]

Bases: object

Base object for grids to share common behavior

classmethod from_netCDF(*args, **kwargs)[source]
import_variable(variable, location='node')[source]

Takes a Variable or VectorVariable and interpolates the data onto this grid. You may pass a location (‘nodes’, ‘faces’, ‘edge1’, ‘edge2) and the variable will be interpolated there if possible If no location is passed, the variable will be interpolated to the nodes of this grid. If the Variable’s grid and this grid are the same, this function will return the Variable unchanged.

If this grid covers area that the source grid does not, all values in this area will be masked. If regridding from cell centers to the nodes, The values of any border point not within will be equal to the value at the center of the border cell.

property shape
class gridded.grids.Grid_R(node_lon=None, node_lat=None, grid_topology=None, node_dimensions=None, node_coordinates=None, *args, **kwargs)[source]

Bases: GridBase

Rectangular Grid

lon and lat of the nodes are vectors

property center_lat
property center_lon
property centers
infer_location(variable)[source]

fixme: should first look for “location” attribute.

But now we are checking variable dimensions to which part of the grid it is on.

interpolate_var_to_points(points, variable, method='linear', indices=None, slices=None, mask=None, **kwargs)[source]
locate_faces(points)[source]

Returns the node grid indices, one per point.

Points that are not on the node grid will have an index of -1

If a single point is passed in, a single index will be returned. If a sequence of points is passed in an array of indexes will be returned.

Parameters

points (array-like containing one or more points: shape (2,) for one point, shape (N, 2) for more than one point.) – The points that you want to locate – (lon, lat). If the shape of point is 1D, function will return a scalar index. If it is 2D, it will return a 1D array of indices.

lonlat_to_yx(variable)[source]

The RegualarGridInterpolator needs to have its two dimensions x and y be associated correctly with lon and lat (or vice versa). The order depends on the orientation in the variable

if the variable provided does not have a dimensions attribute, it will use the dimensions arg

property nodes
class gridded.grids.Grid_S(filename=None, *args, **kwargs)[source]

Bases: GridBase, SGrid

class gridded.grids.Grid_U(filename=None, *args, **kwargs)[source]

Bases: GridBase, UGrid

gridded.time module

class gridded.time.Time(data=(datetime.datetime(2023, 12, 7, 16, 30, 51, 728371),), filename=None, varname=None, tz_offset=None, origin=None, displacement=datetime.timedelta(0), *args, **kwargs)[source]

Bases: object

classmethod constant_time()[source]

Returns a Time object that represents no change in time

In practice, that’s a Time object with a single datetime

property data
classmethod from_netCDF(filename=None, dataset=None, varname=None, datavar=None, tz_offset=None, **kwargs)[source]

construct a Time object from a netcdf file

Parameters

  • filename=None – name of netcddf file

  • dataset=None – netcdf dataset object (one or the other)

  • varname=None – name of the netcdf variable

  • datavar=None – Either the time variable name, or A netcdf variable that needs a Time object. It will try to find the time variable that corresponds to the passed in variable.

  • tz_offset=None – offset to adjust for timezone, in hours.

get_time_array()[source]

returns a copy of the internal data array

index_of(time, extrapolate=False)[source]

Returns the index of the provided time with respect to the time intervals in the file.

Parameters

  • time (datetime.datetime) – Time to be queried

  • extrapolate (bool) – whether to allow extrapolation: i.e. will not raise if outside the bounds of the time data.

Returns

index of first time before specified time

Return type

integer

property info

Provides info about this Time object

interp_alpha(time, extrapolate=False)[source]

Returns interpolation alpha for the specified time

This is the weighting to give the index before – 1-alpha would be the weight to the index after.

Parameters

  • time (datetime.datetime) – Time to be queried

  • extrapolate (bool) – if True, 0.0 (before) or 1.0 (after) is returned. if False, a ValueError is raised if outside the time series.

Returns

interpolation alpha

Return type

float (0 <= r <= 1)

property max_time

Last time in series

Return type

datetime.datetime

property min_time

First time in series

Return type

datetime.datetime

time_in_bounds(time)[source]

Checks if time provided is within the bounds represented by this object.

Parameters

time (datetime.datetime) – time to be queried

Return type

bool

valid_time(time)[source]

Raises a ValueError if time is not within the bounds of the timeseries

gridded.utilities module

assorted utility functions needed by gridded

gridded.utilities.asarraylike(obj)[source]

If it satisfies the requirements of pyugrid the object is returned as is. If not, then numpy’s array() will be called on it.

Parameters

obj – The object to check if it’s like an array

gridded.utilities.convert_mask_to_numpy_mask(mask_var)[source]

Converts a netCDF4.Variable representing a mask into a numpy array mask ‘Water’ Values are converted to False (including ‘lake’, ‘river’ etc) ‘land’ values are converted to True

gridded.utilities.convert_numpy_datetime64_to_datetime(dt)[source]
gridded.utilities.gen_celltree_mask_from_center_mask(center_mask, sl)[source]

Generates celltree face mask from the center mask

gridded.utilities.get_dataset(ncfile, dataset=None)[source]

Utility to create a netCDF4 Dataset from a filename, list of filenames, or just pass it through if it’s already a netCDF4.Dataset

if dataset is not None, it should be a valid netCDF4 Dataset object, and it will simply be returned

gridded.utilities.get_dataset_attrs(ds)[source]

get all the attributes of the dataset as a single dict

Parameters

ds – an open netCDF4.Dataset

gridded.utilities.get_writable_dataset(ncfile, format='netcdf4')[source]

Utility to create a writable netCDF4 Dataset from a filename, list of filenames, or just pass it through if it’s already a netCDF4.Dataset

if dataset is not None, it should be a valid netCDF4 Dataset object, and it will simply be returned

gridded.utilities.isarraylike(obj)[source]

tests if obj acts enough like an array to be used in gridded.

This should catch netCDF4 variables and numpy arrays, at least, etc.

Note: these won’t check if the attributes required actually work right.

gridded.utilities.isstring(obj)[source]

py2/3 compaitlbie way to test for a string

gridded.utilities.merge_var_search_dicts(d1, d2)[source]

Values in D1 take precedence over D2 if they are not None :param d1: str -> netCDF4.Variable dict :type d1: dict :param d1: str -> netCDF4.Variable dict :type d2: dict

Returns

str -> netCDF4.Variable dict

gridded.utilities.regrid_variable(grid, o_var, location='node')[source]
gridded.utilities.search_dataset_for_any_long_name(ds, names)[source]

Searches a netCDF4.Dataset for any netCDF4.Variable that satisfies one of the search terms. :param name: list of strings or str -> list dictionary

Returns

boolean

gridded.utilities.search_dataset_for_variables_by_longname(ds, possible_names)[source]

For each longname list in possible_names, search the Dataset

Parameters

  • ds (netCDF4.Dataset) – Dataset

  • possible_names (dict) – str -> list dictionary

Returns

str -> netCDF4.Variable dictionary

gridded.utilities.search_dataset_for_variables_by_varname(ds, possible_names)[source]

For each varname list in possible_names, search the Dataset

Parameters

  • ds (netCDF4.Dataset) – Dataset

  • possible_names (dict) – str -> list dictionary

Returns

str -> netCDF4.Variable (or None if not found) dictionary

gridded.utilities.varnames_merge(cls, inc_varnames=None)[source]

Helper function to support the varnames argument pattern.

varnames is a keyword used to specify an association between a desired subcomponent of an object and a desired data source name. It is meant to be a mechanism by which custom digestion of a file can be specified.

gridded.variable module

class gridded.variable.Variable(name=None, units=None, time=None, data=None, grid=None, depth=None, data_file=None, grid_file=None, varname=None, fill_value=0, location=None, attributes=None, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', **kwargs)[source]

Bases: object

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.

at(points=None, time=None, units=None, extrapolate=False, lons=None, lats=None, unmask=False, _hash=None, _mem=True, **kwargs)[source]

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. Note that if your Z is positive-up, self.depth.positive_down should be set to False

  • 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

center_values(time, units=None, extrapolate=False)[source]

interpolate data to the center of the cells

Parameters

time – the time to interpolate at

Warning: NOT COMPLETE

NOTE: what if this data is already on the cell centers?

cf_names = []
classmethod constant(value)[source]
property data
property data_shape
default_names = []
property dimension_ordering

Returns a list that describes the dimensions of the property’s data. If a dimension_ordering is assigned, it will continue to use that. If no dimension_ordering is set, then a default ordering will be generated based on the object properties and data shape.

For example, if the data has 4 dimensions and is represented by a Grid_S (structured grid), and the Variable has a depth and time assigned, then the assumed ordering is [‘time’,’depth’,’lon’,’lat’]

If the data has 3 dimensions, self.grid is a Grid_S, and self.time is None, then the ordering is [‘depth’,’lon’,’lat’] If the data has 3 dimensions, self.grid is a Grid_U, the ordering is [‘time’,’depth’,’ele’]

classmethod from_netCDF(filename=None, varname=None, grid_topology=None, name=None, units=None, time=None, time_origin=None, grid=None, depth=None, dataset=None, data_file=None, grid_file=None, location=None, load_all=False, fill_value=0, **kwargs)[source]

Allows one-function creation of a Variable from a file.

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.

  • name (string) – Name of this object

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

  • 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

property grid_shape
property info

Information about the variable object This could be filled out more

interpolate(points=None, time=None, units=None, extrapolate=False, lons=None, lats=None, unmask=False, _hash=None, _mem=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. Note that if your Z is positive-up, self.depth.positive_down should be set to False

  • 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

property is_data_on_nodes
property location
property time
property units

Units of underlying data

Return type

string

class gridded.variable.VectorVariable(name=None, units=None, time=None, variables=None, grid=None, depth=None, grid_file=None, data_file=None, dataset=None, varnames=None, **kwargs)[source]

Bases: object

at(points=None, time=None, units=None, extrapolate=False, lons=None, lats=None, unmask=False, _hash=None, _mem=True, **kwargs)[source]

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.

    Note that if your Z is positive-up, self.depth.positive_down should be set to False

  • 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

cf_names = {}
comp_order = []
property data_shape
default_names = {}
classmethod 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)[source]

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

Parameters

  • filename (string) – Default data source. Parameters below take precedence

  • varnames ([] of string) – Names of the variables in the data source file

  • grid_topology ({string : string, ...}) – Description of the relationship between grid attributes and variable names.

  • name (string) – Name of property

  • units (string) – Units

  • time ([] of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

  • data (netCDF4.Variable or numpy.array) – Underlying data source

  • grid (pysgrid or pyugrid) – Grid that the data corresponds with

  • dataset (netCDF4.Dataset) – Instance of open Dataset

  • data_file (string) – Name of data source file

  • grid_file (string) – Name of grid source file

property is_data_on_nodes
property location
property locations
save(filepath, format='netcdf4')[source]

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

property time
property units

Units of underlying data

Return type

string

property varnames

Names of underlying variables

Return type

[] of strings

Module contents

class gridded.Dataset(ncfile=None, grid=None, variables=None, grid_topology=None, attributes=None)[source]

Bases: object

An object that represent an entire complete dataset – a collection of Variables and the Grid that they are stored on.

get_variables_by_attribute(attr, value)[source]

return the variables that have attributes that fit the defined input

Parameters

  • attr – the name of the attribute you want to match

  • value – the value of the attribute you want to match

fixme: make this a bit more flexible, more like the netCDF4 version

property info

Information about the Dataset object

save(filename, format='netcdf4')[source]

save the dataset to a file

Parameters

  • filename – full path to file to save to.

  • format – format to save – ‘netcdf3’ or ‘netcdf4’ are the only options at this point.

class gridded.Grid[source]

Bases: object

Factory class that generates grid objects. Also handles common loading and parsing operations

static from_netCDF(filename=None, dataset=None, grid_type=None, grid_topology=None, _default_types=(('ugrid', <class 'gridded.grids.Grid_U'>), ('sgrid', <class 'gridded.grids.Grid_S'>), ('rgrid', <class 'gridded.grids.Grid_R'>)), *args, **kwargs)[source]
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

class gridded.Grid_R(node_lon=None, node_lat=None, grid_topology=None, node_dimensions=None, node_coordinates=None, *args, **kwargs)[source]

Bases: GridBase

Rectangular Grid

lon and lat of the nodes are vectors

property center_lat
property center_lon
property centers
infer_location(variable)[source]

fixme: should first look for “location” attribute.

But now we are checking variable dimensions to which part of the grid it is on.

interpolate_var_to_points(points, variable, method='linear', indices=None, slices=None, mask=None, **kwargs)[source]
locate_faces(points)[source]

Returns the node grid indices, one per point.

Points that are not on the node grid will have an index of -1

If a single point is passed in, a single index will be returned. If a sequence of points is passed in an array of indexes will be returned.

Parameters

points (array-like containing one or more points: shape (2,) for one point, shape (N, 2) for more than one point.) – The points that you want to locate – (lon, lat). If the shape of point is 1D, function will return a scalar index. If it is 2D, it will return a 1D array of indices.

lonlat_to_yx(variable)[source]

The RegualarGridInterpolator needs to have its two dimensions x and y be associated correctly with lon and lat (or vice versa). The order depends on the orientation in the variable

if the variable provided does not have a dimensions attribute, it will use the dimensions arg

property nodes
class gridded.Grid_S(filename=None, *args, **kwargs)[source]

Bases: GridBase, SGrid

class gridded.Grid_U(filename=None, *args, **kwargs)[source]

Bases: GridBase, UGrid

class gridded.Time(data=(datetime.datetime(2023, 12, 7, 16, 30, 51, 728371),), filename=None, varname=None, tz_offset=None, origin=None, displacement=datetime.timedelta(0), *args, **kwargs)[source]

Bases: object

classmethod constant_time()[source]

Returns a Time object that represents no change in time

In practice, that’s a Time object with a single datetime

property data
classmethod from_netCDF(filename=None, dataset=None, varname=None, datavar=None, tz_offset=None, **kwargs)[source]

construct a Time object from a netcdf file

Parameters

  • filename=None – name of netcddf file

  • dataset=None – netcdf dataset object (one or the other)

  • varname=None – name of the netcdf variable

  • datavar=None – Either the time variable name, or A netcdf variable that needs a Time object. It will try to find the time variable that corresponds to the passed in variable.

  • tz_offset=None – offset to adjust for timezone, in hours.

get_time_array()[source]

returns a copy of the internal data array

index_of(time, extrapolate=False)[source]

Returns the index of the provided time with respect to the time intervals in the file.

Parameters

  • time (datetime.datetime) – Time to be queried

  • extrapolate (bool) – whether to allow extrapolation: i.e. will not raise if outside the bounds of the time data.

Returns

index of first time before specified time

Return type

integer

property info

Provides info about this Time object

interp_alpha(time, extrapolate=False)[source]

Returns interpolation alpha for the specified time

This is the weighting to give the index before – 1-alpha would be the weight to the index after.

Parameters

  • time (datetime.datetime) – Time to be queried

  • extrapolate (bool) – if True, 0.0 (before) or 1.0 (after) is returned. if False, a ValueError is raised if outside the time series.

Returns

interpolation alpha

Return type

float (0 <= r <= 1)

property max_time

Last time in series

Return type

datetime.datetime

property min_time

First time in series

Return type

datetime.datetime

time_in_bounds(time)[source]

Checks if time provided is within the bounds represented by this object.

Parameters

time (datetime.datetime) – time to be queried

Return type

bool

valid_time(time)[source]

Raises a ValueError if time is not within the bounds of the timeseries

class gridded.Variable(name=None, units=None, time=None, data=None, grid=None, depth=None, data_file=None, grid_file=None, varname=None, fill_value=0, location=None, attributes=None, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', **kwargs)[source]

Bases: object

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.

at(points=None, time=None, units=None, extrapolate=False, lons=None, lats=None, unmask=False, _hash=None, _mem=True, **kwargs)[source]

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. Note that if your Z is positive-up, self.depth.positive_down should be set to False

  • 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

center_values(time, units=None, extrapolate=False)[source]

interpolate data to the center of the cells

Parameters

time – the time to interpolate at

Warning: NOT COMPLETE

NOTE: what if this data is already on the cell centers?

cf_names = []
classmethod constant(value)[source]
property data
property data_shape
default_names = []
property dimension_ordering

Returns a list that describes the dimensions of the property’s data. If a dimension_ordering is assigned, it will continue to use that. If no dimension_ordering is set, then a default ordering will be generated based on the object properties and data shape.

For example, if the data has 4 dimensions and is represented by a Grid_S (structured grid), and the Variable has a depth and time assigned, then the assumed ordering is [‘time’,’depth’,’lon’,’lat’]

If the data has 3 dimensions, self.grid is a Grid_S, and self.time is None, then the ordering is [‘depth’,’lon’,’lat’] If the data has 3 dimensions, self.grid is a Grid_U, the ordering is [‘time’,’depth’,’ele’]

classmethod from_netCDF(filename=None, varname=None, grid_topology=None, name=None, units=None, time=None, time_origin=None, grid=None, depth=None, dataset=None, data_file=None, grid_file=None, location=None, load_all=False, fill_value=0, **kwargs)[source]

Allows one-function creation of a Variable from a file.

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.

  • name (string) – Name of this object

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

  • 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

property grid_shape
property info

Information about the variable object This could be filled out more

interpolate(points=None, time=None, units=None, extrapolate=False, lons=None, lats=None, unmask=False, _hash=None, _mem=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. Note that if your Z is positive-up, self.depth.positive_down should be set to False

  • 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

property is_data_on_nodes
property location
property time
property units

Units of underlying data

Return type

string

class gridded.VectorVariable(name=None, units=None, time=None, variables=None, grid=None, depth=None, grid_file=None, data_file=None, dataset=None, varnames=None, **kwargs)[source]

Bases: object

at(points=None, time=None, units=None, extrapolate=False, lons=None, lats=None, unmask=False, _hash=None, _mem=True, **kwargs)[source]

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.

    Note that if your Z is positive-up, self.depth.positive_down should be set to False

  • 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

cf_names = {}
comp_order = []
property data_shape
default_names = {}
classmethod 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)[source]

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

Parameters

  • filename (string) – Default data source. Parameters below take precedence

  • varnames ([] of string) – Names of the variables in the data source file

  • grid_topology ({string : string, ...}) – Description of the relationship between grid attributes and variable names.

  • name (string) – Name of property

  • units (string) – Units

  • time ([] of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

  • data (netCDF4.Variable or numpy.array) – Underlying data source

  • grid (pysgrid or pyugrid) – Grid that the data corresponds with

  • dataset (netCDF4.Dataset) – Instance of open Dataset

  • data_file (string) – Name of data source file

  • grid_file (string) – Name of grid source file

property is_data_on_nodes
property location
property locations
save(filepath, format='netcdf4')[source]

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

property time
property units

Units of underlying data

Return type

string

property varnames

Names of underlying variables

Return type

[] of strings