edsl 0.1.39.dev2__py3-none-any.whl → 0.1.39.dev3__py3-none-any.whl

edsl/surveys/EditSurvey.py

@@ -1,221 +0,0 @@
-from typing import Union, Optional, TYPE_CHECKING
-from edsl.exceptions.surveys import SurveyError
-
-if TYPE_CHECKING:
-    from edsl.questions.QuestionBase import QuestionBase
-
-from edsl.exceptions.surveys import SurveyError, SurveyCreationError
-from edsl.surveys.Rule import Rule
-from edsl.surveys.base import RulePriority, EndOfSurvey
-
-
-class EditSurvey:
-    def __init__(self, survey):
-        self.survey = survey
-
-    def move_question(self, identifier: Union[str, int], new_index: int) -> "Survey":
-        if isinstance(identifier, str):
-            if identifier not in self.survey.question_names:
-                raise SurveyError(
-                    f"Question name '{identifier}' does not exist in the survey."
-                )
-            index = self.survey.question_name_to_index[identifier]
-        elif isinstance(identifier, int):
-            if identifier < 0 or identifier >= len(self.survey.questions):
-                raise SurveyError(f"Index {identifier} is out of range.")
-            index = identifier
-        else:
-            raise SurveyError(
-                "Identifier must be either a string (question name) or an integer (question index)."
-            )
-
-        moving_question = self.survey._questions[index]
-
-        new_survey = self.survey.delete_question(index)
-        new_survey.add_question(moving_question, new_index)
-        return new_survey
-
-    def add_question(
-        self, question: "QuestionBase", index: Optional[int] = None
-    ) -> "Survey":
-        if question.question_name in self.survey.question_names:
-            raise SurveyCreationError(
-                f"""Question name '{question.question_name}' already exists in survey. Existing names are {self.survey.question_names}."""
-            )
-        if index is None:
-            index = len(self.survey.questions)
-
-        if index > len(self.survey.questions):
-            raise SurveyCreationError(
-                f"Index {index} is greater than the number of questions in the survey."
-            )
-        if index < 0:
-            raise SurveyCreationError(f"Index {index} is less than 0.")
-
-        interior_insertion = index != len(self.survey.questions)
-
-        # index = len(self.survey.questions)
-        # TODO: This is a bit ugly because the user
-        # doesn't "know" about _questions - it's generated by the
-        # descriptor.
-        self.survey._questions.insert(index, question)
-
-        if interior_insertion:
-            for question_name, old_index in self.survey._pseudo_indices.items():
-                if old_index >= index:
-                    self.survey._pseudo_indices[question_name] = old_index + 1
-
-        self.survey._pseudo_indices[question.question_name] = index
-
-        ## Re-do question_name to index - this is done automatically
-        # for question_name, old_index in self.survey.question_name_to_index.items():
-        #     if old_index >= index:
-        #         self.survey.question_name_to_index[question_name] = old_index + 1
-
-        ## Need to re-do the rule collection and the indices of the questions
-
-        ## If a rule is before the insertion index and next_q is also before the insertion index, no change needed.
-        ## If the rule is before the insertion index but next_q is after the insertion index, increment the next_q by 1
-        ## If the rule is after the insertion index, increment the current_q by 1 and the next_q by 1
-
-        # using index + 1 presumes there is a next question
-        if interior_insertion:
-            for rule in self.survey.rule_collection:
-                if rule.current_q >= index:
-                    rule.current_q += 1
-                if rule.next_q >= index:
-                    rule.next_q += 1
-
-        # add a new rule
-        self.survey.rule_collection.add_rule(
-            Rule(
-                current_q=index,
-                expression="True",
-                next_q=index + 1,
-                question_name_to_index=self.survey.question_name_to_index,
-                priority=RulePriority.DEFAULT.value,
-            )
-        )
-
-        # a question might be added before the memory plan is created
-        # it's ok because the memory plan will be updated when it is created
-        if hasattr(self.survey, "memory_plan"):
-            self.survey.memory_plan.add_question(question)
-
-        return self.survey
-
-    def delete_question(self, identifier: Union[str, int]) -> "Survey":
-        """
-        Delete a question from the survey.
-
-        :param identifier: The name or index of the question to delete.
-        :return: The updated Survey object.
-
-        >>> from edsl import QuestionMultipleChoice, Survey
-        >>> q1 = QuestionMultipleChoice(question_text="Q1", question_options=["A", "B"], question_name="q1")
-        >>> q2 = QuestionMultipleChoice(question_text="Q2", question_options=["C", "D"], question_name="q2")
-        >>> s = Survey().add_question(q1).add_question(q2)
-        >>> _ = s.delete_question("q1")
-        >>> len(s.questions)
-        1
-        >>> _ = s.delete_question(0)
-        >>> len(s.questions)
-        0
-        """
-        if isinstance(identifier, str):
-            if identifier not in self.survey.question_names:
-                raise SurveyError(
-                    f"Question name '{identifier}' does not exist in the survey."
-                )
-            index = self.survey.question_name_to_index[identifier]
-        elif isinstance(identifier, int):
-            if identifier < 0 or identifier >= len(self.survey.questions):
-                raise SurveyError(f"Index {identifier} is out of range.")
-            index = identifier
-        else:
-            raise SurveyError(
-                "Identifier must be either a string (question name) or an integer (question index)."
-            )
-
-        # Remove the question
-        deleted_question = self.survey._questions.pop(index)
-        del self.survey._pseudo_indices[deleted_question.question_name]
-
-        # Update indices
-        for question_name, old_index in self.survey._pseudo_indices.items():
-            if old_index > index:
-                self.survey._pseudo_indices[question_name] = old_index - 1
-
-        # Update rules
-        from .RuleCollection import RuleCollection
-
-        new_rule_collection = RuleCollection()
-        for rule in self.survey.rule_collection:
-            if rule.current_q == index:
-                continue  # Remove rules associated with the deleted question
-            if rule.current_q > index:
-                rule.current_q -= 1
-            if rule.next_q > index:
-                rule.next_q -= 1
-
-            if rule.next_q == index:
-                if index == len(self.survey.questions):
-                    rule.next_q = EndOfSurvey
-                else:
-                    rule.next_q = index
-
-            new_rule_collection.add_rule(rule)
-        self.survey.rule_collection = new_rule_collection
-
-        # Update memory plan if it exists
-        if hasattr(self.survey, "memory_plan"):
-            self.survey.memory_plan.remove_question(deleted_question.question_name)
-
-        return self.survey
-
-    def add_instruction(
-        self, instruction: Union["Instruction", "ChangeInstruction"]
-    ) -> "Survey":
-        """
-        Add an instruction to the survey.
-
-        :param instruction: The instruction to add to the survey.
-
-        >>> from edsl import Instruction
-        >>> from edsl.surveys.Survey import Survey
-        >>> i = Instruction(text="Pay attention to the following questions.", name="intro")
-        >>> s = Survey().add_instruction(i)
-        >>> s._instruction_names_to_instructions
-        {'intro': Instruction(name="intro", text="Pay attention to the following questions.")}
-        >>> s._pseudo_indices
-        {'intro': -0.5}
-        """
-        import math
-
-        if instruction.name in self.survey._instruction_names_to_instructions:
-            raise SurveyCreationError(
-                f"""Instruction name '{instruction.name}' already exists in survey. Existing names are {self.survey._instruction_names_to_instructions.keys()}."""
-            )
-        self.survey._instruction_names_to_instructions[instruction.name] = instruction
-
-        # was the last thing added an instruction or a question?
-        if self.survey._pseudo_indices.last_item_was_instruction:
-            pseudo_index = (
-                self.survey._pseudo_indices.max_pseudo_index
-                + (
-                    math.ceil(self.survey._pseudo_indices.max_pseudo_index)
-                    - self.survey._pseudo_indices.max_pseudo_index
-                )
-                / 2
-            )
-        else:
-            pseudo_index = self.survey._pseudo_indices.max_pseudo_index + 1.0 / 2.0
-        self.survey._pseudo_indices[instruction.name] = pseudo_index
-
-        return self.survey
-
-
-if __name__ == "__main__":
-    import doctest
-
-    doctest.testmod()

