edsl 0.1.38.dev3__py3-none-any.whl → 0.1.39__py3-none-any.whl

edsl/surveys/InstructionHandler.py

@@ -0,0 +1,100 @@
+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/Memory.py

@@ -1,31 +1,31 @@
-"""This module contains the Memory class, which is a list of prior questions."""
-
-from collections import UserList
-
-
-class Memory(UserList):
-    """Class for holding the questions (stored as names) that we want the the agent to have available when answering a question."""
-
-    def __init__(self, prior_questions: list[str] = None):
-        """Initialize the Memory object."""
-        super().__init__(prior_questions or [])
-
-    def add_prior_question(self, prior_question):
-        """Add a prior question to the memory."""
-        if prior_question not in self:
-            self.append(prior_question)
-        else:
-            raise ValueError(f"{prior_question} is already in the memory.")
-
-    def __repr__(self):
-        """Return a string representation of the Memory object."""
-        return f"Memory(prior_questions={self.data})"
-
-    def to_dict(self):
-        """Create a dictionary representation of the Memory object."""
-        return {"prior_questions": self.data}
-
-    @classmethod
-    def from_dict(cls, data):
-        """Create a Memory object from a dictionary."""
-        return cls(**data)
+"""This module contains the Memory class, which is a list of prior questions."""
+
+from collections import UserList
+
+
+class Memory(UserList):
+    """Class for holding the questions (stored as names) that we want the the agent to have available when answering a question."""
+
+    def __init__(self, prior_questions: list[str] = None):
+        """Initialize the Memory object."""
+        super().__init__(prior_questions or [])
+
+    def add_prior_question(self, prior_question):
+        """Add a prior question to the memory."""
+        if prior_question not in self:
+            self.append(prior_question)
+        else:
+            raise ValueError(f"{prior_question} is already in the memory.")
+
+    def __repr__(self):
+        """Return a string representation of the Memory object."""
+        return f"Memory(prior_questions={self.data})"
+
+    def to_dict(self):
+        """Create a dictionary representation of the Memory object."""
+        return {"prior_questions": self.data}
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create a Memory object from a dictionary."""
+        return cls(**data)

edsl/surveys/MemoryManagement.py

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