Merge pull request #5074 from SciTools/pandas_ndim

`iris.pandas.as_data_frame()` n-dimensional `Cube` conversion

docs/src/whatsnew/latest.rst

@@ -25,7 +25,8 @@ This document explains the changes made to Iris for this release
 📢 Announcements
 ================
 
-#. Welcome to `@ESadek-MO`_ and `@TTV-Intrepid`_  who made their first contributions to Iris 🎉
+#. Welcome to `@ESadek-MO`_, `@TTV-Intrepid`_ and `@hsteptoe`_,  who made their
+   first contributions to Iris 🎉
 
    .. _try_experimental_stratify:
 
@@ -80,6 +81,14 @@ This document explains the changes made to Iris for this release
    i.e.  ``(c1 & c2) != (c2 & c1)``.
    (:issue:`3616`, :pull:`3749`).
 
+#. `@hsteptoe`_ and `@trexfeathers`_ improved
+   :func:`iris.pandas.as_data_frame`\'s conversion of :class:`~iris.cube.Cube`\s to
+   :class:`~pandas.DataFrame`\s. This includes better handling of multiple
+   :class:`~iris.cube.Cube` dimensions, auxiliary coordinates and attribute
+   information. **Note:** the improvements are opt-in, by setting the
+   :obj:`iris.FUTURE.pandas_ndim` flag (see :class:`iris.Future` for more).
+   (:issue:`4526`, :pull:`4909`, :pull:`4669`, :pull:`5059`, :pull:`5074`)
+
 
 🐛 Bugs Fixed
 =============
@@ -169,7 +178,10 @@ This document explains the changes made to Iris for this release
 🔥 Deprecations
 ===============
 
-#. N/A
+#. `@hsteptoe`_ and `@trexfeathers`_ (reviewer) deprecated
+   :func:`iris.pandas.as_series` in favour of the new
+   :func:`iris.pandas.as_data_frame` - see `✨ Features`_ for more details.
+   (:pull:`4669`)
 
 
 🔗 Dependencies
@@ -248,7 +260,7 @@ This document explains the changes made to Iris for this release
 
 .. _@TTV-Intrepid: https://github.com/TTV-Intrepid
 .. _Julian Heming: https://www.metoffice.gov.uk/research/people/julian-heming
-
+.. _@hsteptoe: https://github.com/hsteptoe
 
 
 .. comment

lib/iris/__init__.py

@@ -140,22 +140,28 @@ def callback(cube, field, filename):
 class Future(threading.local):
     """Run-time configuration controller."""
 
-    def __init__(self, datum_support=False):
+    def __init__(self, datum_support=False, pandas_ndim=False):
         """
         A container for run-time options controls.
 
         To adjust the values simply update the relevant attribute from
         within your code. For example::
 
+            # example_future_flag is a fictional example.
             iris.FUTURE.example_future_flag = False
 
         If Iris code is executed with multiple threads, note the values of
         these options are thread-specific.
 
-        .. note::
-
-            iris.FUTURE.example_future_flag does not exist. It is provided
-            as an example.
+        Parameters
+        ----------
+        datum_support : bool, default=False
+            Opts in to loading coordinate system datum information from NetCDF
+            files into :class:`~iris.coord_systems.CoordSystem`\\ s, wherever
+            this information is present.
+        pandas_ndim : bool, default=False
+            See :func:`iris.pandas.as_data_frame` for details - opts in to the
+            newer n-dimensional behaviour.
 
         """
         # The flag 'example_future_flag' is provided as a reference for the
@@ -166,13 +172,14 @@ def __init__(self, datum_support=False):
         #
         # self.__dict__['example_future_flag'] = example_future_flag
         self.__dict__["datum_support"] = datum_support
+        self.__dict__["pandas_ndim"] = pandas_ndim
 
     def __repr__(self):
 
         # msg = ('Future(example_future_flag={})')
         # return msg.format(self.example_future_flag)
-        msg = "Future(datum_support={})"
-        return msg.format(self.datum_support)
+        msg = "Future(datum_support={}, pandas_ndim={})"
+        return msg.format(self.datum_support, self.pandas_ndim)
 
     # deprecated_options = {'example_future_flag': 'warning',}
     deprecated_options = {}
@@ -211,14 +218,11 @@ def context(self, **kwargs):
         statement, the previous state is restored.
 
         For example::
+
+            # example_future_flag is a fictional example.
             with iris.FUTURE.context(example_future_flag=False):
                 # ... code that expects some past behaviour
 
-        .. note::
-
-            iris.FUTURE.example_future_flag does not exist and is
-            provided only as an example.
-
         """
         # Save the current context
         current_state = self.__dict__.copy()