DOC: update the dtypes/ftypes docstring (Seoul) #20100

jongwony · 2018-03-10T08:32:45Z

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:

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


################################################################################
##################### Docstring (pandas.DataFrame.dtypes)  #####################
################################################################################

Return the dtypes in this object.

Notes
-----
It returns a Series with the data type of each column.
If object contains data multiple dtypes in a single column,
dtypes will be chosen to accommodate all of the data types.
``object`` is the most general.

Examples
--------
>>> df = pd.DataFrame({'f': pd.np.random.rand(3),
...                    'i': 1,
...                    'd': pd.Timestamp('20180310'),
...                    'o': 'foo'})
>>> df.dtypes
f           float64
i             int64
d    datetime64[ns]
o            object
dtype: object

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

Errors found:
	No extended summary found
	No returns section found
	See Also section not found


################################################################################
##################### Docstring (pandas.DataFrame.ftypes)  #####################
################################################################################

Return the ftypes (indication of sparse/dense and dtype)
in this object.

Notes
-----
Sparse data should have the same dtypes as its dense representation

See Also
--------
dtypes, SparseDataFrame

Examples
--------
>>> arr = pd.np.random.randn(100, 4)
>>> arr[arr < .8] = pd.np.nan
>>> pd.DataFrame(arr).ftypes
0    float64:dense
1    float64:dense
2    float64:dense
3    float64:dense
dtype: object
>>> pd.SparseDataFrame(arr).ftypes
0    float64:sparse
1    float64:sparse
2    float64:sparse
3    float64:sparse
dtype: object

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

Errors found:
	No summary found (a short summary in a single line should be present at the beginning of the docstring)
	No returns section found
	Missing description for See Also "dtypes" reference
	Missing description for See Also "SparseDataFrame" reference

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.

Lastly, I left errors already occurred in the previous version without changes.

TomAugspurger · 2018-03-10T12:16:02Z

pandas/core/generic.py

+        """
+        Return the dtypes in this object.
+
+        Notes


I think you can remove the "Notes" header, and just make this the extended summary.

TomAugspurger · 2018-03-10T12:21:17Z

pandas/core/generic.py

+
+        Notes
+        -----
+        It returns a Series with the data type of each column.


Maybe replace "it" with "This method". And let's say what the values and index is.

This returns a Series with the data type of each column. The result's index is the original DataFrame's columns.

Let's also replace all instances of "object" with "DataFrame". I'm not sure why this is in generic.py since I think it's specific to DataFrame.

I'm modifying dtype @property of the NDFrame in generic.py
Is "This property" okay instead of "This method"?

At first, object was NDFrame, but found an error.

Private classes (['NDFrame']) should not be mentioned in public docstring.

but it seems to be better that the way you specify with "DataFrame", I will do that.

TomAugspurger · 2018-03-10T12:22:09Z

pandas/core/generic.py

+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'f': pd.np.random.rand(3),


Can you just write out three floating point values? I'd like to avoid random data.

And FYI in general you don't want to use pd.np. You'll want to import NumPy manually (it's assumed to be imported in our docstrings.)

Ah, and could you just make all these length-1 lists, just to be clearer? so {'f': [1.0], 'i': [1], ...}

TomAugspurger · 2018-03-10T12:23:15Z

pandas/core/generic.py

+
+        Notes
+        -----
+        Sparse data should have the same dtypes as its dense representation


End in a .

TomAugspurger · 2018-03-10T12:23:59Z

pandas/core/generic.py

+        2    float64:dense
+        3    float64:dense
+        dtype: object
+        >>> pd.SparseDataFrame(arr).ftypes


Maybe a blank line before this to break things up a bit.

TomAugspurger · 2018-03-10T12:24:42Z

pandas/core/generic.py

+
+        Examples
+        --------
+        >>> arr = pd.np.random.randn(100, 4)


arr = np.random.RandomState(0).randn(100, 4) for reproducibility

DataOmbudsman · 2018-03-10T12:32:23Z

pandas/core/generic.py

-        """Return the dtypes in this object."""
+        """
+        Return the dtypes in this object.
+


Can you please add a Returns section as specified in the guide?

DataOmbudsman · 2018-03-10T12:34:11Z

pandas/core/generic.py

+        If object contains data multiple dtypes in a single column,
+        dtypes will be chosen to accommodate all of the data types.
+        ``object`` is the most general.
+


I believe in a See Also section ftypes could be mentioned.

DataOmbudsman · 2018-03-10T12:37:04Z

pandas/core/generic.py

@@ -4285,6 +4307,31 @@ def ftypes(self):
        """
        Return the ftypes (indication of sparse/dense and dtype)


The docstring guide asks that the summary should fit in a single line. Could you rephrase it that way? If all information could not fit in a single line you can then use an Extended Summary section.

DataOmbudsman · 2018-03-10T12:45:33Z

pandas/core/generic.py

+
+        See Also
+        --------
+        dtypes, SparseDataFrame


Instead of simply dtypes you should use pandas.DataFrame.dtypes. You can even try linking to dtypes with the notation found in the guide: :meth:`pandas.Series.sum`

joaoavf

Found some points that could be improved. Good sprint for you all!

joaoavf · 2018-03-10T12:36:16Z

pandas/core/generic.py

+
+        Notes
+        -----
+        It returns a Series with the data type of each column.


Create a 'Returns' section to explain the output. Notes should be used only to explain technical details about the implementation of the algorithm or function behavior.

joaoavf · 2018-03-10T12:40:46Z

pandas/core/generic.py

@@ -4275,7 +4275,29 @@ def get_ftype_counts(self):

    @property
    def dtypes(self):
-        """Return the dtypes in this object."""
+        """
+        Return the dtypes in this object.


