Skip to content

DOC: Updating pandas.Interval docstring #20057

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Mar 14, 2018
Merged

DOC: Updating pandas.Interval docstring #20057

Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
eb8ce9f
Added type to the parameter and extend the examples
akielbowicz Mar 8, 2018
e8cbf0b
Merge remote-tracking branch 'upstream/master' into DOC_improve_Inter…
akielbowicz Mar 10, 2018
080654d
Changed referece to parameters with sigle backticks
akielbowicz Mar 10, 2018
f302acc
Merge remote-tracking branch 'upstream/master' into DOC_improve_Inter…
akielbowicz Mar 10, 2018
713d975
Improved the examples and replaced * to backticks
akielbowicz Mar 10, 2018
a0db247
Merge remote-tracking branch 'upstream/master' into DOC_improve_Inter…
akielbowicz Mar 10, 2018
7db6817
Update notes
akielbowicz Mar 10, 2018
5a6727a
Merge remote-tracking branch 'upstream/master' into DOC_improve_Inter…
akielbowicz Mar 10, 2018
c1d7265
Added Period to See Also
akielbowicz Mar 10, 2018
45f7f3b
Merge remote-tracking branch 'upstream/master' into DOC_improve_Inter…
akielbowicz Mar 11, 2018
4682386
Update interval.pyx
jorisvandenbossche Mar 14, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 26 additions & 7 deletions pandas/_libs/interval.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,26 +81,45 @@ cdef class Interval(IntervalMixin):

Parameters
----------
left : value
Left bound for the interval
right : value
Right bound for the interval
left : orderable object
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe 'scalar' instead of object? To make clear an array-like is not accepted?

Left bound for the interval.
right : orderable object
Right bound for the interval.
closed : {'left', 'right', 'both', 'neither'}, default 'right'
Whether the interval is closed on the left-side, right-side, both or
neither
neither.

Notes
-----
You must be able to compare the parameters **left** and **right**,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you use single backticks to refer to the keywords? (like `left`), and double backticks for the code snippet on the line below ?

and they must satisfy **left <= right**.

Examples
--------
The examples below show how you can build Intervals of various types
of elements. In particular a numeric interval, a time interval and
finally a string interval. Given an Interval you can check whether
an element belongs to it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general, I think it can be easier to follow to put some of those explanations between the examples, instead of first all explanation and then all examples.


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

>>> shifted_iv = iv + 3
>>> shifted_iv
Interval(3, 8, closed='right')

>>> 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
>>> year_2017.length
Timedelta('364 days 00:00:00')
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be nice to change year_2017 to

year_2017 = pd.Interval(pd.Timestamp('2017-01-01'),
                        pd.Timestamp('2018-01-01'), closed='left')

That seems like a more accurate representation of a year, since the current version doesn't include anything beyond 2017-12-31 00:00:00, e.g. 2017-12-31 12:00:00 isn't included in year_2017 as currently written. This change would also result in year_2017.length being 365 days, which should be more intuitive for users.


>>> volume_1 = pd.Interval('Ant','Dog',closed='both')
>>> 'Bee' in volume_1
True

See Also
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you add Period here as well (its pretty much a time based interval)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To add a couple of points here: Interval is basically a more generic Period, in that Period requires a frequency and Interval does not. The trade-off being that Period has additional frequency specific functionality that Interval does not.

--------
Expand Down Expand Up @@ -283,4 +302,4 @@ cpdef intervals_to_interval_bounds(ndarray intervals):

return left, right, closed

include "intervaltree.pxi"
include "intervaltree.pxi"