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

classmethod from_netCDF(filename=None, dataset=None, data_file=None, grid_file=None, **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_types = [<class 'gridded.depth.L_Depth'>]
sd_types = [<class 'gridded.depth.ROMS_Depth'>, <class 'gridded.depth.FVCOM_Depth'>]
surf_types = [<class 'gridded.depth.DepthBase'>]
static surface_only(surface_index=-1, **kwargs)[source]

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

class gridded.depth.DepthBase(name=None, surface_index=-1, bottom_index=0, default_surface_boundary_condition='extrapolate', default_bottom_boundary_conditon='mask', **kwargs)[source]

Bases: object

property bottom_index
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.

property surface_index
class gridded.depth.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)[source]

Bases: S_Depth

property bottom_index
cf_names = {'bathymetry': ['sea_floor_depth_below_geoid'], 'h_center': ['sea_floor_depth_below_geoid'], 'siglay': ['ocean_sigma/general_coordinate'], 'siglay_center': ['ocean_sigma/general_coordinate'], 'siglev': ['ocean_sigma/general_coordinate'], 'siglev_center': ['ocean_sigma/general_coordinate'], 'zeta': ['sea_surface_height_above_geoid']}
default_names = {'bathymetry': ['h'], 'h_center': ['h_center'], 'siglay': ['siglay'], 'siglay_center': ['siglev_center'], 'siglev': ['siglev'], 'siglev_center': ['siglev_center'], 'zeta': ['zeta']}
get_transect(points, time, data_shape=None, _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

  • data_shape (tuple of int or None) – Describes the shape of the data to be interpolated. If the first dimension is the number of layers or if None, then siglay is used. If the first dimension is the number of levels, then siglev is used.

Returns:

numpy array of shape (n, num_w_levels) of n s-coordinate transects

property num_layers
property num_levels
property surface_index
class gridded.depth.L_Depth(terms=None, **kwargs)[source]

Bases: DepthBase

property bottom_index
cf_names = {'depth_levels': 'depth'}
default_names = {'depth_levels': ['depth', 'depth_levels', 'Depth']}
default_terms = ['depth_levels']
classmethod from_netCDF(filename=None, dataset=None, grid_file=None, data_file=None, name=None, topology=None, terms=None, **kwargs)[source]
interpolation_alphas(points, time=None, data_shape=None, surface_boundary_condition=None, bottom_boundary_condition=None, extrapolate=False, _hash=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.

property num_layers
property num_levels
property surface_index
class gridded.depth.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)[source]

Bases: S_Depth

Sigma coordinate depth object for ROMS style output

property bottom_index
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']}
default_names = {'Cs_r': ['Cs_r'], 'Cs_w': ['Cs_w'], 'bathymetry': ['h'], 'hc': ['hc'], 's_rho': ['s_rho'], 's_w': ['s_w'], 'zeta': ['zeta']}
get_transect(points, time, data_shape=None, _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

  • data_shape (tuple of int) – shape of the variable to be interpolated. This param is used to determine whether to index on the sigma layers or levels.

Returns:

numpy array of shape (n, num_w_levels) of n s-coordinate transects

property num_layers
property num_levels
property surface_index
class gridded.depth.S_Depth(name=None, time=None, grid=None, bathymetry=None, zeta=None, terms=None, vtransform=2, 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.

property bottom_index
classmethod from_netCDF(filename=None, grid_topology=None, name=None, time=None, time_origin=None, displacement=None, tz_offset=None, grid=None, dataset=None, data_file=None, grid_file=None, bathymetry=None, zeta=None, terms=None, vtransform=2, **kwargs)[source]
Parameters:

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

  • terms (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)

  • tz_offset (datetime.timedelta or float or integer hours) – offset to compensate for time zone shifts

  • 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

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

get_surface_depth(points, time, data_shape, _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

  • data_shape – Shape of the variable to be interpolated. The first dimension is expected to be depth

Returns:

numpy array of shape (n, 1) of n surface level values

get_transect(points, time, data_shape=None, _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

  • data_shape (tuple of int) – Shape of the variable to be interpolated. The first dimension is expected to be depth

Returns:

numpy array of shape (n, data_shape[0]) of n depth level transects

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_layers
property num_levels
property surface_index

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.

classmethod from_netCDF(filename=None, grid_file=None, variable_files=None, grid_topology=None)[source]
NOTE: only loading from a single file is currently implemented.

you can create a DATaset by hand, by loading the grid and variables separately, and then adding them

load a gridded.Dataset from a netCDF file

Parameters:

  • filename – filename or netCDF4 compatible OpeNDAP url. It is assumed to contain the grid and variables.

  • grid_file – filename of the file that contains the grid, if separate.

  • variable_files – filename of filenames that contain the variables.

NOTE: Either the filename or the grid_file and variable_files should be specified.

not all three.

Parameters:

grid_topology (mapping with keys of topology components and values are variable names.) – mapping of grid topology components to netcdf variable names. used to load non-confirming files.

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, data_file=None, grid_file=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

exception gridded.time.OutOfTimeRangeError[source]

Bases: ValueError

Used for when data is asked for outside of the range of times supported by a Time object.

class gridded.time.Time(data=None, filename=None, varname=None, tz_offset=None, new_tz_offset=None, tz_offset_name='', origin=None, displacement=None, *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
property displacement
classmethod from_netCDF(filename=None, dataset=None, varname=None, datavar=None, tz_offset=None, new_tz_offset=None, tz_offset_name=None, origin=None, displacement=None, **kwargs)[source]

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.

Parameters:

  • filename=None – name of netcdf file

  • dataset=None – netcdf dataset object (only one of filename or dataset should be specified)

  • varname=None – Name of the time variable.

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

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

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

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

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)

static locate_time_var_from_var(datavar)[source]
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

property tz_offset

Timezone offset of the time series

Return type:

number

valid_time(time)[source]

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

Parameters:

time – a datetime object that you want to check.

exception gridded.time.TimeSeriesError[source]

Bases: ValueError

Used for when data is asked for outside of the range of times supported by a Time object.

gridded.time.offset_as_iso_string(offset_hours)[source]

returns the offset as an isostring:

-8:00

3:30

etc …

gridded.time.parse_time_offset(unit_str)[source]

find the time offset from a CF-style time units string.

Follows the ISO format(s):

(‘UTC’, ‘days since 2024-1-1T00:00:00Z’), (‘UTC-0’, ‘days since 2024-1-1T00:00:00+00:00’), (‘naive’, ‘days since 2024-1-1T00:00:00’), (‘offset-7’, ‘days since 2024-1-1T00:00:00-7:00’) :param unit_str: CF-style time unit string

Returns:

Number: hours, str: name:

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.can_create_class(cls, ds=None, dg=None)[source]
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

fixme: why can you pass in a dataset specifically ???

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 compatble 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.parse_filename_dataset_args(filename=None, dataset=None, data_file=None, grid_file=None)[source]

A perinnial problem is that we need to be able to accept a variety of filename/dataset arguments. This function will return a tuple of ‘ds’ and ‘dg’ where ds is the netCDF4.Dataset for the data and dg is the netCDF4.Dataset for the grid. If such datasets are from the same file, it will return the same object for both.

Parameters:

  • filename – str or pathlike

  • dataset – netCDF4.Dataset

  • data_file – str, pathlike, or netCDF4.Dataset

  • grid_file – str, pathlike, or netCDF4.Dataset

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.search_netcdf_vars(cls=None, ds=None, dg=None)[source]

Given a class with a .default_names and .cf_names attributes, search a datafile netCDF4.Dataset and a possible grid netCDF4.Dataset for variables that are sought by the class

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.

    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],
 ...]

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

  • lats – 1D iterable of latitude values. This is ignored if points is provided

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.

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, displacement=None, tz_offset=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

  • tz_offset (datetime.timedelta or float or integer hours) – offset to compensate for time zone shifts

  • 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

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.

    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],
 ...]

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

  • lats – 1D iterable of latitude values. This is ignored if points is provided

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.

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.

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

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, displacement=None, tz_offset=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

  • tz_offset (datetime.timedelta or float or integer hours) – offset to compensate for time zone shifts

  • 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

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

classmethod from_netCDF(filename=None, grid_file=None, variable_files=None, grid_topology=None)[source]
NOTE: only loading from a single file is currently implemented.

you can create a DATaset by hand, by loading the grid and variables separately, and then adding them

load a gridded.Dataset from a netCDF file

Parameters:

  • filename – filename or netCDF4 compatible OpeNDAP url. It is assumed to contain the grid and variables.

  • grid_file – filename of the file that contains the grid, if separate.

  • variable_files – filename of filenames that contain the variables.

NOTE: Either the filename or the grid_file and variable_files should be specified.

not all three.

Parameters:

grid_topology (mapping with keys of topology components and values are variable names.) – mapping of grid topology components to netcdf variable names. used to load non-confirming files.

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, data_file=None, grid_file=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

exception gridded.OutOfTimeRangeError[source]

Bases: ValueError

Used for when data is asked for outside of the range of times supported by a Time object.

class gridded.Time(data=None, filename=None, varname=None, tz_offset=None, new_tz_offset=None, tz_offset_name='', origin=None, displacement=None, *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
property displacement
classmethod from_netCDF(filename=None, dataset=None, varname=None, datavar=None, tz_offset=None, new_tz_offset=None, tz_offset_name=None, origin=None, displacement=None, **kwargs)[source]

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.

Parameters:

  • filename=None – name of netcdf file

  • dataset=None – netcdf dataset object (only one of filename or dataset should be specified)

  • varname=None – Name of the time variable.

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

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

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

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

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)

static locate_time_var_from_var(datavar)[source]
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

property tz_offset

Timezone offset of the time series

Return type:

number

valid_time(time)[source]

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

Parameters:

time – a datetime object that you want to check.

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.

    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],
 ...]

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

  • lats – 1D iterable of latitude values. This is ignored if points is provided

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.

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, displacement=None, tz_offset=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

  • tz_offset (datetime.timedelta or float or integer hours) – offset to compensate for time zone shifts

  • 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

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.

    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],
 ...]

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

  • lats – 1D iterable of latitude values. This is ignored if points is provided

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.

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.

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

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, displacement=None, tz_offset=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

  • tz_offset (datetime.timedelta or float or integer hours) – offset to compensate for time zone shifts

  • 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

  • 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