edsl/surveys/InstructionHandler.py

@@ -1,100 +0,0 @@
-from typing import TYPE_CHECKING
-from dataclasses import dataclass
-
-
-@dataclass
-class SeparatedComponents:
-    true_questions: list
-    instruction_names_to_instructions: dict
-    pseudo_indices: dict
-
-
-class InstructionHandler:
-    def __init__(self, survey):
-        self.survey = survey
-
-    @staticmethod
-    def separate_questions_and_instructions(questions_and_instructions: list) -> tuple:
-        """
-        The 'pseudo_indices' attribute is a dictionary that maps question names to pseudo-indices
-        that are used to order questions and instructions in the survey.
-        Only questions get real indices; instructions get pseudo-indices.
-        However, the order of the pseudo-indices is the same as the order questions and instructions are added to the survey.
-
-        We don't have to know how many instructions there are to calculate the pseudo-indices because they are
-        calculated by the inverse of one minus the sum of 1/2^n for n in the number of instructions run so far.
-
-        >>> from edsl import Survey
-        >>> from edsl import Instruction
-        >>> i = Instruction(text = "Pay attention to the following questions.", name = "intro")
-        >>> i2 = Instruction(text = "How are you feeling today?", name = "followon_intro")
-        >>> from edsl import QuestionFreeText; q1 = QuestionFreeText.example()
-        >>> from edsl import QuestionMultipleChoice; q2 = QuestionMultipleChoice.example()
-        >>> s = Survey([q1, i, i2, q2])
-        >>> len(s._instruction_names_to_instructions)
-        2
-        >>> s._pseudo_indices
-        {'how_are_you': 0, 'intro': 0.5, 'followon_intro': 0.75, 'how_feeling': 1}
-
-        >>> from edsl import ChangeInstruction
-        >>> q3 = QuestionFreeText(question_text = "What is your favorite color?", question_name = "color")
-        >>> i_change = ChangeInstruction(drop = ["intro"])
-        >>> s = Survey([q1, i, q2, i_change, q3])
-        >>> [i.name for i in s._relevant_instructions(q1)]
-        []
-        >>> [i.name for i in s._relevant_instructions(q2)]
-        ['intro']
-        >>> [i.name for i in s._relevant_instructions(q3)]
-        []
-
-        >>> i_change = ChangeInstruction(keep = ["poop"], drop = [])
-        >>> s = Survey([q1, i, q2, i_change])
-        Traceback (most recent call last):
-        ...
-        ValueError: ChangeInstruction change_instruction_0 references instruction poop which does not exist.
-        """
-        from edsl.surveys.instructions.Instruction import Instruction
-        from edsl.surveys.instructions.ChangeInstruction import ChangeInstruction
-        from edsl.questions.QuestionBase import QuestionBase
-
-        true_questions = []
-        instruction_names_to_instructions = {}
-
-        num_change_instructions = 0
-        pseudo_indices = {}
-        instructions_run_length = 0
-        for entry in questions_and_instructions:
-            if isinstance(entry, Instruction) or isinstance(entry, ChangeInstruction):
-                if isinstance(entry, ChangeInstruction):
-                    entry.add_name(num_change_instructions)
-                    num_change_instructions += 1
-                    for prior_instruction in entry.keep + entry.drop:
-                        if prior_instruction not in instruction_names_to_instructions:
-                            raise ValueError(
-                                f"ChangeInstruction {entry.name} references instruction {prior_instruction} which does not exist."
-                            )
-                instructions_run_length += 1
-                delta = 1 - 1.0 / (2.0**instructions_run_length)
-                pseudo_index = (len(true_questions) - 1) + delta
-                entry.pseudo_index = pseudo_index
-                instruction_names_to_instructions[entry.name] = entry
-            elif isinstance(entry, QuestionBase):
-                pseudo_index = len(true_questions)
-                instructions_run_length = 0
-                true_questions.append(entry)
-            else:
-                raise ValueError(
-                    f"Entry {repr(entry)} is not a QuestionBase or an Instruction."
-                )
-
-            pseudo_indices[entry.name] = pseudo_index
-
-        return SeparatedComponents(
-            true_questions, instruction_names_to_instructions, pseudo_indices
-        )
-
-
-if __name__ == "__main__":
-    import doctest
-
-    doctest.testmod()

