Spellcheck of docs, a few minor changes #18973

tommyod · 2017-12-28T16:54:15Z

This PR continues my read-through of the docs, the previous PRs submitted are #18941 and #18948.

The following edits have been made:

Missing periods and colons added before introducing code examples.
Increased number of function references (clickable links).
Cleared up a few sentences which I found unclear.

Feedback is welcome.

TomAugspurger

Only partway through, looks good so far.

Style question: we have quite a few places like

The :meth:`Series.cov` method does...

I prefer just saying

:meth:`Series.cov` does...

I think it's clear from the context that we're talking about a method.

TomAugspurger · 2017-12-28T17:03:54Z

doc/source/advanced.rst

@@ -315,7 +316,7 @@ Basic multi-index slicing using slices, lists, and labels.

   dfmi.loc[(slice('A1','A3'), slice(None), ['C1', 'C3']), :]

-You can use a ``pd.IndexSlice`` to have a more natural syntax using ``:`` rather than using ``slice(None)``
+You can use ``pd.IndexSlice`` to facilitate a more natural syntax using ``:``, rather than using ``slice(None)``.


You could link to IndexSlice here

:class:`IndexSlice`

I think (maybe pandas.IndexSlice).

TomAugspurger · 2017-12-28T17:06:46Z

doc/source/advanced.rst


-Slicing is ALWAYS on the values of the index, for ``[],ix,loc`` and ALWAYS positional with ``iloc``
+Slicing is **always** on the values of the index when using ``[],ix,loc``, and 


Except for booleans :)

Perhaps we can rephrase this as "primarily on the values" and mention elsewhere (perhaps after iloc) that booleans are also allowed.

TomAugspurger · 2017-12-28T17:07:43Z

doc/source/computation.rst

@@ -47,17 +48,18 @@ NA/null values *before* computing the percent change).
 Covariance
 ~~~~~~~~~~

-The ``Series`` object has a method ``cov`` to compute covariance between series
-(excluding NA/null values).
+The ``Series`` object has a method :meth:`~Series.cov` to compute covariance 


How about

:meth:`Series.cov` can be used to compute covariance between series (excluding missing values)

TomAugspurger · 2017-12-28T17:08:15Z

doc/source/computation.rst


 .. ipython:: python

   s1 = pd.Series(np.random.randn(1000))
   s2 = pd.Series(np.random.randn(1000))
   s1.cov(s2)

-Analogously, ``DataFrame`` has a method ``cov`` to compute pairwise covariances
-among the series in the DataFrame, also excluding NA/null values.
+Analogously, ``DataFrame`` has a method :meth:`~DataFrame.cov` to compute 


And

Analogously, :meth:`DataFrame.cov` can be used to compute pairwise...

codecov · 2017-12-28T18:48:47Z

Codecov Report

❗ No coverage uploaded for pull request base (master@10edfd0). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master   #18973   +/-   ##
=========================================
  Coverage          ?   91.58%           
=========================================
  Files             ?      150           
  Lines             ?    48972           
  Branches          ?        0           
=========================================
  Hits              ?    44851           
  Misses            ?     4121           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`89.94% <ø> (?)`
#single	`41.72% <ø> (?)`

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 10edfd0...9133861. Read the comment docs.

tommyod · 2017-12-28T19:30:51Z

Thanks for the feedback @TomAugspurger. I have submitted a new PR addressing your comments, which were helpful.

I agree that "... to compute it, use my_method and ..." is more succinct and clear than "... to compute it, use the method my_method and ...".
I am uncertain about starting a sentence with "The my_method method is..." vs. "my_method is...". The first phrasing seems to occur quite a bit in the documentation.

jreback

lgtm! just some small changes. ping on green.

jreback · 2017-12-29T00:31:57Z

doc/source/computation.rst

@@ -110,6 +114,11 @@ Several methods for computing correlations are provided:
 .. \rho = \cov(x, y) / \sigma_x \sigma_y

 All of these are currently computed using pairwise complete observations.
+Wikipedia has articles covering the 


can you make these a bulleted list?

jreback · 2017-12-29T00:34:27Z

doc/source/indexing.rst

-true wherever the Series elements exist in the passed list. This allows you to
-select rows where one or more columns have values you want:
+Consider the :meth:`~Series.isin` method of Series, which returns a boolean 
+vector that is true wherever the Series elements exist in the passed list. 


generally like to use double-backticks around Series, DataFrame, Index where possible.

jreback · 2017-12-29T00:36:08Z

doc/source/indexing.rst

@@ -1123,8 +1125,6 @@ as condition and ``other`` argument.
                       'C': [7, 8, 9]})
   df3.where(lambda x: x > 4, lambda x: x + 10)

-**mask**


could make mask a sub-section (of the where section).

jreback · 2017-12-29T00:36:26Z

doc/source/indexing.rst

@@ -1123,8 +1125,6 @@ as condition and ``other`` argument.
                       'C': [7, 8, 9]})
   df3.where(lambda x: x > 4, lambda x: x + 10)

-**mask**
-
 ``mask`` is the inverse boolean operation of ``where``.


you can remove the experimental from the Query section.

jreback · 2017-12-29T00:37:23Z

doc/source/options.rst

@@ -37,7 +37,7 @@ namespace:
 - :func:`~pandas.option_context` - execute a codeblock with a set of options
  that revert to prior settings after execution.

-**Note:** developers can check out pandas/core/config.py for more info.
+**Note:** Developers can check out ``pandas/core/config.py`` for more info.


you can put this link in: https://github.com/pandas-dev/pandas/blob/master/pandas/core/config.py

jreback · 2017-12-29T00:37:48Z

doc/source/options.rst

