DOC: update the Series.reset_index DocString #20107

ludusrusso · 2018-03-10T11:11:47Z

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.core.series.Series.reset_index)  ##############
################################################################################

Reset the index of the Serie.

For a Serie with multi-level index, return a new Serie with labeling
information in the columns under the index names, defaulting to ‘level_0’,
‘level_1’, etc. if any are None. For a standard index,
the index name will be used (if set), otherwise a default
‘index’ or ‘level_0’ (if ‘index’ is already taken) will be used.

Parameters
----------
level : `int`, `str`, `tuple`, or `list`, default `None`
    Only remove the given levels from the index. Removes all levels by
    default.
drop : `boolean`, default `False`
    Do not try to insert index into dataframe columns.
name : `object`, default `None`
    The name of the column corresponding to the Series values.
inplace : `boolean`, default `False`
    Modify the Series in place (do not create a new object).

Returns
----------
resetted : `DataFrame`, or Series if `drop == True`

See Also
--------
:meth:`pandas.DataFrame.reset_index`: Analogous funciton for DataFrame

Examples
--------
>>> s = pd.Series([1, 2, 3, 4], index=pd.Index(['a', 'b', 'c', 'd'],
...                                            name = 'idx'))
>>> s.reset_index()
  idx  0
0   a  1
1   b  2
2   c  3
3   d  4

>>> arrays = [np.array(['bar', 'bar', 'baz', 'baz', 'foo',
...                     'foo', 'qux', 'qux']),
...           np.array(['one', 'two', 'one', 'two', 'one', 'two',
...                     'one', 'two'])]
>>> s2 = pd.Series(
...     range(8),
...     index=pd.MultiIndex.from_arrays(arrays,
...                                     names=['a', 'b']))
>>> s2.reset_index(level='a')
       a  0
b
one  bar  0
two  bar  1
one  baz  2
two  baz  3
one  foo  4
two  foo  5
one  qux  6
two  qux  7

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

Docstring for "pandas.core.series.Series.reset_index" correct. :)

pep8speaks · 2018-03-10T11:11:49Z

Hello @ludusrusso! Thanks for updating the PR.

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

Comment last updated on March 15, 2018 at 20:46 Hours UTC

jorisvandenbossche

Thanks for the PR! Added some comments

Can you add an examples with drop=True as well?

jorisvandenbossche · 2018-03-10T11:41:56Z

pandas/core/series.py

