DOC: Improved the docstring of pandas.Series.truncate #20125

simobasso · 2018-03-10T13:24:58Z

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:


################################################################################
###################### Docstring (pandas.Series.truncate) ######################
################################################################################

Truncate a DataFrame/Series before/after some index value.

If the axis contains only datetime values,
before/after parameters are converted to datetime values.

Parameters
----------
before : date, string, int
    Truncate all rows before this index value.
after : date, string, int
    Truncate all rows after this index value.
axis : {0 or 'index', 1 or 'columns'}
    Default is stat axis for given data type (0 for Series and
    DataFrames, 1 for Panels).
copy : boolean, default is True,
    Return a copy of the truncated section.

Returns
-------
truncated : type of caller

See Also
--------
DataFrame.truncate : Truncate a DataFrame before/after some index value.
Series.truncate : Truncate a Series before/after some index value.

Examples
--------
>>> df = pd.DataFrame({'A': ['a', 'b', 'c', 'd', 'e'],
...                    'B': ['f', 'g', 'h', 'i', 'j'],
...                    'C': ['k', 'l', 'm', 'n', 'o']},
...                    index=[1, 2, 3, 4, 5])
>>> df.truncate(before=2, after=4)
   A  B  C
2  b  g  l
3  c  h  m
4  d  i  n
>>> df = pd.DataFrame({'A': [1, 2, 3, 4, 5],
...                    'B': [6, 7, 8, 9, 10],
...                    'C': [11, 12, 13, 14, 15]},
...                    index=['a', 'b', 'c', 'd', 'e'])
>>> df.truncate(before='b', after='d')
   A  B   C
b  2  7  12
c  3  8  13
d  4  9  14

The index values in ``truncate`` can be datetimes or string
dates. Note that ``truncate`` assumes a 0 value for any unspecified
date component in a ``DatetimeIndex`` in contrast to slicing which
returns any partially matching dates.

>>> dates = pd.date_range('2016-01-01', '2016-02-01', freq='s')
>>> df = pd.DataFrame(index=dates, data={'A': 1})
>>> df.truncate('2016-01-05', '2016-01-10').tail()
                     A
2016-01-09 23:59:56  1
2016-01-09 23:59:57  1
2016-01-09 23:59:58  1
2016-01-09 23:59:59  1
2016-01-10 00:00:00  1
>>> df.loc['2016-01-05':'2016-01-10', :].tail()
                     A
2016-01-10 23:59:55  1
2016-01-10 23:59:56  1
2016-01-10 23:59:57  1
2016-01-10 23:59:58  1
2016-01-10 23:59:59  1

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

Docstring for "pandas.Series.truncate" correct. :)

pep8speaks · 2018-03-10T13:25:01Z

Hello @simobasso! Thanks for updating the PR.

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

Comment last updated on March 15, 2018 at 21:27 Hours UTC

arnau126 · 2018-03-10T14:23:11Z

pandas/core/generic.py

        copy : boolean, default is True,
-            return a copy of the truncated section
+            Return a copy of the truncated section.

        Returns
        -------
        truncated : type of caller


If function returns a single value, name is no necessary.

It should be, for example:

Returns ------- type of caller The truncated DataFrame/Series.

arnau126 · 2018-03-10T14:26:59Z

pandas/core/generic.py

+        See Also
+        --------
+        DataFrame.truncate :
+            Truncate a DataFrame before/after some index value.


Description must start in the same line:

DataFrame.truncate : Truncate a DataFrame before/after some index value.

If more than 80 chars:

DataFrame.truncate : Truncate a DataFrame before/after some index value.

simobasso · 2018-03-10T14:55:35Z

@arnau126 thanks for review!

jreback · 2018-03-10T15:37:34Z

pandas/core/generic.py

            Default is stat axis for given data type (0 for Series and
-            DataFrames, 1 for Panels)


you can remove the default for Panel

done thanks!

jreback · 2018-03-10T17:06:25Z

pandas/core/generic.py

+
+        See Also
+        --------
+        DataFrame.truncate : Truncate a DataFrame before/after some index


we don't have these defined in Series/DataFrame, so not sure these can be here @jorisvandenbossche

Yes, since the docstring is shared for both Series and DataFrame, those "see also" are referring to themselves. So indeed not needed in this case (and you ignore the error in the validation script about missing "See Also")

