DOC: update the DataFrame.stack docstring #20430

samuelsinayoko · 2018-03-20T22:44:01Z

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

PR title is "DOC: update the DataFrame.stack 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:

# paste output of "scripts/validate_docstrings.py <your-function-or-method>" here
# between the "```" (remove this comment, but keep the "```")

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.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

closes #xxxx
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

- Make description and summary clearer. - Fix doctests

Reviewed by Marco.

Separate creation of data with examples.

datapythonista

Great work. Added some comments about formatting, and some that in my opinion should make the examples better.

datapythonista · 2018-03-20T23:56:53Z

pandas/core/frame.py

+        -----
+        The function is named by analogy with a stack of books
+        (levels) being re-organised from a horizontal position (column
+        levels) to a vertical position (index levels).

        Examples


Examples section should go at the end, after Returns and See Also.

Fixed in 99734ac

datapythonista · 2018-03-21T00:00:14Z

pandas/core/frame.py

+             onto column axis.
+        DataFrame.pivot: reshape dataframe from long format to wide
+             format.
+        DataFrame.pivot_table: create a spreadsheet-style pivot table


It should be a space between the colon, and the description should start with a capital letter.

Fixed in 652f7b2

datapythonista · 2018-03-21T00:09:43Z

pandas/core/frame.py

+             b    1
+        two  a    2
+             b    3
+        dtype: int64


It's just a personal opinion, but I think defining all the data first with descriptive names make it a bit more complex to understand.

We could have separate sections for each case, with a title in bold (surrounding the text with double stars, followed by the data creation, using simply df in all the cases.

Also, in this case I think it would make the example easier to understand using more real-world examples. As a, b... don't have a meaning, it'd a bit harder to understand what's going on.

A minor thing, when creating the data, I think it makes more sense that each row is defined as a tuple, than as a list.

For example:

**Single level** >>> df = pd.DataFrame([(8, 12), (22, 35)], ... index=['cat', 'dog'], ... columns=['weight', 'max_speed']) >>> df >>> df.stack()

👍 split the examples in several sections in 15902ed

codecov · 2018-03-21T06:28:32Z

Codecov Report

Merging #20430 into master will increase coverage by 0.04%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #20430      +/-   ##
==========================================
+ Coverage    91.8%   91.85%   +0.04%     
==========================================
  Files         152      152              
  Lines       49215    49231      +16     
==========================================
+ Hits        45181    45220      +39     
+ Misses       4034     4011      -23

Flag	Coverage Δ
#multiple	`90.23% <100%> (+0.04%)`	⬆️
#single	`41.83% <66.66%> (-0.01%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/frame.py	`97.18% <100%> (ø)`	⬆️
pandas/core/arrays/categorical.py	`96.2% <0%> (-0.02%)`	⬇️
pandas/core/base.py	`96.78% <0%> (ø)`	⬆️
pandas/core/indexes/datetimelike.py	`96.72% <0%> (ø)`	⬆️
pandas/core/series.py	`93.84% <0%> (ø)`	⬆️
pandas/core/panel.py	`97.29% <0%> (ø)`	⬆️
pandas/core/generic.py	`95.85% <0%> (ø)`	⬆️
pandas/core/indexes/category.py	`97.3% <0%> (ø)`	⬆️
pandas/core/indexes/base.py	`96.68% <0%> (ø)`	⬆️
... and 8 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 01882ba...5bc794c. Read the comment docs.

More clear than lumping all the definitions into a single section at the start.

Easier to follow.

pep8speaks · 2018-03-22T20:05:37Z

Hello @samuelsinayoko! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on March 26, 2018 at 13:05 Hours UTC

TomAugspurger · 2018-03-22T20:12:34Z

pandas/core/frame.py

-        column labels) having a hierarchical index with a new inner-most level
-        of row labels.
-        The level involved will automatically get sorted.
+        Stack the prescribed level(s) from the column axis onto the index


This should be a single line. Can you shorten by "column axis" -> "columns" and "index axis" -> "index"?

Thanks for the review. Fixed in a2c9b1a.

I've also modified the description in the Notes section. It was never completely clear to me why method was called stack (I think I was imagining the column as a board being moved from an horizontal position to a vertical position, whereas I think the name comes from a collection of items being moved from a side by side position to a stack), so I've tried to explain that in the notes section. Hope it makes sense!

samuelsinayoko · 2018-03-25T12:07:07Z

@datapythonista Nice seeing you at the London meetup this week, thanks again for organising. Are you happy with the latest changes?

[ci skip]

TomAugspurger · 2018-03-26T13:06:20Z

Thanks @samuelsinayoko !

samuelsinayoko added 14 commits March 20, 2018 20:29

Fix docstring or pandas.DataFrame.stack.

a73bd9a

