podpac.coordinates.Coordinates

class podpac.coordinates.Coordinates(**kwargs: Any)[source]

Bases: HasTraits

Multidimensional Coordinates.

Coordinates are used to evaluate Nodes and to define the coordinates of a DataSource nodes. The API is modeled after coords in xarray:

Coordinates are created from a list of coordinate values and dimension names.

Coordinate values are always either float or np.datetime64. For convenience, podpac automatically converts datetime strings such as '2018-01-01' to np.datetime64.

The allowed dimensions are 'lat', 'lon', 'time', and 'alt'.

Coordinates from multiple dimensions can be stacked together to represent a list of coordinates instead of a grid of coordinates. The name of the stacked coordinates uses an underscore to combine the underlying dimensions, e.g. 'lat_lon'.

Coordinates are dict-like, for example:

get coordinates by dimension name: coords['lat']

get iterable dimension keys and coordinates values: coords.keys(), coords.values()

loop through dimensions: for dim in coords: ...

Parameters:

dims – Tuple of dimension names, potentially stacked.
udims – Tuple of individual dimension names, always unstacked.

Alternative Constructors

`from_definition`(d)	Create podpac Coordinates from a coordinates definition.
`from_json`(s)	Create podpac Coordinates from a coordinates JSON definition.
`from_xarray`(x[, crs, validate_crs])	Create podpac Coordinates from xarray coords.
`grid`([dims, crs])	Create a grid of coordinates.
`points`([crs, dims])	Create a list of multidimensional coordinates.

Methods

`__init__`(coords[, dims, crs, validate_crs])	Create multidimensional coordinates.
`drop`(dims[, ignore_missing])	Remove the given dimensions from the Coordinates dims.
`from_geotransform`(geotransform, shape[, ...])	Creates Coordinates from GDAL Geotransform.
`from_url`(url)	Create podpac Coordinates from a WMS/WCS request.
`get`(dim[, default])	dict-like get: get coordinates by dimension name with an optional
`get_area_bounds`(boundary)	Get coordinate area bounds, including segment information, for each unstacked dimension.
`intersect`(other[, dims, outer, return_index])	Get the coordinate values that are within the bounds of a given coordinates object.
`is_stacked`(dim)
`issubset`(other)	Report whether other Coordinates contains these coordinates.
`items`()	dict-like items: (dim, coordinates) pairs
`iterchunks`(shape[, return_slices])	Get a generator that yields Coordinates no larger than the given shape until the entire Coordinates is covered.
`keys`()	dict-like keys: dims
`select`(bounds[, return_index, outer])	Get the coordinate values that are within the given bounds for each dimension.
`simplify`()	Simplify coordinates in each dimension.
`trait_defaults`(names, *metadata)	Return a trait's default value or a dictionary of them
`trait_has_value`(name)	Returns True if the specified trait has a value.
`trait_values`(**metadata)	A `dict` of trait names and their values.
`transform`(crs)	Transform coordinate dimensions (lat, lon, alt) into a different coordinate reference system.
`transform_time`(units)
`transpose`(dims, *kwargs)	Transpose (re-order) the dimensions of the Coordinates.
`udrop`(dims[, ignore_missing])	Remove the given individual dimensions from the Coordinates udims.
`unique`([return_index])	Remove duplicate coordinate values from each dimension.
`unstack`()	Unstack the coordinates of all of the dimensions.
`update`(other)	dict-like update: add/replace coordinates using another Coordinates object
`values`()	dict-like values: coordinates for each key/dimension

Attributes

`CRS`
`alt_units`
`bounds`	Dictionary of (low, high) coordinates bounds in each unstacked dimension
`crs`	A trait for unicode strings.
`definition`	Serializable coordinates definition.
`dims`	Tuple of dimension names, potentially stacked.
`full_definition`	Serializable coordinates definition, containing all properties.
`geotransform`	GDAL geotransform.
`hash`
`json`	JSON-serialized coordinates definition.
`ndim`	Number of dimensions.
`properties`	Dictionary of the coordinate properties.
`shape`	Tuple of the number of coordinates in each dimension.
`size`	Total number of coordinates.
`udims`	Tuple of unstacked dimension names.
`ushape`
`xcoords`	xarray coords
`xdims`	Tuple of indexing dimension names used to make xarray DataArray.

Members:

