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

edsl/surveys/DAG.py

@@ -1,20 +1,31 @@
-from collections import UserDict
+"""Directed Acyclic Graph (DAG) class."""
 
+from collections import UserDict
 from graphlib import TopologicalSorter
 
 
 class DAG(UserDict):
+    """Class for creating a Directed Acyclic Graph (DAG) from a dictionary."""
+
     def __init__(self, data: dict):
+        """Initialize the DAG class."""
         super().__init__(data)
         self.reverse_mapping = self._create_reverse_mapping()
+        self.validate_no_cycles()
 
     def _create_reverse_mapping(self):
         """
-        Creates a reverse mapping of the DAG, where the keys are the children and the values are the parents.
-        >>> data = {"a": ["b", "c"], "b": ["d"], "c": [], "d": []}
-        >>> dag = DAG(data)
-        >>> dag._create_reverse_mapping()
-        {'b': {'a'}, 'c': {'a'}, 'd': {'b'}}
+        Create a reverse mapping of the DAG, where the keys are the children and the values are the parents.
+
+        Example usage:
+
+        .. code-block:: python
+
+            data = {"a": ["b", "c"], "b": ["d"], "c": [], "d": []}
+            dag = DAG(data)
+            dag._create_reverse_mapping()
+            {'b': {'a'}, 'c': {'a'}, 'd': {'b'}}
+
         """
         rev_map = {}
         for key, values in self.items():
@@ -23,6 +34,7 @@ class DAG(UserDict):
         return rev_map
 
     def get_all_children(self, key):
+        """Get all children of a node in the DAG."""
         children = set()
 
         def dfs(node):
@@ -36,15 +48,22 @@ class DAG(UserDict):
 
     def topologically_sorted_nodes(self):
         """
-        Returns a sequence of the DAG.
-        >>> data = {"a": ["b", "c"], "b": ["d"], "c": [], "d": []}
-        >>> dag = DAG(data)
-        >>> dag.topologically_sorted_nodes() == ['c', 'd', 'b', 'a']
-        True
+        Return a sequence of the DAG.
+
+        Example usage:
+
+        .. code-block:: python
+
+            data = {"a": ["b", "c"], "b": ["d"], "c": [], "d": []}
+            dag = DAG(data)
+            dag.topologically_sorted_nodes() == ['c', 'd', 'b', 'a']
+            True
+
         """
         return list(TopologicalSorter(self).static_order())
 
     def __add__(self, other_dag):
+        """Combine two DAGs."""
         d = {}
         combined_keys = set(self.keys()).union(set(other_dag.keys()))
         for key in combined_keys:
@@ -55,11 +74,73 @@ class DAG(UserDict):
         # else:
         #     return DAG(d)
 
+    def remove_node(self, node: int) -> None:
+        """Remove a node and all its connections from the DAG."""
+        self.pop(node, None)
+        for connections in self.values():
+            connections.discard(node)
+        # Adjust remaining nodes if necessary
+        self._adjust_nodes_after_removal(node)
+
+    def _adjust_nodes_after_removal(self, removed_node: int) -> None:
+        """Adjust node indices after a node is removed."""
+        new_dag = {}
+        for node, connections in self.items():
+            new_node = node if node < removed_node else node - 1
+            new_connections = {c if c < removed_node else c - 1 for c in connections}
+            new_dag[new_node] = new_connections
+        self.clear()
+        self.update(new_dag)
+
     @classmethod
     def example(cls):
+        """Return an example of the `DAG`."""
         data = {"a": ["b", "c"], "b": ["d"], "c": [], "d": []}
         return cls(data)
 
+    def detect_cycles(self):
+        """
+        Detect cycles in the DAG using depth-first search.
+
+        :return: A list of cycles if any are found, otherwise an empty list.
+        """
+        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 self.get(node, []):
+                dfs(child)
+
+            path.pop()
+
+        for node in self:
+            if node not in visited:
+                dfs(node)
+
+        return cycles
+
+    def validate_no_cycles(self):
+        """
+        Validate that the DAG does not contain any cycles.
+
+        :raises ValueError: If cycles are detected in the DAG.
+        """
+        cycles = self.detect_cycles()
+        if cycles:
+            raise ValueError(f"Cycles detected in the DAG: {cycles}")
+
 
 if __name__ == "__main__":
     import doctest

edsl/surveys/EditSurvey.py

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

@@ -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,26 +1,31 @@
+"""This module contains the Memory class, which is a list of prior questions."""
+
 from collections import UserList
 
 
 class Memory(UserList):
-    """This list holds the questions (stored as names) that we want the
-    the agent to have available when answering a question.
-    """
+    """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):
-        return {"prior_questions": 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