Merge pull request #11 from venaturum/GH1_superset

Added issuperset issubset

docs/reference/accessors.rst

@@ -13,4 +13,6 @@ Accessors
    ArrayAccessor.intersection
    ArrayAccessor.difference
    ArrayAccessor.symmetric_difference
-   ArrayAccessor.isdisjoint
+   ArrayAccessor.isdisjoint
+   ArrayAccessor.issuperset
+   ArrayAccessor.issubset

docs/reference/interval.rst

@@ -12,4 +12,6 @@ Interval
    union
    intersection
    difference
-   symmetric_difference
+   symmetric_difference
+   issuperset
+   issubset

docs/reference/package.rst

@@ -15,4 +15,6 @@ Top level functions
    intersection
    difference
    symmetric_difference
-   isdisjoint
+   isdisjoint
+   issuperset
+   issubset

docs/release_notes/index.rst

@@ -4,19 +4,32 @@
 Release notes
 ========================
 
-- added :meth:`piso.isdisjoint` method, and corresponding accessor method
+Added the following methods
 
-ADD UNRELEASED CHANGED ABOVE THIS LINE
+- :meth:`piso.isdisjoint`
+- :meth:`piso.issuperset`
+- :meth:`piso.issubset`
+- :meth:`ArrayAccessor.isdisjoint() <piso.accessor.ArrayAccessor.isdisjoint>`
+- :meth:`ArrayAccessor.issuperset() <piso.accessor.ArrayAccessor.issuperset>`
+- :meth:`ArrayAccessor.issubset() <piso.accessor.ArrayAccessor.issubset>`
+- :meth:`piso.interval.issuperset`
+- :meth:`piso.interval.issubset`
+
+ADD UNRELEASED CHANGES ABOVE THIS LINE
 
 **v0.1.0 2021-10-10**
 
-The following methods (and corresponding accessor methods) are included in the initial release of `piso`
+The following methods are included in the initial release of `piso`
 
 - :meth:`piso.register_accessors`
 - :meth:`piso.union`
 - :meth:`piso.intersection`
 - :meth:`piso.difference`
 - :meth:`piso.symmetric_difference`
+- :meth:`ArrayAccessor.union() <piso.accessor.ArrayAccessor.union>`
+- :meth:`ArrayAccessor.intersection() <piso.accessor.ArrayAccessor.intersection>`
+- :meth:`ArrayAccessor.difference() <piso.accessor.ArrayAccessor.difference>`
+- :meth:`ArrayAccessor.symmetric_difference() <piso.accessor.ArrayAccessor.symmetric_difference>`
 - :meth:`piso.interval.union`
 - :meth:`piso.interval.intersection`
 - :meth:`piso.interval.difference`

piso/__init__.py

@@ -2,6 +2,8 @@
     difference,
     intersection,
     isdisjoint,
+    issubset,
+    issuperset,
     symmetric_difference,
     union,
 )

piso/accessor.py

@@ -125,6 +125,22 @@ def isdisjoint(self, *interval_arrays):
             *interval_arrays,
         )
 
+    @Appender(docstrings.issuperset_docstring, join="\n", indents=1)
+    def issuperset(self, *interval_arrays, squeeze=False):
+        return intervalarray.issuperset(
+            self._interval_array,
+            *interval_arrays,
+            squeeze=squeeze,
+        )
+
+    @Appender(docstrings.issubset_docstring, join="\n", indents=1)
+    def issubset(self, *interval_arrays, squeeze=False):
+        return intervalarray.issubset(
+            self._interval_array,
+            *interval_arrays,
+            squeeze=squeeze,
+        )
+
 
 def _register_accessors():
     _register_accessor("piso", pd.IntervalIndex)(ArrayAccessor)

piso/docstrings/accessor.py

@@ -288,6 +288,69 @@
 False
 """
 
+issuperset_examples = """
+Examples
+-----------
+
+>>> import pandas as pd
+>>> import piso
+>>> piso.register_accessors()
+
+>>> arr1 = pd.arrays.IntervalArray.from_tuples(
+...     [(0, 4), (3, 6), (7, 8), (10, 12)],
+... )
+>>> arr2 = pd.arrays.IntervalArray.from_tuples(
+...     [(2, 5), (7, 8)],
+... )
+>>> arr3 = pd.arrays.IntervalArray.from_tuples(
+...     [(3, 4), (10, 11)],
+... )
+
+>>> arr1.piso.issuperset(arr2)
+True
+
+>>> arr1.piso.issuperset(arr2, squeeze=False)
+array([ True])
+
+>>> arr1.piso.issuperset(arr2, arr3)
+array([ True, True])
+
+>>> arr2.piso.issuperset(arr3)
+False
+"""
+
+
+issubset_examples = """
+Examples
+-----------
+
+>>> import pandas as pd
+>>> import piso
+>>> piso.register_accessors()
+
+>>> arr1 = pd.arrays.IntervalArray.from_tuples(
+...     [(2, 5), (7, 8)],
+... )
+>>> arr2 = pd.arrays.IntervalArray.from_tuples(
+...     [(0, 4), (3, 6), (7, 8), (10, 12)],
+... )
+>>> arr3 = pd.arrays.IntervalArray.from_tuples(
+...     [(3, 4), (10, 11)],
+... )
+
+>>> arr1.piso.issubset(arr2)
+True
+
+>>> arr1.piso.issubset(arr2, squeeze=False)
+array([ True])
+
+>>> arr1.piso.issubset(arr2, arr3)
+array([ True, False])
+
+>>> arr1.piso.issubset(arr3)
+False
+"""
+
 
 def join_params(list_of_param_strings):
     return "".join(list_of_param_strings).replace("\n\n", "\n")
@@ -298,7 +361,7 @@ def join_params(list_of_param_strings):
     May contain zero or more arguments.
 """
 