jorisvandenbossche · 2018-03-15T14:13:34Z

pandas/core/generic.py

        axis : {0 or 'index', 1 or 'columns'}
-
-            * 0 or 'index': apply truncation to rows
-            * 1 or 'columns': apply truncation to columns


I think this list was still informative? So I would keep it.

jorisvandenbossche · 2018-03-15T14:15:25Z

pandas/core/generic.py

+
+        See Also
+        --------
+        DataFrame.truncate : Truncate a DataFrame before/after some index


Yes, since the docstring is shared for both Series and DataFrame, those "see also" are referring to themselves. So indeed not needed in this case (and you ignore the error in the validation script about missing "See Also")

* reword summaries * standard `axis` * show df * added series * reword datetime coercion [ci skip]

codecov · 2018-03-15T21:27:15Z

Codecov Report

❗ No coverage uploaded for pull request base (master@ec631ce). Click here to learn what that means.
The diff coverage is 100%.

@@            Coverage Diff            @@
##             master   #20125   +/-   ##
=========================================
  Coverage          ?   91.72%           
=========================================
  Files             ?      150           
  Lines             ?    49152           
  Branches          ?        0           
=========================================
  Hits              ?    45086           
  Misses            ?     4066           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`90.11% <100%> (?)`
#single	`41.84% <0%> (?)`

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

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 ec631ce...1058dae. Read the comment docs.

TomAugspurger

Updated.

I think the original doc for axis was wrong. rows is always truncated by default (which makes more sense to me). See the examples.

jorisvandenbossche · 2018-03-15T21:57:34Z

@simobasso Thanks for the PR!

simobasso force-pushed the doc_generic_truncate branch from 37bf639 to 2763ae4 Compare March 10, 2018 13:46

arnau126 reviewed Mar 10, 2018

View reviewed changes

simobasso force-pushed the doc_generic_truncate branch from 2763ae4 to 5471ca3 Compare March 10, 2018 14:55

jreback requested changes Mar 10, 2018

View reviewed changes

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

DOC: Improved the docstring of pandas.Series.truncate

f68b9af

simobasso force-pushed the doc_generic_truncate branch from 5471ca3 to f68b9af Compare March 10, 2018 16:15

jreback requested changes Mar 10, 2018

View reviewed changes

jorisvandenbossche reviewed Mar 15, 2018

View reviewed changes

Updated [ci skip]

1058dae

* reword summaries * standard `axis` * show df * added series * reword datetime coercion [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 b97a5ad into pandas-dev:master Mar 15, 2018

jorisvandenbossche added this to the 0.23.0 milestone Mar 15, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Improved the docstring of pandas.Series.truncate #20125

DOC: Improved the docstring of pandas.Series.truncate #20125

simobasso commented Mar 10, 2018

pep8speaks commented Mar 10, 2018 •

edited

Loading

arnau126 Mar 10, 2018

arnau126 Mar 10, 2018 •

edited

Loading

arnau126 Mar 10, 2018

arnau126 Mar 10, 2018

simobasso commented Mar 10, 2018

jreback Mar 10, 2018

simobasso Mar 10, 2018

jreback Mar 10, 2018

jorisvandenbossche Mar 15, 2018

jorisvandenbossche Mar 15, 2018

jorisvandenbossche Mar 15, 2018

codecov bot commented Mar 15, 2018

TomAugspurger left a comment

jorisvandenbossche commented Mar 15, 2018

		Default is stat axis for given data type (0 for Series and
		DataFrames, 1 for Panels)

DOC: Improved the docstring of pandas.Series.truncate #20125

DOC: Improved the docstring of pandas.Series.truncate #20125

Conversation

simobasso commented Mar 10, 2018

pep8speaks commented Mar 10, 2018 • edited Loading

Comment last updated on March 15, 2018 at 21:27 Hours UTC

Choose a reason for hiding this comment

arnau126 Mar 10, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

simobasso 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

codecov bot commented Mar 15, 2018

Codecov Report

TomAugspurger left a comment

Choose a reason for hiding this comment

jorisvandenbossche commented Mar 15, 2018

pep8speaks commented Mar 10, 2018 •

edited

Loading

arnau126 Mar 10, 2018 •

edited

Loading