@@ -1002,24 +1002,33 @@ def _set_value(self, label, value, takeable=False):

    def reset_index(self, level=None, drop=False, name=None, inplace=False):
        """
-        Analogous to the :meth:`pandas.DataFrame.reset_index` function, see
-        docstring there.
+        Reset the index of the Serie.


General comment: Serie -> Series (the singular of Series is still Series :))

Solved tnx!

Did you already push? Because this one is not yet fixed

Sorry, I missed it!

jorisvandenbossche · 2018-03-10T11:42:37Z

pandas/core/series.py


        Parameters
        ----------
-        level : int, str, tuple, or list, default None
+        level : `int`, `str`, `tuple`, or `list`, default `None`


Those quotes in the type description is not needed

jorisvandenbossche · 2018-03-10T11:43:52Z

pandas/core/series.py

-        docstring there.
+        Reset the index of the Serie.
+
+        For a Serie with multi-level index, return a new Serie with labeling 


I would start the explanation with the standard case of normal index

jorisvandenbossche · 2018-03-10T11:44:15Z

pandas/core/series.py

+
+        See Also
+        --------
+        :meth:`pandas.DataFrame.reset_index`: Analogous funciton for DataFrame


funciton -> function

:meth:`pandas.DataFrame.reset_index` -> DataFrame.reset_index (without any mark-up)

DataFrame.reset_index I've removed the mark-up, but are you sure about that? It should be nice tu have a link the the related method.

jreback · 2018-03-10T13:38:20Z

pandas/core/series.py

-        docstring there.
+        Reset the index of the Serie.
+
+        For a standard index, the index name will be used (if set), 


just say Index

jreback · 2018-03-10T13:38:26Z

pandas/core/series.py

+        For a standard index, the index name will be used (if set), 
+        otherwise a default index or `level_0` (if `index` is already taken) 
+        will be used.
+        For a Series with multi-level index, return a new Series with labeling


say MultiIndex

jreback · 2018-03-10T13:38:47Z

pandas/core/series.py

-        inplace : boolean, default False
-            Modify the Series in place (do not create a new object)
+            default.
+        drop : `boolean`, default `False`


boolean -> bool

jreback · 2018-03-10T13:39:51Z

pandas/core/series.py

+        >>> s.reset_index(drop=True)
+        0    1
+        1    2
+        2    3


can you add an example with name

Done, for name and for inplace

villasv · 2018-03-10T13:47:03Z

pandas/core/series.py


        Returns
        ----------
-        resetted : DataFrame, or Series if drop == True
+        resetted : `DataFrame`, or Series if `drop == True`


Resetted should probably just "reset"

ludusrusso · 2018-03-10T15:23:20Z

Update pull request after review! Tnx!

jreback · 2018-03-10T15:24:04Z

pandas/core/series.py

+        Reset the index of the Serie.
+
+        For an Index, the index name will be used (if set), 
+        otherwise a default index or `level_0` (if `index` is already taken) 


the default IS 'index', can you make this a bit more clear

jreback · 2018-03-10T15:24:42Z

pandas/core/series.py


        Returns
        ----------
-        resetted : DataFrame, or Series if drop == True
+        reset : `DataFrame`, or Series if `drop == True`


I don't recall whether we are single ticking Series, DataFrame in doc-strings. @datapythonista @jorisvandenbossche

decision was to not use ticks in this case

ok @ludusrusso can you update

jreback · 2018-03-10T15:24:59Z

pandas/core/series.py

+
+        >>> s = pd.Series([1, 2, 3, 4], index=pd.Index(['a', 'b', 'c', 'd'],
+        ...                                            name = 'idx'))
+        >>> s.reset_index(name = 'new_idx')


no spaces around the equals

jorisvandenbossche · 2018-03-10T15:28:29Z

pandas/core/series.py

+            Do not try to insert index into dataframe columns.
+        name : `object`, default `None`
+            The name of the column corresponding to the Series values.
+        inplace : `bool`, default `False`


Can you also remove the backticks here? In general: no backticks in the type descriptions

jorisvandenbossche · 2018-03-10T15:29:17Z

pandas/core/series.py

+        2   c        3
+        3   d        4
+
+        >>> s = pd.Series([1, 2, 3, 4], index=pd.Index(['a', 'b', 'c', 'd'],


you don't need to re-define the series, you can reuse from the previous code block

Can you also put some explanation sentence between the examples?

ludusrusso · 2018-03-10T16:23:36Z

Thanks you all! I've updated the examples with comments!

jreback · 2018-03-10T16:55:50Z

pandas/core/series.py

@@ -1002,36 +1002,86 @@ def _set_value(self, label, value, takeable=False):

    def reset_index(self, level=None, drop=False, name=None, inplace=False):
        """
-        Analogous to the :meth:`pandas.DataFrame.reset_index` function, see
-        docstring there.
+        Reset the index of the Series.


so this is not correct, .reset_index(drop=False) (the default) on a Series will return a DataFrame. The columns will be the name of the Series and a new column of the index, with its name being the name of the column or 'index' if its not named.

jreback · 2018-03-10T16:56:42Z

pandas/core/series.py

+        For an Index, the index name will be used (if set), 
+        otherwise a default index or level_0 (if index is already taken) 
+        will be used.
+        For a MultiIndex, return a new Series with labeling


you will get a multi-column DataFrame, with each level being turned into a column, here the levels will be named level_n if the name is None.

jreback · 2018-03-10T16:56:54Z

pandas/core/series.py


        Returns
        ----------
-        resetted : DataFrame, or Series if drop == True
+        reset : DataFrame, or Series if `drop == True`


no back ticks

jreback · 2018-03-10T16:57:12Z

pandas/core/series.py


        Examples
        --------
+
+        Generate a pandas.Series with a given Index.


this comment is a bit odd here

jreback · 2018-03-10T16:57:25Z

