xarray to and from Iris

.travis.yml

@@ -13,7 +13,7 @@ matrix:
   - python: 2.7
     env: CONDA_ENV=py27-min
   - python: 2.7
-    env: CONDA_ENV=py27-cdat+pynio
+    env: CONDA_ENV=py27-cdat+iris+pynio
   - python: 3.4
     env: CONDA_ENV=py34
   - python: 3.5

ci/requirements-py27-cdat+pynio.yml → ci/requirements-py27-cdat+iris+pynio.yml

@@ -22,6 +22,7 @@ dependencies:
   - seaborn
   - toolz
   - rasterio
+  - iris>=1.10
   - pip:
     - coveralls
     - pytest-cov

doc/api.rst

@@ -446,6 +446,8 @@ DataArray methods
    DataArray.to_index
    DataArray.to_masked_array
    DataArray.to_cdms2
+   DataArray.to_iris
+   DataArray.from_iris
    DataArray.to_dict
    DataArray.from_series
    DataArray.from_cdms2

doc/io.rst

@@ -338,6 +338,34 @@ supported by netCDF4-python: 'standard', 'gregorian', 'proleptic_gregorian' 'nol
 By default, xarray uses the 'proleptic_gregorian' calendar and units of the smallest time
 difference between values, with a reference time of the first time value.
 
+.. _io.iris:
+
+Iris
+----
+
+The Iris_ tool allows easy reading of common meteorological and climate model formats
+(including GRIB and UK MetOffice PP files) into ``Cube``s which are in many ways very
+similar to to ``DataArray``s, while enforcing a CF-compliant data model. If iris is
+installaed xarray can convert a ``Cube`` into a ``DataArray`` using
+:py:meth:`~xarray.Dataset.from_iris`:
+
+.. ipython:: python
+
+    da_cube = xr.Dataset.from_iris(cube)
+    da_cube
+
+
+Conversly, We can create a new cube object from a ``DataArray`` using
+:py:meth:`~xarray.Dataset.from_dict`:
+
+.. ipython:: python
+
+    cube = da.to_iris()
+    cube
+
+.. _Iris: http://scitools.org.uk/iris
+
+
 OPeNDAP
 -------
 

doc/whats-new.rst

@@ -23,7 +23,11 @@ Enhancements
 
 - :py:func:`~plot.contourf()` learned to contour 2D variables that have both a 1D co-ordinate (e.g. time) and a 2D co-ordinate (e.g. depth as a function of time).
   By `Deepak Cherian <https://github.com/dcherian>`_.
+- Added :py:meth:`DataArray.to_iris <xray.DataArray.to_iris>` and :py:meth:`DataArray.from_iris <xray.DataArray.from_iris>` for
+  converting data arrays to and from Iris_ Cubes with the same data and coordinates (:issue:`621` and :issue:`37`).
+  By `Neil Parley <https://github.com/nparley>`_ and `Duncan Watson-Parris <https://github.com/duncanwp>`_.
 
+.. _Iris: http://scitools.org.uk/iris
 
 Bug fixes
 ~~~~~~~~~

xarray/convert.py

@@ -7,24 +7,38 @@
 import numpy as np
 
 from .core.dataarray import DataArray
+from .core.pycompat import OrderedDict, range
 from .conventions import (
     maybe_encode_timedelta, maybe_encode_datetime, decode_cf)
 
-ignored_attrs = set(['name', 'tileIndex'])
+cdms2_ignored_attrs = {'name', 'tileIndex'}
+iris_forbidden_keys = {'standard_name', 'long_name', 'units', 'bounds', 'axis', 'calendar', 'leap_month', 'leap_year',
+                       'month_lengths', 'coordinates', 'grid_mapping', 'climatology', 'cell_methods', 'formula_terms',
+                       'compress', 'missing_value', 'add_offset', 'scale_factor', 'valid_max', 'valid_min',
+                       'valid_range', '_FillValue'}
+cell_methods_strings = {'point', 'sum', 'maximum', 'median', 'mid_range', 'minimum', 'mean', 'mode',
+                        'standard_deviation', 'variance'}
+
+
+def encode(var):
+    return maybe_encode_timedelta(maybe_encode_datetime(var.variable))
+
+
+def _filter_attrs(attrs, ignored_attrs):
+    """ Return attrs that are not in ignored_attrs
+    """
+    return dict((k, v) for k, v in attrs.items() if k not in ignored_attrs)
 
 
 def from_cdms2(variable):
     """Convert a cdms2 variable into an DataArray
     """
-    def get_cdms2_attrs(var):
-        return dict((k, v) for k, v in var.attributes.items()
-                    if k not in ignored_attrs)
-
     values = np.asarray(variable)
     name = variable.id
