DOC:Improve the docstring of DataFrame.iloc() #20228

tuhinmahmud · 2018-03-10T20:02:25Z

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

[X ] PR title is "DOC: update the docstring"
[ X] The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
[ X] The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
[ X] The html version looks good: python doc/make.py --single <your-function-or-method>
[X ] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

(pandas_dev) tuhins-mbp:pandas [email protected]$ python scripts/validate_docstrings.py pandas.DataFrame.iloc

################################################################################
###################### Docstring (pandas.DataFrame.iloc)  ######################
################################################################################

Purely integer-location based indexing for selection by position.

``.iloc[]`` is primarily integer position based (from ``0`` to
``length-1`` of the axis), but may also be used with a boolean
array.

Allowed inputs are:

- An integer, e.g. ``5``.
- A list or array of integers, e.g. ``[4, 3, 0]``.
- A slice object with ints, e.g. ``1:7``.
- A boolean array.
- A ``callable`` function with one argument (the calling Series, DataFrame
  or Panel) and that returns valid output for indexing (one of the above)

``.iloc`` will raise ``IndexError`` if a requested indexer is
out-of-bounds, except *slice* indexers which allow out-of-bounds
indexing (this conforms with python/numpy *slice* semantics).

See Also
--------
DataFrame.ix : A primarily label-location based indexer, with integer position fallback.
DataFrame.loc : Fast integer location scalar accessor.

Examples
--------
>>> import pandas as pd
>>> mydict = [{'a': 1, 'b': 2, 'c': 3, 'd': 4},
...           {'a': 100,  'b': 200, 'c': 300, 'd': 400},
...           {'a': 1000,  'b': 2000,  'c': 3000,  'd': 4000 }]
>>> df = pd.DataFrame(mydict)
>>> print(df.head())
      a     b     c     d
0     1     2     3     4
1   100   200   300   400
2  1000  2000  3000  4000
>>> print(df.iloc[0])
a    1
b    2
c    3
d    4
Name: 0, dtype: int64
>>> print(df.iloc[0:2])
     a    b    c    d
0        1    2    3    4
1  100  200  300  400

ref:`Selection by Position <indexing.integer>`

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

Errors found:
	No returns section found

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.

Error Returned because Class do not need return

pep8speaks · 2018-03-10T20:02:27Z

Hello @tuhinmahmud! Thanks for updating the PR.

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

Comment last updated on July 07, 2018 at 19:10 Hours UTC

…3_2018

TomAugspurger · 2018-03-10T20:08:49Z

pandas/core/indexing.py

+    0        1    2    3    4
+    1  100  200  300  400
+
+    ref:`Selection by Position <indexing.integer>`


Could you use the "extended summary" section for this, right below the opening summary? I think the prose docs are the most important for indexing, and I don't want them to get lost.

moved it to "extended summary"

TomAugspurger · 2018-03-10T20:09:17Z

pandas/core/indexing.py

-    See more at :ref:`Selection by Position <indexing.integer>`
+    See Also
+    --------
+    DataFrame.ix : A primarily label-location based indexer


ix is deprecated, you can remove.

TomAugspurger · 2018-03-10T20:10:04Z

pandas/core/indexing.py

+    See Also
+    --------
+    DataFrame.ix : A primarily label-location based indexer
+    DataFrame.loc : Fast integer location scalar accessor.


I think you may want the " A primarily label-location based indexer" for the .loc description.

You may be thinking of DataFrame.iat for this dsecription.

Remove ix and update loc description:

DataFrame.ix : A primarily label-location based indexer

DataFrame.loc : Fast integer location scalar accessor.

DataFrame.iat : Fast integer location scalar accessor.

DataFrame.loc : Purely label-location based indexer for selection by label.

missed your comment about .loc .. but instead got the description from https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.loc.html

TomAugspurger · 2018-03-10T20:10:13Z

pandas/core/indexing.py

+    --------
+    >>> import pandas as pd
+    >>> mydict = [{'a': 1, 'b': 2, 'c': 3, 'd': 4},
+    ...           {'a': 100,  'b': 200, 'c': 300, 'd': 400},


PEP8: single spaces.

updated the double spaces with single

TomAugspurger · 2018-03-10T20:10:39Z

pandas/core/indexing.py

+    Name: 0, dtype: int64
+    >>> print(df.iloc[0:2])
+         a    b    c    d
+    0        1    2    3    4


formatting seems a bit off. Can you double check this?

reran the command and updated.

jreback · 2018-03-10T21:06:27Z

pandas/core/indexing.py

+    c    3
+    d    4
+    Name: 0, dtype: int64
+    >>> print(df.iloc[0:2])


don't need the prints here and above

took off the prints

tuhinmahmud

ok

tuhinmahmud · 2018-03-10T21:53:41Z

pandas/core/indexing.py

+    0        1    2    3    4
+    1  100  200  300  400
+
+    ref:`Selection by Position <indexing.integer>`


moved it to "extended summary"

jreback · 2018-03-11T14:30:01Z

pandas/core/indexing.py

+    See Also
+    --------
+    DataFrame.iat : Fast integer location scalar accessor.
+    DataFrame.loc : Purely label-location based indexer for selection by label.


add Series.iloc

added Series.iloc

Can you look at other PRs for those accessors to have a consistent way to reference them? See eg https://github.com/pandas-dev/pandas/pull/20229/files, They use:

DateFrame.at : Access a single value for a row/column label pair DateFrame.iloc : Access group of rows and columns by integer position(s) Series.loc : Access group of values using labels

@tuhinmahmud make sure to pull my changes before looking into this.

jreback · 2018-03-11T14:30:09Z

pandas/core/indexing.py


+    Examples
+    --------
+    >>> import pandas as pd


don't need the pandas import

removed pandas import

jreback · 2018-03-11T14:30:24Z

pandas/core/indexing.py

+    --------
+    >>> import pandas as pd
+    >>> mydict = [{'a': 1, 'b': 2, 'c': 3, 'd': 4},
+    ... {'a': 100, 'b': 200, 'c': 300, 'd': 400},


need to indent here

undated the indentation

jreback · 2018-03-11T14:31:36Z

pandas/core/indexing.py

+    0     1     2     3     4
+    1   100   200   300   400
+    2  1000  2000  3000  4000
+    >>> df.iloc[0]


blank lines between cases.

show additional examples, including selecting with .iloc[0] vs .iloc[[0]], and use a multi-axis selction .iloc[0, 0] and lists for the last, e.g. .iloc[[0, 1], [0, 1]]

also add a sentence for each case explaining it.

added sentences and put different types of example of .iloc in paragraph

added 5 types of examples for iloc * Select using integer.r * Select via index slicing. * Select using boolean array. * Select using callable function. * Multi index selection. Updated indentation removed import

TomAugspurger · 2018-03-12T15:17:19Z

@tuhinmahmud pushed an update to your examples to make the ordering a bit more logical. We now show each of the valid indexer values (scalar, sequence, slice, mask, callable) for just indexing the rows. Then we show the same for rows and columns.

TomAugspurger · 2018-03-12T15:18:58Z

tuhinmahmud

made requested changes
i) Remove ix and update loc description
ii) removed pandas import
iii) single space issue

tuhinmahmud

Looks good.. Do you know what is the next step to get it commited?

…ent_sprint_03_2018

codecov · 2018-03-26T13:26:07Z

Codecov Report

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

@@            Coverage Diff            @@
##             master   #20228   +/-   ##
=========================================
  Coverage          ?   91.95%           
=========================================
  Files             ?      160           
  Lines             ?    49837           
  Branches          ?        0           
=========================================
  Hits              ?    45830           
  Misses            ?     4007           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`90.34% <ø> (?)`
#single	`42.08% <ø> (?)`

Impacted Files	Coverage Δ
pandas/core/indexing.py	`93.73% <ø> (ø)`

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 dcbf8b5...329b05b. Read the comment docs.

