Merge "default_units" feature branch

docs/iris/gallery_code/meteorology/plot_lagged_ensemble.py

@@ -41,7 +41,7 @@ def realization_metadata(cube, field, fname):
         import iris.coords
 
         realization_coord = iris.coords.AuxCoord(
-            np.int32(realization_number), "realization"
+            np.int32(realization_number), "realization", units="1"
         )
         cube.add_aux_coord(realization_coord)
 

docs/iris/src/userguide/navigating_a_cube.rst

@@ -229,7 +229,7 @@ by field basis *before* they are automatically merged together:
         # Add our own realization coordinate if it doesn't already exist.
         if not cube.coords('realization'):
             realization = np.int32(filename[-6:-3])
-            ensemble_coord = icoords.AuxCoord(realization, standard_name='realization')
+            ensemble_coord = icoords.AuxCoord(realization, standard_name='realization', units="1")
             cube.add_aux_coord(ensemble_coord)
 
     filename = iris.sample_data_path('GloSea4', '*.pp')

docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2020-May-15_change_default_unit_loading.txt

@@ -0,0 +1 @@
+* When loading data from netcdf-CF files, where a variable has no "units" property, the corresponding Iris object will have "units='unknown'". Prior to Iris 3.0, these cases defaulted to "units='1'".

lib/iris/analysis/__init__.py

@@ -803,7 +803,9 @@ def post_process(self, collapsed_cube, data_result, coords, **kwargs):
         # order cube.
         for point in points:
             cube = collapsed_cube.copy()
-            coord = iris.coords.AuxCoord(point, long_name=coord_name)
+            coord = iris.coords.AuxCoord(
+                point, long_name=coord_name, units="percent"
+            )
             cube.add_aux_coord(coord)
             cubes.append(cube)
 

lib/iris/coords.py

@@ -65,7 +65,7 @@ def __init__(
         standard_name=None,
         long_name=None,
         var_name=None,
-        units="no-unit",
+        units=None,
         attributes=None,
     ):
         """
@@ -687,7 +687,7 @@ def __init__(
         standard_name=None,
         long_name=None,
         var_name=None,
-        units="no-unit",
+        units=None,
         attributes=None,
     ):
         """
@@ -793,7 +793,7 @@ def __init__(
         standard_name=None,
         long_name=None,
         var_name=None,
-        units="1",
+        units=None,
         attributes=None,
         measure=None,
     ):