-    coords = [(v.id, np.asarray(v), get_cdms2_attrs(v))
+    coords = [(v.id, np.asarray(v),
+               _filter_attrs(v.attributes, cdms2_ignored_attrs))
               for v in variable.getAxisList()]
-    attrs = get_cdms2_attrs(variable)
+    attrs = _filter_attrs(variable.attributes, cdms2_ignored_attrs)
     dataarray = DataArray(values, coords=coords, name=name, attrs=attrs)
     return decode_cf(dataarray.to_dataset())[dataarray.name]
 
@@ -35,9 +49,6 @@ def to_cdms2(dataarray):
     # we don't want cdms2 to be a hard dependency
     import cdms2
 
-    def encode(var):
-        return maybe_encode_timedelta(maybe_encode_datetime(var.variable))
-
     def set_cdms2_attrs(var, attrs):
         for k, v in attrs.items():
             setattr(var, k, v)
@@ -53,3 +64,124 @@ def set_cdms2_attrs(var, attrs):
     cdms2_var = cdms2.createVariable(var.values, axes=axes, id=dataarray.name)
     set_cdms2_attrs(cdms2_var, var.attrs)
     return cdms2_var
+
+
+def _pick_attrs(attrs, keys):
+    """ Return attrs with keys in keys list
+    """
+    return dict((k, v) for k, v in attrs.items() if k in keys)
+
+
+def _get_iris_args(attrs):
+    """ Converts the xarray attrs into args that can be passed into Iris
+    """
+    # iris.unit is deprecated in Iris v1.9
+    import cf_units
+    args = {'attributes': _filter_attrs(attrs, iris_forbidden_keys)}
+    args.update(_pick_attrs(attrs, ('standard_name', 'long_name',)))
+    unit_args = _pick_attrs(attrs, ('calendar',))
+    if 'units' in attrs:
+        args['units'] = cf_units.Unit(attrs['units'], **unit_args)
+    return args
+
+
+# TODO: Add converting bounds from xarray to Iris and back
+def to_iris(dataarray):
+    """ Convert a DataArray into a Iris Cube
+    """
+    # Iris not a hard dependency
+    import iris
+    from iris.fileformats.netcdf import parse_cell_methods
+
+    dim_coords = []
+    aux_coords = []
+
+    for coord_name in dataarray.coords:
+        coord = encode(dataarray.coords[coord_name])
+        coord_args = _get_iris_args(coord.attrs)
+        coord_args['var_name'] = coord_name
+        axis = None
+        if coord.dims:
+            axis = dataarray.get_axis_num(coord.dims)
+        if coord_name in dataarray.dims:
+            iris_coord = iris.coords.DimCoord(coord.values, **coord_args)
+            dim_coords.append((iris_coord, axis))
+        else:
+            iris_coord = iris.coords.AuxCoord(coord.values, **coord_args)
+            aux_coords.append((iris_coord, axis))
+
+    args = _get_iris_args(dataarray.attrs)
+    args['var_name'] = dataarray.name
+    args['dim_coords_and_dims'] = dim_coords
+    args['aux_coords_and_dims'] = aux_coords
+    if 'cell_methods' in dataarray.attrs:
+        args['cell_methods'] = parse_cell_methods(dataarray.attrs['cell_methods'])
+
+    cube = iris.cube.Cube(dataarray.to_masked_array(), **args)
+    return cube
+
+
+def _iris_obj_to_attrs(obj):
+    """ Return a dictionary of attrs when given a Iris object
+    """
+    attrs = {'standard_name': obj.standard_name,
+             'long_name': obj.long_name}
+    if obj.units.calendar:
+        attrs['calendar'] = obj.units.calendar
+    if obj.units.origin != '1':
+        attrs['units'] = obj.units.origin
+    attrs.update(obj.attributes)
+    return dict((k, v) for k, v in attrs.items() if v is not None)
+
+
+def _iris_cell_methods_to_str(cell_methods_obj):
+    """ Converts a Iris cell methods into a string
+    """
+    cell_methods = []
+    for cell_method in cell_methods_obj:
+        names = ''.join(['{}: '.format(n) for n in cell_method.coord_names])
+        intervals = ' '.join(['interval: {}'.format(interval)
+                              for interval in cell_method.intervals])
+        comments = ' '.join(['comment: {}'.format(comment)
+                             for comment in cell_method.comments])
+        extra = ' '.join([intervals, comments]).strip()
+        if extra:
+            extra = ' ({})'.format(extra)
+        cell_methods.append(names + cell_method.method + extra)
+    return ' '.join(cell_methods)
+
+
+def from_iris(cube):
+    """ Convert a Iris cube into an DataArray
+    """
+    import iris.exceptions
+    name = cube.var_name
+    dims = []
+    for i in range(cube.ndim):
+        try:
+            dim_coord = cube.coord(dim_coords=True, dimensions=(i,))
+            dims.append(dim_coord.var_name)
+        except iris.exceptions.CoordinateNotFoundError:
+            dims.append("dim_{}".format(i))
+
+    coords = OrderedDict()
+
+    for coord in cube.coords():
+        coord_attrs = _iris_obj_to_attrs(coord)
+        coord_dims = [dims[i] for i in cube.coord_dims(coord)]
+        if not coord.var_name:
+            raise ValueError('Coordinate has no var_name')
+        if coord_dims:
+            coords[coord.var_name] = (coord_dims, coord.points, coord_attrs)
+        else:
+            coords[coord.var_name] = ((),
+                                      np.asscalar(coord.points), coord_attrs)
+
+    array_attrs = _iris_obj_to_attrs(cube)
+    cell_methods = _iris_cell_methods_to_str(cube.cell_methods)
+    if cell_methods:
+        array_attrs['cell_methods'] = cell_methods
+    dataarray = DataArray(cube.data, coords=coords, name=name,
+                          attrs=array_attrs, dims=dims)
+    decoded_ds = decode_cf(dataarray._to_temp_dataset())
+    return dataarray._from_temp_dataset(decoded_ds)

xarray/core/dataarray.py

@@ -1532,6 +1532,19 @@ def from_cdms2(cls, variable):
         from ..convert import from_cdms2
         return from_cdms2(variable)
 
+    def to_iris(self):
+        """Convert this array into a iris.cube.Cube
+        """
+        from ..convert import to_iris
+        return to_iris(self)
+
+    @classmethod
+    def from_iris(cls, cube):
+        """Convert a iris.cube.Cube into an xarray.DataArray
+        """
+        from ..convert import from_iris
+        return from_iris(cube)
+
     def _all_compat(self, other, compat_str):
         """Helper function for equals and identical"""
 

xarray/tests/test_dataarray.py

@@ -15,7 +15,7 @@
                     IndexVariable, Variable)
 from xarray.core.pycompat import iteritems, OrderedDict
 from xarray.core.common import full_like
