DOC: Improve the docstring of DataFrame.transpose()

[igorcadelima]

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:

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

Errors found:
	Errors in parameters section
		Parameters {'args', 'kwargs'} not documented
		Unknown parameters {'*args', '**kwargs'}
		Parameter "*args" has no type
		Parameter "**kwargs" has no type

The errors are well-known false positives.

[math-and-data]

Another recommendation to include in the See Also section:
DataFrame.T: alias for DataFrame.transpose

[jorisvandenbossche]

That's a good idea, the only problem with that is that we use the same docstring for .T, so then it would be pointing to itself.

So I would just reflect the full docstring for both, like you already did in the examples.

@igorcadelima maybe add in the extended summary that it is both as method transpose() and property T

[math-and-data]

Fantastic to see the usage of both T and transpose!
If possible, please add an example with a non-square DataFrame, e.g. 2 rows and 5 columns to show off some functionality - or maybe add some information about the fact it can be applied to square and non-square DataFrames?

[igorcadelima]

Done. How do you like it now? :)

[jreback]

@jorisvandenbossche I think standard for this has changed? we don't need to mention the internal functions here

[jorisvandenbossche]

Yes, the explanation we are using in other PRs is "Additional keywords have no effect but might be accepted for compatibility with numpy".

@igorcadelima and you can put both on a single line, like:

*args, **kwargs
    Additional keywords have no effect but might be accepted for
    compatibility with numpy

[igorcadelima]

Thanks for the comments!

The reason I didn't just use "Additional keywords have no effect but might be accepted for compatibility with numpy" is because there will be noticeable effects if we pass copy=True.

In [1]: import pandas as pd

In [2]: d = {'col1': [1, 2], 'col2': [3, 4]}

In [3]: df = pd.DataFrame(d)

In [4]: df
Out[4]: 
   col1  col2
0     1     3
1     2     4

In [5]: df2 = df.transpose() # or df.T

In [6]: df2
Out[6]: 
      0  1
col1  1  2
col2  3  4

In [7]: df3 = df.transpose(copy=True)

In [8]: df3
Out[8]: 
      0  1
col1  1  2
col2  3  4

In [9]: df['col1'] = 10

In [10]: df
Out[10]: 
   col1  col2
0    10     3
1    10     4

In [11]: df2
Out[11]: 
       0   1
col1  10  10
col2   3   4

In [12]: df3
Out[12]: 
      0  1
col1  1  2
col2  3  4

copy is the only keyword I have found to have any effect on the transpose operation. What do you think I should do in this case, @jorisvandenbossche @jreback ?

[jorisvandenbossche]

But copy is not a numpy keyword? https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.transpose.html
So I think we should actually just document copy as an actual keyword (although it is not in the signature, for technical reasons, and so the validation script will complain about that, but you can ignore that)

[igorcadelima]

Not really. What happens is that when copy=True, the method copy is called on the DataFrame's values, as can be confirmed here.

I just incorporated your comments.

[jreback]

can you also add an example with a mixed dtypes, and show the dtypes before/after. and add in the Notes section how transposing can change the dtypes.

[igorcadelima]

Hi, @jreback . I've made some changes to incorporate your suggestion.

[codecov]

Codecov Report

Merging #20254 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #20254   +/-   ##
=======================================
  Coverage   91.84%   91.84%           
=======================================
  Files         152      152           
  Lines       49231    49231           
=======================================
  Hits        45215    45215           
  Misses       4016     4016

Flag	Coverage Δ
#multiple	90.22% <ø> (ø)	⬆️
#single	41.83% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/core/frame.py	97.18% <ø> (ø)	⬆️

---

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 85817a7...ead247c. Read the comment docs.

[jorisvandenbossche]

Very nice updates! Looking good

[jorisvandenbossche]

(I only made a small clarification of the copy keyword, that even if copy=False it is not always no copy)

[jorisvandenbossche]

@igorcadelima @cemsbr Thanks for the PR!