Merge branch 'master' of https://github.com/pandas-dev/pandas into opprep

Author: jbrockmendel

ci/requirements_dev.txt

@@ -7,4 +7,4 @@ pytest>=3.1
 python-dateutil>=2.5.0
 pytz
 setuptools>=3.3
-sphinx
+sphinx=1.5*

doc/source/advanced.rst

@@ -113,7 +113,13 @@ of the index is up to you:
    pd.DataFrame(np.random.randn(6, 6), index=index[:6], columns=index[:6])
 
 We've "sparsified" the higher levels of the indexes to make the console output a
-bit easier on the eyes.
+bit easier on the eyes. Note that how the index is displayed can be controlled using the
+``multi_sparse`` option in ``pandas.set_options()``:
+
+.. ipython:: python
+
+   with pd.option_context('display.multi_sparse', False):
+       df
 
 It's worth keeping in mind that there's nothing preventing you from using
 tuples as atomic labels on an axis:
@@ -129,15 +135,6 @@ can find yourself working with hierarchically-indexed data without creating a
 ``MultiIndex`` explicitly yourself. However, when loading data from a file, you
 may wish to generate your own ``MultiIndex`` when preparing the data set.
 
-Note that how the index is displayed by be controlled using the
-``multi_sparse`` option in ``pandas.set_options()``:
-
-.. ipython:: python
-
-   pd.set_option('display.multi_sparse', False)
-   df
-   pd.set_option('display.multi_sparse', True)
-
 .. _advanced.get_level_values:
 
 Reconstructing the level labels
@@ -180,14 +177,13 @@ For example:
 
 .. ipython:: python
 
-   # original MultiIndex
-   df.columns
+   df.columns  # original MultiIndex
 
-   # sliced
-   df[['foo','qux']].columns
+   df[['foo','qux']].columns  # sliced
 
 This is done to avoid a recomputation of the levels in order to make slicing
-highly performant. If you want to see the actual used levels.
+highly performant. If you want to see only the used levels, you can use the
+:func:`MultiIndex.get_level_values` method.
 
 .. ipython:: python
 
@@ -196,7 +192,7 @@ highly performant. If you want to see the actual used levels.
    # for a specific level
    df[['foo','qux']].columns.get_level_values(0)
 
-To reconstruct the ``MultiIndex`` with only the used levels, the 
+To reconstruct the ``MultiIndex`` with only the used levels, the
 ``remove_unused_levels`` method may be used.
 
 .. versionadded:: 0.20.0
@@ -231,15 +227,33 @@ Advanced indexing with hierarchical index
 -----------------------------------------
 
 Syntactically integrating ``MultiIndex`` in advanced indexing with ``.loc`` is a
-bit challenging, but we've made every effort to do so. For example the
-following works as you would expect:
+bit challenging, but we've made every effort to do so. In general, MultiIndex
+keys take the form of tuples. For example, the following works as you would expect:
 
 .. ipython:: python
 
    df = df.T
    df
-   df.loc['bar']
-   df.loc['bar', 'two']
+   df.loc[('bar', 'two'),]
+
+Note that ``df.loc['bar', 'two']`` would also work in this example, but this shorthand
+notation can lead to ambiguity in general.
+
+If you also want to index a specific column with ``.loc``, you must use a tuple
+like this:
+
+.. ipython:: python
+
+   df.loc[('bar', 'two'), 'A']
+
+You don't have to specify all levels of the ``MultiIndex`` by passing only the
+first elements of the tuple. For example, you can use "partial" indexing to
+get all elements with ``bar`` in the first level as follows:
+
+df.loc['bar']
+
+This is a shortcut for the slightly more verbose notation ``df.loc[('bar',),]`` (equivalent
+to ``df.loc['bar',]`` in this example).
 
 "Partial" slicing also works quite nicely.
 
@@ -260,6 +274,24 @@ Passing a list of labels or tuples works similar to reindexing:
 
    df.loc[[('bar', 'two'), ('qux', 'one')]]
 