pandas/core/series.py

        >>> s = pd.Series([1, 2, 3, 4], index=pd.Index(['a', 'b', 'c', 'd'],
        ...                                            name = 'idx'))
+
+        To generate a pandas.DataFrame with resetted index, 


resetted -> default index

jreback · 2018-03-10T16:57:38Z

pandas/core/series.py

+        2   c       3
+        3   d       4
+
+        To generate a new pandas.Series with the resetted


resetted -> default index

jorisvandenbossche · 2018-03-11T12:42:44Z

@ludusrusso did you run the validation script again after updating?

datapythonista

Looks good in general, but still needs some work.

datapythonista · 2018-03-11T12:55:49Z

pandas/core/series.py

-        docstring there.
+        Generate a new DataFrame with columns containing the data and 
+        the index of the original Series, or, if drop is True, 
+        a Series with numeric index.


Short summary must fit in one line.

It's hard to summarize it! I'll try!

datapythonista · 2018-03-11T12:57:36Z

pandas/core/series.py


        Returns
        ----------
-        resetted : DataFrame, or Series if drop == True
+        reset : DataFrame, or Series if drop == True


Check the first example here to see how the output of Returns is: https://python-sprints.github.io/pandas/guide/pandas_docstring.html#section-4-returns-or-yields

Also, not your change, but the hyphens under return are too long.

datapythonista · 2018-03-11T12:58:37Z

pandas/core/series.py

        >>> s.reset_index()
          idx  0
        0   a  1
        1   b  2
        2   c  3
        3   d  4

+        To specify the name of the column corrisponding


corrIsponding.

datapythonista · 2018-03-11T12:59:46Z

pandas/core/series.py


        Examples
        --------
+
+        Generate a pandas.Series.
+
        >>> s = pd.Series([1, 2, 3, 4], index=pd.Index(['a', 'b', 'c', 'd'],
        ...                                            name = 'idx'))


spaces around = don't follow PEP-8.

datapythonista · 2018-03-11T13:02:31Z

pandas/core/series.py

