Function Reference

ocgis.format_return(ret_path, ops, with_auxiliary_files=False)[source]

Format an OpenClimateGIS path returning an absolute path to a zip file or simply passing ret_path through.

>>> import ocgis
>>> ops = ocgis.OcgOperations(...)
>>> ret = ops.execute()
>>> new_path = ocgis.format_return(ret,ops)
Parameters:
Raises:

NotImplementedError

Returns:

str

ocgis.util.helpers.add_shapefile_unique_identifier(in_path, out_path, name=None, template=None)[source]
>>> add_shapefile_unique_identifier('/path/to/foo.shp', '/path/to/new_foo.shp')
'/path/to/new_foo.shp'
Parameters:
  • in_path (str) – Full path to the input shapefile.
  • out_path (str) – Full path to the output shapefile.
  • name (str) – The name of the unique identifer. If None, defaults to ocgis.constants.OCGIS_UNIQUE_GEOMETRY_IDENTIFIER.
  • template (str) – The integer attribute to copy as the unique identifier.
Returns:

Path to the copied shapefile with the addition of a unique integer attribute called name.

Return type:

str

ocgis.util.helpers.get_bounds_from_1d(centroids)[source]
Parameters:centroids (numpy.ndarray) – Vector representing center coordinates from which to interpolate bounds.
Returns:A n-by-2 array with n equal to the shape of centroids.
>>> import numpy as np
>>> centroids = np.array([1,2,3])
>>> get_bounds_from_1d(centroids)
np.array([[0, 1],[1, 2],[2, 3]])
Return type:numpy.ndarray
Raises:NotImplementedError, ValueError
ocgis.util.helpers.get_sorted_uris_by_time_dimension(uris, variable=None)[source]

Sort a sequence of NetCDF URIs by the maximum time extent in ascending order.

Parameters:uris (list[str]) – The sequence of NetCDF URIs to sort.
>>> uris = ['/path/to/file2.nc', 'path/to/file1.nc']
Parameters:variable (str) – The target variable for sorting. If None is provided, then the variable will be autodiscovered.
Returns:A sequence of sorted URIs.
Return type:list[str]
ocgis.util.large_array.compute(ops, tile_dimension, verbose=False, use_optimizations=True)[source]

Used for computations on large arrays where memory limitations are a consideration. It is is also useful for extracting data from a server that has limitations on the size of requested data arrays. This function creates an empty destination NetCDF file that is then filled by executing the operations on chunks of the requested target dataset(s) and filling the destination NetCDF file.

Parameters:
  • ops (ocgis.OcgOperations) – The target operations to tile. There must be a calculation associated with the operations.
  • tile_dimension (int) – The target tile/chunk dimension. This integer value must be greater than zero.
  • verbose (bool) – If True, print more verbose information to terminal.
  • use_optimizations (bool) – If True, cache Field and TemporalGroupDimension objects for reuse during tile iteration.
Raises:

AssertionError, ValuError

Returns:

Path to the output NetCDF file.

Return type:

str

>>> from ocgis import RequestDataset, OcgOperations
>>> from ocgis.util.large_array import compute
>>> rd = RequestDataset(uri='/path/to/file', variable='tas')
>>> ops = OcgOperations(dataset=rd,calc=[{'func':'mean','name':'mean'}],output_format='nc')
>>> ret = compute(ops, 25)
ocgis.regrid.base.iter_esmf_fields(ofield, regrid_method='auto', value_mask=None, split=True)[source]

For all data or a single time coordinate, yield an ESMF Field from the input OCGIS field ofield. Only one realization and level are allowed.

Parameters:
  • ofield (ocgis.Field) – The input OCGIS Field object.
  • regrid_method – See get_esmf_grid().
  • value_mask – See get_esmf_grid().
  • split (bool) – If True, yield a single time slice/coordinate from the source field. If False, yield all time coordinates. When False, OCGIS uses ESMF’s ndbounds argument to field creation. Use True if there are memory limitations. Use False for faster performance.
Return type:

tuple(str, ESMF.driver.field.Field, int)

The returned tuple elements are:

Index Type Description
0 str The variable name currently being converted.
1 Field The ESMF Field object.
2 int The current time index of the yielded ESMF field. If split=False, This will be slice(None).
Raises:AssertionError
ocgis.regrid.base.regrid_field(source, destination, regrid_method='auto', value_mask=None, split=True)[source]

Regrid source data to match the grid of destination.

Parameters:
Return type:

ocgis.Field

ocgis.regrid.base.get_esmf_grid(ogrid, regrid_method='auto', value_mask=None)[source]

Create an ESMF Grid object from an OCGIS ocgis.Grid object.

Parameters:
  • ogrid (Grid) – The target OCGIS grid to convert to an ESMF grid.
  • regrid_method – If 'auto' or ESMF.api.constants.RegridMethod.CONSERVE, use corners/bounds from the grid object. If ESMF.api.constants.RegridMethod.CONSERVE, the corners/bounds must be present on the grid.
  • value_mask (numpy.array) – If an bool numpy.array with same shape as ogrid, use a logical or operation with the OCGIS field mask when creating the input grid’s mask. Values of True in value_mask are assumed to be masked. If None is provided (the default) then the mask will be set using the spatial mask on ogrid.
Return type:

ESMF.driver.grid.Grid