refactor: update how Range works (#60)

* refactor: update how `Range` works

* docs: fix typos

* fix: RTD error

---------

Co-authored-by: KD-7 <[email protected]>

Author: yuxqiu

truelearn/__init__.py

@@ -6,5 +6,5 @@
 
 # Follows Semantic Versioning 2.0.0
 # https://semver.org/
-# Append '-dev' to version for development versions
+# Append '-dev' to a version for development versions
 __version__ = "1.0.0" + "-dev"

truelearn/_constraint.py

@@ -1,4 +1,4 @@
-from typing import Any, Callable, List, Optional
+from typing import Any, Callable, Optional
 
 from truelearn.base import BaseClassifier
 from truelearn.errors import TrueLearnTypeError, TrueLearnValueError
@@ -72,7 +72,7 @@ def __init__(self, *value_constraints: Any, vtype: type = object):
             vtype:
                 The type of the given values. Defaults to object.
                 This is typically used if the type constraint of the parameter
-                supports multuple types, and you only want to check the value
+                supports multiple types, and you only want to check the value
                 for one of the types listed in the type constraint.
         """
         self.vtype = vtype
@@ -167,16 +167,16 @@ class Range:
 
     def __init__(
         self,
-        gt: Optional[List] = None,
-        ge: Optional[List] = None,
-        le: Optional[List] = None,
-        lt: Optional[List] = None,
+        gt: Optional[float] = None,
+        ge: Optional[float] = None,
+        le: Optional[float] = None,
+        lt: Optional[float] = None,
     ):
         """Init a Range object."""
-        self.greater = gt or []
-        self.greater_or_equal = ge or []
-        self.less_or_equal = le or []
-        self.less = lt or []
+        self.greater = gt
+        self.greater_or_equal = ge
+        self.less_or_equal = le
+        self.less = lt
 
     def __repr__(self) -> str:
         """Get a description of the range object.
@@ -190,7 +190,7 @@ def __repr__(self) -> str:
             symbols,
             [self.greater_or_equal, self.greater, self.less_or_equal, self.less],
         ):
-            if not val:
+            if val is None:
                 continue
             fmt_strs.append(f"{symbol}{val}")
         return f"Range({', '.join(fmt_strs)})"
@@ -206,8 +206,8 @@ def __eq__(self, other):
             Whether the value is within the range.
         """
         return (
-            all(other > num for num in self.greater)
-            and all(other >= num for num in self.greater_or_equal)
-            and all(other <= num for num in self.less_or_equal)
-            and all(other < num for num in self.less)
+            (self.greater is None or other > self.greater)
+            and (self.greater_or_equal is None or other >= self.greater_or_equal)
+            and (self.less_or_equal is None or other <= self.less_or_equal)
+            and (self.less is None or other < self.less)
         )

truelearn/base.py

@@ -71,7 +71,7 @@ def get_params(self, deep: bool = True) -> Dict[str, Any]:
         Args:
             deep:
                 If True, will return the parameters for this Classifier and
-                contained sub-objects that inherits BaseClassifier class.
+                contained sub-objects that inherit BaseClassifier class.
 
         Returns:
             A dict mapping variable names to the corresponding objects.
@@ -113,9 +113,9 @@ def set_params(self, **args) -> Self:
 
         Raises:
             TrueLearnTypeError:
-                Types of parameters does not satisfy their constraints.
+                Types of parameters do not satisfy their constraints.
             TrueLearnValueError:
-                Values of parameters does not satisfy their constraints.
+                Values of parameters do not satisfy their constraints.
             InvalidArgumentError:
                 If the given argument name is not in the class.
         """
@@ -175,9 +175,9 @@ def _validate_params(self) -> None:
 
         Raises:
             TrueLearnTypeError:
-                Types of parameters does not satisfy their constraints.
+                Types of parameters do not satisfy their constraints.
             TrueLearnValueError:
-                Values of parameters does not satisfy their constraints.
+                Values of parameters do not satisfy their constraints.
         """
         for (
             param_name,

truelearn/datasets/_peek.py

@@ -86,7 +86,7 @@ def __call__(
 
 
 def __sanity_check(train_limit: Optional[int], test_limit: Optional[int]):
-    """Check if train_limit and test_limit is valid.
+    """Check if train_limit and test_limit are valid.
 
     Args:
         train_limit:
@@ -211,7 +211,7 @@ def __restructure_data(
 
     This function extracts the time, session (learner_id),
     topics, and label from the data, and constructs the appropriate
-    the model for these data.
+    model for this data.
 
     Args:
         filepath:

truelearn/learning/_base.py

@@ -149,11 +149,11 @@ class InterestNoveltyKnowledgeBaseClassifier(BaseClassifier):
     _parameter_constraints: Dict[str, Any] = {
         **BaseClassifier._parameter_constraints,
         "learner_model": TypeConstraint(LearnerModel),
-        "threshold": [TypeConstraint(float), ValueConstraint(Range(ge=[0], le=[1]))],
+        "threshold": [TypeConstraint(float), ValueConstraint(Range(ge=0, le=1))],
         "init_skill": TypeConstraint(float),
         "def_var": [
             TypeConstraint(float),
-            ValueConstraint(Range(gt=[0])),
+            ValueConstraint(Range(gt=0)),
         ],
         "tau": TypeConstraint(float),
         "beta": TypeConstraint(float),
@@ -162,11 +162,11 @@ class InterestNoveltyKnowledgeBaseClassifier(BaseClassifier):
         "draw_proba_static": [
             TypeConstraint(float, type(None)),
             FuncConstraint(draw_proba_static_constraint),
-            ValueConstraint(Range(ge=[0], le=[1]), vtype=float),
+            ValueConstraint(Range(ge=0, le=1), vtype=float),
         ],
         "draw_proba_factor": [
             TypeConstraint(float),
-            ValueConstraint(Range(ge=[0])),
+            ValueConstraint(Range(ge=0)),
         ],
     }
 

truelearn/learning/_engage_classifier.py

@@ -6,15 +6,15 @@
 
 
 class EngageClassifier(BaseClassifier):
-    """A Classifier that always makes positive prediction.
+    """A Classifier that always makes a positive prediction.
 
     Examples:
         >>> from truelearn.learning import EngageClassifier
         >>> from truelearn.models import EventModel
         >>> engage = EngageClassifier()
         >>> engage
         EngageClassifier()
-        >>> # prepare event model with empty knowledge
+        >>> # prepare an event model with empty knowledge
         >>> event = EventModel()
         >>> engage.fit(event, False)
         EngageClassifier()

truelearn/learning/_ink_classifier.py

@@ -18,7 +18,7 @@ class INKClassifier(BaseClassifier):
     During the training process, the meta-classifier individually trains
     the KnowledgeClassifier and the InterestClassifier. After that, the
     meta-classifier trains a set of weights by again using the ideas of team matching.
-    One team consists of the weights of the knowledge, interest and bias and
+    One team consists of the weights of the knowledge, interest and bias, and
     the other team consists of the threshold. Then, the meta-classifier
     uses the given label to adjust the weights accordingly.
 
@@ -39,7 +39,7 @@ class INKClassifier(BaseClassifier):
         >>> meta_weights = LearnerMetaWeights(novelty_weights=weights)
         >>> ink_classifier = INKClassifier(learner_meta_weights=meta_weights)
         >>>
-        >>> # prepare event model
+        >>> # prepare an event model
         >>> knowledges = [
         ...     Knowledge({1: KnowledgeComponent(mean=0.15, variance=1e-9)}),
         ...     Knowledge({
@@ -115,15 +115,15 @@ def __init__(
                 The dynamic factor of learner's learning process.
                 It's used to avoid the halting of the learning process.
             greedy:
-                A bool indicating whether the meta-learning should
+                A bool indicating whether meta-learning should
                 take the greedy approach. In the greedy approach,
                 only incorrect predictions lead to the update of the weights.
 
         Raises:
             TrueLearnTypeError:
-                Types of parameters does not satisfy their constraints.
+                Types of parameters do not satisfy their constraints.
             TrueLearnValueError:
-                Values of parameters does not satisfy their constraints.
+                Values of parameters do not satisfy their constraints.
         """
         self._novelty_classifier = novelty_classifier or NoveltyClassifier()
         self._interest_classifier = interest_classifier or InterestClassifier()
