diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py index ccf2e5e3c4486..54800d0d76d2e 100644 --- a/pandas/core/indexes/interval.py +++ b/pandas/core/indexes/interval.py @@ -457,7 +457,7 @@ 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 from two arrays defining the left and right bounds. Parameters ---------- @@ -471,11 +471,38 @@ 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 - dtype : dtype or None, default None - If None, dtype will be inferred + Copy the data. + dtype : dtype, optional + If None, dtype will be inferred. - ..versionadded:: 0.23.0 + .. versionadded:: 0.23.0 + + Returns + ------- + index : IntervalIndex + + Notes + ----- + Each element of `left` must be less than or equal to the `right` + element at the same position. If an element is missing, it must be + missing in both `left` and `right`. A TypeError is raised when + using an unsupported type for `left` or `right`. At the moment, + 'category', 'object', and 'string' subtypes are not supported. + + Raises + ------ + ValueError + When a value is missing in only one of `left` or `right`. + When a value in `left` is greater than the corresponding value + in `right`. + + See Also + -------- + interval_range : Function to create a fixed frequency IntervalIndex. + IntervalIndex.from_breaks : Construct an IntervalIndex from an array of + splits. + IntervalIndex.from_tuples : Construct an IntervalIndex from a + list/array of tuples. Examples -------- @@ -484,13 +511,29 @@ def from_arrays(cls, left, right, closed='right', name=None, copy=False, closed='right', dtype='interval[int64]') - See Also - -------- - interval_range : Function to create a fixed frequency IntervalIndex - IntervalIndex.from_breaks : Construct an IntervalIndex from an array of - splits - IntervalIndex.from_tuples : Construct an IntervalIndex from a - list/array of tuples + 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 + + Values may be missing, but they must be missing in both arrays. + + >>> pd.IntervalIndex.from_arrays([0, np.nan, 13], + ... [2, np.nan, 19]) + IntervalIndex([(0.0, 2.0], nan, (13.0, 19.0]] + closed='right', + dtype='interval[float64]') """ left = maybe_convert_platform_interval(left) right = maybe_convert_platform_interval(right)