+.. info::
+
+   It is important to note that tuples and lists are not treated identically
+   in pandas when it comes to indexing. Whereas a tuple is interpreted as one
+   multi-level key, a list is used to specify several keys. Or in other words,
+   tuples go horizontally (traversing levels), lists go vertically (scanning levels).
+
+Importantly, a list of tuples indexes several complete ``MultiIndex`` keys,
+whereas a tuple of lists refer to several values within a level:
+
+.. ipython:: python
+
+   s = pd.Series([1, 2, 3, 4, 5, 6],
+                 index=pd.MultiIndex.from_product([["A", "B"], ["c", "d", "e"]]))
+   s.loc[[("A", "c"), ("B", "d")]]  # list of tuples
+   s.loc[(["A", "B"], ["c", "d"])]  # tuple of lists
+
+
 .. _advanced.mi_slicers:
 
 Using slicers
@@ -317,7 +349,7 @@ Basic multi-index slicing using slices, lists, and labels.
    dfmi.loc[(slice('A1','A3'), slice(None), ['C1', 'C3']), :]
 
 
-You can use :class:`pandas.IndexSlice` to facilitate a more natural syntax 
+You can use :class:`pandas.IndexSlice` to facilitate a more natural syntax
 using ``:``, rather than using ``slice(None)``.
 
 .. ipython:: python
@@ -626,7 +658,7 @@ Index Types
 -----------
 
 We have discussed ``MultiIndex`` in the previous sections pretty extensively. ``DatetimeIndex`` and ``PeriodIndex``
-are shown :ref:`here <timeseries.overview>`, and information about 
+are shown :ref:`here <timeseries.overview>`, and information about
 `TimedeltaIndex`` is found :ref:`here <timedeltas.timedeltas>`.
 
 In the following sub-sections we will highlight some other index types.
@@ -671,9 +703,9 @@ The ``CategoricalIndex`` is **preserved** after indexing:
 
    df2.loc['a'].index
 
-Sorting the index will sort by the order of the categories (Recall that we 
-created the index with ``CategoricalDtype(list('cab'))``, so the sorted 
-order is ``cab``.). 
+Sorting the index will sort by the order of the categories (recall that we
+created the index with ``CategoricalDtype(list('cab'))``, so the sorted
+order is ``cab``).
 
 .. ipython:: python
 
@@ -726,7 +758,7 @@ Int64Index and RangeIndex
 
    Indexing on an integer-based Index with floats has been clarified in 0.18.0, for a summary of the changes, see :ref:`here <whatsnew_0180.float_indexers>`.
 
-``Int64Index`` is a fundamental basic index in pandas. 
+``Int64Index`` is a fundamental basic index in pandas.
 This is an Immutable array implementing an ordered, sliceable set.
 Prior to 0.18.0, the ``Int64Index`` would provide the default index for all ``NDFrame`` objects.
 
@@ -765,7 +797,7 @@ The only positional indexing is via ``iloc``.
    sf.iloc[3]
 
 A scalar index that is not found will raise a ``KeyError``.
-Slicing is primarily on the values of the index when using ``[],ix,loc``, and 
+Slicing is primarily on the values of the index when using ``[],ix,loc``, and
 **always** positional when using ``iloc``. The exception is when the slice is
 boolean, in which case it will always be positional.
 

doc/source/api.rst

@@ -2240,6 +2240,8 @@ The following methods are available only for ``SeriesGroupBy`` objects.
    SeriesGroupBy.nunique
    SeriesGroupBy.unique
    SeriesGroupBy.value_counts
+   SeriesGroupBy.is_monotonic_increasing
+   SeriesGroupBy.is_monotonic_decreasing
 
 The following methods are available only for ``DataFrameGroupBy`` objects.
 

doc/source/tutorials.rst

@@ -9,52 +9,52 @@ This is a guide to many pandas tutorials, geared mainly for new users.
 Internal Guides
 ---------------
 
-pandas own :ref:`10 Minutes to pandas<10min>`
+pandas' own :ref:`10 Minutes to pandas<10min>`.
 
-More complex recipes are in the :ref:`Cookbook<cookbook>`
+More complex recipes are in the :ref:`Cookbook<cookbook>`.
 
 pandas Cookbook
 ---------------
 
-The goal of this cookbook (by `Julia Evans <http://jvns.ca>`_) is to
+The goal of this 2015 cookbook (by `Julia Evans <http://jvns.ca>`_) is to
 give you some concrete examples for getting started with pandas. These
 are examples with real-world data, and all the bugs and weirdness that
 entails.
 
