podpac.coordinates.Coordinates¶
-
class
podpac.coordinates.
Coordinates
(coords, dims=None, crs=None, validate_crs=True)[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
ornp.datetime64
. For convenience, podpac automatically converts datetime strings such as'2018-01-01'
tonp.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
Create podpac Coordinates from a coordinates definition.
from_json
(s)Create podpac Coordinates from a coordinates JSON definition.
from_xarray
(xcoord[, 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[, crs])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
Dictionary of (low, high) coordinates bounds in each unstacked dimension
A trait for unicode strings.
Serializable coordinates definition.
Tuple of dimension names, potentially stacked.
Serializable coordinates definition, containing all properties.
GDAL geotransform.
Coordinates hash value.
JSON-serialized coordinates definition.
Number of dimensions.
Dictionary of the coordinate properties.
Tuple of the number of coordinates in each dimension.
Total number of coordinates.
Tuple of unstacked dimension names.
xarray coords
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
orStackedCoordinates
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
-
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
. DefaultFalse
.
- Returns
Coordinates object with the given dimensions removed
- Return type
- Raises
KeyError – If a given dimension is missing in the Coordinates (and ignore_missing is
False
).
See also
-
classmethod
from_definition
(d)[source]¶ Create podpac Coordinates from a coordinates definition.
- Parameters
d (list) – coordinates definition
- Returns
podpac Coordinates
- Return type
See also
-
classmethod
from_geotransform
(geotransform, shape, crs=None)[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
See also
-
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
-
classmethod
from_xarray
(xcoord, crs=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 or PROJ6 compliant string (https://proj.org/).
- Returns
podpac Coordinates
- Return type
-
property
full_definition
¶ Serializable coordinates definition, containing all properties. For internal use.
- Type
list
-
property
geotransform
¶ GDAL geotransform.
- Type
tuple
-
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 coordinatesCoordinates1d 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
See also
-
property
hash
¶ Coordinates hash value.
- Type
str
-
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.
-
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
-
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
- Type
str
-
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 coordinatesCoordinates1d 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
See also
-
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
-
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
- 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
See also
xarray.DataArray.transpose()
return a transposed DataArray
-
property
udims
¶ Tuple of unstacked dimension names.
If there are no stacked dimensions, then
dims
andudims
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
- 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
. DefaultFalse
.
- Returns
Coordinates object with the given dimensions removed.
- Return type
- Raises
KeyError – If a given dimension is missing in the Coordinates (and ignore_missing is
False
).
See also
-
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
See also
xr.DataArray.unstack()
-
property
ushape
¶
-
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