edsl/surveys/MemoryManagement.py

@@ -1,72 +0,0 @@
-from __future__ import annotations
-from typing import Callable, Union, List, TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from edsl.questions.QuestionBase import QuestionBase
-
-
-class MemoryManagement:
-    def __init__(self, survey):
-        self.survey = survey
-
-    def _set_memory_plan(self, prior_questions_func: Callable) -> None:
-        """Set memory plan based on a provided function determining prior questions.
-        :param prior_questions_func: A function that takes an index and returns a list of prior questions.
-        """
-        for i, question_name in enumerate(self.survey.question_names):
-            self.survey.memory_plan.add_memory_collection(
-                focal_question=question_name,
-                prior_questions=prior_questions_func(i),
-            )
-
-    def add_targeted_memory(
-        self,
-        focal_question: Union[QuestionBase, str],
-        prior_question: Union[QuestionBase, str],
-    ) -> "Survey":
-        """Add instructions to a survey than when answering focal_question.
-
-        :param focal_question: The question that the agent is answering.
-        :param prior_question: The question that the agent should remember when answering the focal question.
-
-        Here we add instructions to a survey than when answering q2 they should remember q1:
-        """
-        focal_question_name = self.survey.question_names[
-            self.survey._get_question_index(focal_question)
-        ]
-        prior_question_name = self.survey.question_names[
-            self.survey._get_question_index(prior_question)
-        ]
-
-        self.survey.memory_plan.add_single_memory(
-            focal_question=focal_question_name,
-            prior_question=prior_question_name,
-        )
-
-        return self.survey
-
-    def add_memory_collection(
-        self,
-        focal_question: Union[QuestionBase, str],
-        prior_questions: List[Union[QuestionBase, str]],
-    ) -> "Survey":
-        """Add prior questions and responses so the agent has them when answering.
-
-        This adds instructions to a survey than when answering focal_question, the agent should also remember the answers to prior_questions listed in prior_questions.
-
-        :param focal_question: The question that the agent is answering.
-        :param prior_questions: The questions that the agent should remember when answering the focal question.
-        """
-        focal_question_name = self.survey.question_names[
-            self.survey._get_question_index(focal_question)
-        ]
-
-        prior_question_names = [
-            self.survey.question_names[self.survey._get_question_index(prior_question)]
-            for prior_question in prior_questions
-        ]
-
-        self.survey.memory_plan.add_memory_collection(
-            focal_question=focal_question_name, prior_questions=prior_question_names
-        )
-        return self.survey

edsl/surveys/RuleManager.py

@@ -1,172 +0,0 @@
-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

@@ -1,75 +0,0 @@
-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()