DOC: update the docstrings of Interval and IntervalMixin #20132

akoeltringer · 2018-03-10T13:44:49Z

Improved the docstrings of Interval (the class) and the following methods
of IntervalMixin:

closed_right
closed_left
open_right
open_left

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.Interval)  #########################
################################################################################

Immutable object implementing an Interval, a bounded slice-like interval.

.. versionadded:: 0.20.0

Parameters
----------
left : value
    Left bound for the interval.
right : value
    Right bound for the interval.
closed : {'right', 'left', 'both', 'neither'}, default 'right'
    Whether the interval is closed on the left-side, right-side, both or
    neither.
    A closed interval (in mathematics denoted by square brackets)
    contains the edge points, i.e. the closed interval `[1, 5]` consists
    of the points `1, 2, 3, 4, 5`.
    An open interval (in mathematics denoted by parentheses) does not
    contain the edge points, i.e. the open interval `(1, 5)` consists of
    the points 2, 3, 4.
    Intervals can also be half-open or half closed, i.e.
    `[1,5) = 1, 2, 3, 4` and `(1, 5] = 2, 3, 4, 5`. See also the examples
    section below.

Examples
--------
>>> iv = pd.Interval(left=0, right=5)
>>> iv
Interval(0, 5, closed='right')
>>> 2.5 in iv
True
>>> 0 in iv
False
>>> 5 in iv
True

>>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'),
...                         pd.Timestamp('2017-12-31'), closed='both')
>>> pd.Timestamp('2017-01-01 00:00') in year_2017
True

See Also
--------
IntervalIndex : An Index of Interval objects that are all closed on the
                same side.
cut : Convert arrays of continuous data into bins of Series/Categoricals
      of Interval.
qcut : Convert arrays of continuous data into bins of Series/Categoricals
       of Interval based on quantiles.

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

Errors found:
        Errors in parameters section
                Unknown parameters {'left', 'right', 'closed'}
        No returns section found
(venv) [akoeltringer@client7 pandas]$ python scripts/validate_docstrings.py pandas.Interval.closed_left

################################################################################
################### Docstring (pandas.Interval.closed_left)  ###################
################################################################################

Check if the interval is closed on the left side.

For the meaning of `closed` and `open` see :class:`~pandas.Interval`.

Returns
-------
bool
    `True` if the Interval is closed on the left-side, else `False`.

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

Errors found:
        See Also section not found
        No examples section found
(venv) [akoeltringer@client7 pandas]$ python scripts/validate_docstrings.py pandas.Interval.closed_right

################################################################################
################### Docstring (pandas.Interval.closed_right) ###################
################################################################################

Check if the interval is closed on the right side.

For the meaning of `closed` and `open` see :class:`~pandas.Interval`.

Returns
-------
bool
    `True` if the Interval is closed on the right-side, else `False`.

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

Errors found:
        See Also section not found
        No examples section found
(venv) [akoeltringer@client7 pandas]$ python scripts/validate_docstrings.py pandas.Interval.open_left

################################################################################
#################### Docstring (pandas.Interval.open_left)  ####################
################################################################################

Check if the interval is open on the left side.

For the meaning of `closed` and `open` see :class:`~pandas.Interval`.

Returns
-------
bool
    `True` if the Interval is open on the left-side, else `False`.

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

Errors found:
        See Also section not found
        No examples section found
(venv) [akoeltringer@client7 pandas]$ python scripts/validate_docstrings.py pandas.Interval.open_right

################################################################################
#################### Docstring (pandas.Interval.open_right) ####################
################################################################################

Check if the interval is open on the right side.

For the meaning of `closed` and `open` see :class:`~pandas.Interval`.

Returns
-------
bool
    `True` if the Interval is open on the right-side, else `False`.

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

Errors found:
        See Also section not found
        No examples 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.