Explain in more depth to a novice user that this is used to get the dtypes per column of the DataFrame.

joaoavf · 2018-03-10T12:45:09Z

pandas/core/generic.py

+        It returns a Series with the data type of each column.
+        If object contains data multiple dtypes in a single column,
+        dtypes will be chosen to accommodate all of the data types.
+        ``object`` is the most general.


It is worth explaining that str will be represented as object.

joaoavf · 2018-03-10T12:47:41Z

pandas/core/generic.py

-        """Return the dtypes in this object."""
+        """
+        Return the dtypes in this object.
+


Add a 'See Also' section to contemplate common dtypes.

joaoavf · 2018-03-10T12:51:51Z

pandas/core/generic.py

@@ -4285,6 +4307,31 @@ def ftypes(self):
        """


It would better organized it there was pull request for dtypes and another pull request for ftypes.

joaoavf · 2018-03-10T12:54:02Z

pandas/core/generic.py

@@ -4285,6 +4307,31 @@ def ftypes(self):
        """
        Return the ftypes (indication of sparse/dense and dtype)


Short summary should have 1 line.

joaoavf · 2018-03-10T12:54:40Z

pandas/core/generic.py

@@ -4285,6 +4307,31 @@ def ftypes(self):
        """
        Return the ftypes (indication of sparse/dense and dtype)
        in this object.
+


Add a return section.

joaoavf · 2018-03-10T12:55:35Z

pandas/core/generic.py

+        -----
+        Sparse data should have the same dtypes as its dense representation
+
+        See Also


'See Also' should go before notes.

joaoavf · 2018-03-10T12:57:42Z

pandas/core/generic.py

+
+        See Also
+        --------
+        dtypes, SparseDataFrame


Make a short description for the itens cited in the summary.

jreback · 2018-03-10T13:15:29Z

is this overlapping with #20099 ?

jreback · 2018-03-10T13:18:48Z

pandas/core/generic.py

+        >>> df = pd.DataFrame({'f': pd.np.random.rand(3),
+        ...                    'i': 1,
+        ...                    'd': pd.Timestamp('20180310'),
+        ...                    'o': 'foo'})


add in See Also to Series.dtype

pep8speaks · 2018-03-11T07:37:17Z

Hello @lastone9182! Thanks for updating the PR.

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

Comment last updated on March 12, 2018 at 21:10 Hours UTC

codecov · 2018-03-11T07:37:38Z

Codecov Report

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

@@           Coverage Diff           @@
##           master   #20100   +/-   ##
=======================================
  Coverage   91.72%   91.72%           
=======================================
  Files         150      150           
  Lines       49149    49149           
=======================================
  Hits        45083    45083           
  Misses       4066     4066

Flag	Coverage Δ
#multiple	`90.11% <ø> (ø)`	⬆️
#single	`41.85% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	`95.84% <ø> (ø)`	⬆️

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 52cffa3...8058931. Read the comment docs.

DOC: Improved the docstring of dtypes/ftypes property in NDFrame

8bce675

TomAugspurger reviewed Mar 10, 2018

View reviewed changes

DataOmbudsman suggested changes Mar 10, 2018

View reviewed changes

joaoavf reviewed Mar 10, 2018

View reviewed changes

jreback added the Docs label Mar 10, 2018

jreback reviewed Mar 10, 2018

View reviewed changes

DOC: Improved the docstring of dtypes/ftypes

05306db

jongwony and others added 4 commits March 11, 2018 16:47

DOC: Improved the docstring of dtypes/ftypes

1b34fcd

Grammar, updates

14cc494

use longer column names

14b754f

Updates

8058931

TomAugspurger merged commit 22b6749 into pandas-dev:master Mar 12, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the dtypes/ftypes docstring (Seoul) #20100

DOC: update the dtypes/ftypes docstring (Seoul) #20100

jongwony commented Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

jongwony Mar 11, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

DataOmbudsman Mar 10, 2018

DataOmbudsman Mar 10, 2018

DataOmbudsman Mar 10, 2018

DataOmbudsman Mar 10, 2018

joaoavf left a comment

joaoavf Mar 10, 2018

joaoavf Mar 10, 2018

joaoavf Mar 10, 2018

joaoavf Mar 10, 2018

joaoavf Mar 10, 2018

joaoavf Mar 10, 2018

joaoavf Mar 10, 2018

joaoavf Mar 10, 2018

joaoavf Mar 10, 2018

jreback commented Mar 10, 2018

jreback Mar 10, 2018

pep8speaks commented Mar 11, 2018 •

edited

Loading

codecov bot commented Mar 11, 2018 •

edited

Loading

		@@ -4285,6 +4307,31 @@ def ftypes(self):
		"""
		Return the ftypes (indication of sparse/dense and dtype)

DOC: update the dtypes/ftypes docstring (Seoul) #20100

DOC: update the dtypes/ftypes docstring (Seoul) #20100

Conversation

jongwony commented Mar 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joaoavf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback commented Mar 10, 2018

Choose a reason for hiding this comment

pep8speaks commented Mar 11, 2018 • edited Loading

Comment last updated on March 12, 2018 at 21:10 Hours UTC

codecov bot commented Mar 11, 2018 • edited Loading

Codecov Report

pep8speaks commented Mar 11, 2018 •

edited

Loading

codecov bot commented Mar 11, 2018 •

edited

Loading