@@ -219,12 +219,12 @@ def __update_weights(
                 The predicted probability of the learner's engagement by using
                 InterestClassifier.
             pred_actual:
-                Whether the learner actually engage in the given event. This value is
+                Whether the learner actually engages in the given event. This value is
                 either 0 or 1.
         """
         cur_pred = self.predict(x)
 
-        # if prediction is correct and greedy, don't train
+        # if the prediction is correct and greedy, don't train
         if self._greedy and cur_pred == pred_actual:
             return
 
@@ -251,7 +251,7 @@ def __update_weights(
             ),
         )
 
-        if pred_actual:  # weights need to be larger than threshold
+        if pred_actual:  # weights need to be larger than a threshold
             new_team_experts, _ = env.rate(
                 [team_experts, team_threshold],
                 weights=[(pred_novelty, pred_interest, 1), (1,)],

truelearn/learning/_interest_classifier.py

@@ -26,8 +26,8 @@ class InterestClassifier(InterestNoveltyKnowledgeBaseClassifier):
 
     During the training process, the classifier uses the idea of game matching
     established in TrueSkill. It represents the learning process as a game of two teams.
-    One team consists of all the knowledge components from the learnable unit and
-    the other consist of all the corresponding knowledge components from the learner.
+    One team consists of all the knowledge components from the learnable unit, and
+    the other consists of all the corresponding knowledge components from the learner.
     Then, the classifier uses the given label to update the knowledge components of
     the learner.
 
@@ -37,7 +37,7 @@ class InterestClassifier(InterestNoveltyKnowledgeBaseClassifier):
     the learner wins the game.
 
     During the prediction process, the classifier uses cumulative density function
-    of normal distribution to calculate the probability that the learner engage in
+    of normal distribution to calculate the probability that the learner engages in
     the learning event. It calculates the probability of getting x in a
     Normal Distribution N(0, std) where x is the difference between
     the learner's skill (mean) and the learnable unit's skill (mean) and
@@ -52,7 +52,7 @@ class InterestClassifier(InterestNoveltyKnowledgeBaseClassifier):
         >>> interest_classifier = InterestClassifier()
         >>> interest_classifier
         InterestClassifier()
-        >>> # prepare event model
+        >>> # prepare an event model
         >>> knowledges = [
         ...     Knowledge({1: KnowledgeComponent(mean=0.57, variance=1e-9)}),
         ...     Knowledge({
@@ -90,7 +90,7 @@ class InterestClassifier(InterestNoveltyKnowledgeBaseClassifier):
         "decay_func_type": ValueConstraint("short", "long"),
         "decay_func_factor": [
             TypeConstraint(float),
-            ValueConstraint(Range(ge=[0])),
+            ValueConstraint(Range(ge=0)),
         ],
     }
 
@@ -121,11 +121,11 @@ def __init__(
             init_skill:
                 The initial mean of the learner's knowledge component.
                 It will be used when the learner interacts with knowledge components
-                at its first time.
+                for the first time.
             def_var:
                 The initial variance (>0) of the learner's knowledge component.
                 It will be used when the learner interacts with knowledge components
-                at its first time.
+                for the first time.
             beta:
                 The distance which guarantees about 76% chance of winning.
                 The recommended value is sqrt(def_var) / 2.
@@ -150,13 +150,13 @@ def __init__(
             decay_func_factor:
                 A factor (>=0) that will be used in both short and long
                 interest decay function. Defaults to 0, which disables
-                the interest decay function .
+                the interest decay function.
 
         Raises:
             TrueLearnTypeError:
-                Types of parameters does not satisfy their constraints.
+                Types of parameters do not satisfy their constraints.
             TrueLearnValueError:
-                Values of parameters does not satisfy their constraints.
+                Values of parameters do not satisfy their constraints.
         """
         super().__init__(
             learner_model=learner_model,
@@ -165,7 +165,7 @@ def __init__(
             def_var=def_var,
             tau=tau,
             beta=beta,
-            # learner always wins in interest classifier
+            # learner always wins in interest classifier,
             # hence we should always update regardless of the actual label
             # positive_only should be disabled to ensure the update method
             # is always called
@@ -219,7 +219,7 @@ def _generate_ratings(
             event_time:
                 An optional float representing the event time.
             _y:
-                A bool indicating whether the learner engage in
+                A bool indicating whether the learner engages in
                 the learning event.
 
         Returns:

truelearn/learning/_knowledge_classifier.py

@@ -16,8 +16,8 @@ class KnowledgeClassifier(InterestNoveltyKnowledgeBaseClassifier):
 
     During the training process, the classifier uses the idea of game matching
     established in TrueSkill. It represents the learning process as a game of two teams.
-    One team consists of all the knowledge components from the learnable unit and
-    the other consist of all the corresponding knowledge components from the learner.
+    One team consists of all the knowledge components from the learnable unit, and
+    the other consists of all the corresponding knowledge components from the learner.
     Then, the classifier uses the given label to update the knowledge components
     of the learner.
 
@@ -27,7 +27,7 @@ class KnowledgeClassifier(InterestNoveltyKnowledgeBaseClassifier):
     means that the learner wins the game.
 
     During the prediction process, the classifier uses cumulative density function of
-    normal distribution to calculate the probability that the learner engage
+    normal distribution to calculate the probability that the learner engages
     in the learning event. It calculates the probability of getting x in a
     Normal Distribution N(0, std) where x is the difference between
     the learner's skill (mean) and the learnable unit's skill (mean) and
@@ -42,7 +42,7 @@ class KnowledgeClassifier(InterestNoveltyKnowledgeBaseClassifier):
         >>> knowledge_classifier = KnowledgeClassifier()
         >>> knowledge_classifier
         KnowledgeClassifier()
-        >>> # prepare event model
+        >>> # prepare an event model
         >>> knowledges = [
         ...     Knowledge({1: KnowledgeComponent(mean=0.57, variance=1e-9)}),
         ...     Knowledge({
@@ -101,11 +101,11 @@ def __init__(
             init_skill:
                 The initial mean of the learner's knowledge component.
                 It will be used when the learner interacts with knowledge components
-                at its first time.
+                for the first time.
             def_var:
                 The initial variance (>0) of the learner's knowledge component.
                 It will be used when the learner interacts with knowledge components
-                at its first time.
+                for the first time.
             beta:
                 The distance which guarantees about 76% chance of winning.
                 The recommended value is sqrt(def_var) / 2.
@@ -130,13 +130,13 @@ def __init__(
 
         Raises:
             TrueLearnTypeError:
-                Types of parameters does not satisfy their constraints.
+                Types of parameters do not satisfy their constraints.
             TrueLearnValueError:
-                Values of parameters does not satisfy their constraints.
+                Values of parameters do not satisfy their constraints.
         """
         # the knowledge classifier doesn't rely on the draw probability
-        # it utilizes different assumptions
-        # so, we set draw probability to a very small value to avoid its impact
+        # it utilises different assumptions, so
+        # we set draw probability to a very small value to avoid its impact
         super().__init__(
             learner_model=learner_model,
             threshold=threshold,