@@ -1283,7 +1283,7 @@ def __init__(
         standard_name=None,
         long_name=None,
         var_name=None,
-        units="1",
+        units=None,
         bounds=None,
         attributes=None,
         coord_system=None,
@@ -2262,7 +2262,7 @@ def from_regular(
         standard_name=None,
         long_name=None,
         var_name=None,
-        units="1",
+        units=None,
         attributes=None,
         coord_system=None,
         circular=False,
@@ -2325,7 +2325,7 @@ def __init__(
         standard_name=None,
         long_name=None,
         var_name=None,
-        units="1",
+        units=None,
         bounds=None,
         attributes=None,
         coord_system=None,

lib/iris/fileformats/_pyke_rules/fc_rules_cf.krb

@@ -1195,6 +1195,8 @@ fc_extras
     UD_UNITS_LON = ['degrees_east', 'degree_east', 'degree_e', 'degrees_e',
                     'degreee', 'degreese', 'degrees', 'degrees east',
                     'degree east', 'degree e', 'degrees e']
+    UNKNOWN_UNIT_STRING = "?"
+    NO_UNIT_STRING = "-"
 
     #
     # CF Dimensionless Vertical Coordinates
@@ -1651,9 +1653,9 @@ fc_extras
 
     ################################################################################
     def get_attr_units(cf_var, attributes):
-        attr_units = getattr(cf_var, CF_ATTR_UNITS, cf_units._UNIT_DIMENSIONLESS)
+        attr_units = getattr(cf_var, CF_ATTR_UNITS, UNKNOWN_UNIT_STRING)
         if not attr_units:
-            attr_units = '1'
+            attr_units = UNKNOWN_UNIT_STRING
 
         # Sanitise lat/lon units.
         if attr_units in UD_UNITS_LAT or attr_units in UD_UNITS_LON:
@@ -1668,10 +1670,10 @@ fc_extras
                 cf_var.cf_name, attr_units)
             warnings.warn(msg)
             attributes['invalid_units'] = attr_units
-            attr_units = cf_units._UNKNOWN_UNIT_STRING
+            attr_units = UNKNOWN_UNIT_STRING
 
         if np.issubdtype(cf_var.dtype, np.str_):
-            attr_units = cf_units._NO_UNIT_STRING
+            attr_units = NO_UNIT_STRING
 
         # Get any assoicated calendar for a time reference coordinate.
         if cf_units.as_unit(attr_units).is_time_reference():

lib/iris/fileformats/netcdf.py

@@ -22,6 +22,7 @@
 import warnings
 
 import dask.array as da
+import cf_units
 import netCDF4
 import numpy as np
 import numpy.ma as ma
@@ -1760,7 +1761,7 @@ def _inner_create_cf_cellmeasure_or_ancil_variable(
         # Add the data to the CF-netCDF variable.
         cf_var[:] = data
 
-        if dimensional_metadata.units != "unknown":
+        if dimensional_metadata.units.is_udunits():
             _setncattr(cf_var, "units", str(dimensional_metadata.units))
 
         if dimensional_metadata.standard_name is not None:
@@ -1926,7 +1927,7 @@ def _create_cf_coord_variable(self, cube, dimension_names, coord):
         # Deal with CF-netCDF units and standard name.
         standard_name, long_name, units = self._cf_coord_identity(coord)
 
-        if units != "unknown":
+        if cf_units.as_unit(units).is_udunits():
             _setncattr(cf_var, "units", units)
 
         if standard_name is not None:
@@ -2371,7 +2372,7 @@ def store(data, cf_var, fill_value):
         if cube.long_name:
             _setncattr(cf_var, "long_name", cube.long_name)
 
-        if cube.units != "unknown":
+        if cube.units.is_udunits():
             _setncattr(cf_var, "units", str(cube.units))
 
         # Add the CF-netCDF calendar attribute.

lib/iris/fileformats/pp_load_rules.py

@@ -147,6 +147,7 @@ def _convert_vertical_coords(
             model_level_number,
             standard_name="model_level_number",
             attributes={"positive": "down"},
+            units="1",
         )
         coords_and_dims.append((coord, dim))
 
@@ -197,6 +198,7 @@ def _convert_vertical_coords(
                 model_level_number,
                 long_name="soil_model_level_number",
                 attributes={"positive": "down"},
+                units="1",
             )
             coords_and_dims.append((coord, dim))
         elif np.any(brsvd1 != brlev):
@@ -235,6 +237,7 @@ def _convert_vertical_coords(
             model_level_number,
             standard_name="model_level_number",
             attributes={"positive": "up"},
+            units="1",
         )
         level_pressure = _dim_or_aux(
             bhlev,
@@ -243,7 +246,10 @@ def _convert_vertical_coords(
             bounds=np.vstack((bhrlev, brsvd2)).T,
         )
         sigma = AuxCoord(
-            blev, long_name="sigma", bounds=np.vstack((brlev, brsvd1)).T
+            blev,
+            long_name="sigma",
+            bounds=np.vstack((brlev, brsvd1)).T,
+            units="1",
         )
         coords_and_dims.extend(
             [(model_level_number, dim), (level_pressure, dim), (sigma, dim)]
@@ -265,6 +271,7 @@ def _convert_vertical_coords(
             model_level_number,
             standard_name="model_level_number",
             attributes={"positive": "up"},
+            units="1",
         )
         level_height = _dim_or_aux(
             blev,
@@ -274,7 +281,10 @@ def _convert_vertical_coords(
             attributes={"positive": "up"},
         )
         sigma = AuxCoord(
-            bhlev, long_name="sigma", bounds=np.vstack((bhrlev, brsvd2)).T
+            bhlev,
+            long_name="sigma",
+            bounds=np.vstack((bhrlev, brsvd2)).T,
+            units="1",
         )
         coords_and_dims.extend(
             [(model_level_number, dim), (level_height, dim), (sigma, dim)]
@@ -846,7 +856,7 @@ def _convert_scalar_realization_coords(lbrsvd4):
     coords_and_dims = []
     if lbrsvd4 != 0:
         coords_and_dims.append(
-            (DimCoord(lbrsvd4, standard_name="realization"), None)
+            (DimCoord(lbrsvd4, standard_name="realization", units="1"), None)
         )
     return coords_and_dims
 
@@ -1078,7 +1088,7 @@ def _all_other_rules(f):
         and f.lbmon == f.lbmond
     ):
         aux_coords_and_dims.append(
-            (AuxCoord(f.lbmon, long_name="month_number"), None)
+            (AuxCoord(f.lbmon, long_name="month_number", units="1"), None)
         )
         aux_coords_and_dims.append(
             (

lib/iris/tests/integration/test_netcdf.py

@@ -81,7 +81,9 @@ def test_hybrid_height_and_pressure(self):
                 1200.0, long_name="level_pressure", units="hPa"
             )
         )
-        cube.add_aux_coord(iris.coords.DimCoord(0.5, long_name="other sigma"))
+        cube.add_aux_coord(
+            iris.coords.DimCoord(0.5, long_name="other sigma", units="1")
+        )
         cube.add_aux_coord(
             iris.coords.DimCoord(
                 1000.0, long_name="surface_air_pressure", units="hPa"

lib/iris/tests/integration/test_pp.py

@@ -299,7 +299,7 @@ def test_hybrid_height_with_non_standard_coords(self):
         delta_lower, delta, delta_upper = 150, 200, 250
 
         cube = Cube(np.zeros((ny, nx)), "air_temperature")
-        level_coord = AuxCoord(0, "model_level_number")
+        level_coord = AuxCoord(0, "model_level_number", units="1")
         cube.add_aux_coord(level_coord)
         delta_coord = AuxCoord(
             delta,
@@ -308,7 +308,10 @@ def test_hybrid_height_with_non_standard_coords(self):
             units="m",
         )
         sigma_coord = AuxCoord(
-            sigma, bounds=[[sigma_lower, sigma_upper]], long_name="mavis"
+            sigma,
+            bounds=[[sigma_lower, sigma_upper]],
+            long_name="mavis",
+            units="1",
         )
         surface_altitude_coord = AuxCoord(
             np.zeros((ny, nx)), "surface_altitude", units="m"
@@ -343,7 +346,7 @@ def test_hybrid_pressure_with_non_standard_coords(self):
         delta_lower, delta, delta_upper = 0.15, 0.2, 0.25
 
         cube = Cube(np.zeros((ny, nx)), "air_temperature")
-        level_coord = AuxCoord(0, "model_level_number")
+        level_coord = AuxCoord(0, "model_level_number", units="1")
         cube.add_aux_coord(level_coord)
         delta_coord = AuxCoord(
             delta,
@@ -352,7 +355,10 @@ def test_hybrid_pressure_with_non_standard_coords(self):
             units="Pa",
         )
         sigma_coord = AuxCoord(
-            sigma, bounds=[[sigma_lower, sigma_upper]], long_name="mavis"
+            sigma,
+            bounds=[[sigma_lower, sigma_upper]],
+            long_name="mavis",
+            units="1",
         )
         surface_air_pressure_coord = AuxCoord(
             np.zeros((ny, nx)), "surface_air_pressure", units="Pa"

lib/iris/tests/results/analysis/first_quartile_foo_1d.cml

@@ -6,7 +6,7 @@
         <dimCoord bounds="[[0, 11]]" id="b0d35dcf" long_name="foo" points="[5]" shape="(1,)" units="Unit('1')" value_type="int32"/>
       </coord>
       <coord>
-        <dimCoord id="3d9231d0" long_name="percentile_over_foo" points="[25]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="f5bc1733" long_name="percentile_over_foo" points="[25]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/analysis/first_quartile_foo_1d_fast_percentile.cml

@@ -6,7 +6,7 @@
         <dimCoord bounds="[[0, 11]]" id="b0d35dcf" long_name="foo" points="[5]" shape="(1,)" units="Unit('1')" value_type="int32"/>
       </coord>
       <coord>
-        <dimCoord id="3d9231d0" long_name="percentile_over_foo" points="[25]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="f5bc1733" long_name="percentile_over_foo" points="[25]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/analysis/first_quartile_foo_2d.cml

@@ -11,7 +11,7 @@
         <dimCoord bounds="[[-15, 45]]" id="b0d35dcf" long_name="foo" points="[15.0]" shape="(1,)" units="Unit('1')" value_type="float64"/>
       </coord>
       <coord>
-        <dimCoord id="3d9231d0" long_name="percentile_over_foo" points="[25]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="f5bc1733" long_name="percentile_over_foo" points="[25]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/analysis/first_quartile_foo_2d_fast_percentile.cml

@@ -11,7 +11,7 @@
         <dimCoord bounds="[[-15, 45]]" id="b0d35dcf" long_name="foo" points="[15.0]" shape="(1,)" units="Unit('1')" value_type="float64"/>
       </coord>
       <coord>
-        <dimCoord id="3d9231d0" long_name="percentile_over_foo" points="[25]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="f5bc1733" long_name="percentile_over_foo" points="[25]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/analysis/first_quartile_foo_bar_2d.cml

@@ -9,7 +9,7 @@
         <dimCoord bounds="[[-15, 45]]" id="b0d35dcf" long_name="foo" points="[15.0]" shape="(1,)" units="Unit('1')" value_type="float64"/>
       </coord>
       <coord>
-        <dimCoord id="3a1fa26e" long_name="percentile_over_foo_bar" points="[25]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="59a64095" long_name="percentile_over_foo_bar" points="[25]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/analysis/first_quartile_foo_bar_2d_fast_percentile.cml

@@ -9,7 +9,7 @@
         <dimCoord bounds="[[-15, 45]]" id="b0d35dcf" long_name="foo" points="[15.0]" shape="(1,)" units="Unit('1')" value_type="float64"/>
       </coord>
       <coord>
-        <dimCoord id="3a1fa26e" long_name="percentile_over_foo_bar" points="[25]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="59a64095" long_name="percentile_over_foo_bar" points="[25]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/analysis/last_quartile_foo_3d_masked.cml

@@ -9,7 +9,7 @@
         <dimCoord circular="True" id="62e940e0" points="[-180, -90, 0, 90]" shape="(4,)" standard_name="longitude" units="Unit('degrees')" value_type="int64"/>
       </coord>
       <coord>
-        <dimCoord id="cf515091" long_name="percentile_over_wibble" points="[75]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="47527651" long_name="percentile_over_wibble" points="[75]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
       <coord>
         <dimCoord bounds="[[10.0, 30.0]]" id="10b8e1fc" long_name="wibble" points="[20.0]" shape="(1,)" units="Unit('1')" value_type="float32"/>

lib/iris/tests/results/analysis/last_quartile_foo_3d_notmasked.cml

@@ -9,7 +9,7 @@
         <dimCoord circular="True" id="62e940e0" points="[-180, -90, 0, 90]" shape="(4,)" standard_name="longitude" units="Unit('degrees')" value_type="int64"/>
       </coord>
       <coord>
-        <dimCoord id="cf515091" long_name="percentile_over_wibble" points="[75]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="47527651" long_name="percentile_over_wibble" points="[75]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
       <coord>
         <dimCoord bounds="[[10.0, 30.0]]" id="10b8e1fc" long_name="wibble" points="[20.0]" shape="(1,)" units="Unit('1')" value_type="float32"/>

lib/iris/tests/results/analysis/last_quartile_foo_3d_notmasked_fast_percentile.cml

@@ -9,7 +9,7 @@
         <dimCoord circular="True" id="62e940e0" points="[-180, -90, 0, 90]" shape="(4,)" standard_name="longitude" units="Unit('degrees')" value_type="int64"/>
       </coord>
       <coord>
-        <dimCoord id="cf515091" long_name="percentile_over_wibble" points="[75]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="47527651" long_name="percentile_over_wibble" points="[75]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
       <coord>
         <dimCoord bounds="[[10.0, 30.0]]" id="10b8e1fc" long_name="wibble" points="[20.0]" shape="(1,)" units="Unit('1')" value_type="float32"/>

lib/iris/tests/results/analysis/third_quartile_foo_1d.cml

@@ -6,7 +6,7 @@
         <dimCoord bounds="[[0, 11]]" id="b0d35dcf" long_name="foo" points="[5]" shape="(1,)" units="Unit('1')" value_type="int32"/>
       </coord>
       <coord>
-        <dimCoord id="3d9231d0" long_name="percentile_over_foo" points="[75]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="f5bc1733" long_name="percentile_over_foo" points="[75]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/analysis/third_quartile_foo_1d_fast_percentile.cml

@@ -6,7 +6,7 @@
         <dimCoord bounds="[[0, 11]]" id="b0d35dcf" long_name="foo" points="[5]" shape="(1,)" units="Unit('1')" value_type="int32"/>
       </coord>
       <coord>
-        <dimCoord id="3d9231d0" long_name="percentile_over_foo" points="[75]" shape="(1,)" units="Unit('1')" value_type="int64"/>
+        <dimCoord id="f5bc1733" long_name="percentile_over_foo" points="[75]" shape="(1,)" units="Unit('percent')" value_type="int64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/coord_api/minimal.xml

@@ -1,2 +1,2 @@
 <?xml version="1.0" ?>
-<dimCoord id="3658c2fd" points="[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]" shape="(10,)" units="Unit('1')" value_type="int32"/>
+<dimCoord id="2d33cf28" points="[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]" shape="(10,)" units="Unit('unknown')" value_type="int32"/>

lib/iris/tests/results/integration/climatology/TestClimatology/reference_simpledata.cdl

@@ -17,11 +17,11 @@ variables:
 	double time_climatology(time, bnds) ;
 	double latitude(latitude) ;
 		latitude:axis = "Y" ;
-		latitude:units = "1" ;
+		latitude:units = "degrees_north" ;
 		latitude:standard_name = "latitude" ;
 	double longitude(longitude) ;
 		longitude:axis = "X" ;
-		longitude:units = "1" ;
+		longitude:units = "degrees_east" ;
 		longitude:standard_name = "longitude" ;
 
 // global attributes: