adjacency_matrix methods added (GH25) (#43)

* adjacency_matrix methods added (GH25)

* extra tests

closes #25

docs/reference/accessors.rst

@@ -19,4 +19,5 @@ Accessors
    ArrayAccessor.coverage
    ArrayAccessor.complement
    ArrayAccessor.contains
-   ArrayAccessor.split
+   ArrayAccessor.split
+   ArrayAccessor.adjacency_matrix

docs/reference/package.rst

@@ -24,4 +24,4 @@ Top level functions
    split
    lookup
    join
-
+   adjacency_matrix

docs/release_notes/index.rst

@@ -7,7 +7,9 @@ Release notes
 Added the following methods
 
 - :func:`piso.split`
+- :func:`piso.adjacency_matrix`
 - :meth:`ArrayAccessor.split() <piso.accessor.ArrayAccessor.split>`
+- :meth:`ArrayAccessor.adjacency_matrix() <piso.accessor.ArrayAccessor.adjacency_matrix>`
 
 - removed :func:`piso.get_indexer` in favour of :meth:`pandas.IntervalIndex.get_indexer`
 

piso/__init__.py

@@ -1,3 +1,4 @@
+from piso.graph import adjacency_matrix
 from piso.intervalarray import (
     complement,
     contains,

piso/accessor.py

@@ -3,7 +3,7 @@
 import pandas as pd
 
 import piso.docstrings.accessor as docstrings
-from piso import intervalarray
+from piso import graph, intervalarray
 from piso._decorators import Appender
 
 
@@ -170,6 +170,14 @@ def split(self, x):
             x,
         )
 
+    @Appender(docstrings.adjacency_matrix_docstring, join="\n", indents=1)
+    def adjacency_matrix(self, edges="intersect", include_index=True):
+        return graph.adjacency_matrix(
+            self._interval_array,
+            edges=edges,
+            include_index=include_index,
+        )
+
 
 def _register_accessors():
     _register_accessor("piso", pd.IntervalIndex)(ArrayAccessor)

piso/docstrings/accessor.py

@@ -1,3 +1,5 @@
+from piso.graph import adjacency_matrix
+
 union_examples = """
 Examples
 -----------
@@ -832,3 +834,61 @@ def join_params(list_of_param_strings):
               closed='neither',
               dtype='interval[float64]')
 """
+
+
+adjacency_matrix_docstring = """
+Returns a 2D array (or dataframe) of boolean values indicating edges between nodes in a graph.
+
+The set of nodes correspond to intervals and the edges are defined by the relationship
+defined by the *edges* parameter.
+
+Note that the diagonal is defined with False values by default.
+
+Parameters
+----------
+edges : {"intersect", "disjoint"}, default "intersect"
+    Defines the relationship that edges between nodes represent.
+include_index : bool, default True
+    If True then a :class:`pandas.DataFrame`, indexed by the intervals, is returned.
+    If False then a :class:`numpy.ndarray` is returned.
+
+Returns
+-------
+:class:`pandas.DataFrame` or :class:`numpy.ndarray`
+    Boolean valued, symmetrical, with False along diagonal.
+
+Examples
+---------
+
+>>> import pandas as pd
+>>> import piso
+>>> piso.register_accessors()
+
+>>> arr = pd.arrays.IntervalArray.from_tuples(
+...    [(0,4), (3,6), (5, 7), (8,9), (9,10)],
+...    closed="both",
+... )
+
+>>> arr.piso.adjacency_matrix()
+         [0, 4]  [3, 6]  [5, 7]  [8, 9]  [9, 10]
+[0, 4]    False    True   False   False    False
+[3, 6]     True   False    True   False    False
+[5, 7]    False    True   False   False    False
+[8, 9]    False   False   False   False     True
+[9, 10]   False   False   False    True    False
+
+>>> arr.piso.adjacency_matrix(arr, include_index=False)
+array([[False,  True, False, False, False],
+       [ True, False,  True, False, False],
+       [False,  True, False, False, False],
+       [False, False, False, False,  True],
+       [False, False, False,  True, False]])
+
+>>> arr.piso.adjacency_matrix(arr, edges="disjoint")
+         [0, 4]  [3, 6]  [5, 7]  [8, 9]  [9, 10]
+[0, 4]    False   False    True    True     True
+[3, 6]    False   False   False    True     True
+[5, 7]     True   False   False    True     True
+[8, 9]     True    True    True   False    False
+[9, 10]    True    True    True   False    False
+"""

piso/graph.py

@@ -0,0 +1,89 @@
+import numpy as np
+import pandas as pd
+from pandas.core.indexes import interval
+
+
+def adjacency_matrix(interval_array, edges="intersect", include_index=True):
+    """
+    Returns a 2D array (or dataframe) of boolean values indicating edges between nodes in a graph.
+
+    The set of nodes correspond to intervals and the edges are defined by the relationship
+    defined by the *edges* parameter.
+
+    Note that the diagonal is defined with False values by default.
+
+    Parameters
+    ----------
+    interval_array : :class:`pandas.arrays.IntervalArray` or :class:`pandas.IntervalIndex`
+        Contains the intervals.
+    edges : {"intersect", "disjoint"}, default "intersect"
+        Defines the relationship that edges between nodes represent.
+    include_index : bool, default True
+        If True then a :class:`pandas.DataFrame`, indexed by the intervals, is returned.
+        If False then a :class:`numpy.ndarray` is returned.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame` or :class:`numpy.ndarray`
+        Boolean valued, symmetrical, with False along diagonal.
+
+    Examples
+    ---------
+
+    >>> import pandas as pd
+    >>> import piso
+
+    >>> arr = pd.arrays.IntervalArray.from_tuples(
+    ...    [(0,4), (3,6), (5, 7), (8,9), (9,10)],
+    ...    closed="both",
+    ... )
+
+    >>> piso.adjacency_matrix(arr)
+             [0, 4]  [3, 6]  [5, 7]  [8, 9]  [9, 10]
+    [0, 4]    False    True   False   False    False
+    [3, 6]     True   False    True   False    False
+    [5, 7]    False    True   False   False    False
+    [8, 9]    False   False   False   False     True
+    [9, 10]   False   False   False    True    False
+
+    >>> piso.adjacency_matrix(arr, include_index=False)
+    array([[False,  True, False, False, False],
+           [ True, False,  True, False, False],
+           [False,  True, False, False, False],
+           [False, False, False, False,  True],
+           [False, False, False,  True, False]])
+
+    >>> piso.adjacency_matrix(arr, edges="disjoint")
+             [0, 4]  [3, 6]  [5, 7]  [8, 9]  [9, 10]
+    [0, 4]    False   False    True    True     True
+    [3, 6]    False   False   False    True     True
+    [5, 7]     True   False   False    True     True
+    [8, 9]     True    True    True   False    False
+    [9, 10]    True    True    True   False    False
+    """
+    if edges == "intersect":
+        result = _adj_mat_intersection(interval_array)
+    elif edges == "disjoint":
+        result = ~_adj_mat_intersection(interval_array, fill_diagonal=False)
+    else:
+        raise ValueError(f"Invalid value for edges parameter: {edges}")
+
+    if include_index:
+        result = pd.DataFrame(result, index=interval_array, columns=interval_array)
+
+    return result
+
+
+def _adj_mat_intersection(interval_array, fill_diagonal=True):
+    result = np.greater.outer(
+        interval_array.right, interval_array.left
+    ) & np.less.outer(interval_array.left, interval_array.right)
+    if interval_array.closed == "both":
+        result = (
+            result
+            | np.equal.outer(interval_array.right, interval_array.left)
+            | np.equal.outer(interval_array.left, interval_array.right)
+        )
+    if fill_diagonal:
+        np.fill_diagonal(result, False)
+    return result