+        dtype: int64
+
+        Generate a MultiIndex Series.
+
        >>> arrays = [np.array(['bar', 'bar', 'baz', 'baz', 'foo',
        ...                     'foo', 'qux', 'qux']),
        ...           np.array(['one', 'two', 'one', 'two', 'one', 'two',


If I'm not wrong, just 4 rows should be enough to illustrate the example. That would make it more compact, and easier to understand for the user.

You're right, that was an existing example!

jreback · 2018-03-11T13:03:08Z

pandas/core/series.py

@@ -1002,36 +1002,88 @@ def _set_value(self, label, value, takeable=False):

    def reset_index(self, level=None, drop=False, name=None, inplace=False):
        """
-        Analogous to the :meth:`pandas.DataFrame.reset_index` function, see
-        docstring there.
+        Generate a new DataFrame with columns containing the data and 


this needs to be a single line.

jreback · 2018-03-11T13:03:26Z

pandas/core/series.py

+        the index of the original Series, or, if drop is True, 
+        a Series with numeric index.
+
+        For an Index Series, the results is a two-column DataFrame with 


Index Series doesn't make sense, more like: For a Series with a single level index (Index)

jreback · 2018-03-11T13:03:55Z

pandas/core/series.py

+
+        For an Index Series, the results is a two-column DataFrame with 
+        index tourned in column.
+        For a MultiIndex Series, the results is a multi-column 


for a Series with a multi-level index (MultiIndex)

jreback · 2018-03-11T13:04:20Z

pandas/core/series.py

+
+        See Also
+        --------
+        pandas.DataFrame.reset_index: Analogous function for DataFrame


link to pandas.Series.set_index as well

Series does not have a method set_index(), did you mean DataFrame.set_index()?

s.set_index() Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/Users/ludus/develop/pandas-meetup/pandas/pandas/core/generic.py", line 4046, in __getattr__ return object.__getattribute__(self, name) AttributeError: 'Series' object has no attribute 'set_index'

jreback · 2018-03-11T13:04:43Z

pandas/core/series.py

        >>> s = pd.Series([1, 2, 3, 4], index=pd.Index(['a', 'b', 'c', 'd'],
        ...                                            name = 'idx'))
+
+        To generate a pandas.DataFrame with default index, 
+        call the reset_index() method.


you don't need to say 'call the reset_index() method'

jreback · 2018-03-11T13:04:49Z

pandas/core/series.py

        >>> s.reset_index()
          idx  0
        0   a  1
        1   b  2
        2   c  3
        3   d  4

+        To specify the name of the column corrisponding


jreback · 2018-03-11T13:05:00Z

pandas/core/series.py

+        2   c       3
+        3   d       4
+
+        To generate a new pandas.Series with the default


can just say Series

codecov · 2018-03-11T16:34:15Z

Codecov Report

Merging #20107 into master will increase coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20107      +/-   ##
==========================================
+ Coverage   91.72%   91.72%   +<.01%     
==========================================
  Files         150      150              
  Lines       49149    49159      +10     
==========================================
+ Hits        45083    45093      +10     
  Misses       4066     4066

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

Impacted Files	Coverage Δ
pandas/core/series.py	`93.85% <ø> (-0.01%)`	⬇️
pandas/core/base.py	`96.78% <0%> (-0.02%)`	⬇️
pandas/core/indexes/datetimes.py	`95.64% <0%> (-0.01%)`	⬇️
pandas/core/indexes/base.py	`96.66% <0%> (-0.01%)`	⬇️
pandas/core/strings.py	`98.32% <0%> (ø)`	⬆️
pandas/core/indexing.py	`93.02% <0%> (ø)`	⬆️
pandas/core/indexes/timedeltas.py	`91.03% <0%> (ø)`	⬆️
pandas/core/indexes/multi.py	`95.06% <0%> (ø)`	⬆️
pandas/core/generic.py	`95.84% <0%> (ø)`	⬆️
... and 7 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 4131149...8b0cefd. Read the comment docs.

ludusrusso · 2018-03-11T16:34:34Z

@jorisvandenbossche you're right.. I've checked it this time!

[ci skip]

jorisvandenbossche · 2018-03-15T22:03:21Z

Very nice docstring, thanks @ludusrusso !

DOC: update the Series.reset_index DocString

0d97714

solved pep issues

291b5c0

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

ludusrusso added 3 commits March 10, 2018 13:31

fix typos and unnecessary quotes

a45970e

add examples for drop=True

4e70101

up description

8f3ddb4

jreback added Docs Reshaping Concat, Merge/Join, Stack/Unstack, Explode labels Mar 10, 2018

jreback requested changes Mar 10, 2018

View reviewed changes

jreback reviewed Mar 10, 2018

View reviewed changes

villasv reviewed Mar 10, 2018

View reviewed changes

add more examples and fix some typos in description

25d706a

jreback requested changes Mar 10, 2018

View reviewed changes

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

ludusrusso added 2 commits March 10, 2018 17:20

add comments to examples, improved docs

a9a69d0

fix typo

28974ac

jreback requested changes Mar 10, 2018

View reviewed changes

up descirption

1af336d

datapythonista reviewed Mar 11, 2018

View reviewed changes

jreback requested changes Mar 11, 2018

View reviewed changes

update docs according to reviews

9a27e63

TomAugspurger added 2 commits March 15, 2018 15:43

Updates [ci skip]

0604a3c

[ci skip]

Whitespace [ci skip]

8b0cefd

[ci skip]

TomAugspurger approved these changes Mar 15, 2018

View reviewed changes

jorisvandenbossche approved these changes Mar 15, 2018

View reviewed changes

jorisvandenbossche merged commit 6a2ece9 into pandas-dev:master Mar 15, 2018

jorisvandenbossche added this to the 0.23.0 milestone Mar 15, 2018

Uh oh!

DOC: update the Series.reset_index DocString #20107

DOC: update the Series.reset_index DocString #20107

Uh oh!

Conversation

ludusrusso commented Mar 10, 2018

Uh oh!

pep8speaks commented Mar 10, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comment last updated on March 15, 2018 at 20:46 Hours UTC

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ludusrusso commented Mar 10, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ludusrusso commented Mar 10, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pep8speaks commented Mar 10, 2018 •

edited

Loading