Lockfile update and Gregorian to Standard calendar change (#4847)

* sed gregorian

* sed CALENDAR_GREGORIAN

* rename cml files

* revert whatsnew 2.1 and test_cf.py

* revert spelling_allow

* post rebase sed 'gregorian'

* Updated environment lockfiles

* cf-units minimum pin

* review actions

Co-authored-by: Lockfile bot <[email protected]>

docs/gallery_code/general/plot_custom_file_loading.py

@@ -57,7 +57,7 @@
 
 import datetime
 
-from cf_units import CALENDAR_GREGORIAN, Unit
+from cf_units import CALENDAR_STANDARD, Unit
 import matplotlib.pyplot as plt
 import numpy as np
 
@@ -225,7 +225,7 @@ def NAME_to_cube(filenames, callback):
 
             # define the time unit and use it to serialise the datetime for the
             # time coordinate
-            time_unit = Unit("hours since epoch", calendar=CALENDAR_GREGORIAN)
+            time_unit = Unit("hours since epoch", calendar=CALENDAR_STANDARD)
             time_coord = icoords.AuxCoord(
                 time_unit.date2num(field_headings["time"]),
                 standard_name="time",

docs/src/techpapers/um_files_loading.rst

@@ -350,7 +350,7 @@ information is contained in the :attr:`~iris.coords.Coord.units` property.
     always 1st Jan 1970 (times before this are represented as negative values).
 
 The units.calendar property of time coordinates is set from the lowest decimal
-digit of LBTIM, known as LBTIM.IC.  Note that the non-gregorian calendars (e.g.
+digit of LBTIM, known as LBTIM.IC.  Note that the non-standard calendars (e.g.
 360-day 'model' calendar) are defined in CF, not udunits.
 
 There are a number of different time encoding methods used in UM data, but the

docs/src/userguide/subsetting_a_cube.rst

@@ -172,7 +172,7 @@ objects for ease of calendar-based testing.
     >>> cube_all = iris.load_cube(filename, 'air_potential_temperature')
     >>> print('All times :\n' + str(cube_all.coord('time')))
     All times :
-    DimCoord :  time / (hours since 1970-01-01 00:00:00, gregorian calendar)
+    DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
         points: [2009-11-19 10:00:00, 2009-11-19 11:00:00, 2009-11-19 12:00:00]
         shape: (3,)
         dtype: float64
@@ -182,7 +182,7 @@ objects for ease of calendar-based testing.
     >>> cube_11 = cube_all.extract(hour_11)
     >>> print('Selected times :\n' + str(cube_11.coord('time')))
     Selected times :
-    DimCoord :  time / (hours since 1970-01-01 00:00:00, gregorian calendar)
+    DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
         points: [2009-11-19 11:00:00]
         shape: (1,)
         dtype: float64
@@ -210,7 +210,7 @@ The previous constraint example can now be written as:
     >>> print(iris.load_cube(
     ...     iris.sample_data_path('uk_hires.pp'),
     ...	   'air_potential_temperature' & the_11th_hour).coord('time'))
-    DimCoord :  time / (hours since 1970-01-01 00:00:00, gregorian calendar)
+    DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
         points: [2009-11-19 11:00:00]
         shape: (1,)
         dtype: float64
@@ -234,7 +234,7 @@ day of every week for many years:
     :options: +NORMALIZE_WHITESPACE, +ELLIPSIS
 
     >>> print(long_ts.coord('time'))
-    DimCoord :  time / (days since 2007-04-09, gregorian calendar)
+    DimCoord :  time / (days since 2007-04-09, standard calendar)
         points: [
             2007-04-09 00:00:00, 2007-04-16 00:00:00, ...,
             2010-02-08 00:00:00, 2010-02-15 00:00:00]
@@ -255,7 +255,7 @@ we constrain that coord using :class:`iris.cube.Cube.extract`
     ...     time=lambda cell: d1 <= cell.point < d2)
     >>> within_st_swithuns_07 = long_ts.extract(st_swithuns_daterange_07)
     >>> print(within_st_swithuns_07.coord('time'))
-    DimCoord :  time / (days since 2007-04-09, gregorian calendar)
+    DimCoord :  time / (days since 2007-04-09, standard calendar)
         points: [
             2007-07-16 00:00:00, 2007-07-23 00:00:00, 2007-07-30 00:00:00,
             2007-08-06 00:00:00, 2007-08-13 00:00:00, 2007-08-20 00:00:00]
@@ -275,7 +275,7 @@ objects.
     ...     time=lambda cell: pdt1 <= cell.point < pdt2)
     >>> within_st_swithuns_07 = long_ts.extract(st_swithuns_daterange_07)
     >>> print(within_st_swithuns_07.coord('time'))
-    DimCoord :  time / (days since 2007-04-09, gregorian calendar)
+    DimCoord :  time / (days since 2007-04-09, standard calendar)
         points: [
             2007-07-16 00:00:00, 2007-07-23 00:00:00, 2007-07-30 00:00:00,
             2007-08-06 00:00:00, 2007-08-13 00:00:00, 2007-08-20 00:00:00]
@@ -296,7 +296,7 @@ PartialDateTime this becomes simple:
     ...
     >>> # Note: using summary(max_values) to show more of the points
     >>> print(within_st_swithuns.coord('time').summary(max_values=100))
-    DimCoord :  time / (days since 2007-04-09, gregorian calendar)
+    DimCoord :  time / (days since 2007-04-09, standard calendar)
         points: [
             2007-07-16 00:00:00, 2007-07-23 00:00:00, 2007-07-30 00:00:00,
             2007-08-06 00:00:00, 2007-08-13 00:00:00, 2007-08-20 00:00:00,

docs/src/whatsnew/latest.rst

@@ -132,7 +132,13 @@ This document explains the changes made to Iris for this release
 💣 Incompatible Changes
 =======================
 
-#. N/A
+#. `@rcomer`_ and `@bjlittle`_ (reviewer) updated Iris's calendar handling to be
+   consistent with ``cf-units`` version 3.1.  In line with the `Calendar`_
+   section in version 1.9 of the CF Conventions, we now use "standard" rather
+   than the deprecated "gregorian" label for the default calendar.  Units may
+   still be instantiated with ``calendar="gregorian"`` but their calendar
+   attribute will be silently changed to "standard".  This may cause failures in
+   code that explicitly checks the calendar attribute. (:pull:`4847`)
 
 
 🚀 Performance Enhancements
@@ -173,6 +179,10 @@ This document explains the changes made to Iris for this release
 
 #. `@wjbenfold`_ and `@bjlittle`_ (reviewer) unpinned ``pillow``. (:pull:`4826`)
 
+#. `@rcomer`_ introduced the ``cf-units >=3.1`` minimum pin, reflecting the
+   alignment of calendar behaviour in the two packages (see Incompatible Changes).
+   (:pull:`4847`)
+
 
 📚 Documentation
 ================
@@ -248,5 +258,6 @@ This document explains the changes made to Iris for this release
 .. comment
     Whatsnew resources in alphabetical order:
 
+.. _Calendar: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#calendar
 .. _Cell Boundaries: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#cell-boundaries
 .. _PyData Sphinx Theme: https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html

lib/iris/cube.py

@@ -4431,7 +4431,7 @@ def interpolate(self, sample_points, scheme, collapse_scalar=True):
             air_potential_temperature / (K)     \
 (time: 3; model_level_number: 7; grid_latitude: 204; grid_longitude: 187)
             >>> print(cube.coord('time'))
-            DimCoord :  time / (hours since 1970-01-01 00:00:00, gregorian calendar)
+            DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
                 points: [2009-11-19 10:00:00, 2009-11-19 11:00:00, 2009-11-19 12:00:00]
                 shape: (3,)
                 dtype: float64
@@ -4444,7 +4444,7 @@ def interpolate(self, sample_points, scheme, collapse_scalar=True):
             air_potential_temperature / (K)     \
 (model_level_number: 7; grid_latitude: 204; grid_longitude: 187)
             >>> print(result.coord('time'))
-            DimCoord :  time / (hours since 1970-01-01 00:00:00, gregorian calendar)
+            DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
                 points: [2009-11-19 10:30:00]
                 shape: (1,)
                 dtype: float64
@@ -4459,7 +4459,7 @@ def interpolate(self, sample_points, scheme, collapse_scalar=True):
             air_potential_temperature / (K)     \
 (model_level_number: 7; grid_latitude: 204; grid_longitude: 187)
             >>> print(result2.coord('time'))
-            DimCoord :  time / (hours since 1970-01-01 00:00:00, gregorian calendar)
+            DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
                 points: [2009-11-19 10:30:00]
                 shape: (1,)
                 dtype: float64

lib/iris/fileformats/name_loaders.py

@@ -456,7 +456,7 @@ def _generate_cubes(
         # Define the time unit and use it to serialise the datetime for
         # the time coordinate.
         time_unit = cf_units.Unit(
-            "hours since epoch", calendar=cf_units.CALENDAR_GREGORIAN
+            "hours since epoch", calendar=cf_units.CALENDAR_STANDARD
         )
 
         # Build time, height, latitude and longitude coordinates.
@@ -1212,7 +1212,7 @@ def load_NAMEIII_trajectory(filename):
 
     """
     time_unit = cf_units.Unit(
-        "hours since epoch", calendar=cf_units.CALENDAR_GREGORIAN
+        "hours since epoch", calendar=cf_units.CALENDAR_STANDARD
     )
 
     with open(filename, "r") as infile:

lib/iris/fileformats/nimrod_load_rules.py

@@ -24,7 +24,7 @@
 NIMROD_DEFAULT = -32767.0
 
 TIME_UNIT = cf_units.Unit(
-    "seconds since 1970-01-01 00:00:00", calendar=cf_units.CALENDAR_GREGORIAN
+    "seconds since 1970-01-01 00:00:00", calendar=cf_units.CALENDAR_STANDARD
 )
 
 

lib/iris/fileformats/pp.py

@@ -1066,7 +1066,7 @@ def core_data(self):
     def calendar(self):
         """Return the calendar of the field."""
         # TODO #577 What calendar to return when ibtim.ic in [0, 3]
-        calendar = cf_units.CALENDAR_GREGORIAN
+        calendar = cf_units.CALENDAR_STANDARD
         if self.lbtim.ic == 2:
             calendar = cf_units.CALENDAR_360_DAY
         elif self.lbtim.ic == 4:

lib/iris/fileformats/pp_load_rules.py

@@ -548,7 +548,7 @@ def _epoch_date_hours_internals(epoch_hours_unit, datetime):
         if m == 0:
             # Add a 'January', by changing month=0 to 1.
             m = 1
-            if calendar == cf_units.CALENDAR_GREGORIAN:
+            if calendar == cf_units.CALENDAR_STANDARD:
                 days_offset += 31
             elif calendar == cf_units.CALENDAR_360_DAY:
                 days_offset += 30
@@ -561,7 +561,7 @@ def _epoch_date_hours_internals(epoch_hours_unit, datetime):
         if y == 0:
             # Add a 'Year 0', by changing year=0 to 1.
             y = 1
-            if calendar == cf_units.CALENDAR_GREGORIAN:
+            if calendar == cf_units.CALENDAR_STANDARD:
                 days_in_year_0 = 366
             elif calendar == cf_units.CALENDAR_360_DAY:
                 days_in_year_0 = 360

lib/iris/fileformats/pp_save_rules.py

@@ -398,7 +398,7 @@ def _calendar_rules(cube, pp):
     if time_coord is not None:
         if time_coord.units.calendar == "360_day":
             pp.lbtim.ic = 2
-        elif time_coord.units.calendar == "gregorian":
+        elif time_coord.units.calendar == "standard":
             pp.lbtim.ic = 1
         elif time_coord.units.calendar == "365_day":
             pp.lbtim.ic = 4

lib/iris/pandas.py

@@ -33,12 +33,12 @@ def _add_iris_coord(cube, name, points, dim, calendar=None):
     """
     Add a Coord to a Cube from a Pandas index or columns array.
 
-    If no calendar is specified for a time series, Gregorian is assumed.
+    If no calendar is specified for a time series, Standard is assumed.
 
     """
     units = Unit("unknown")
     if calendar is None:
-        calendar = cf_units.CALENDAR_GREGORIAN
+        calendar = cf_units.CALENDAR_STANDARD
 
     # Convert pandas datetime objects to python datetime obejcts.
     if isinstance(points, DatetimeIndex):
@@ -83,7 +83,7 @@ def as_cube(pandas_array, copy=True, calendars=None):
     Example usage::
 
         as_cube(series, calendars={0: cf_units.CALENDAR_360_DAY})
-        as_cube(data_frame, calendars={1: cf_units.CALENDAR_GREGORIAN})
+        as_cube(data_frame, calendars={1: cf_units.CALENDAR_STANDARD})
 
     .. note:: This function will copy your data by default.
 

lib/iris/plot.py

@@ -587,14 +587,14 @@ def _fixup_dates(coord, values):
         # Convert coordinate values into tuples of
         # (year, month, day, hour, min, sec)
         dates = [coord.units.num2date(val).timetuple()[0:6] for val in values]
-        if coord.units.calendar == "gregorian":
+        if coord.units.calendar == "standard":
             r = [datetime.datetime(*date) for date in dates]
         else:
             try:
                 import nc_time_axis  # noqa: F401
             except ImportError:
                 msg = (
-                    "Cannot plot against time in a non-gregorian "
+                    "Cannot plot against time in a non-standard "
                     'calendar, because "nc_time_axis" is not available :  '
                     "Install the package from "
                     "https://github.com/SciTools/nc-time-axis to enable "

lib/iris/tests/integration/concatenate/test_concatenate.py

@@ -33,7 +33,7 @@ def simple_1d_time_cubes(self, reftimes, coords_points):
                 standard_name="air_temperature",
                 units="K",
             )
-            unit = cf_units.Unit(reftime, calendar="gregorian")
+            unit = cf_units.Unit(reftime, calendar="standard")
             coord = iris.coords.DimCoord(
                 points=np.array(coord_points, dtype=np.float32),
                 standard_name="time",
@@ -68,7 +68,7 @@ def create_cube(self):
         )
         height = iris.coords.AuxCoord([1.5], standard_name="height", units="m")
         t_unit = cf_units.Unit(
-            "hours since 1970-01-01 00:00:00", calendar="gregorian"
+            "hours since 1970-01-01 00:00:00", calendar="standard"
         )
         time = iris.coords.DimCoord([0, 6], standard_name="time", units=t_unit)
 
@@ -113,7 +113,7 @@ def create_cube(self):
             [1.5], standard_name="height", units="m"
         )
         t_unit = cf_units.Unit(
-            "hours since 1970-01-01 00:00:00", calendar="gregorian"
+            "hours since 1970-01-01 00:00:00", calendar="standard"
         )
         time = iris.coords.DimCoord([0, 6], standard_name="time", units=t_unit)
 
@@ -156,7 +156,7 @@ def create_cube(self):
             [1.5], standard_name="height", units="m"
         )
         t_unit = cf_units.Unit(
-            "hours since 1970-01-01 00:00:00", calendar="gregorian"
+            "hours since 1970-01-01 00:00:00", calendar="standard"
         )
         time = iris.coords.DimCoord([0, 6], standard_name="time", units=t_unit)
 
@@ -196,7 +196,7 @@ def setUp(self):
 
         # Time coord
         t_unit = cf_units.Unit(
-            "hours since 1970-01-01 00:00:00", calendar="gregorian"
+            "hours since 1970-01-01 00:00:00", calendar="standard"
         )
         t_coord = iris.coords.DimCoord(
             [0, 6], standard_name="time", units=t_unit

lib/iris/tests/integration/plot/test_netcdftime.py

@@ -4,7 +4,7 @@
 # See COPYING and COPYING.LESSER in the root of the repository for full
 # licensing details.
 """
-Test plot of time coord with non-gregorian calendar.
+Test plot of time coord with non-standard calendar.
 
 """
 

lib/iris/tests/integration/test_pp.py

@@ -683,7 +683,7 @@ def test_as_pairs(self):
 class TestSaveLBPROC(tests.IrisTest):
     def create_cube(self, longitude_coord="longitude"):
         cube = Cube(np.zeros((2, 3, 4)))
-        tunit = Unit("days since epoch", calendar="gregorian")
+        tunit = Unit("days since epoch", calendar="standard")
         tcoord = DimCoord(np.arange(2), standard_name="time", units=tunit)
         xcoord = DimCoord(
             np.arange(3), standard_name=longitude_coord, units="degrees"

lib/iris/tests/results/COLPEX/small_colpex_theta_p_alt.cml

@@ -400,7 +400,7 @@
 		0.666666666686, 0.833333333314, 1.0]" shape="(6,)" standard_name="forecast_period" units="Unit('hours')" value_type="float64"/>
       </coord>
       <coord>
-        <dimCoord id="9c8bdf81" points="[347926.0]" shape="(1,)" standard_name="forecast_reference_time" units="Unit('hours since 1970-01-01 00:00:00', calendar='gregorian')" value_type="float64"/>
+        <dimCoord id="9c8bdf81" points="[347926.0]" shape="(1,)" standard_name="forecast_reference_time" units="Unit('hours since 1970-01-01 00:00:00', calendar='standard')" value_type="float64"/>
       </coord>
       <coord datadims="[2]">
         <dimCoord bounds="[[-0.53415, -0.52065],
@@ -517,7 +517,7 @@
       </coord>
       <coord datadims="[0]">
         <dimCoord id="cb784457" points="[347926.166667, 347926.333333, 347926.5,
-		347926.666667, 347926.833333, 347927.0]" shape="(6,)" standard_name="time" units="Unit('hours since 1970-01-01 00:00:00', calendar='gregorian')" value_type="float64"/>
+		347926.666667, 347926.833333, 347927.0]" shape="(6,)" standard_name="time" units="Unit('hours since 1970-01-01 00:00:00', calendar='standard')" value_type="float64"/>
       </coord>
     </coords>
     <cellMethods/>
@@ -923,7 +923,7 @@
 		0.666666666686, 0.833333333314, 1.0]" shape="(6,)" standard_name="forecast_period" units="Unit('hours')" value_type="float64"/>
       </coord>
       <coord>
-        <dimCoord id="9c8bdf81" points="[347926.0]" shape="(1,)" standard_name="forecast_reference_time" units="Unit('hours since 1970-01-01 00:00:00', calendar='gregorian')" value_type="float64"/>
+        <dimCoord id="9c8bdf81" points="[347926.0]" shape="(1,)" standard_name="forecast_reference_time" units="Unit('hours since 1970-01-01 00:00:00', calendar='standard')" value_type="float64"/>
       </coord>
       <coord datadims="[2]">
         <dimCoord bounds="[[-0.53415, -0.52065],
@@ -1040,7 +1040,7 @@
       </coord>
       <coord datadims="[0]">
         <dimCoord id="cb784457" points="[347926.166667, 347926.333333, 347926.5,
-		347926.666667, 347926.833333, 347927.0]" shape="(6,)" standard_name="time" units="Unit('hours since 1970-01-01 00:00:00', calendar='gregorian')" value_type="float64"/>
+		347926.666667, 347926.833333, 347927.0]" shape="(6,)" standard_name="time" units="Unit('hours since 1970-01-01 00:00:00', calendar='standard')" value_type="float64"/>
       </coord>
     </coords>
     <cellMethods/>
@@ -1057,7 +1057,7 @@
         <dimCoord id="1d45e087" points="[1.0]" shape="(1,)" standard_name="forecast_period" units="Unit('hours')" value_type="float64"/>
       </coord>
       <coord>
-        <dimCoord id="9c8bdf81" points="[347920.0]" shape="(1,)" standard_name="forecast_reference_time" units="Unit('hours since 1970-01-01 00:00:00', calendar='gregorian')" value_type="float64"/>
+        <dimCoord id="9c8bdf81" points="[347920.0]" shape="(1,)" standard_name="forecast_reference_time" units="Unit('hours since 1970-01-01 00:00:00', calendar='standard')" value_type="float64"/>
       </coord>
       <coord datadims="[0]">
         <dimCoord id="f1ab3066" points="[-0.5274, -0.4599, -0.397941, -0.350291,
@@ -1103,7 +1103,7 @@
         </dimCoord>
       </coord>
       <coord>
-        <dimCoord id="cb784457" points="[347921.0]" shape="(1,)" standard_name="time" units="Unit('hours since 1970-01-01 00:00:00', calendar='gregorian')" value_type="float64"/>
+        <dimCoord id="cb784457" points="[347921.0]" shape="(1,)" standard_name="time" units="Unit('hours since 1970-01-01 00:00:00', calendar='standard')" value_type="float64"/>
       </coord>
     </coords>
     <cellMethods/>

lib/iris/tests/results/FF/air_temperature_1.cml

@@ -11,7 +11,7 @@
         <dimCoord id="1d45e087" points="[0.0]" shape="(1,)" standard_name="forecast_period" units="Unit('hours')" value_type="float64"/>
       </coord>
       <coord>
-        <dimCoord id="9c8bdf81" points="[363984.0]" shape="(1,)" standard_name="forecast_reference_time" units="Unit('hours since 1970-01-01 00:00:00', calendar='gregorian')" value_type="float64"/>
+        <dimCoord id="9c8bdf81" points="[363984.0]" shape="(1,)" standard_name="forecast_reference_time" units="Unit('hours since 1970-01-01 00:00:00', calendar='standard')" value_type="float64"/>
       </coord>
       <coord>
         <dimCoord id="a2cbc1ea" points="[1.5]" shape="(1,)" standard_name="height" units="Unit('m')" value_type="float64">
@@ -40,7 +40,7 @@
         </dimCoord>
       </coord>
       <coord>
-        <dimCoord id="cb784457" points="[363984.0]" shape="(1,)" standard_name="time" units="Unit('hours since 1970-01-01 00:00:00', calendar='gregorian')" value_type="float64"/>
+        <dimCoord id="cb784457" points="[363984.0]" shape="(1,)" standard_name="time" units="Unit('hours since 1970-01-01 00:00:00', calendar='standard')" value_type="float64"/>
       </coord>
     </coords>
     <cellMethods/>