It is not clear why the error for pandas.Interval (Unknown parameters {'left', 'right', 'closed'}) arises - respondents to this question on Gitter were not sure either
the closed_right, closed_left, open_right and open_left methods have no 'examples' and no 'see also' section because for that the reader is referred to the Interval class.

Improved the docstrings of Interval (the class) and the following methods of IntervalMixin: * closed_right * closed_left * open_right * open_left

jorisvandenbossche · 2018-03-10T14:09:03Z

Damn, from my phone now, but there is already another open PR. Can you search for that?

jorisvandenbossche · 2018-03-10T14:53:28Z

So back on laptop now: it is #20057. Luckily it is not fully overlapping as you also have the attributes.
Would you like to give feedback on the other PR regarding Interval itself? And then we keep this PR for the attributes.

Sorry for the overlap! (when assigning I think we forgot the PRs that were already opened by the organisers)

cmdelatorre

I agree on the comments and I think this PR is OK.

akoeltringer · 2018-03-10T15:01:41Z

I was also outside so I could not respond earlier. I have to admit that we (PyData Karlsruhe) went a bit 'out of our bounds' - we had the Interval.open_* and Interval.closed_* assigned but figured it would be better to document the concepts of openness and closedness once... in Interval...

#20057 has the better docs on the left and right parameters, also the examples section seems good.

Its your decision but you could merge #20057, and then I update my PR based on new master...

jschendel

Thanks, looks good! Added a few comments.

jschendel · 2018-03-10T20:12:33Z

pandas/_libs/interval.pyx

+        of the points `1, 2, 3, 4, 5`.
+        An open interval (in mathematics denoted by parentheses) does not
+        contain the edge points, i.e. the open interval `(1, 5)` consists of
+        the points 2, 3, 4.


I understand what's being said here, but I think this could potentially be misinterpreted as the interval being discrete instead of continuous, i.e. only containing the integer points mentioned here, whereas floats such as 1.01 and 4.99 are also included. Might be beneficial to mention that "open" corresponds to a strict inequality (<) at the endpoint and "closed" corresponds to a non-strict inequality (<=).

jschendel · 2018-03-10T20:13:24Z

pandas/_libs/interval.pyx

+        the points 2, 3, 4.
+        Intervals can also be half-open or half closed, i.e.
+        `[1,5) = 1, 2, 3, 4` and `(1, 5] = 2, 3, 4, 5`. See also the examples
+        section below.


For each of the four examples above, it might be nice to explicitly say the corresponding pandas closed value, e.g (1, 5] corresponds to 'right'.

jschendel · 2018-03-10T20:13:37Z

pandas/_libs/interval.pyx

-        neither
+        neither.
+        A closed interval (in mathematics denoted by square brackets)
+        contains the edge points, i.e. the closed interval `[1, 5]` consists


"the edge points" --> "its endpoints"

jschendel · 2018-03-10T20:13:42Z

pandas/_libs/interval.pyx

+        contains the edge points, i.e. the closed interval `[1, 5]` consists
+        of the points `1, 2, 3, 4, 5`.
+        An open interval (in mathematics denoted by parentheses) does not
+        contain the edge points, i.e. the open interval `(1, 5)` consists of


"the edge points" --> "its endpoints"

jschendel · 2018-03-10T20:13:45Z

pandas/_libs/interval.pyx

+        An open interval (in mathematics denoted by parentheses) does not
+        contain the edge points, i.e. the open interval `(1, 5)` consists of
+        the points 2, 3, 4.
+        Intervals can also be half-open or half closed, i.e.


half closed --> half-closed

codecov · 2018-03-10T21:39:38Z

Codecov Report

Merging #20132 into master will decrease coverage by 0.04%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20132      +/-   ##
==========================================
- Coverage   91.77%   91.72%   -0.05%     
==========================================
  Files         152      150       -2     
  Lines       49185    49152      -33     
==========================================
- Hits        45140    45086      -54     
- Misses       4045     4066      +21