- Make description and summary clearer. - Fix doctests

Polish the docstring (plural issues and the like).

1771437

Add description to example.

f17b52b

Add an example with multi-level column.

c756141

Add more examples.

4d09b85

Fix sphinx docs

d5a262a

Fix parameter types

d3ef094

Post review improvements.

4d60246

Reviewed by Marco.

Start refactoring the examples.

16301d6

Separate creation of data with examples.

Refactor examples

310511d

Polish examples.

7e10273

Add an example where multiple levels are stacked at once.

77c9fac

Clarify filling behaviour with missing values

98a4a93

flake8

41ad4cf

datapythonista reviewed Mar 21, 2018

View reviewed changes

Put Examples section at the end.

99734ac

samuelsinayoko added 6 commits March 21, 2018 06:30

Fix 'See Also' section.

652f7b2

Create separate section for single level columns.

7f422d6

More clear than lumping all the definitions into a single section at the start.

Split the examples into several sections.

15902ed

Easier to follow.

remove unwanted blank lines

2379886

Start using more meaningful index & column names

2e0873b

Use more meaningful column and index names.

718f212

TomAugspurger reviewed Mar 22, 2018

View reviewed changes

samuelsinayoko added 3 commits March 25, 2018 12:57

Shorten overly long lines in examples.

747d245

Shorter one line description.

a2c9b1a

Better description in the notes section.

d34732d

Formatting [ci skip]

5bc794c

[ci skip]

TomAugspurger added the Docs label Mar 26, 2018

TomAugspurger added this to the 0.23.0 milestone Mar 26, 2018

TomAugspurger added the Reshaping Concat, Merge/Join, Stack/Unstack, Explode label Mar 26, 2018

TomAugspurger merged commit 402ad45 into pandas-dev:master Mar 26, 2018

ZackStone pushed a commit to ZackStone/pandas that referenced this pull request Mar 26, 2018

DOC: update the DataFrame.stack docstring (pandas-dev#20430)

ca3de1a

javadnoorb pushed a commit to javadnoorb/pandas that referenced this pull request Mar 29, 2018

DOC: update the DataFrame.stack docstring (pandas-dev#20430)

56ca9a3

dworvos pushed a commit to dworvos/pandas that referenced this pull request Apr 2, 2018

DOC: update the DataFrame.stack docstring (pandas-dev#20430)

cb30e3b

kornilova203 pushed a commit to kornilova203/pandas that referenced this pull request Apr 23, 2018

DOC: update the DataFrame.stack docstring (pandas-dev#20430)

3fd81ad

samuelsinayoko mentioned this pull request Apr 29, 2018

Pandas docs data frame.stack #20858

Closed

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the DataFrame.stack docstring #20430

DOC: update the DataFrame.stack docstring #20430

samuelsinayoko commented Mar 20, 2018

datapythonista left a comment

datapythonista Mar 20, 2018

samuelsinayoko Mar 21, 2018

datapythonista Mar 21, 2018

samuelsinayoko Mar 21, 2018

datapythonista Mar 21, 2018

samuelsinayoko Mar 22, 2018 •

edited

Loading

codecov bot commented Mar 21, 2018 •

edited

Loading

pep8speaks commented Mar 22, 2018 •

edited

Loading

TomAugspurger Mar 22, 2018

samuelsinayoko Mar 25, 2018

samuelsinayoko commented Mar 25, 2018

TomAugspurger commented Mar 26, 2018

DOC: update the DataFrame.stack docstring #20430

DOC: update the DataFrame.stack docstring #20430

Conversation

samuelsinayoko commented Mar 20, 2018

datapythonista left a comment

Choose a reason for hiding this comment

datapythonista Mar 20, 2018

Choose a reason for hiding this comment

samuelsinayoko Mar 21, 2018

Choose a reason for hiding this comment

datapythonista Mar 21, 2018

Choose a reason for hiding this comment

samuelsinayoko Mar 21, 2018

Choose a reason for hiding this comment

datapythonista Mar 21, 2018

Choose a reason for hiding this comment

samuelsinayoko Mar 22, 2018 • edited Loading

Choose a reason for hiding this comment

codecov bot commented Mar 21, 2018 • edited Loading

Codecov Report

pep8speaks commented Mar 22, 2018 • edited Loading

Comment last updated on March 26, 2018 at 13:05 Hours UTC

TomAugspurger Mar 22, 2018

Choose a reason for hiding this comment

samuelsinayoko Mar 25, 2018

Choose a reason for hiding this comment

samuelsinayoko commented Mar 25, 2018

TomAugspurger commented Mar 26, 2018

samuelsinayoko Mar 22, 2018 •

edited

Loading

codecov bot commented Mar 21, 2018 •

edited

Loading

pep8speaks commented Mar 22, 2018 •

edited

Loading