DOC: update the DataFrame.pivot docstring

[amuta]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
###################### Docstring (pandas.DataFrame.pivot) ######################
################################################################################

Return reshaped DataFrame summarized by given index / column values.

Reshape data (produce a "pivot" table) based on column values. Uses
unique values from index / columns to form axes of the resulting
DataFrame. This function does not support data aggregation, multiple
values will result in hierarchically indexed columns.

Parameters
----------
index : string or object, optional
    Column name to use to make new frame's index. If None, uses
    existing index.
columns : string or object, optional
    Column name to use to make new frame's columns.
values : string or object, optional
    Column name to use for populating new frame's values. If not
    specified, all remaining columns will be used and the result will
    have hierarchically indexed columns.

Returns
-------
DataFrame
    Returns reshaped DataFrame.

See Also
--------
DataFrame.pivot_table : generalization of pivot that can handle
    duplicate values for one index/column pair
DataFrame.unstack : pivot based on the index values instead of a
    column

Notes
-----
For finer-tuned control, see hierarchical indexing documentation along
with the related stack/unstack methods

Examples
--------

>>> df = pd.DataFrame({'foo': ['one','one','one','two','two','two'],
...                    'bar': ['A', 'B', 'C', 'A', 'B', 'C'],
...                    'baz': [1, 2, 3, 4, 5, 6]})
>>> df
    foo   bar  baz
0   one   A    1
1   one   B    2
2   one   C    3
3   two   A    4
4   two   B    5
5   two   C    6

>>> df.pivot(index='foo', columns='bar', values='baz')
bar  A   B   C
foo
one  1   2   3
two  4   5   6

>>> df.pivot(index='foo', columns='bar')['baz']
bar  A   B   C
foo
one  1   2   3
two  4   5   6

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.pivot" correct. :)

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

[jorisvandenbossche]

Thanks! Added a few comments

Can you add a "Raises" section? As I think this is commonly encountered (so the case where you have duplicate values in index / column combinations, so when you need to use pivot_table instead)

[jorisvandenbossche]

I think "summarized" is misleading here, as there is no "summary" (aggregation) calculation happening.

(I don't directly have the "better" wording in mind though. And the "reshaping" is important, as you already mention)

[jorisvandenbossche]

can you add single backtick around index and column ? (to reference them as parameters).

I would maybe also say "from specified index / columns" to make it clear it is not the existing index / columns

[jorisvandenbossche]

What happens in this case if you do not specify it?

[jorisvandenbossche]

Would it be clearer to just say "Column" instead of "Column name". I know the value you specify is the name, but what you actually use to make the new frame's index is the actual column, not the column name ...

[pep8speaks]

Hello @amuta! Thanks for updating the PR.

• In the file pandas/core/frame.py, following are the PEP8 issues :

Line 4347:80: E501 line too long (86 > 79 characters)

Comment last updated on March 12, 2018 at 20:47 Hours UTC

[jreback]

in multiindexed columns.

[TomAugspurger]

Thanks @amuta !