podpac.coordinates.Coordinates

class podpac.coordinates.Coordinates(coords, dims=None, crs=None, alt_units=None, ctype=None)[source]

Bases: traitlets.traitlets.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(xcoord[, crs, alt_units, ctype])

Create podpac Coordinates from xarray coords.

grid([dims, crs, alt_units, ctype])

Create a grid of coordinates.

points([crs, alt_units, ctype, dims])

Create a list of multidimensional coordinates.

Methods

__init__(coords[, dims, crs, alt_units, ctype])

Create multidimensional coordinates.

drop(dims[, ignore_missing])

Remove the given dimensions from the Coordinates dims.

get(dim[, default])

dict-like get: get coordinates by dimension name with an optional

intersect(other[, dims, outer, return_indices])

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

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_indices, outer])

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

transform([crs, alt_units])

Transform coordinate dimensions (lat, lon, alt) into a different coordinate reference system.

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_indices])

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

A trait for unicode strings.

area_bounds

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

bounds

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

coords

xarray coords, a dictionary-like container of coordinate arrays.

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.

hash

Coordinates hash value.

idims

Tuple of indexing dimension names.

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.

Members

__init__(coords, dims=None, crs=None, alt_units=None, ctype=None)[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 any PROJ4 compliant string (https://proj4.org/index.html).

  • alt_units (str, optional) – Altitude units. Supports any PROJ4 Distance Units <https://proj4.org/operations/conversions/unitconvert.html#distance-units>. Must not contradict the crs.

  • ctype (str, optional) – Default coordinates type. One of ‘point’, ‘midpoint’, ‘left’, ‘right’.

CRS
alt_units

A trait for unicode strings.

area_bounds

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

Type

dict

bounds

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

Type

dict

coords

xarray coords, a dictionary-like container of coordinate arrays.

Type

xarray.core.coordinates.DataArrayCoordinates

crs

A trait for unicode strings.

definition

Serializable coordinates definition.

Type

list

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

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",
        "ctype": "left"
        "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_xarray(xcoord, crs=None, alt_units=None, ctype=None)[source]

Create podpac Coordinates from xarray coords.

Parameters
  • xcoord (xarray.core.coordinates.DataArrayCoordinates) – xarray coords

  • crs (str, optional) – Coordinate reference system. Supports any PROJ4 compliant string (https://proj4.org/index.html).

  • alt_units (str, optional) – Altitude units. Supports any PROJ4 Distance Units <https://proj4.org/operations/conversions/unitconvert.html#distance-units>. Must not contradict the crs.

  • ctype (str, optional) – Default coordinates type. One of ‘point’, ‘midpoint’, ‘left’, ‘right’.

Returns

podpac Coordinates

Return type

Coordinates

full_definition

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

Type

list

get(dim, default=None)[source]

dict-like get: get coordinates by dimension name with an optional

classmethod grid(dims=None, crs=None, alt_units=None, ctype=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 compliant string (https://proj4.org/index.html).

  • alt_units (str, optional) – Altitude units. Supports any PROJ4 Distance Units <https://proj4.org/operations/conversions/unitconvert.html#distance-units>. Must not contradict the crs.

  • ctype (str, optional) – Default coordinates type. One of ‘point’, ‘midpoint’, ‘left’, ‘right’.

Returns

podpac Coordinates

Return type

Coordinates

See also

points()

hash

Coordinates hash value.

Type

str

idims

Tuple of indexing dimension names.

Unless there are dependent coordinates, this will match the dims. For dependent coordinates, indexing dimensions ‘i’, ‘j’, etc are used by default.

Type

tuple

intersect(other, dims=None, outer=False, return_indices=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_indices (bool, optional) – If True, return slice or indices for the selection in addition to coordinates. Default False.

Returns

  • intersection (Coordinates) – Coordinates object consisting of the intersection in each dimension.

  • idx (list) – List of indices for each dimension that produces the intersection, only if return_indices is True.

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

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 pipelines 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

ndim

Number of dimensions.

Type

int

classmethod points(crs=None, alt_units=None, ctype=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 compliant string (https://proj4.org/index.html).

  • alt_units (str, optional) – Altitude units. Supports any PROJ4 Distance Units <https://proj4.org/operations/conversions/unitconvert.html#distance-units>. Must not contradict the crs.

  • ctype (str, optional) – Default coordinates type. One of ‘point’, ‘midpoint’, ‘left’, ‘right’.

Returns

podpac Coordinates

Return type

Coordinates

See also

grid()

properties

Dictionary of the coordinate properties.

Type

dict

select(bounds, return_indices=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], ctype['midpoint']
        lon: ArrayCoordinates1d(lon): Bounds[10.0, 40.0], N[4], ctype['midpoint']

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], ctype['midpoint']
        lon: ArrayCoordinates1d(lon): Bounds[30.0, 40.0], N[2], ctype['midpoint']

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], ctype['midpoint']
        lon: ArrayCoordinates1d(lon): Bounds[10.0, 40.0], N[4], ctype['midpoint']
Parameters
  • bounds (dict) – Selection bounds for the desired coordinates.

  • outer (bool, optional) – If True, do outer selections. Default False.

  • return_indices (bool, optional) – If True, return slice or indices for the selections in addition to coordinates. Default False.

Returns

  • selection (Coordinates) – Coordinates object with coordinates within the given bounds.

  • I (list of indices (slices/lists)) – index or slice for the selected coordinates in each dimension (only if return_indices=True)

shape

Tuple of the number of coordinates in each dimension.

Type

tuple

size

Total number of coordinates.

Type

int

transform(crs=None, alt_units=None)[source]

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

See PROJ4 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], ctype['point']
    lon: ArrayCoordinates1d(lon): Bounds[1928928.7360588573, 4187156.434405213], N[21], ctype['midpoint']

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], ctype['point']
    lat_lon[lon]: ArrayCoordinates1d(lon): Bounds[1928928.7360588573, 4187156.434405213], N[21], ctype['midpoint']

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], ctype['midpoint']
    lon: ArrayCoordinates1d(lon): Bounds[-614897.0725896168, 614897.0725896184], N[21], ctype['midpoint']

Transform coordinates with altitude:

# include alt units in proj4 string
c = Coordinates([[0, 1, 2], [0, 1, 2], [1, 2, 3]], dims=['lat', 'lon', 'alt'])
c.transform('+init=epsg:2193 +vunits=ft')

>> Coordinates
    lat: ArrayCoordinates1d(lat): Bounds[594971.8894642257, 819117.0608407748], N[3], ctype['midpoint']
    lon: ArrayCoordinates1d(lon): Bounds[29772096.71234478, 29995929.885877542], N[3], ctype['midpoint']
    alt: ArrayCoordinates1d(alt): Bounds[3.280839895013123, 9.842519685039369], N[3], ctype['midpoint']

# specify alt units seperately
c.transform('EPSG:2193', alt_units='ft')

>> Coordinates
    lat: ArrayCoordinates1d(lat): Bounds[594971.8894642257, 819117.0608407748], N[3], ctype['midpoint']
    lon: ArrayCoordinates1d(lon): Bounds[29772096.71234478, 29995929.885877542], N[3], ctype['midpoint']
    alt: ArrayCoordinates1d(alt): Bounds[3.280839895013123, 9.842519685039369], N[3], ctype['midpoint']

# using alt_units will save the property `crs` as a proj4 string:
ct = c.transform('EPSG:2193', alt_units='ft')
ct.crs

>> '+proj=tmerc +lat_0=0 +lon_0=173 +k=0.9996 +x_0=1600000 +y_0=10000000 +ellps=GRS80 +units=m +no_defs +type=crs +vunits=ft'
Parameters
  • crs (str, optional) – PROJ4 compatible coordinate reference system string. Defaults to the current crs

  • alt_units (str, optional) – Override the alt units defined in crs string. This is implemented to provide a shorthand for transforming alt units without specifying the whole proj4 string.

Returns

Transformed Coordinates

Return type

podpac.Coordinates

Raises

ValueError – Coordinates must have both lat and lon dimensions if either is defined

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

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

Parameters
  • dim_2, .. (dim_1,) – 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

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], ctype['midpoint']
    lat_lon[lon]: ArrayCoordinates1d(lon): Bounds[10.0, 20.0], N[2], ctype['midpoint']
    time: ArrayCoordinates1d(time): Bounds[2018-01-01, 2018-01-01], N[1], ctype['midpoint']

In [3]: c.udrop('lat')
Out[3]:
Coordinates
    lon: ArrayCoordinates1d(lon): Bounds[10.0, 20.0], N[2], ctype['midpoint']
    time: ArrayCoordinates1d(time): Bounds[2018-01-01, 2018-01-01], N[1], ctype['midpoint']
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_indices=False)[source]

Remove duplicate coordinate values from each dimension.

Parameters

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

Returns

  • coords (Coordinates) – New Coordinates object with unique, sorted coordinate values in each dimension.

  • I (list of indices) – index for the unique coordinates in each dimension (only if return_indices=True)

unstack()[source]

Unstack the coordinates of all of the dimensions.

Returns

unstacked – A new Coordinates object with unstacked coordinates.

Return type

Coordinates

See also

xr.DataArray.unstack()

update(other)[source]

dict-like update: add/replace coordinates using another Coordinates object

values()[source]

dict-like values: coordinates for each key/dimension