IntervalIndex
=============

.. currentmodule:: pandasCore

.. class:: IntervalIndex

   Immutable index backed by interval data.


Example
-------

.. code-block:: python

   import pandasCore as pd

   # Create IntervalIndex
   idx = pd.IntervalIndex([1, 2, 3], name='my_index')
   print(len(idx))  # 3

Attributes
----------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Attribute
     - Description
     - Example
   * - :attr:`~IntervalIndex.closed`
     - String describing the inclusive side(s) of the intervals
     - 
   * - :attr:`~IntervalIndex.dtype`
     - Return the dtype object of the underlying data
     - 
   * - :attr:`~IntervalIndex.empty`
     - Indicator whether IntervalIndex is empty
     - 
   * - :attr:`~IntervalIndex.has_duplicates`
     - Return if the index has duplicate values
     - 
   * - :attr:`~IntervalIndex.is_empty`
     - Indicates if an interval is empty (left == right and not both-closed)
     - 
   * - :attr:`~IntervalIndex.is_monotonic_decreasing`
     - Return if the index is monotonic decreasing
     - 
   * - :attr:`~IntervalIndex.is_monotonic_increasing`
     - Return if the index is monotonic increasing
     - 
   * - :attr:`~IntervalIndex.is_non_overlapping_monotonic`
     - Return True if intervals are non-overlapping and monotonically sorted
     - 
   * - :attr:`~IntervalIndex.is_overlapping`
     - Return True if any intervals overlap
     - 
   * - :attr:`~IntervalIndex.is_unique`
     - Return if the index has unique values
     - 
   * - :attr:`~IntervalIndex.left`
     - Return the left bounds of the intervals
     - 
   * - :attr:`~IntervalIndex.length`
     - Return the length of each interval
     - 
   * - :attr:`~IntervalIndex.mid`
     - Return the midpoint of each interval
     - 
   * - :attr:`~IntervalIndex.name`
     - Return the name of the IntervalIndex
     - 
   * - :attr:`~IntervalIndex.ndim`
     - Number of dimensions of the underlying data
     - 
   * - :attr:`~IntervalIndex.nlevels`
     - Number of levels in this index
     - 
   * - :attr:`~IntervalIndex.right`
     - Return the right bounds of the intervals
     - 
   * - :attr:`~IntervalIndex.shape`
     - Return a tuple of the shape of the underlying data
     - 
   * - :attr:`~IntervalIndex.size`
     - Return the number of elements in the IntervalIndex
     - 
   * - :attr:`~IntervalIndex.str`
     - Vectorized string functions for Index.
     - :ref:`View <example-intervalindex-str-0>`

Construction
------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.__init__` ``(*args, **kwargs) | () | (data: collections.abc.Sequence[tuple[typing.SupportsFloat, typing.SupportsFloat]], closed: object = None, dtype: object = None, copy: bool = False, name: object = None, verify_integrity: bool = True)``
     - Create an empty IntervalIndex
     - :ref:`View <example-intervalindex-dunder-initdunder--1>`

Indexing / Selection
--------------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.__getitem__` ``(arg0: typing.SupportsInt)``
     - 
     - 
   * - :meth:`~IntervalIndex.take` ``(indices: collections.abc.Sequence[typing.SupportsInt], axis: typing.SupportsInt = 0, allow_fill: bool = True, fill_value: object = None, **kwargs)``
     - Return new IntervalIndex with elements at specified positions
     - 
   * - :meth:`~IntervalIndex.where` ``(cond: object, other: object = None)``
     - Replace values where the condition is False.
     - 

Data Manipulation
-----------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.drop` ``(labels: object, errors: str = 'raise')``
     - Make new Index with passed list of labels deleted
     - 
   * - :meth:`~IntervalIndex.droplevel` ``(level: typing.SupportsInt = 0)``
     - Return index with requested level(s) removed.
     - 
   * - :meth:`~IntervalIndex.insert` ``(loc: typing.SupportsInt, item: object)``
     - Make new IntervalIndex inserting new item at location
     - 
   * - :meth:`~IntervalIndex.reindex` ``(target: pandasCore.IntervalIndex, method: object = None, level: object = None, limit: object = None, tolerance: object = None)``
     - Conform Index to new index with optional filling logic
     - 
   * - :meth:`~IntervalIndex.rename` ``(name: object, *, inplace: bool = False)``
     - Alter IntervalIndex name.
     - 
   * - :meth:`~IntervalIndex.set_names` ``(names: object, *, level: object = None, inplace: bool = False)``
     - Set IntervalIndex name
     - 

Missing Data
------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.dropna` ``(how: str = 'any')``
     - Return IntervalIndex without NA values
     - 
   * - :meth:`~IntervalIndex.fillna` ``(value: object = None, downcast: object = None)``
     - Fill NA/NaN values with the specified value
     - 
   * - :meth:`~IntervalIndex.isna` ``()``
     - Detect missing values
     - 
   * - :meth:`~IntervalIndex.isnull` ``()``
     - Detect missing values (alias for isna)
     - 
   * - :meth:`~IntervalIndex.notna` ``()``
     - Detect existing (non-missing) values
     - 
   * - :meth:`~IntervalIndex.notnull` ``()``
     - Detect existing (non-missing) values (alias for notna)
     - 

