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