From 341121fc0f52cfc95cab7ea0a8c0e99206d35579 Mon Sep 17 00:00:00 2001
From: Nicholas Landry <nicholas.landry.91@gmail.com>
Date: Sat, 2 Mar 2024 18:34:47 -0600
Subject: [PATCH] updated docs

---
 xgi/core/diviews.py | 18 ++++++++++++++----
 xgi/core/views.py   |  8 +++++---
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/xgi/core/diviews.py b/xgi/core/diviews.py
index 29d9e447e..5ca57e0f5 100644
--- a/xgi/core/diviews.py
+++ b/xgi/core/diviews.py
@@ -190,7 +190,7 @@ def filterby(self, stat, val, mode="eq"):
         val : Any
             Value of the statistic.  Usually a single numeric value.  When mode is
             'between', must be a tuple of exactly two values.
-        mode : str, optional
+        mode : str or function, optional
             How to compare each value to `val`.  Can be one of the following.
 
             * 'eq' (default): Return IDs whose value is exactly equal to `val`.
@@ -201,6 +201,7 @@ def filterby(self, stat, val, mode="eq"):
             * 'geq': Return IDs whose value is greater than or equal to `val`.
             * 'between': In this mode, `val` must be a tuple `(val1, val2)`.  Return IDs
               whose value `v` satisfies `val1 <= v <= val2`.
+            * function, must be able to call `mode(attribute, val)` and have it map to a bool.
 
         See Also
         --------
@@ -256,6 +257,8 @@ def filterby(self, stat, val, mode="eq"):
             bunch = [idx for idx in self if values[idx] >= val]
         elif mode == "between":
             bunch = [node for node in self if val[0] <= values[node] <= val[1]]
+        elif callable(mode):
+            bunch = [idx for idx in self if mode(values[idx], val)]
         else:
             raise ValueError(
                 f"Unrecognized mode {mode}. mode must be one of 'eq', 'neq', 'lt', 'gt', 'leq', 'geq', or 'between'."
@@ -271,9 +274,10 @@ def filterby_attr(self, attr, val, mode="eq", missing=None):
             The name of the attribute
         val : Any
             A single value or, in the case of 'between', a list of length 2
-        mode : str, optional
+        mode : str or function, optional
             Comparison mode. Valid options are 'eq' (default), 'neq', 'lt', 'gt',
-            'leq', 'geq', or 'between'.
+            'leq', 'geq', or 'between'. If a function, must be able to call
+            `mode(attribute, val)` and have it map to a bool.
         missing : Any, optional
             The default value if the attribute is missing. If None (default),
             ignores those IDs.
@@ -323,9 +327,15 @@ def filterby_attr(self, attr, val, mode="eq", missing=None):
                 for idx in self
                 if values[idx] is not None and val[0] <= values[idx] <= val[1]
             ]
+        elif callable(mode):
+            bunch = [
+                idx
+                for idx in self
+                if values[idx] is not None and mode(values[idx], val)
+            ]
         else:
             raise ValueError(
-                f"Unrecognized mode {mode}. mode must be one of 'eq', 'neq', 'lt', 'gt', 'leq', 'geq', or 'between'."
+                f"Unrecognized mode {mode}. mode must be one of 'eq', 'neq', 'lt', 'gt', 'leq', 'geq', 'between', or a callable function."
             )
         return type(self).from_view(self, bunch)
 
diff --git a/xgi/core/views.py b/xgi/core/views.py
index 13278b7d0..a802c25ef 100644
--- a/xgi/core/views.py
+++ b/xgi/core/views.py
@@ -183,7 +183,7 @@ def filterby(self, stat, val, mode="eq"):
         val : Any
             Value of the statistic.  Usually a single numeric value.  When mode is
             'between', must be a tuple of exactly two values.
-        mode : str, optional
+        mode : str or function, optional
             How to compare each value to `val`.  Can be one of the following.
 
             * 'eq' (default): Return IDs whose value is exactly equal to `val`.
@@ -194,6 +194,7 @@ def filterby(self, stat, val, mode="eq"):
             * 'geq': Return IDs whose value is greater than or equal to `val`.
             * 'between': In this mode, `val` must be a tuple `(val1, val2)`.  Return IDs
               whose value `v` satisfies `val1 <= v <= val2`.
+            * function, must be able to call `mode(attribute, val)` and have it map to a bool.
 
         See Also
         --------
@@ -273,9 +274,10 @@ def filterby_attr(self, attr, val, mode="eq", missing=None):
             The name of the attribute
         val : Any
             A single value or, in the case of 'between', a list of length 2
-        mode : str, optional
+        mode : str or function, optional
             Comparison mode. Valid options are 'eq' (default), 'neq', 'lt', 'gt',
-            'leq', 'geq', or 'between'.
+            'leq', 'geq', or 'between'. If a function, must be able to call
+            `mode(attribute, val)` and have it map to a bool.
         missing : Any, optional
             The default value if the attribute is missing. If None (default),
             ignores those IDs.