Statistics
----------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.max` ``(axis: object = None, skipna: bool = True, *args, **kwargs)``
     - Return the maximum interval (by left bound)
     - 
   * - :meth:`~IntervalIndex.min` ``(axis: object = None, skipna: bool = True, *args, **kwargs)``
     - Return the minimum interval (by left bound)
     - 
   * - :meth:`~IntervalIndex.nunique` ``(dropna: bool = True)``
     - Return number of unique elements in the index
     - 
   * - :meth:`~IntervalIndex.value_counts` ``(normalize: bool = False, sort: bool = True, ascending: bool = False, bins: object = None, dropna: bool = True)``
     - Return a dict containing counts of unique values
     - 

Aggregation
-----------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.groupby` ``(values: collections.abc.Sequence[typing.SupportsInt])``
     - Group the index labels by a given array of values
     - 
   * - :meth:`~IntervalIndex.map` ``(mapper: object, na_action: object = None)``
     - Map values using an input mapping or function
     - 

Comparison
----------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.__eq__` ``(self, value, /)``
     - Return self==value.
     - 
   * - :meth:`~IntervalIndex.__ge__` ``(self, value, /)``
     - Return self>=value.
     - 
   * - :meth:`~IntervalIndex.__gt__` ``(self, value, /)``
     - Return self>value.
     - 
   * - :meth:`~IntervalIndex.__le__` ``(self, value, /)``
     - Return self<=value.
     - 
   * - :meth:`~IntervalIndex.__lt__` ``(self, value, /)``
     - Return self<value.
     - 
   * - :meth:`~IntervalIndex.__ne__` ``(self, value, /)``
     - Return self!=value.
     - 
   * - :meth:`~IntervalIndex.equals` ``(other: pandasCore.IntervalIndex)``
     - Determine if two IntervalIndex objects are equal
     - 

Sorting
-------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.argsort` ``(*args, **kwargs)``
     - Return the indices that would sort the index
     - 
   * - :meth:`~IntervalIndex.searchsorted` ``(value: object, side: str = 'left', sorter: object = None)``
     - Find indices where elements should be inserted to maintain order
     - 
   * - :meth:`~IntervalIndex.sort_values` ``(*, return_indexer: bool = False, ascending: bool = True, na_position: str = 'last', key: object = None)``
     - Return a sorted copy of the index
     - 

Reshaping
---------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.to_frame` ``(index: bool = True, name: object = None)``
     - Create a DataFrame with a column containing the IntervalIndex values
     - 
   * - :meth:`~IntervalIndex.transpose` ``()``
     - Return the transpose (self for 1D index)
     - 

Combining
---------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.append` ``(other: pandasCore.IntervalIndex)``
     - Append another IntervalIndex to this one
     - 
   * - :meth:`~IntervalIndex.join` ``(other: pandasCore.IntervalIndex, *, how: str = 'left', level: object = None, return_indexers: bool = False, sort: bool = False)``
     - Join this index with another
     - 

Time Series
-----------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.asof` ``(label: object)``
     - Return the label from the index, or, if not present, the previous one.
     - 
   * - :meth:`~IntervalIndex.diff` ``(periods: typing.SupportsInt = 1)``
     - Compute first-order differences
     - 
   * - :meth:`~IntervalIndex.shift` ``(periods: typing.SupportsInt = 1, freq: object = None)``
     - Shift index by desired number of periods
     - 

I/O
---

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.to_flat_index` ``()``
     - Return a flattened index
     - 
   * - :meth:`~IntervalIndex.to_list` ``()``
     - Return a list of the intervals as tuples
     - 
   * - :meth:`~IntervalIndex.to_numpy` ``(dtype: object = None, copy: bool = False, na_value: object = None, **kwargs)``
     - A NumPy ndarray representing the values in this Series or Index
     - 
   * - :meth:`~IntervalIndex.to_series` ``(index: object = None, name: object = None)``
     - Create a Series with the IntervalIndex values
     - 
   * - :meth:`~IntervalIndex.to_tuples` ``()``
     - Return a list of tuples of the form (left, right)
     - 
   * - :meth:`~IntervalIndex.tolist` ``()``
     - Return a list of the intervals as tuples
     - 