-param_optional_args_difference = """
+param_optional_args_min_one = """
 *interval_arrays : argument list of :class:`pandas.IntervalIndex` or :class:`pandas.arrays.IntervalArray`
     Must contain at least one argument.
 """
@@ -312,8 +375,8 @@ def join_params(list_of_param_strings):
 """
 
 param_squeeze = """
-squeeze : boolean, default True
-    If True, will try to coerce the return value to a pandas.Interval.
+squeeze : boolean, default {default}
+    If True, will try to coerce the return value to a single pandas.Interval.
     If supplied, must be done so as a keyword argument.
 """
 
@@ -368,9 +431,6 @@ def join_params(list_of_param_strings):
 and the union of the sets in *interval_arrays*.  This is equivalent to iteratively applying a set difference operation with each array
 in *interval_arrays* as the second operand.
 
-Each of these array operands is assumed to contain disjoint intervals (and satisfy the definition of a set).  Any array containing
-overlaps between intervals will be mapped to one with disjoint intervals via a union operation.
-
 {extra_desc}
 Parameters
 ----------
@@ -383,14 +443,38 @@ def join_params(list_of_param_strings):
 {examples}
 """
 
+is_super_sub_set_template = """
+Indicates whether a set is a {operation} of one, or more, other sets.
+
+The array elements of *interval_arrays*, and the interval array object the accessor belongs to
+(an instance of :class:`pandas.IntervalIndex`, :class:`pandas.arrays.IntervalArray`) are considered to be the sets over which
+the operation is performed.  Each of these arrays is assumed to contain disjoint intervals (and satisfy the definition of a set).
+Any array containing overlaps between intervals will be mapped to one with disjoint intervals via a union operation.
+
+The list *interval_arrays* must contain at least one element.  The {operation} comparison is iteratively applied between
+the interval array the accessor belongs to, and each array in *interval_arrays*.  When *interval_arrays* contains multiple
+interval arrays, the return type will be a numpy array.  If it contains one interval array then the result can be coerced to
+a single boolean using the *squeeze* parameter.
+
+Parameters
+----------
+{params}
+
+Returns
+----------
+:class:`pandas.IntervalIndex` or :class:`pandas.arrays.IntervalArray`
+
+{examples}
+"""
+
 array_return_type = (
     ":class:`pandas.IntervalIndex` or :class:`pandas.arrays.IntervalArray`"
 )
 
 union_params = join_params(
     [
         param_optional_args,
-        param_squeeze,
+        param_squeeze.format(default="False"),
         param_return_type,
     ]
 )
@@ -406,7 +490,7 @@ def join_params(list_of_param_strings):
     [
         param_optional_args,
         param_min_overlaps,
-        param_squeeze,
+        param_squeeze.format(default="False"),
         param_return_type,
     ]
 )
@@ -420,8 +504,8 @@ def join_params(list_of_param_strings):
 
 difference_params = join_params(
     [
-        param_optional_args_difference,
-        param_squeeze,
+        param_optional_args_min_one,
+        param_squeeze.format(default="False"),
         param_return_type,
     ]
 )
@@ -438,7 +522,7 @@ def join_params(list_of_param_strings):
     [
         param_optional_args,
         param_min_overlaps,
-        param_squeeze,
+        param_squeeze.format(default="False"),
         param_return_type,
     ]
 )
@@ -474,3 +558,28 @@ def join_params(list_of_param_strings):
     return_type="boolean",
     examples=isdisjoint_examples,
 )
+
+
+issuperset_params = join_params(
+    [
+        param_optional_args_min_one,
+        param_squeeze.format(default="True"),
+    ]
+)
+issuperset_docstring = is_super_sub_set_template.format(
+    operation="superset",
+    params=issuperset_params,
+    examples=issuperset_examples,
+)
+
+issubset_params = join_params(
+    [
+        param_optional_args_min_one,
+        param_squeeze.format(default="True"),
+    ]
+)
+issubset_docstring = is_super_sub_set_template.format(
+    operation="subset",
+    params=issubset_params,
+    examples=issubset_examples,
+)