TomAugspurger · 2018-03-26T13:26:18Z

Merged in master to restart the CI. They were complaining about a non-ASCII character, but that may have been on master when you made the PR, and not in your actual branch.

Ping if you notice that the tests all pass before we do.

tuhinmahmud · 2018-04-03T21:58:10Z

@TomAugspurger Hi .. I am kind of lost as to what I can do to make it work .. I see one of the test continuous-integration/travi-ci/pr failing.. not sure what to make of it

TomAugspurger · 2018-04-03T22:01:04Z

Sometimes travis jobs take much longer than others, and exceed Travis' time limit. I restarted that one.

…3_2018

mroeschke · 2018-07-07T19:12:53Z

Looks like everything was addressed. Will merge on green since it looks like CI caught an issue before.

…3_2018

DOC:Improve the docstring of DataFrame.iloc()

28222cd

TomAugspurger added the Docs label Mar 10, 2018

tuhinmahmud added 2 commits March 10, 2018 14:07

Merge remote-tracking branch 'upstream/master' into document_sprint_0…

e5dc827

…3_2018

DOC:Improve the docstring of DataFrame.iloc()

9b103c1

TomAugspurger requested changes Mar 10, 2018

View reviewed changes

TomAugspurger added the Indexing Related to indexing on series/frames, not to indexes themselves label Mar 10, 2018

jreback requested changes Mar 10, 2018

View reviewed changes

DOC:Improve the docstring of DataFrame.iloc()

76271f6

tuhinmahmud commented Mar 10, 2018

View reviewed changes

DOC:Improve the docstring of DataFrame.iloc()

9cda098

jreback requested changes Mar 11, 2018

View reviewed changes

tuhinmahmud and others added 3 commits March 11, 2018 13:23

DOC:Improve the docstring of DataFrame.iloc()

1ede54b

added 5 types of examples for iloc * Select using integer.r * Select via index slicing. * Select using boolean array. * Select using callable function. * Multi index selection. Updated indentation removed import

Updated examples.

a72f864

Consistency

3d10bd8

Example updates

f553ceb

tuhinmahmud commented Mar 22, 2018

View reviewed changes

Merge remote-tracking branch 'upstream/master' into tuhinmahmud-docum…

100b62e

…ent_sprint_03_2018

Merge remote-tracking branch 'upstream/master' into document_sprint_0…

dfd8be0

…3_2018

mroeschke added this to the 0.24.0 milestone Jul 7, 2018

Merge remote-tracking branch 'upstream/master' into document_sprint_0…

329b05b

…3_2018

jreback merged commit f49355d into pandas-dev:master Jul 7, 2018

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

DOC:Improve the docstring of DataFrame.iloc() (pandas-dev#20228)

e120c09

DOC:Improve the docstring of DataFrame.iloc() #20228

DOC:Improve the docstring of DataFrame.iloc() #20228

Conversation

tuhinmahmud commented Mar 10, 2018 • edited Loading

pep8speaks commented Mar 10, 2018 • edited Loading

Comment last updated on July 07, 2018 at 19:10 Hours UTC

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

Choose a reason for hiding this comment

tuhinmahmud 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TomAugspurger commented Mar 12, 2018

TomAugspurger commented Mar 12, 2018

tuhinmahmud left a comment

Choose a reason for hiding this comment

tuhinmahmud left a comment

Choose a reason for hiding this comment

codecov bot commented Mar 26, 2018 • edited Loading

Codecov Report

TomAugspurger commented Mar 26, 2018

tuhinmahmud commented Apr 3, 2018 • edited Loading

TomAugspurger commented Apr 3, 2018

mroeschke commented Jul 7, 2018 • edited Loading

tuhinmahmud commented Mar 10, 2018 •

edited

Loading

pep8speaks commented Mar 10, 2018 •

edited

Loading

codecov bot commented Mar 26, 2018 •

edited

Loading

tuhinmahmud commented Apr 3, 2018 •

edited

Loading

mroeschke commented Jul 7, 2018 •

edited

Loading