Conversion
----------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.astype` ``(dtype: str, copy: bool = True)``
     - Cast to a specified dtype.
     - 
   * - :meth:`~IntervalIndex.copy` ``(name: object = None, deep: bool = False)``
     - Make a copy of this IntervalIndex.
     - 
   * - :meth:`~IntervalIndex.infer_objects` ``(copy: bool = True)``
     - Infer objects type and return a converted version.
     - 
   * - :meth:`~IntervalIndex.view` ``(cls: object = None)``
     - Return a view of the index.
     - 

Iteration
---------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.__contains__` ``(key: tuple[typing.SupportsFloat, typing.SupportsFloat])``
     - 
     - 
   * - :meth:`~IntervalIndex.__iter__` ``()``
     - 
     - 
   * - :meth:`~IntervalIndex.__len__` ``()``
     - 
     - 

Set Operations
--------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.difference` ``(other: pandasCore.IntervalIndex, sort: object = None)``
     - Form the set difference of two IntervalIndex objects
     - 
   * - :meth:`~IntervalIndex.drop_duplicates` ``(*, keep: str = 'first')``
     - Return IntervalIndex with duplicate values removed
     - 
   * - :meth:`~IntervalIndex.duplicated` ``(keep: str = 'first')``
     - Indicate duplicate index values
     - 
   * - :meth:`~IntervalIndex.intersection` ``(other: pandasCore.IntervalIndex, sort: bool = False)``
     - Form the intersection of two IntervalIndex objects
     - 
   * - :meth:`~IntervalIndex.isin` ``(values: collections.abc.Sequence[tuple[typing.SupportsFloat, typing.SupportsFloat]], level: object = None)``
     - Check if values are in the IntervalIndex
     - 
   * - :meth:`~IntervalIndex.symmetric_difference` ``(other: pandasCore.IntervalIndex, result_name: object = None, sort: object = None)``
     - Form the symmetric difference of two IntervalIndex objects
     - 
   * - :meth:`~IntervalIndex.union` ``(other: pandasCore.IntervalIndex, sort: object = None)``
     - Form the union of two IntervalIndex objects
     - 
   * - :meth:`~IntervalIndex.unique` ``(level: object = None)``
     - Return unique values in the index
     - 

String Methods
--------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.contains` ``(other: typing.SupportsFloat)``
     - Check elementwise if the Intervals contain the value.
     - 