@@ -79,15 +79,15 @@ Getting and Setting Options
 ---------------------------

 As described above, ``get_option()`` and ``set_option()`` are available from the


you can use :func:`get_option` and so on

jreback · 2017-12-29T00:38:07Z

doc/source/text.rst

@@ -99,7 +99,7 @@ Elements in the split lists can be accessed using ``get`` or ``[]`` notation:
   s2.str.split('_').str.get(1)
   s2.str.split('_').str[1]

-Easy to expand this to return a DataFrame using ``expand``.
+It's easy to expand this to return a DataFrame using ``expand``.


tommyod · 2017-12-29T14:34:54Z

@jreback I've addressed your comments. I've been noting some stylistic preferences (which I agree with), such as "It is ..." instead of "It's" and using double-backticks on objects. For now I have not addressed these globally in the docs, but I hope to do so in a future PR.

jreback · 2017-12-29T14:45:31Z

@tommyod totally cool. updating things like this is generally, do a few docs / files at once. it becomes too hard to review otherwise.

jreback

small comments.

jreback · 2017-12-29T14:48:09Z

doc/source/indexing.rst


-``mask`` is the inverse boolean operation of ``where``.
+Mask
+~~~~~~~~~


this needs to be the same length as the title (otherwise sphinx warns)

jreback · 2017-12-29T14:48:14Z

doc/source/indexing.rst

@@ -1134,7 +1138,7 @@ as condition and ``other`` argument.

 .. _indexing.query:

-The :meth:`~pandas.DataFrame.query` Method (Experimental)
+The :meth:`~pandas.DataFrame.query` Method


jreback · 2017-12-29T14:48:53Z

doc/source/indexing.rst

-indexed DataFrame:
+DataFrame has a :meth:`~DataFrame.set_index` method which takes a column name 
+(for a regular ``Index``) or a list of column names (for a ``MultiIndex``), 
+to create a new, indexed DataFrame:


capitalize as beginning of sentence?

jreback · 2017-12-29T14:49:13Z

doc/source/indexing.rst

+As a convenience, there is a new function on DataFrame called 
+:meth:`~DataFrame.reset_index` which transfers the index values into the 
+DataFrame's columns and sets a simple integer index. 
+This is the inverse operation to ``set_index``.


put a :func:`DataFrame.set_index`

jreback · 2017-12-29T14:49:32Z

doc/source/indexing.rst

@@ -1728,7 +1733,7 @@ discards the index, instead of putting index values in the DataFrame's columns.

 .. note::

-   The ``reset_index`` method used to be called ``delevel`` which is now
+   The ``reset_index`` method used to be called ``delevel``, which is now


you can remove this, delevel is removed

tommyod · 2017-12-29T15:11:13Z

@jreback 👍 . Addressed comments.

jreback · 2017-12-29T21:49:00Z

thanks @tommyod

TomAugspurger reviewed Dec 28, 2017

View reviewed changes

jreback added the Docs label Dec 28, 2017

jreback requested changes Dec 29, 2017

View reviewed changes

tommyod added 4 commits December 29, 2017 16:09

Spellcheck of docs, a few minor changes

cd2a858

Reviewer comments. Slicing with boolean, rephrasing

46e4193

Adressed reviewer comments

81fc385

Small changes to indexing.rst as per review

9133861

jreback added this to the 0.23.0 milestone Dec 29, 2017

jreback approved these changes Dec 29, 2017

View reviewed changes

jreback merged commit 8433562 into pandas-dev:master Dec 29, 2017

tommyod mentioned this pull request Dec 31, 2017

Spellcheck #19017

Merged

hexgnu pushed a commit to hexgnu/pandas that referenced this pull request Jan 1, 2018

Spellcheck of docs, a few minor changes (pandas-dev#18973)

23f52ca

tommyod mentioned this pull request Jan 4, 2018

DOC: Spellcheck of merging.rst, reshaping.rst and timeseries.rst #19081

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Spellcheck of docs, a few minor changes #18973

Spellcheck of docs, a few minor changes #18973

tommyod commented Dec 28, 2017

TomAugspurger left a comment

TomAugspurger Dec 28, 2017

TomAugspurger Dec 28, 2017

TomAugspurger Dec 28, 2017

TomAugspurger Dec 28, 2017

codecov bot commented Dec 28, 2017 •

edited

tommyod commented Dec 28, 2017

jreback left a comment

jreback Dec 29, 2017

jreback Dec 29, 2017

jreback Dec 29, 2017

jreback Dec 29, 2017

jreback Dec 29, 2017

jreback Dec 29, 2017

jreback Dec 29, 2017

tommyod commented Dec 29, 2017

jreback commented Dec 29, 2017

jreback left a comment

jreback Dec 29, 2017

jreback Dec 29, 2017

jreback Dec 29, 2017

jreback Dec 29, 2017

jreback Dec 29, 2017

tommyod commented Dec 29, 2017

jreback commented Dec 29, 2017


		Slicing is ALWAYS on the values of the index, for ``[],ix,loc`` and ALWAYS positional with ``iloc``
		Slicing is always on the values of the index when using ``[],ix,loc``, and

		@@ -79,15 +79,15 @@ Getting and Setting Options
		---------------------------

		As described above, ``get_option()`` and ``set_option()`` are available from the

Spellcheck of docs, a few minor changes #18973

Spellcheck of docs, a few minor changes #18973

Conversation

tommyod commented Dec 28, 2017

TomAugspurger 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

codecov bot commented Dec 28, 2017 • edited

Codecov Report

tommyod commented Dec 28, 2017

jreback 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

tommyod commented Dec 29, 2017

jreback commented Dec 29, 2017

jreback 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

tommyod commented Dec 29, 2017

jreback commented Dec 29, 2017

codecov bot commented Dec 28, 2017 •

edited