__init__(coords, dims=None, crs=None, validate_crs=True)[source]

Create multidimensional coordinates.

Parameters:

coords (list) –
List of coordinate values for each dimension. Valid coordinate values:
- single coordinate value (number, datetime64, or str)
- array of coordinate values
- list of stacked coordinate values
- Coordinates1d or StackedCoordinates object
dims (list of str, optional) –
List of dimension names. Optional if all items in coords are named. Valid names are
- ’lat’, ‘lon’, ‘alt’, or ‘time’ for unstacked coordinates
- dimension names joined by an underscore for stacked coordinates
crs (str, optional) – Coordinate reference system. Supports PROJ4 and WKT.
validate_crs (bool, optional) – Use False to skip crs validation. Default True.

property CRS

property alt_units

property bounds

Dictionary of (low, high) coordinates bounds in each unstacked dimension

Type:: dict

crs: A trait for unicode strings.

property definition

Serializable coordinates definition.

Type:: list

property dims

Tuple of dimension names, potentially stacked.

See also

udims

Type:: tuple

drop(dims, ignore_missing=False)[source]

Remove the given dimensions from the Coordinates dims.

Parameters:

dims (str, list) – Dimension(s) to drop.
ignore_missing (bool, optional) – If True, do not raise an exception if a given dimension is not in dims. Default False.

Returns:

Coordinates object with the given dimensions removed

Return type:

Coordinates

Raises:

KeyError – If a given dimension is missing in the Coordinates (and ignore_missing is False).

See also

udrop

classmethod from_definition(d)[source]

Create podpac Coordinates from a coordinates definition.

Parameters:: d (list) – coordinates definition
Returns:: podpac Coordinates
Return type:: Coordinates

See also

from_json, definition

classmethod from_geotransform(geotransform, shape, crs=None, validate_crs=True)[source]: Creates Coordinates from GDAL Geotransform.

classmethod from_json(s)[source]

Create podpac Coordinates from a coordinates JSON definition.

Example JSON definition:

[
    {
        "name": "lat",
        "start": 1,
        "stop": 10,
        "step": 0.5,
    },
    {
        "name": "lon",
        "start": 1,
        "stop": 2,
        "size": 100
    },
    {
        "name": "time",
        "values": [
            "2018-01-01",
            "2018-01-03",
            "2018-01-10"
        ]
    }
]

Parameters:: s (str) – coordinates JSON definition
Returns:: podpac Coordinates
Return type:: Coordinates

See also

json

classmethod from_url(url)[source]

Create podpac Coordinates from a WMS/WCS request.

Parameters:: url (str, dict) – The raw WMS/WCS request url, or a dictionary of query parameters
Returns:: podpac Coordinates
Return type:: Coordinates

classmethod from_xarray(x, crs=None, validate_crs=False)[source]

Create podpac Coordinates from xarray coords.

Parameters:

x (DataArray, Dataset, DataArrayCoordinates, DatasetCoordinates) – DataArray, Dataset, or xarray coordinates
crs (str, optional) – Coordinate reference system. Supports any PROJ4 or PROJ6 compliant string (https://proj.org/). If not provided, the crs will be loaded from x.attrs if possible.
validate_crs (bool, optional) – Default is False. If True, the crs will be validated.

Returns:

coords – podpac Coordinates

Return type:

Coordinates

property full_definition

Serializable coordinates definition, containing all properties. For internal use.

Type:: list

property geotransform

GDAL geotransform.

Type:: tuple

get(dim, default=None)[source]: dict-like get: get coordinates by dimension name with an optional

get_area_bounds(boundary)[source]

Get coordinate area bounds, including segment information, for each unstacked dimension.

Parameters:: boundary (dict) – dictionary of boundary offsets for each unstacked dimension. Non-segment dimensions can be omitted.
Returns:: area_bounds – Dictionary of (low, high) coordinates area_bounds in each unstacked dimension
Return type:: dict

classmethod grid(dims=None, crs=None, **kwargs)[source]

Create a grid of coordinates.

Valid coordinate values:

single coordinate value (number, datetime64, or str)

array of coordinate values

(start, stop, step) tuple for uniformly-spaced coordinates

Coordinates1d object

This is equivalent to creating unstacked coordinates with a list of coordinate values:

podpac.Coordinates.grid(lat=[0, 1, 2], lon=[10, 20], dims=['lat', 'lon'])
podpac.Coordinates([[0, 1, 2], [10, 20]], dims=['lan', 'lon'])

Parameters:

lat (optional) – coordinates for the latitude dimension
lon (optional) – coordinates for the longitude dimension
alt (optional) – coordinates for the altitude dimension
time (optional) – coordinates for the time dimension
dims (list of str, optional in Python>=3.6) – List of dimension names, must match the provided keyword arguments. In Python 3.6 and above, the dims argument is optional, and the dims will match the order of the provided keyword arguments.
crs (str, optional) – Coordinate reference system. Supports any PROJ4 or PROJ6 compliant string (https://proj.org).

Returns:

podpac Coordinates

Return type:

Coordinates

See also

points

property hash

intersect(other, dims=None, outer=False, return_index=False)[source]

Get the coordinate values that are within the bounds of a given coordinates object.

The intersection is calculated in each dimension separately.

The default intersection selects coordinates that are within the other coordinates bounds:

In [1]: coords = Coordinates([[0, 1, 2, 3]], dims=['lat'])

In [2]: other = Coordinates([[1.5, 2.5]], dims=['lat'])

In [3]: coords.intersect(other).coords
Out[3]:
Coordinates:
  * lat      (lat) float64 2.0

The outer intersection selects the minimal set of coordinates that contain the other coordinates:

In [4]: coords.intersect(other, outer=True).coords
Out[4]:
Coordinates:
  * lat      (lat) float64 1.0 2.0 3.0

The outer intersection also selects a boundary coordinate if the other coordinates are outside this coordinates bounds but inside its area bounds:

In [5]: other_near = Coordinates([[3.25]], dims=['lat'])

In [6]: other_far = Coordinates([[10.0]], dims=['lat'])

In [7]: coords.intersect(other_near, outer=True).coords
Coordinates:
  * lat      (lat) float64 3.0

In [8]: coords.intersect(other_far, outer=True).coords
Coordinates:
  * lat      (lat) float64

Parameters:

other (Coordinates1d, StackedCoordinates, Coordinates) – Coordinates to intersect with.
dims (list, optional) – Restrict intersection to the given dimensions. Default is all available dimensions.
outer (bool, optional) – If True, do an outer intersection. Default False.
return_index (bool, optional) – If True, return index for the selection in addition to coordinates. Default False.

Returns:

intersection (Coordinates) – Coordinates object consisting of the intersection in each dimension.
selection_index (list) – List of indices for each dimension that produces the intersection, only if return_index is True.

is_stacked(dim)[source]

issubset(other)[source]

Report whether other Coordinates contains these coordinates.

Note that the dimension order and stacking is ignored.

Parameters:: other (Coordinates) – Other coordinates to check
Returns:: issubset – True if these coordinates are a subset of the other coordinates in every dimension.
Return type:: bool

items()[source]: dict-like items: (dim, coordinates) pairs

iterchunks(shape, return_slices=False)[source]

Get a generator that yields Coordinates no larger than the given shape until the entire Coordinates is covered.

Parameters:

shape (tuple) – The maximum shape of the chunk, with sizes corresponding to the dims.
return_slice (boolean, optional) – Return slice in addition to Coordinates chunk.

Yields:

coords (Coordinates) – A Coordinates object with one chunk of the coordinates.
slices (list) – slices for this Coordinates chunk, only if return_slices is True

property json

JSON-serialized coordinates definition.

The json can be used to create new Coordinates:

c = podapc.Coordinates(...)
c2 = podpac.Coordinates.from_json(c.definition)

The serialized definition is used to define coordinates in node definitions and to transport coordinates, e.g. over HTTP and in AWS lambda functions. It also provides a consistent hashable value.

See also

from_json

Type:: str

keys()[source]: dict-like keys: dims

property ndim

Number of dimensions.

Type:: int

classmethod points(crs=None, dims=None, **kwargs)[source]

Create a list of multidimensional coordinates.

Valid coordinate values:

single coordinate value (number, datetime64, or str)

array of coordinate values

(start, stop, step) tuple for uniformly-spaced coordinates

Coordinates1d object

Note that the coordinates for each dimension must be the same size.

This is equivalent to creating stacked coordinates with a list of coordinate values and a stacked dimension name:

podpac.Coordinates.points(lat=[0, 1, 2], lon=[10, 20, 30], dims=['lat', 'lon'])
podpac.Coordinates([[[0, 1, 2], [10, 20, 30]]], dims=['lan_lon'])

Parameters:

lat (optional) – coordinates for the latitude dimension
lon (optional) – coordinates for the longitude dimension
alt (optional) – coordinates for the altitude dimension
time (optional) – coordinates for the time dimension
dims (list of str, optional in Python>=3.6) – List of dimension names, must match the provided keyword arguments. In Python 3.6 and above, the dims argument is optional, and the dims will match the order of the provided keyword arguments.
crs (str, optional) – Coordinate reference system. Supports any PROJ4 or PROJ6 compliant string (https://proj.org/).

Returns:

podpac Coordinates

Return type:

Coordinates

See also

grid

property properties

Dictionary of the coordinate properties.

Type:: dict

select(bounds, return_index=False, outer=False)[source]

Get the coordinate values that are within the given bounds for each dimension.

The default selection returns coordinates that are within the bounds:

In [1]: c = Coordinates([[0, 1, 2, 3], [10, 20, 30, 40]], dims=['lat', 'lon'])

In [2]: c.select({'lat': [1.5, 3.5]})
Out[2]:
Coordinates
        lat: ArrayCoordinates1d(lat): Bounds[2.0, 3.0], N[2]
        lon: ArrayCoordinates1d(lon): Bounds[10.0, 40.0], N[4]

In [3]: c.select({'lat': [1.5, 3.5], 'lon': [25, 45]})
Out[3]:
Coordinates
        lat: ArrayCoordinates1d(lat): Bounds[2.0, 3.0], N[2]
        lon: ArrayCoordinates1d(lon): Bounds[30.0, 40.0], N[2]

The outer selection returns the minimal set of coordinates that contain the bounds:

In [4]: c.select({'lat':[1.5, 3.5]}, outer=True)
Out[4]:
Coordinates
        lat: ArrayCoordinates1d(lat): Bounds[1.0, 3.0], N[3]
        lon: ArrayCoordinates1d(lon): Bounds[10.0, 40.0], N[4]

Parameters:

bounds (dict) – Selection bounds for the desired coordinates.
outer (bool, optional) – If True, do outer selections. Default False.
return_index (bool, optional) – If True, return index for the selections in addition to coordinates. Default False.

Returns:

selection (Coordinates) – Coordinates object with coordinates within the given bounds.
selection_index (list) – index for the selected coordinates in each dimension (only if return_index=True)

property shape

Tuple of the number of coordinates in each dimension.

Type:: tuple

simplify()[source]

Simplify coordinates in each dimension.

Returns:: simplified – Simplified coordinates.
Return type:: Coordinates

property size

Total number of coordinates.

Type:: int

transform(crs)[source]

Transform coordinate dimensions (lat, lon, alt) into a different coordinate reference system. Uses PROJ syntax for coordinate reference systems and units.

See PROJ Documentation for more information about creating PROJ4 strings. See PROJ4 Distance Units for unit string references.

Examples

Transform gridded coordinates:

c = Coordinates([np.linspace(-10, 10, 21), np.linspace(-30, -10, 21)], dims=['lat', 'lon'])
c.crs

>> 'EPSG:4326'

c.transform('EPSG:2193')

>> Coordinates
    lat: ArrayCoordinates1d(lat): Bounds[-9881992.849134896, 29995929.885877542], N[21]
    lon: ArrayCoordinates1d(lon): Bounds[1928928.7360588573, 4187156.434405213], N[21]

Transform stacked coordinates:

c = Coordinates([(np.linspace(-10, 10, 21), np.linspace(-30, -10, 21))], dims=['lat_lon'])
c.transform('EPSG:2193')

>> Coordinates
    lat_lon[lat]: ArrayCoordinates1d(lat): Bounds[-9881992.849134896, 29995929.885877542], N[21]
    lat_lon[lon]: ArrayCoordinates1d(lon): Bounds[1928928.7360588573, 4187156.434405213], N[21]

Transform coordinates using a PROJ4 string:

c = Coordinates([np.linspace(-10, 10, 21), np.linspace(-30, -10, 21)], dims=['lat', 'lon'])
c.transform('+proj=merc +lat_ts=56.5 +ellps=GRS80')

>> Coordinates
    lat: ArrayCoordinates1d(lat): Bounds[-1847545.541169525, -615848.513723175], N[21]
    lon: ArrayCoordinates1d(lon): Bounds[-614897.0725896168, 614897.0725896184], N[21]

Parameters:: crs (str) – PROJ4 compatible coordinate reference system string.
Returns:: Transformed Coordinates
Return type:: podpac.Coordinates
Raises:: ValueError – Coordinates must have both lat and lon dimensions if either is defined

transform_time(units)[source]

transpose(*dims, **kwargs)[source]

Transpose (re-order) the dimensions of the Coordinates.

Parameters:

dim_1 (str, optional) – Reorder dims to this order. By default, reverse the dims.
dim_2 (str, optional) – Reorder dims to this order. By default, reverse the dims.
... (str, optional) – Reorder dims to this order. By default, reverse the dims.
in_place (boolean, optional) – If True, transpose the dimensions in-place. Otherwise (default), return a new, transposed Coordinates object.

Returns:

transposed – The transposed Coordinates object.

Return type:

Coordinates

See also

xarray.DataArray.transpose: return a transposed DataArray

property udims

Tuple of unstacked dimension names.

If there are no stacked dimensions, then dims and udims will be the same:

In [1]: lat = [0, 1]

In [2]: lon = [10, 20]

In [3]: time = '2018-01-01'

In [4]: c = podpac.Coordinates([lat, lon, time], dims=['lat', 'lon', 'time'])

In [5]: c.dims
Out[5]: ('lat', 'lon', 'time')

In [6]: c.udims
Out[6]: ('lat', 'lon', 'time')

If there are stacked dimensions, then udims contains the individual dimension names:

In [7]: c = podpac.Coordinates([[lat, lon], time], dims=['lat_lon', 'time'])

In [8]: c.dims
Out[8]: ('lat_lon', 'time')

In [9]: c.udims
Out[9]: ('lat', 'lon', 'time')

See also

dims

Type:: tuple

udrop(dims, ignore_missing=False)[source]

Remove the given individual dimensions from the Coordinates udims.

Unlike drop, udrop will remove parts of stacked coordinates:

In [1]: c = podpac.Coordinates([[[0, 1], [10, 20]], '2018-01-01'], dims=['lat_lon', 'time'])

In [2]: c
Out[2]:
Coordinates
    lat_lon[lat]: ArrayCoordinates1d(lat): Bounds[0.0, 1.0], N[2]
    lat_lon[lon]: ArrayCoordinates1d(lon): Bounds[10.0, 20.0], N[2]
    time: ArrayCoordinates1d(time): Bounds[2018-01-01, 2018-01-01], N[1]

In [3]: c.udrop('lat')
Out[3]:
Coordinates
    lon: ArrayCoordinates1d(lon): Bounds[10.0, 20.0], N[2]
    time: ArrayCoordinates1d(time): Bounds[2018-01-01, 2018-01-01], N[1]

Parameters:

dims (str, list) – Individual dimension(s) to drop.
ignore_missing (bool, optional) – If True, do not raise an exception if a given dimension is not in udims. Default False.

Returns:

Coordinates object with the given dimensions removed.

Return type:

Coordinates

Raises:

KeyError – If a given dimension is missing in the Coordinates (and ignore_missing is False).

See also

drop

unique(return_index=False)[source]

Remove duplicate coordinate values from each dimension.

Parameters:

return_index (bool, optional) – If True, return index for the unique coordinates in addition to the coordinates. Default False.

Returns:

unique (podpac.Coordinates) – New Coordinates object with unique, sorted coordinate values in each dimension.
unique_index (list of indices) – index for the unique coordinates in each dimension (only if return_index=True)

unstack()[source]

Unstack the coordinates of all of the dimensions.

Returns:: unstacked – A new Coordinates object with unstacked coordinates.
Return type:: podpac.Coordinates

See also

xr.DataArray.unstack

update(other)[source]: dict-like update: add/replace coordinates using another Coordinates object

property ushape

values()[source]: dict-like values: coordinates for each key/dimension

property xcoords

xarray coords

Type:: dict

property xdims

Tuple of indexing dimension names used to make xarray DataArray.

Unless there are shaped (ndim>1) coordinates, this will match the dims.

Type:: tuple