Datetime Methods
----------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.round` ``(decimals: typing.SupportsInt = 0)``
     - Round interval bounds to specified number of decimals
     - 

Other Methods
-------------

.. list-table::
   :widths: 25 60 15
   :header-rows: 1

   * - Method
     - Description
     - Example
   * - :meth:`~IntervalIndex.__hash__` ``(self, /)``
     - Return hash(self).
     - 
   * - :meth:`~IntervalIndex.__repr__` ``()``
     - 
     - 
   * - :meth:`~IntervalIndex.__str__` ``()``
     - 
     - 
   * - :meth:`~IntervalIndex.all` ``(*args, **kwargs)``
     - Return whether all elements are truthy
     - 
   * - :meth:`~IntervalIndex.any` ``(*args, **kwargs)``
     - Return whether any element is truthy
     - 
   * - :meth:`~IntervalIndex.argmax` ``(axis: object = None, skipna: bool = True, *args, **kwargs)``
     - Return the index of the maximum value
     - 
   * - :meth:`~IntervalIndex.argmin` ``(axis: object = None, skipna: bool = True, *args, **kwargs)``
     - Return the index of the minimum value
     - 
   * - :meth:`~IntervalIndex.asof_locs` ``(where: object, mask: object = None)``
     - Return the locations (indices) of labels in the index.
     - 
   * - :meth:`~IntervalIndex.delete` ``(loc: typing.SupportsInt)``
     - Make new IntervalIndex with element at position deleted
     - 
   * - :meth:`~IntervalIndex.factorize` ``(sort: bool = False, use_na_sentinel: bool = True)``
     - Encode the object as an enumerated type or categorical variable
     - 
   * - :meth:`~IntervalIndex.format` ``(name: bool = False, formatter: object = None, na_rep: str = 'NaN')``
     - Format the IntervalIndex as list of strings
     - 
   * - :meth:`~IntervalIndex.get_indexer` ``(target: pandasCore.IntervalIndex, method: object = None, limit: object = None, tolerance: object = None)``
     - Compute indexer for new index given the current index
     - 
   * - :meth:`~IntervalIndex.get_indexer_for` ``(target: pandasCore.IntervalIndex)``
     - Guaranteed return of an indexer even when non-unique
     - 
   * - :meth:`~IntervalIndex.get_indexer_non_unique` ``(target: pandasCore.IntervalIndex)``
     - Compute indexer and mask for new index given the current index.
     - 
   * - :meth:`~IntervalIndex.get_level_values` ``(level: object)``
     - Return an IntervalIndex of values for requested level
     - 
   * - :meth:`~IntervalIndex.get_loc` ``(key: tuple[typing.SupportsFloat, typing.SupportsFloat])``
     - Get integer location for requested label
     - 
   * - :meth:`~IntervalIndex.get_slice_bound` ``(label: object, side: str)``
     - Calculate slice bound that corresponds to given label.
     - 
   * - :meth:`~IntervalIndex.holds_integer` ``()``
     - Check if the index holds integers (always False for float64 Interva...
     - 
   * - :meth:`~IntervalIndex.identical` ``(other: pandasCore.IntervalIndex)``
     - Determine if two IntervalIndex objects are identical
     - 
   * - :meth:`~IntervalIndex.item` ``()``
     - Return the first element as a scalar (only for single-element index)
     - 
   * - :meth:`~IntervalIndex.memory_usage` ``(deep: bool = False)``
     - Return memory usage of the index in bytes
     - 
   * - :meth:`~IntervalIndex.overlaps` ``(left: typing.SupportsFloat, right: typing.SupportsFloat)``
     - Check elementwise if an interval overlaps the values.
     - 
   * - :meth:`~IntervalIndex.putmask` ``(mask: object, value: object)``
     - Return a new IntervalIndex with values put where mask is True.
     - 
   * - :meth:`~IntervalIndex.ravel` ``(order: str = 'C')``
     - Return a flattened view of the index.
     - 
   * - :meth:`~IntervalIndex.repeat` ``(repeats: typing.SupportsInt, axis: object = None)``
     - Repeat elements of the index
     - 
   * - :meth:`~IntervalIndex.set_closed` ``(closed: str)``
     - Return an IntervalIndex with the specified closed side.
     - 
   * - :meth:`~IntervalIndex.slice_indexer` ``(start: object = None, end: object = None, step: object = None)``
     - Compute slice indexer for input labels.
     - 
   * - :meth:`~IntervalIndex.slice_locs` ``(start: object = None, end: object = None, step: object = None)``
     - Compute slice locations for input labels
     - 
   * - :meth:`~IntervalIndex.sort` ``(ascending: bool = True)``
     - Return a sorted copy of the index.
     - 
   * - :meth:`~IntervalIndex.sortlevel` ``(level: object = None, ascending: bool = True, sort_remaining: object = None, na_position: str = 'first')``
     - Sort index by level
     - 


Code Examples
-------------

The following examples are extracted from the test suite.

.. _example-intervalindex-str-0:

.. dropdown:: str (test_interval_multi_range_str.py:79)
   :class-title: example-dropdown

   .. code-block:: python
      :linenos:
      :lineno-start: 69
      :emphasize-lines: 11

      
      def test_intervalindex_str_call_with_data():
          """Test IntervalIndex.str(data) call."""
          print("Testing IntervalIndex.str(data) call...")
      
          # Create an IntervalIndex
          ii = pandasCore.IntervalIndex.from_breaks([0, 1, 2])
      
          # Call IntervalIndex.str with the index as argument
          try:
              str_accessor = pandasCore.IntervalIndex.str(ii)
              print(f"  IntervalIndex.str(ii) returned: {type(str_accessor)}")
              print("  PASSED: IntervalIndex.str(data) call works")
          except Exception as e:
              # Expected to raise error since IntervalIndex doesn't contain strings
              print(f"  Error (expected for non-string data): {e}")
              print("  PASSED: Appropriate error raised for non-string Index")
      
      # =============================================================================
      # MultiIndex.str tests
      # =============================================================================

.. _example-intervalindex-dunder-initdunder--1:

.. dropdown:: __init__ (test_intervalindex.py:87)
   :class-title: example-dropdown

   .. code-block:: python
      :linenos:
      :lineno-start: 77
      :emphasize-lines: 11

          ctx.assert_equal((0.0, 1.0), ii[0], "from_tuples first interval")
          ctx.assert_equal((2.0, 3.0), ii[1], "from_tuples second interval")
          ctx.assert_equal((4.0, 5.0), ii[2], "from_tuples third interval")
      
      
      def test_constructor():
          """Test IntervalIndex constructor with list of tuples"""
          f_print_header("Test: constructor")
      
          data = [(0.0, 1.0), (1.0, 2.0), (2.0, 3.0)]
          ii = pandasCore.IntervalIndex(data)
      
          ctx.assert_equal(3, ii.size, "constructor size")
          ctx.assert_equal("right", ii.closed, "constructor closed")
      
          # With closed parameter
          ii_both = pandasCore.IntervalIndex(data, closed="both")
          ctx.assert_equal("both", ii_both.closed, "constructor closed=both")
      
      
      def test_properties():