The geo sub-package

Download notebook

New in version 0.1.9.

dimarray.geo.GeoArray is a subclass of dimarray.DimArray that is more specific to geoscientific applications. The most recognizable features are automatic checks for longitude and latitude coordinates.

>>> from dimarray.geo import GeoArray
>>> a = GeoArray([0,0,0], axes=[('lon',[-180,0,180])])
>>> a
geoarray: 3 non-null elements (0 null)
0 / lon (3): -180.0 to 180.0
array([0, 0, 0])

Coordinate axes can now be defined as keyword arguments:

>>> import numpy as np
>>> a = GeoArray(np.ones((2,3,4)), time=[1950., 1960.], lat=np.linspace(-90,90,3), lon=np.linspace(-180,180,4))
>>> a
geoarray: 24 non-null elements (0 null)
0 / time (2): 1950.0 to 1960.0
1 / lat (3): -90.0 to 90.0
2 / lon (4): -180.0 to 180.0
array([[[ 1.,  1.,  1.,  1.],
        [ 1.,  1.,  1.,  1.],
        [ 1.,  1.,  1.,  1.]],

       [[ 1.,  1.,  1.,  1.],
        [ 1.,  1.,  1.,  1.],
        [ 1.,  1.,  1.,  1.]]])

Note

The keyword arguments assume an order time (time), vertical dimension (z), horizontal northing dimension (lat or y) and horizontal easting dimension (x or lon), following CF-recommandations.

All standard dimarray functions are available under dimarray.geo (so that import dimarray.geo as da works), and a few functions or classes such as read_nc() or Dataset are modified to return GeoArray instead of DimArray instances.

Coordinate Axes

Under the hood, there are new Coordinate classes which inherit from Axis.

For example, the inheritance relations of Latitude is: Latitude -> Y -> Coordinate -> Axis.

>>> from dimarray.geo import Latitude, Y, Coordinate, Axis
>>> assert isinstance(a.axes['lat'], Latitude)
>>> assert issubclass(Latitude, Y)
>>> assert issubclass(Y, Coordinate)
>>> assert issubclass(Coordinate, Axis)

Weights are automatically defined Latitude axis, so that a mean is weighed by default.

>>> a.axes['lat'].weights  # lat -> cos(lat) weighted mean 
<function dimarray.geo.geoarray.<lambda>>

In the case of Latitude and Longitude, some metadata are also provided by default.

>>> a.axes['lat'].attrs  
OrderedDict([('units', 'degrees_north'), ('long_name', 'latitude'), ('standard_name', 'latitude')])

Note

For now there is no constraint on the coordinate axis. This might change in the future, by imposing a strict ordering relationship.

See also

dimarray.geo API

Projections

dimarray.geo is shipped with dimarray.geo.transform() and dimarray.geo.transform_vectors() functions to handle transformations across coordinate reference systems. They are based on cartopy.crs.CRS. Cartopy itself makes use of the PROJ.4 library. In addition to the list of cartopy projections, the dimarray.geo.crs.Proj4 class makes it possible to define a projection directly from PROJ.4 parameters. For the most common projections, dimarray.geo.crs also provides wrapper classes that can be initialized with CF parameters. See dimarray.geo.crs.get_crs() for more information.

In contrast to cartopy/PROJ.4, dimarray.geo functions perform both coordinate transforms and regridding onto a regular grid in the new coordinate system. This is because of the structure of DimArray and GeoArray classes, which only accept regular grids (in the sense of a collection of 1-D axes).

Note

Why cartopy and not just pyproj? Pyproj would be just fine, and is more minimalistic, but cartopy also implements vector transformas and offers other useful features related to plotting, reading shapefiles, download online data and so on, which come in handy. Moreover it feels more “pythonic”, is actively developed with support from the Met’ Office, and is related to another interesting project, iris. It builds on other powerful packages such as shapely and it feels like in the long (or not so long) run it might grow toward something even more useful.