Flag	Coverage Δ
#multiple	`90.11% <ø> (-0.05%)`	⬇️
#single	`41.84% <ø> (-0.01%)`	⬇️

Impacted Files	Coverage Δ
pandas/plotting/_compat.py	`62% <0%> (-28.91%)`	⬇️
pandas/core/arrays/base.py	`74.35% <0%> (-2.39%)`	⬇️
pandas/io/html.py	`86.6% <0%> (-2.19%)`	⬇️
pandas/io/formats/format.py	`96.26% <0%> (-1.99%)`	⬇️
pandas/core/reshape/melt.py	`97.19% <0%> (-0.15%)`	⬇️
pandas/compat/__init__.py	`57.62% <0%> (-0.12%)`	⬇️
pandas/plotting/_core.py	`82.23% <0%> (-0.04%)`	⬇️
pandas/core/indexes/datetimelike.py	`96.7% <0%> (-0.02%)`	⬇️
pandas/core/ops.py	`96.33% <0%> (-0.02%)`	⬇️
pandas/core/generic.py	`95.84% <0%> (-0.02%)`	⬇️
... and 20 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 921fefb...1db1fc3. Read the comment docs.

akoeltringer · 2018-03-10T21:43:22Z

@jschendel Yes you are right. Added a commit.

jschendel · 2018-03-14T00:26:47Z

lgtm

ping @jorisvandenbossche @jreback

jreback

lgtm

…interval_doc_improvement

jorisvandenbossche

Fixed the conflict after merging #20057 and did some minor formatting edits.
Looking good!

jorisvandenbossche · 2018-03-14T14:21:37Z

@akoeltringer Thanks for the PR!

akoeltringer · 2018-03-14T14:41:20Z

@jorisvandenbossche thx to you for going the extra mile (merging the conflicting PR)!

DOC: improved the docstrings of Interval and IntervalMixin

8300b90

Improved the docstrings of Interval (the class) and the following methods of IntervalMixin: * closed_right * closed_left * open_right * open_left

cmdelatorre approved these changes Mar 10, 2018

View reviewed changes

jreback added Docs Interval Interval data type labels Mar 10, 2018

jreback added this to the 0.23.0 milestone Mar 10, 2018

jreback approved these changes Mar 10, 2018

View reviewed changes

jschendel reviewed Mar 10, 2018

View reviewed changes

DOC: reflect also the continuous nature of pandas.Interval

88977c8

jreback approved these changes Mar 14, 2018

View reviewed changes

jorisvandenbossche added 2 commits March 14, 2018 15:12

Merge remote-tracking branch 'upstream/master' into akoeltringer-doc_…

2291f74

…interval_doc_improvement

minor formatting

1db1fc3

jorisvandenbossche approved these changes Mar 14, 2018

View reviewed changes

jorisvandenbossche merged commit 0ba1fae into pandas-dev:master Mar 14, 2018

Uh oh!

DOC: update the docstrings of Interval and IntervalMixin #20132

DOC: update the docstrings of Interval and IntervalMixin #20132

Uh oh!

Conversation

akoeltringer commented Mar 10, 2018

Uh oh!

jorisvandenbossche commented Mar 10, 2018

Uh oh!

jorisvandenbossche commented Mar 10, 2018

Uh oh!

cmdelatorre left a comment

Choose a reason for hiding this comment

Uh oh!

akoeltringer commented Mar 10, 2018

Uh oh!

jschendel left a comment

Choose a reason for hiding this comment

Uh oh!

jschendel Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

jschendel Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

jschendel Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

jschendel Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

jschendel Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

akoeltringer commented Mar 10, 2018

Uh oh!

jschendel commented Mar 14, 2018

Uh oh!

jreback left a comment

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche commented Mar 14, 2018

Uh oh!

akoeltringer commented Mar 14, 2018

Uh oh!

Uh oh!

codecov bot commented Mar 10, 2018 •

edited

Loading