-Here are links to the v0.1 release. For an up-to-date table of contents, see the `pandas-cookbook GitHub
+Here are links to the v0.2 release. For an up-to-date table of contents, see the `pandas-cookbook GitHub
 repository <http://github.com/jvns/pandas-cookbook>`_. To run the examples in this tutorial, you'll need to
 clone the GitHub repository and get IPython Notebook running.
 See `How to use this cookbook <https://github.com/jvns/pandas-cookbook#how-to-use-this-cookbook>`_.
 
--  `A quick tour of the IPython Notebook: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/A%20quick%20tour%20of%20IPython%20Notebook.ipynb>`_
+-  `A quick tour of the IPython Notebook: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/A%20quick%20tour%20of%20IPython%20Notebook.ipynb>`_
    Shows off IPython's awesome tab completion and magic functions.
--  `Chapter 1: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/Chapter%201%20-%20Reading%20from%20a%20CSV.ipynb>`_
+-  `Chapter 1: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/Chapter%201%20-%20Reading%20from%20a%20CSV.ipynb>`_
    Reading your data into pandas is pretty much the easiest thing. Even
    when the encoding is wrong!
--  `Chapter 2: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/Chapter%202%20-%20Selecting%20data%20&%20finding%20the%20most%20common%20complaint%20type.ipynb>`_
+-  `Chapter 2: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/Chapter%202%20-%20Selecting%20data%20&%20finding%20the%20most%20common%20complaint%20type.ipynb>`_
    It's not totally obvious how to select data from a pandas dataframe.
    Here we explain the basics (how to take slices and get columns)
--  `Chapter 3: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/Chapter%203%20-%20Which%20borough%20has%20the%20most%20noise%20complaints%3F%20%28or%2C%20more%20selecting%20data%29.ipynb>`_
+-  `Chapter 3: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/Chapter%203%20-%20Which%20borough%20has%20the%20most%20noise%20complaints%3F%20%28or%2C%20more%20selecting%20data%29.ipynb>`_
    Here we get into serious slicing and dicing and learn how to filter
    dataframes in complicated ways, really fast.
--  `Chapter 4: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/Chapter%204%20-%20Find%20out%20on%20which%20weekday%20people%20bike%20the%20most%20with%20groupby%20and%20aggregate.ipynb>`_
+-  `Chapter 4: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/Chapter%204%20-%20Find%20out%20on%20which%20weekday%20people%20bike%20the%20most%20with%20groupby%20and%20aggregate.ipynb>`_
    Groupby/aggregate is seriously my favorite thing about pandas
    and I use it all the time. You should probably read this.
--  `Chapter 5:  <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/Chapter%205%20-%20Combining%20dataframes%20and%20scraping%20Canadian%20weather%20data.ipynb>`_
+-  `Chapter 5:  <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/Chapter%205%20-%20Combining%20dataframes%20and%20scraping%20Canadian%20weather%20data.ipynb>`_
    Here you get to find out if it's cold in Montreal in the winter
    (spoiler: yes). Web scraping with pandas is fun! Here we combine dataframes.
--  `Chapter 6:  <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/Chapter%206%20-%20String%20operations%21%20Which%20month%20was%20the%20snowiest%3F.ipynb>`_
+-  `Chapter 6:  <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/Chapter%206%20-%20String%20operations%21%20Which%20month%20was%20the%20snowiest%3F.ipynb>`_
    Strings with pandas are great. It has all these vectorized string
    operations and they're the best. We will turn a bunch of strings
    containing "Snow" into vectors of numbers in a trice.