-
+from xarray.conventions import maybe_encode_datetime
 from xarray.tests import (
     TestCase, ReturnItem, source_ndarray, unittest, requires_dask,
     assert_identical, assert_equal, assert_allclose, assert_array_equal,
@@ -2724,6 +2724,60 @@ def test_to_and_from_cdms2(self):
         roundtripped = DataArray.from_cdms2(actual)
         self.assertDataArrayIdentical(original, roundtripped)
 
+    def test_to_and_from_iris(self):
+        try:
+            import iris
+            import cf_units
+        except ImportError:
+            raise unittest.SkipTest('iris not installed')
+
+        coord_dict = OrderedDict()
+        coord_dict['distance'] = ('distance', [-2, 2], {'units': 'meters'})
+        coord_dict['time'] = ('time', pd.date_range('2000-01-01', periods=3))
+        coord_dict['height'] = 10
+        coord_dict['distance2'] = ('distance', [0, 1], {'foo': 'bar'})
+        coord_dict['time2'] = (('distance', 'time'), [[0, 1, 2], [2, 3, 4]])
+
+        original = DataArray(np.arange(6).reshape(2, 3), coord_dict,
+                             name='Temperature', attrs={'baz': 123,
+                                                        'units': 'Kelvin',
+                                                        'standard_name':
+                                                            'fire_temperature',
+                                                        'long_name':
+                                                            'Fire Temperature'},
+                             dims=('distance', 'time'))
+
+        original.attrs['cell_methods'] = 'height: mean (comment: A cell method)'
+        actual = original.to_iris()
+        self.assertArrayEqual(actual.data, original.data)
+        self.assertEqual(actual.var_name, original.name)
+        self.assertItemsEqual([d.var_name for d in actual.dim_coords],
+                              original.dims)
+        self.assertEqual(actual.cell_methods,
+                         (iris.coords.CellMethod(method='mean',
+                                                 coords=('height',),
+                                                 intervals=(),
+                                                 comments=('A cell method',)),))
+
+        for coord, orginal_key in zip((actual.coords()), original.coords):
+            original_coord = original.coords[orginal_key]
+            self.assertEqual(coord.var_name, original_coord.name)
+            self.assertArrayEqual(coord.points,
+                                  maybe_encode_datetime(original_coord).values)
+            self.assertEqual(actual.coord_dims(coord),
+                             original.get_axis_num
+                             (original.coords[coord.var_name].dims))
+
+        self.assertEqual(actual.coord('distance2').attributes['foo'],
+                         original.coords['distance2'].attrs['foo'])
+        self.assertEqual(actual.coord('distance').units,
+                         cf_units.Unit(original.coords['distance'].units))
+        self.assertEqual(actual.attributes['baz'], original.attrs['baz'])
+        self.assertEqual(actual.standard_name, original.attrs['standard_name'])
+
+        roundtripped = DataArray.from_iris(actual)
+        self.assertDataArrayIdentical(original, roundtripped)
+
     def test_to_dataset_whole(self):
         unnamed = DataArray([1, 2], dims='x')
         with raises_regex(ValueError, 'unable to convert unnamed'):