DOC: Added example of using OrderedDict for agg.

closes #12879

Author: Ben Kandel <[email protected]>

Closes #13938 from bkandel/ordered_dict_example and squashes the following commits:

8097de8 [Ben Kandel] Changed to note.
0676294 [Ben Kandel] DOC: Added example of using OrderedDict for agg.

Author: bkandel-picwell

doc/source/groupby.rst

@@ -13,6 +13,7 @@
    matplotlib.style.use('ggplot')
    import matplotlib.pyplot as plt
    plt.close('all')
+   from collections import OrderedDict
 
 *****************************
 Group By: split-apply-combine
@@ -487,6 +488,17 @@ must be either implemented on GroupBy or available via :ref:`dispatching
 
    grouped.agg({'C' : 'sum', 'D' : 'std'})
 
+.. note::
+
+    If you pass a dict to ``aggregate``, the ordering of the output colums is
+    non-deterministic. If you want to be sure the output columns will be in a specific
+    order, you can use an ``OrderedDict``.  Compare the output of the following two commands:
+
+.. ipython:: python
+
+   grouped.agg({'D': 'std', 'C': 'mean'})
+   grouped.agg(OrderedDict([('D', 'std'), ('C', 'mean')]))
+
 .. _groupby.aggregate.cython:
 
 Cython-optimized aggregation functions