--  `Chapter 7: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/Chapter%207%20-%20Cleaning%20up%20messy%20data.ipynb>`_
+-  `Chapter 7: <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/Chapter%207%20-%20Cleaning%20up%20messy%20data.ipynb>`_
    Cleaning up messy data is never a joy, but with pandas it's easier.
--  `Chapter 8:  <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.1/cookbook/Chapter%208%20-%20How%20to%20deal%20with%20timestamps.ipynb>`_
+-  `Chapter 8:  <http://nbviewer.ipython.org/github/jvns/pandas-cookbook/blob/v0.2/cookbook/Chapter%208%20-%20How%20to%20deal%20with%20timestamps.ipynb>`_
    Parsing Unix timestamps is confusing at first but it turns out
    to be really easy.
 
 
-Lessons for New pandas Users
+Lessons for new pandas users
 ----------------------------
 
 For more resources, please visit the main `repository <https://bitbucket.org/hrojas/learn-pandas>`__.
@@ -125,7 +125,7 @@ There are four sections covering selected topics as follows:
 
 .. _tutorial-exercises-new-users:
 
-Exercises for New Users
+Exercises for new users
 -----------------------
 Practice your skills with real data sets and exercises.
 For more resources, please visit the main `repository <https://github.com/guipsamora/pandas_exercises>`__.
@@ -152,9 +152,14 @@ For more resources, please visit the main `repository <https://github.com/guipsa
 
 .. _tutorial-modern:
 
-Modern Pandas
+Modern pandas
 -------------
 
+Tutorial series written in 2016 by 
+`Tom Augspurger <https://github.com/TomAugspurger>`_.
+The source may be found in the GitHub repository
+`TomAugspurger/effective-pandas <https://github.com/TomAugspurger/effective-pandas>`_.
+
 - `Modern Pandas <http://tomaugspurger.github.io/modern-1-intro.html>`_
 - `Method Chaining <http://tomaugspurger.github.io/method-chaining.html>`_
 - `Indexes <http://tomaugspurger.github.io/modern-3-indexes.html>`_
@@ -168,6 +173,20 @@ Excel charts with pandas, vincent and xlsxwriter
 
 -  `Using Pandas and XlsxWriter to create Excel charts <https://pandas-xlsxwriter-charts.readthedocs.io/>`_
 
+Video Tutorials
+---------------
+
+- `Pandas From The Ground Up <https://www.youtube.com/watch?v=5JnMutdy6Fw>`_ 
+  (2015) (2:24)
+  `GitHub repo <https://github.com/brandon-rhodes/pycon-pandas-tutorial>`_ 
+- `Introduction Into Pandas <https://www.youtube.com/watch?v=-NR-ynQg0YM>`_ 
+  (2016) (1:28)
+  `GitHub repo <https://github.com/chendaniely/2016-pydata-carolinas-pandas>`_ 
+- `Pandas: .head() to .tail() <https://www.youtube.com/watch?v=7vuO9QXDN50>`_ 
+  (2016) (1:26)
+  `GitHub repo <https://github.com/TomAugspurger/pydata-chi-h2t>`_ 
+
+
 Various Tutorials
 -----------------
 

doc/source/whatsnew/v0.23.0.txt

@@ -323,6 +323,7 @@ Other Enhancements
 
 - ``IntervalIndex.astype`` now supports conversions between subtypes when passed an ``IntervalDtype`` (:issue:`19197`)
 - :class:`IntervalIndex` and its associated constructor methods (``from_arrays``, ``from_breaks``, ``from_tuples``) have gained a ``dtype`` parameter (:issue:`19262`)
+- Added :func:`SeriesGroupBy.is_monotonic_increasing` and :func:`SeriesGroupBy.is_monotonic_decreasing` (:issue:`17015`)
 
 .. _whatsnew_0230.api_breaking:
 
@@ -848,3 +849,5 @@ Other
 ^^^^^
 
 - Improved error message when attempting to use a Python keyword as an identifier in a ``numexpr`` backed query (:issue:`18221`)
+- Comparisons between :class:`Series` and :class:`Index` would return a ``Series`` with an incorrect name, ignoring the ``Index``'s name attribute (:issue:`19582`)
+-