edsl 0.1.14__py3-none-any.whl → 0.1.40__py3-none-any.whl

edsl/surveys/RuleCollection.py

@@ -1,42 +1,68 @@
-from typing import List, Union, Any
-from collections import defaultdict, UserList
+"""A collection of rules for a survey."""
 
-from edsl.exceptions import (
+from typing import List, Union, Any, Optional
+from collections import defaultdict, UserList, namedtuple
+
+from edsl.exceptions.surveys import (
     SurveyRuleCannotEvaluateError,
     SurveyRuleCollectionHasNoRulesAtNodeError,
 )
-from edsl.utilities.interface import print_table_with_rich
+
 from edsl.surveys.Rule import Rule
 from edsl.surveys.base import EndOfSurvey
 from edsl.surveys.DAG import DAG
 
-from graphlib import TopologicalSorter
-
-from collections import namedtuple
 
 NextQuestion = namedtuple(
     "NextQuestion", "next_q, num_rules_found, expressions_evaluating_to_true, priority"
 )
 
-## We're going to need the survey object itself
-## so we know how long the survey is, unless we move
-
 
 class RuleCollection(UserList):
-    "A collection of rules for a particular survey"
+    """A collection of rules for a particular survey."""
+
+    def __init__(self, num_questions: Optional[int] = None, rules: List[Rule] = None):
+        """Initialize the RuleCollection object.
 
-    def __init__(self, num_questions: int = None, rules: List[Rule] = None):
+        :param num_questions: The number of questions in the survey.
+        :param rules: A list of Rule objects.
+        """
         super().__init__(rules or [])
         self.num_questions = num_questions
 
     def __repr__(self):
-        """
-        >>> rule_collection = RuleCollection.example()
-        >>> _ = eval(repr(rule_collection))
+        """Return a string representation of the RuleCollection object.
+
+        Example usage:
+
+        .. code-block:: python
+
+            rule_collection = RuleCollection.example()
+            _ = eval(repr(rule_collection))
+
         """
         return f"RuleCollection(rules={self.data}, num_questions={self.num_questions})"
 
-    def to_dict(self):
+    def to_dataset(self):
+        """Return a Dataset object representation of the RuleCollection object."""
+        from edsl.results.Dataset import Dataset
+
+        keys = ["current_q", "expression", "next_q", "priority", "before_rule"]
+        rule_list = {}
+        for rule in sorted(self, key=lambda r: r.current_q):
+            for k in keys:
+                rule_list.setdefault(k, []).append(getattr(rule, k))
+
+        return Dataset([{k: v} for k, v in rule_list.items()])
+
+    def _repr_html_(self):
+        """Return an HTML representation of the RuleCollection object."""
+        from edsl.results.Dataset import Dataset
+
+        return self.to_dataset()._repr_html_()
+
+    def to_dict(self, add_edsl_version=True):
+        """Create a dictionary representation of the RuleCollection object."""
         return {
             "rules": [rule.to_dict() for rule in self],
             "num_questions": self.num_questions,
@@ -44,6 +70,14 @@ class RuleCollection(UserList):
 
     @classmethod
     def from_dict(cls, rule_collection_dict):
+        """Create a RuleCollection object from a dictionary.
+
+        >>> rule_collection = RuleCollection.example()
+        >>> rule_collection_dict = rule_collection.to_dict()
+        >>> new_rule_collection = RuleCollection.from_dict(rule_collection_dict)
+        >>> repr(new_rule_collection) == repr(rule_collection)
+        True
+        """
         rules = [
             Rule.from_dict(rule_dict) for rule_dict in rule_collection_dict["rules"]
         ]
@@ -52,44 +86,119 @@ class RuleCollection(UserList):
         new_rc.num_questions = num_questions
         return new_rc
 
-    def add_rule(self, rule: Rule):
-        """Adds a rule to a survey. If it's not, return human-readable complaints"""
+    def add_rule(self, rule: Rule) -> None:
+        """Add a rule to a survey.
+
+        >>> rule_collection = RuleCollection()
+        >>> rule_collection.add_rule(Rule(current_q=1, expression="q1 == 'yes'", next_q=3, priority=1, question_name_to_index={'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4}))
+        >>> len(rule_collection)
+        1
+
+        >>> rule_collection = RuleCollection()
+        >>> r = Rule(current_q=1, expression="True", next_q=3, priority=1, question_name_to_index={'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4}, before_rule = True)
+        >>> rule_collection.add_rule(r)
+        >>> rule_collection[0] == r
+        True
+        >>> len(rule_collection.applicable_rules(1, before_rule=True))
+        1
+        >>> len(rule_collection.applicable_rules(1, before_rule=False))
+        0
+        """
         self.append(rule)
 
     def show_rules(self) -> None:
-        keys = ["current_q", "expression", "next_q", "priority"]
-        rule_list = []
-        for rule in sorted(self, key=lambda r: r.current_q):
-            rule_list.append({k: getattr(rule, k) for k in keys})
+        """Print the rules in a table.
+
+
+        .. code-block:: python
+
+        rule_collection = RuleCollection.example()
+        rule_collection.show_rules()
+        ┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
+        ┃ current_q ┃ expression  ┃ next_q ┃ priority ┃ before_rule ┃
+        ┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
+        │ 1         │ q1 == 'yes' │ 3      │ 1        │ False       │
+        │ 1         │ q1 == 'no'  │ 2      │ 1        │ False       │
+        └───────────┴─────────────┴────────┴──────────┴─────────────┘
+        """
+        return self.to_dataset()
 
-        print_table_with_rich(rule_list)
+    def skip_question_before_running(self, q_now: int, answers: dict[str, Any]) -> bool:
+        """Determine if a question should be skipped before running the question.
 
-    def applicable_rules(self, q_now: int) -> list:
-        """Which rules apply at the current node?
+        :param q_now: The current question index.
+        :param answers: The answers to the survey questions.
+
+        >>> rule_collection = RuleCollection()
+        >>> r = Rule(current_q=1, expression="True", next_q=2, priority=1, question_name_to_index={}, before_rule = True)
+        >>> rule_collection.add_rule(r)
+        >>> rule_collection.skip_question_before_running(1, {})
+        True
+
+        >>> rule_collection = RuleCollection()
+        >>> r = Rule(current_q=1, expression="False", next_q=2, priority=1, question_name_to_index={}, before_rule = True)
+        >>> rule_collection.add_rule(r)
+        >>> rule_collection.skip_question_before_running(1, {})
+        False
+
+        """
+        for rule in self.applicable_rules(q_now, before_rule=True):
+            if rule.evaluate(answers):
+                return True
+        return False
+
+    def applicable_rules(self, q_now: int, before_rule: bool = False) -> list:
+        """Show the rules that apply at the current node.
+
+        :param q_now: The current question index.
+        :param before_rule: If True, return rules that are of the type that apply before the question is asked.
+
+        Example usage:
 
         >>> rule_collection = RuleCollection.example()
         >>> rule_collection.applicable_rules(1)
-        [Rule(current_q=1, expression="q1 == 'yes'", next_q=3, priority=1, question_name_to_index={'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4}), Rule(current_q=1, expression="q1 == 'no'", next_q=2, priority=1, question_name_to_index={'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4})]
+        [Rule(current_q=1, expression="q1 == 'yes'", next_q=3, priority=1, question_name_to_index={'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4}, before_rule=False), Rule(current_q=1, expression="q1 == 'no'", next_q=2, priority=1, question_name_to_index={'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4}, before_rule=False)]
+
+        The default is that the rule is applied after the question is asked.
+        If we want to see the rules that apply before the question is asked, we can set before_rule=True.
+
+        .. code-block:: python
 
-        More than one rule can apply. E.g., suppose we are at node 1.
+            rule_collection = RuleCollection.example()
+            rule_collection.applicable_rules(1)
+            [Rule(current_q=1, expression="q1 == 'yes'", next_q=3, priority=1, question_name_to_index={'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4}), Rule(current_q=1, expression="q1 == 'no'", next_q=2, priority=1, question_name_to_index={'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4})]
+
+        More than one rule can apply. For example, suppose we are at node 1.
         We could have three rules:
         1. "q1 == 'a' ==> 3
         2. "q1 == 'b' ==> 4
         3. "q1 == 'c' ==> 5
         """
-        return [rule for rule in self if rule.current_q == q_now]
+        return [
+            rule
+            for rule in self
+            if rule.current_q == q_now and rule.before_rule == before_rule
+        ]
 
     def next_question(self, q_now: int, answers: dict[str, Any]) -> NextQuestion:
-        """Find the next question by index, given the rule collection"""
-        # what rules apply at the current node?
+        """Find the next question by index, given the rule collection.
+
+        This rule is applied after the question is answered.
 
-        # tracking
+        :param q_now: The current question index.
+        :param answers: The answers to the survey questions so far, including the current question.
+
+        >>> rule_collection = RuleCollection.example()
+        >>> rule_collection.next_question(1, {'q1': 'yes'})
+        NextQuestion(next_q=3, num_rules_found=2, expressions_evaluating_to_true=1, priority=1)
+
+        """
         expressions_evaluating_to_true = 0
         next_q = None
         highest_priority = -2  # start with -2 to 'pick up' the default rule added
         num_rules_found = 0
 
-        for rule in self.applicable_rules(q_now):
+        for rule in self.applicable_rules(q_now, before_rule=False):
             num_rules_found += 1
             try:
                 if rule.evaluate(answers):  # evaluates to True
@@ -105,36 +214,55 @@ class RuleCollection(UserList):
                 f"No rules found for question {q_now}"
             )
 
+        ## Now we need to check if the *next question* has any 'before; rules that we should follow
+        for rule in self.applicable_rules(next_q, before_rule=True):
+            if rule.evaluate(answers):  # rule evaluates to True
+                return self.next_question(next_q, answers)
+
         return NextQuestion(
             next_q, num_rules_found, expressions_evaluating_to_true, highest_priority
         )
 
     @property
     def non_default_rules(self) -> List[Rule]:
-        """Returns all rules that are not the default rule"
+        """Return all rules that are not the default rule.
+
         >>> rule_collection = RuleCollection.example()
         >>> len(rule_collection.non_default_rules)
         2
+
+        Example usage:
+
+        .. code-block:: python
+
+            rule_collection = RuleCollection.example()
+            len(rule_collection.non_default_rules)
+            2
+
         """
         return [rule for rule in self if rule.priority > -1]
 
     def keys_between(self, start_q, end_q, right_inclusive=True):
-        """Returns a list of all question indices between start_q and end_q
-        >>> rule_collection = RuleCollection(num_questions=5)
-        >>> rule_collection.keys_between(1, 3)
-        [2, 3]
-        >>> rule_collection.keys_between(1, 4)
-        [2, 3, 4]
-        >>> rule_collection.keys_between(1, EndOfSurvey, right_inclusive=False)
-        [2, 3]
-        """
+        """Return a list of all question indices between start_q and end_q.
 
-        # If it's the end of the survey, all questions between the start_q and the end of the survey
-        # now depend on the start_q
+        Example usage:
+
+        .. code-block:: python
+
+            rule_collection = RuleCollection(num_questions=5)
+            rule_collection.keys_between(1, 3)
+            [2, 3]
+            rule_collection.keys_between(1, 4)
+            [2, 3, 4]
+            rule_collection.keys_between(1, EndOfSurvey, right_inclusive=False)
+            [2, 3]
+
+        """
+        # If it's the end of the survey, all questions between the start_q and the end of the survey now depend on the start_q
         if end_q == EndOfSurvey:
             if self.num_questions is None:
                 raise ValueError(
-                    "Cannot determine DAG when EndOfSurvey and when num_questions is not known"
+                    "Cannot determine DAG when EndOfSurvey and when num_questions is not known."
                 )
             end_q = self.num_questions - 1
 
@@ -145,7 +273,8 @@ class RuleCollection(UserList):
     @property
     def dag(self) -> dict:
         """
-        Finds the DAG of the survey, based on the skip logic.
+        Find the DAG of the survey, based on the skip logic.
+
         Keys are children questions; the list of values are nodes that must be answered first
 
         Rules are designated at the current question and then direct where
@@ -154,28 +283,78 @@ class RuleCollection(UserList):
         the current and destination nodes are also included as keys, as they will depend
         on the answer to the focal node as well.
 
-        ## If we have a rule that says "if q1 == 'yes', go to q3",
-        ## Then q3 depends on q1, but so does q2
-        ## So the DAG would be {3: [1], 2: [1]}
+        For exmaple, if we have a rule that says "if q1 == 'yes', go to q3", then q3 depends on q1, but so does q2.
+        So the DAG would be {3: [1], 2: [1]}.
+
+        Example usage:
+
+        .. code-block:: python
+
+            rule_collection = RuleCollection(num_questions=5)
+            qn2i = {'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4}
+            rule_collection.add_rule(Rule(current_q=1, expression="q1 == 'yes'", next_q=3, priority=1,  question_name_to_index = qn2i))
+            rule_collection.add_rule(Rule(current_q=1, expression="q1 == 'no'", next_q=2, priority=1, question_name_to_index = qn2i))
+            rule_collection.dag
+            {2: {1}, 3: {1}}
 
-        >>> rule_collection = RuleCollection(num_questions=5)
-        >>> qn2i = {'q1': 1, 'q2': 2, 'q3': 3, 'q4': 4}
-        >>> rule_collection.add_rule(Rule(current_q=1, expression="q1 == 'yes'", next_q=3, priority=1,  question_name_to_index = qn2i))
-        >>> rule_collection.add_rule(Rule(current_q=1, expression="q1 == 'no'", next_q=2, priority=1, question_name_to_index = qn2i))
-        >>> rule_collection.dag
-        {2: {1}, 3: {1}}
         """
         children_to_parents = defaultdict(set)
-        # we are only interested in non-default rules. Default rules are those
+        # We are only interested in non-default rules. Default rules are those
         # that just go to the next question, so they don't add any dependencies
+
+        ## I think for a skip-question, the potenially-skippable question
+        ## depends on all the other questions bein answered first.
         for rule in self.non_default_rules:
-            current_q, next_q = rule.current_q, rule.next_q
-            for q in self.keys_between(current_q, next_q):
-                children_to_parents[q].add(current_q)
+            if not rule.before_rule:
+                # for a regular rule, the next question depends on the current question answer
+                current_q, next_q = rule.current_q, rule.next_q
+                for q in self.keys_between(current_q, next_q):
+                    children_to_parents[q].add(current_q)
+            else:
+                # for the 'before rule' skipping depends on all previous answers.
+                focal_q = rule.current_q
+                for q in range(0, focal_q):
+                    children_to_parents[focal_q].add(q)
+
         return DAG(dict(sorted(children_to_parents.items())))
 
+    def detect_cycles(self):
+        """
+        Detect cycles in the survey rules using depth-first search.
+
+        :return: A list of cycles if any are found, otherwise an empty list.
+        """
+        dag = self.dag
+        visited = set()
+        path = []
+        cycles = []
+
+        def dfs(node):
+            if node in path:
+                cycle = path[path.index(node) :]
+                cycles.append(cycle + [node])
+                return
+
+            if node in visited:
+                return
+
+            visited.add(node)
+            path.append(node)
+
+            for child in dag.get(node, []):
+                dfs(child)
+
+            path.pop()
+
+        for node in dag:
+            if node not in visited:
+                dfs(node)
+
+        return cycles
+
     @classmethod
     def example(cls):
+        """Create an example RuleCollection object."""
         qn2i = {"q1": 1, "q2": 2, "q3": 3, "q4": 4}
         return cls(
             num_questions=5,
@@ -199,7 +378,8 @@ class RuleCollection(UserList):
 
 
 if __name__ == "__main__":
-    # pass
     import doctest
 
-    doctest.testmod()
+    doctest.testmod(optionflags=doctest.ELLIPSIS)
+
+    print(RuleCollection.example()._repr_html_())

edsl/surveys/RuleManager.py

@@ -0,0 +1,172 @@
+from typing import Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from edsl.questions.QuestionBase import QuestionBase
+
+from edsl.surveys.Rule import Rule
+from .base import RulePriority, EndOfSurvey
+from edsl.exceptions.surveys import SurveyError, SurveyCreationError
+
+
+class ValidatedString(str):
+    def __new__(cls, content):
+        if "<>" in content:
+            raise SurveyCreationError(
+                "The expression contains '<>', which is not allowed. You probably mean '!='."
+            )
+        return super().__new__(cls, content)
+
+
+class RuleManager:
+    def __init__(self, survey):
+        self.survey = survey
+
+    def _get_question_index(
+        self, q: Union["QuestionBase", str, EndOfSurvey.__class__]
+    ) -> Union[int, EndOfSurvey.__class__]:
+        """Return the index of the question or EndOfSurvey object.
+
+        :param q: The question or question name to get the index of.
+
+        It can handle it if the user passes in the question name, the question object, or the EndOfSurvey object.
+
+        >>> from edsl.questions import QuestionFreeText
+        >>> from edsl import Survey
+        >>> s = Survey.example()
+        >>> s._get_question_index("q0")
+        0
+
+        This doesnt' work with questions that don't exist:
+
+        >>> s._get_question_index("poop")
+        Traceback (most recent call last):
+        ...
+        edsl.exceptions.surveys.SurveyError: Question name poop not found in survey. The current question names are {'q0': 0, 'q1': 1, 'q2': 2}.
+        ...
+        """
+        if q == EndOfSurvey:
+            return EndOfSurvey
+        else:
+            question_name = q if isinstance(q, str) else q.question_name
+            if question_name not in self.survey.question_name_to_index:
+                raise SurveyError(
+                    f"""Question name {question_name} not found in survey. The current question names are {self.survey.question_name_to_index}."""
+                )
+            return self.survey.question_name_to_index[question_name]
+
+    def _get_new_rule_priority(
+        self, question_index: int, before_rule: bool = False
+    ) -> int:
+        """Return the priority for the new rule.
+
+        :param question_index: The index of the question to add the rule to.
+        :param before_rule: Whether the rule is evaluated before the question is answered.
+
+        >>> from edsl import Survey
+        >>> s = Survey.example()
+        >>> RuleManager(s)._get_new_rule_priority(0)
+        1
+        """
+        current_priorities = [
+            rule.priority
+            for rule in self.survey.rule_collection.applicable_rules(
+                question_index, before_rule
+            )
+        ]
+        if len(current_priorities) == 0:
+            return RulePriority.DEFAULT.value + 1
+
+        max_priority = max(current_priorities)
+        # newer rules take priority over older rules
+        new_priority = (
+            RulePriority.DEFAULT.value
+            if len(current_priorities) == 0
+            else max_priority + 1
+        )
+        return new_priority
+
+    def add_rule(
+        self,
+        question: Union["QuestionBase", str],
+        expression: str,
+        next_question: Union["QuestionBase", str, int],
+        before_rule: bool = False,
+    ) -> "Survey":
+        """
+        Add a rule to a Question of the Survey with the appropriate priority.
+
+        :param question: The question to add the rule to.
+        :param expression: The expression to evaluate.
+        :param next_question: The next question to go to if the rule is true.
+        :param before_rule: Whether the rule is evaluated before the question is answered.
+
+
+        - The last rule added for the question will have the highest priority.
+        - If there are no rules, the rule added gets priority -1.
+        """
+        question_index = self.survey._get_question_index(question)  # Fix
+
+        # Might not have the name of the next question yet
+        if isinstance(next_question, int):
+            next_question_index = next_question
+        else:
+            next_question_index = self._get_question_index(next_question)
+
+        new_priority = self._get_new_rule_priority(question_index, before_rule)  # fix
+
+        self.survey.rule_collection.add_rule(
+            Rule(
+                current_q=question_index,
+                expression=expression,
+                next_q=next_question_index,
+                question_name_to_index=self.survey.question_name_to_index,
+                priority=new_priority,
+                before_rule=before_rule,
+            )
+        )
+
+        return self.survey
+
+    def add_stop_rule(
+        self, question: Union["QuestionBase", str], expression: str
+    ) -> "Survey":
+        """Add a rule that stops the survey.
+        The rule is evaluated *after* the question is answered. If the rule is true, the survey ends.
+
+        :param question: The question to add the stop rule to.
+        :param expression: The expression to evaluate.
+
+        If this rule is true, the survey ends.
+
+        Here, answering "yes" to q0 ends the survey:
+
+        >>> from edsl import Survey
+        >>> s = Survey.example().add_stop_rule("q0", "q0 == 'yes'")
+        >>> s.next_question("q0", {"q0": "yes"})
+        EndOfSurvey
+
+        By comparison, answering "no" to q0 does not end the survey:
+
+        >>> s.next_question("q0", {"q0": "no"}).question_name
+        'q1'
+
+        >>> s.add_stop_rule("q0", "q1 <> 'yes'")
+        Traceback (most recent call last):
+        ...
+        edsl.exceptions.surveys.SurveyCreationError: The expression contains '<>', which is not allowed. You probably mean '!='.
+        ...
+        """
+        expression = ValidatedString(expression)
+        prior_question_appears = False
+        for prior_question in self.survey.questions:
+            if prior_question.question_name in expression:
+                prior_question_appears = True
+
+        if not prior_question_appears:
+            import warnings
+
+            warnings.warn(
+                f"The expression {expression} does not contain any prior question names. This is probably a mistake."
+            )
+        self.survey.add_rule(question, expression, EndOfSurvey)
+        return self.survey

edsl/surveys/Simulator.py

@@ -0,0 +1,75 @@
+from typing import Callable
+
+
+class Simulator:
+    def __init__(self, survey):
+        self.survey = survey
+
+    @classmethod
+    def random_survey(cls):
+        """Create a random survey."""
+        from edsl.questions import QuestionMultipleChoice, QuestionFreeText
+        from random import choice
+        from edsl.surveys.Survey import Survey
+
+        num_questions = 10
+        questions = []
+        for i in range(num_questions):
+            if choice([True, False]):
+                q = QuestionMultipleChoice(
+                    question_text="nothing",
+                    question_name="q_" + str(i),
+                    question_options=list(range(3)),
+                )
+                questions.append(q)
+            else:
+                questions.append(
+                    QuestionFreeText(
+                        question_text="nothing", question_name="q_" + str(i)
+                    )
+                )
+        s = Survey(questions)
+        start_index = choice(range(num_questions - 1))
+        end_index = choice(range(start_index + 1, 10))
+        s = s.add_rule(f"q_{start_index}", "True", f"q_{end_index}")
+        question_to_delete = choice(range(num_questions))
+        s.delete_question(f"q_{question_to_delete}")
+        return s
+
+    def simulate(self) -> dict:
+        """Simulate the survey and return the answers."""
+        i = self.survey.gen_path_through_survey()
+        q = next(i)
+        num_passes = 0
+        while True:
+            num_passes += 1
+            try:
+                answer = q._simulate_answer()
+                q = i.send({q.question_name: answer["answer"]})
+            except StopIteration:
+                break
+
+            if num_passes > 100:
+                print("Too many passes.")
+                raise Exception("Too many passes.")
+        return self.survey.answers
+
+    def create_agent(self) -> "Agent":
+        """Create an agent from the simulated answers."""
+        answers_dict = self.survey.simulate()
+        from edsl.agents.Agent import Agent
+
+        def construct_answer_dict_function(traits: dict) -> Callable:
+            def func(self, question: "QuestionBase", scenario=None):
+                return traits.get(question.question_name, None)
+
+            return func
+
+        return Agent(traits=answers_dict).add_direct_question_answering_method(
+            construct_answer_dict_function(answers_dict)
+        )
+
+    def simulate_results(self) -> "Results":
+        """Simulate the survey and return the results."""
+        a = self.create_agent()
+        return self.survey.by([a]).run()