Skip to content

DOC: update the IntervalIndex.from_array docstring #20224

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 10 commits into from
Mar 13, 2018
Merged

DOC: update the IntervalIndex.from_array docstring #20224

Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
b3bb7f5
update pandas.IntervalIndex docstring
verakai Mar 10, 2018
a1d6e46
Merge remote-tracking branch 'upstream/master' into DOC_IntervalIndex…
verakai Mar 10, 2018
7c8dcee
updating IntervalIndex parameters
verakai Mar 10, 2018
fa3f2f5
Merge remote-tracking branch 'upstream/master' into DOC_IntervalIndex…
verakai Mar 10, 2018
9cb8748
Merge remote-tracking branch 'upstream/master' into DOC_IntervalIndex…
verakai Mar 10, 2018
dbac886
updating return, summary, example and some linting
verakai Mar 10, 2018
591c741
Revert class changes
TomAugspurger Mar 13, 2018
982ed02
Updated
TomAugspurger Mar 13, 2018
a971704
Revert changes
TomAugspurger Mar 13, 2018
277a0c5
NA example [ci skip]
TomAugspurger Mar 13, 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
68 changes: 49 additions & 19 deletions pandas/core/indexes/interval.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,20 +142,24 @@ class IntervalIndex(IntervalMixin, Index):

Parameters
----------
data : array-like (1-dimensional)
data : array-Like (1-dimensional)
Copy link
Contributor

Choose a reason for hiding this comment

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

array-like is fine

Copy link
Contributor

Choose a reason for hiding this comment

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

Also could you limit your changes to just the from_array method? Don't want conflicts with others.

Array-like containing Interval objects from which to build the
IntervalIndex
IntervalIndex.
closed : {'left', 'right', 'both', 'neither'}, default 'right'
Whether the intervals are closed on the left-side, right-side, both or
neither.
dtype : dtype or None, default None
If None, dtype will be inferred.
copy : boolean, default False
Copy the meta-data.
name : object, optional
Name to be stored in the index.
copy : boolean, default False
Copy the meta-data
dtype : dtype or None, default None
If None, dtype will be inferred
fastpath : boolean, default False
Create IntervalIndex without verifying integrity.
verify_integrity : boolean, default True
Verify that the IntervalIndex is valid.

..versionadded:: 0.23.0
..versionadded:: 0.23.0.

Attributes
----------
Expand Down Expand Up @@ -198,11 +202,11 @@ class IntervalIndex(IntervalMixin, Index):

See Also
--------
Index : The base pandas Index type
Interval : A bounded slice-like interval; the elements of an IntervalIndex
interval_range : Function to create a fixed frequency IntervalIndex
cut, qcut : Convert arrays of continuous data into Categoricals/Series of
Intervals
Index : The base pandas Index type.
Interval : A bounded slice-like interval; the elements of an IntervalIndex.
qcut : Quantile-based discretization function.
cut : Return indices of half-open bins to which each value of x belongs.
Copy link
Member

Choose a reason for hiding this comment

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

I know this is the explanation in the cut docstring, but it is actually not correct (we are having a discussion about this in the PR doing the cut function :)). I would keep the explanation that was there before about converting array of continuous data into intervals

interval_range : Function to create a fixed frequency IntervalIndex.
"""
_typ = 'intervalindex'
_comparables = ['name']
Expand Down Expand Up @@ -457,7 +461,8 @@ def from_breaks(cls, breaks, closed='right', name=None, copy=False,
def from_arrays(cls, left, right, closed='right', name=None, copy=False,
dtype=None):
"""
Construct an IntervalIndex from a a left and right array
Construct an IntervalIndex from a given element in a left
and right array.
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 try to keep this in a single line? I also don't fully understand the "from a given element in ", so would maybe remove that part


Parameters
----------
Expand All @@ -471,11 +476,15 @@ def from_arrays(cls, left, right, closed='right', name=None, copy=False,
name : object, optional
Name to be stored in the index.
copy : boolean, default False
copy the data
Copy the data.
dtype : dtype or None, default None
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 change "dtype or None, default None" to "dtype, optional" ?

If None, dtype will be inferred
If None, dtype will be inferred.

..versionadded:: 0.23.0
.. versionadded:: 0.23.0.

Returns
-------
index : IntervalIndex

Examples
--------
Expand All @@ -484,13 +493,34 @@ def from_arrays(cls, left, right, closed='right', name=None, copy=False,
closed='right',
dtype='interval[int64]')

If you want to segment different groups of people based on
ages, you can apply the method as follows:

>>> ages = pd.IntervalIndex.from_arrays([0, 2, 13],
... [2, 13, 19], closed='left')
>>> ages
IntervalIndex([[0, 2), [2, 13), [13, 19)]
closed='left',
dtype='interval[int64]')
>>> s = pd.Series(['baby', 'kid', 'teen'], ages)
>>> s
[0, 2) baby
[2, 13) kid
[13, 19) teen
dtype: object

Notes
Copy link
Contributor

Choose a reason for hiding this comment

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

I thin kthe order is Returns, Notes, See Also, then Examples.

-----
Each element of `left` must be smaller or equal to the `right` element
Copy link
Member

Choose a reason for hiding this comment

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

smaller --> less than

at the same position, ie, ``left[i] <= right[i]``.
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 also add that all elements within each array should have similar type? For example, the following raises on master since the mixed types result in object subtype (works on 0.22.0, but will be disallowed in the next release):

In [2]: pd.__version__
Out[2]: '0.23.0.dev0+482.gc3d491a'

In [3]: left = [1, pd.Timestamp('20180101')]

In [4]: right = [2, pd.Timestamp('20180201')]

In [5]: pd.IntervalIndex.from_arrays(left, right)
---------------------------------------------------------------------------
TypeError: category, object, and string subtypes are not supported for IntervalIndex


See Also
--------
interval_range : Function to create a fixed frequency IntervalIndex
interval_range : Function to create a fixed frequency IntervalIndex.
IntervalIndex.from_breaks : Construct an IntervalIndex from an array of
splits
splits.
IntervalIndex.from_tuples : Construct an IntervalIndex from a
list/array of tuples
list/array of tuples.
"""
left = maybe_convert_platform_interval(left)
right = maybe_convert_platform_interval(right)
Expand Down