DOC: update the IntervalIndex.from_array docstring (#20224)

Author: verakai

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)