edsl 0.1.32__py3-none-any.whl → 0.1.33__py3-none-any.whl

edsl/surveys/Survey.py

@@ -20,6 +20,24 @@ from edsl.surveys.SurveyExportMixin import SurveyExportMixin
 from edsl.surveys.SurveyFlowVisualizationMixin import SurveyFlowVisualizationMixin
 from edsl.utilities.decorators import add_edsl_version, remove_edsl_version
 
+from edsl.agents.Agent import Agent
+
+
+class ValidatedString(str):
+    def __new__(cls, content):
+        if "<>" in content:
+            raise ValueError(
+                "The expression contains '<>', which is not allowed. You probably mean '!='."
+            )
+        return super().__new__(cls, content)
+
+
+# from edsl.surveys.Instruction import Instruction
+# from edsl.surveys.Instruction import ChangeInstruction
+from edsl.surveys.instructions.InstructionCollection import InstructionCollection
+from edsl.surveys.instructions.Instruction import Instruction
+from edsl.surveys.instructions.ChangeInstruction import ChangeInstruction
+
 
 class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
     """A collection of questions that supports skip logic."""
@@ -42,11 +60,13 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
     def __init__(
         self,
-        questions: Optional[list[QuestionBase]] = None,
+        questions: Optional[
+            list[Union[QuestionBase, Instruction, ChangeInstruction]]
+        ] = None,
         memory_plan: Optional[MemoryPlan] = None,
         rule_collection: Optional[RuleCollection] = None,
         question_groups: Optional[dict[str, tuple[int, int]]] = None,
-        name: str = None,
+        name: Optional[str] = None,
     ):
         """Create a new survey.
 
@@ -56,13 +76,33 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         :param question_groups: The groups of questions in the survey.
         :param name: The name of the survey - DEPRECATED.
 
+
+        >>> from edsl import QuestionFreeText
+        >>> q1 = QuestionFreeText(question_text = "What is your name?", question_name = "name")
+        >>> q2 = QuestionFreeText(question_text = "What is your favorite color?", question_name = "color")
+        >>> q3 = QuestionFreeText(question_text = "Is a hot dog a sandwich", question_name = "food")
+        >>> s = Survey([q1, q2, q3], question_groups = {"demographics": (0, 1), "substantive":(3)})
+
+
         """
+
+        self.raw_passed_questions = questions
+
+        (
+            true_questions,
+            instruction_names_to_instructions,
+            self.pseudo_indices,
+        ) = self._separate_questions_and_instructions(questions or [])
+
         self.rule_collection = RuleCollection(
-            num_questions=len(questions) if questions else None
+            num_questions=len(true_questions) if true_questions else None
         )
         # the RuleCollection needs to be present while we add the questions; we might override this later
         # if a rule_collection is provided. This allows us to serialize the survey with the rule_collection.
-        self.questions = questions or []
+
+        self.questions = true_questions
+        self.instruction_names_to_instructions = instruction_names_to_instructions
+
         self.memory_plan = memory_plan or MemoryPlan(self)
         if question_groups is not None:
             self.question_groups = question_groups
@@ -78,6 +118,177 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
             warnings.warn("name parameter to a survey is deprecated.")
 
+    # region: Suvry instruction handling
+    @property
+    def relevant_instructions_dict(self) -> InstructionCollection:
+        """Return a dictionary with keys as question names and values as instructions that are relevant to the question.
+
+        >>> s = Survey.example(include_instructions=True)
+        >>> s.relevant_instructions_dict
+        {'q0': [Instruction(name="attention", text="Please pay attention!")], 'q1': [Instruction(name="attention", text="Please pay attention!")], 'q2': [Instruction(name="attention", text="Please pay attention!")]}
+
+        """
+        return InstructionCollection(
+            self.instruction_names_to_instructions, self.questions
+        )
+
+    @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 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
+
+        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 true_questions, instruction_names_to_instructions, pseudo_indices
+
+    def relevant_instructions(self, question) -> dict:
+        """This should be a dictionry with keys as question names and values as instructions that are relevant to the question.
+
+        :param question: The question to get the relevant instructions for.
+
+        # Did the instruction come before the question and was it not modified by a change instruction?
+
+        """
+        return self.relevant_instructions_dict[question]
+
+    @property
+    def max_pseudo_index(self) -> float:
+        """Return the maximum pseudo index in the survey.
+
+        Example:
+
+        >>> s = Survey.example()
+        >>> s.max_pseudo_index
+        2
+        """
+        if len(self.pseudo_indices) == 0:
+            return -1
+        return max(self.pseudo_indices.values())
+
+    @property
+    def last_item_was_instruction(self) -> bool:
+        """Return whether the last item added to the survey was an instruction.
+        This is used to determine the pseudo-index of the next item added to the survey.
+
+        Example:
+
+        >>> s = Survey.example()
+        >>> s.last_item_was_instruction
+        False
+        >>> from edsl.surveys.instructions.Instruction import Instruction
+        >>> s = s.add_instruction(Instruction(text="Pay attention to the following questions.", name="intro"))
+        >>> s.last_item_was_instruction
+        True
+        """
+        return isinstance(self.max_pseudo_index, float)
+
+    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
+        >>> 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.instruction_names_to_instructions:
+            raise SurveyCreationError(
+                f"""Instruction name '{instruction.name}' already exists in survey. Existing names are {self.instruction_names_to_instructions.keys()}."""
+            )
+        self.instruction_names_to_instructions[instruction.name] = instruction
+
+        # was the last thing added an instruction or a question?
+        if self.last_item_was_instruction:
+            pseudo_index = (
+                self.max_pseudo_index
+                + (math.ceil(self.max_pseudo_index) - self.max_pseudo_index) / 2
+            )
+        else:
+            pseudo_index = self.max_pseudo_index + 1.0 / 2.0
+        self.pseudo_indices[instruction.name] = pseudo_index
+
+        return self
+
+    # endregion
+
+    # region: Simulation methods
+
     def simulate(self) -> dict:
         """Simulate the survey and return the answers."""
         i = self.gen_path_through_survey()
@@ -93,9 +304,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
     def create_agent(self) -> "Agent":
         """Create an agent from the simulated answers."""
         answers_dict = self.simulate()
-        from edsl.agents.Agent import Agent
-
-        a = Agent(traits=answers_dict)
 
         def construct_answer_dict_function(traits: dict) -> Callable:
             def func(self, question: "QuestionBase", scenario=None):
@@ -103,16 +311,48 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
             return func
 
-        a.add_direct_question_answering_method(
+        return Agent(traits=answers_dict).add_direct_question_answering_method(
             construct_answer_dict_function(answers_dict)
         )
-        return a
 
     def simulate_results(self) -> "Results":
         """Simulate the survey and return the results."""
         a = self.create_agent()
         return self.by([a]).run()
 
+    # endregion
+
+    # region: Access methods
+    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.
+
+        >>> 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):
+        ...
+        ValueError: 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.question_name_to_index:
+                raise ValueError(
+                    f"""Question name {question_name} not found in survey. The current question names are {self.question_name_to_index}."""
+                )
+            return self.question_name_to_index[question_name]
+
     def get(self, question_name: str) -> QuestionBase:
         """
         Return the question object given the question name.
@@ -128,54 +368,157 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         index = self.question_name_to_index[question_name]
         return self._questions[index]
 
-    def question_names_to_questions(self) -> dict:
-        """Return a dictionary mapping question names to question attributes."""
-        return {q.question_name: q for q in self.questions}
-
     def get_question(self, question_name: str) -> QuestionBase:
         """Return the question object given the question name."""
         # import warnings
         # warnings.warn("survey.get_question is deprecated. Use subscript operator instead.")
         return self.get(question_name)
 
+    def question_names_to_questions(self) -> dict:
+        """Return a dictionary mapping question names to question attributes."""
+        return {q.question_name: q for q in self.questions}
+
+    @property
+    def question_names(self) -> list[str]:
+        """Return a list of question names in the survey.
+
+        Example:
+
+        >>> s = Survey.example()
+        >>> s.question_names
+        ['q0', 'q1', 'q2']
+        """
+        # return list(self.question_name_to_index.keys())
+        return [q.question_name for q in self.questions]
+
+    @property
+    def question_name_to_index(self) -> dict[str, int]:
+        """Return a dictionary mapping question names to question indices.
+
+        Example:
+
+        >>> s = Survey.example()
+        >>> s.question_name_to_index
+        {'q0': 0, 'q1': 1, 'q2': 2}
+        """
+        return {q.question_name: i for i, q in enumerate(self.questions)}
+
+    # endregion
+
+    # region: serialization methods
     def __hash__(self) -> int:
         """Return a hash of the question."""
         from edsl.utilities.utilities import dict_hash
 
         return dict_hash(self._to_dict())
 
-    def __add__(self, other: Survey) -> Survey:
-        """Combine two surveys.
+    def _to_dict(self) -> dict[str, Any]:
+        """Serialize the Survey object to a dictionary.
 
-        :param other: The other survey to combine with this one.
-        >>> s1 = Survey.example()
-        >>> from edsl import QuestionFreeText
-        >>> s2 = Survey([QuestionFreeText(question_text="What is your name?", question_name="yo")])
-        >>> s3 = s1 + s2
-        Traceback (most recent call last):
-        ...
-        ValueError: ('Cannot combine two surveys with non-default rules.', "Please use the 'clear_non_default_rules' method to remove non-default rules from the survey.")
-        >>> s3 = s1.clear_non_default_rules() + s2
-        >>> len(s3.questions)
-        4
+        >>> s = Survey.example()
+        >>> s._to_dict().keys()
+        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups'])
+        """
+        return {
+            "questions": [
+                q._to_dict() for q in self.recombined_questions_and_instructions()
+            ],
+            "memory_plan": self.memory_plan.to_dict(),
+            "rule_collection": self.rule_collection.to_dict(),
+            "question_groups": self.question_groups,
+        }
+
+    @add_edsl_version
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the Survey object to a dictionary.
+
+        >>> s = Survey.example()
+        >>> s.to_dict().keys()
+        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups', 'edsl_version', 'edsl_class_name'])
 
         """
-        if (
-            len(self.rule_collection.non_default_rules) > 0
-            or len(other.rule_collection.non_default_rules) > 0
-        ):
-            raise ValueError(
-                "Cannot combine two surveys with non-default rules.",
-                "Please use the 'clear_non_default_rules' method to remove non-default rules from the survey.",
-            )
+        return self._to_dict()
 
-        return Survey(questions=self.questions + other.questions)
+    @classmethod
+    @remove_edsl_version
+    def from_dict(cls, data: dict) -> Survey:
+        """Deserialize the dictionary back to a Survey object.
 
-    def clear_non_default_rules(self) -> Survey:
-        s = Survey()
+        :param data: The dictionary to deserialize.
+
+        >>> d = Survey.example().to_dict()
+        >>> s = Survey.from_dict(d)
+        >>> s == Survey.example()
+        True
+
+        >>> s = Survey.example(include_instructions = True)
+        >>> d = s.to_dict()
+        >>> news = Survey.from_dict(d)
+        >>> news == s
+        True
+
+        """
+
+        def get_class(pass_dict):
+            if (class_name := pass_dict.get("edsl_class_name")) == "QuestionBase":
+                return QuestionBase
+            elif class_name == "Instruction":
+                from edsl.surveys.instructions.Instruction import Instruction
+
+                return Instruction
+            elif class_name == "ChangeInstruction":
+                from edsl.surveys.instructions.ChangeInstruction import (
+                    ChangeInstruction,
+                )
+
+                return ChangeInstruction
+            else:
+                # some data might not have the edsl_class_name
+                return QuestionBase
+                # raise ValueError(f"Class {pass_dict['edsl_class_name']} not found")
+
+        questions = [
+            get_class(q_dict).from_dict(q_dict) for q_dict in data["questions"]
+        ]
+        memory_plan = MemoryPlan.from_dict(data["memory_plan"])
+        survey = cls(
+            questions=questions,
+            memory_plan=memory_plan,
+            rule_collection=RuleCollection.from_dict(data["rule_collection"]),
+            question_groups=data["question_groups"],
+        )
+        return survey
+
+    # endregion
+
+    # region: Survey template parameters
+    @property
+    def scenario_attributes(self) -> list[str]:
+        """Return a list of attributes that admissible Scenarios should have.
+
+        Here we have a survey with a question that uses a jinja2 style {{ }} template:
+
+        >>> from edsl import QuestionFreeText
+        >>> s = Survey().add_question(QuestionFreeText(question_text="{{ greeting }}. What is your name?", question_name="name"))
+        >>> s.scenario_attributes
+        ['greeting']
+
+        >>> s = Survey().add_question(QuestionFreeText(question_text="{{ greeting }}. What is your {{ attribute }}?", question_name="name"))
+        >>> s.scenario_attributes
+        ['greeting', 'attribute']
+
+
+        """
+        temp = []
         for question in self.questions:
-            s.add_question(question)
-        return s
+            question_text = question.question_text
+            # extract the contents of all {{ }} in the question text using regex
+            matches = re.findall(r"\{\{(.+?)\}\}", question_text)
+            # remove whitespace
+            matches = [match.strip() for match in matches]
+            # add them to the temp list
+            temp.extend(matches)
+        return temp
 
     @property
     def parameters(self):
@@ -189,32 +532,46 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
     @property
     def parameters_by_question(self):
+        """Return a dictionary of parameters by question in the survey.
+        >>> from edsl import QuestionFreeText
+        >>> q = QuestionFreeText(question_name = "example", question_text = "What is the capital of {{ country}}?")
+        >>> s = Survey([q])
+        >>> s.parameters_by_question
+        {'example': {'country'}}
+        """
         return {q.question_name: q.parameters for q in self.questions}
 
-    @property
-    def question_names(self) -> list[str]:
-        """Return a list of question names in the survey.
-
-        Example:
+    # endregion
 
-        >>> s = Survey.example()
-        >>> s.question_names
-        ['q0', 'q1', 'q2']
-        """
-        # return list(self.question_name_to_index.keys())
-        return [q.question_name for q in self.questions]
+    # region: Survey construction
 
-    @property
-    def question_name_to_index(self) -> dict[str, int]:
-        """Return a dictionary mapping question names to question indices.
+    # region: Adding questions and combining surveys
+    def __add__(self, other: Survey) -> Survey:
+        """Combine two surveys.
 
-        Example:
+        :param other: The other survey to combine with this one.
+        >>> s1 = Survey.example()
+        >>> from edsl import QuestionFreeText
+        >>> s2 = Survey([QuestionFreeText(question_text="What is your name?", question_name="yo")])
+        >>> s3 = s1 + s2
+        Traceback (most recent call last):
+        ...
+        ValueError: ('Cannot combine two surveys with non-default rules.', "Please use the 'clear_non_default_rules' method to remove non-default rules from the survey.")
+        >>> s3 = s1.clear_non_default_rules() + s2
+        >>> len(s3.questions)
+        4
 
-        >>> s = Survey.example()
-        >>> s.question_name_to_index
-        {'q0': 0, 'q1': 1, 'q2': 2}
         """
-        return {q.question_name: i for i, q in enumerate(self.questions)}
+        if (
+            len(self.rule_collection.non_default_rules) > 0
+            or len(other.rule_collection.non_default_rules) > 0
+        ):
+            raise ValueError(
+                "Cannot combine two surveys with non-default rules.",
+                "Please use the 'clear_non_default_rules' method to remove non-default rules from the survey.",
+            )
+
+        return Survey(questions=self.questions + other.questions)
 
     def add_question(self, question: QuestionBase) -> Survey:
         """
@@ -233,11 +590,11 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         >>> s = Survey().add_question(q).add_question(q)
         Traceback (most recent call last):
         ...
-        edsl.exceptions.surveys.SurveyCreationError: Question name already exists in survey. ...
+        edsl.exceptions.surveys.SurveyCreationError: Question name 'q0' already exists in survey. Existing names are ['q0'].
         """
         if question.question_name in self.question_names:
             raise SurveyCreationError(
-                f"""Question name already exists in survey. Please use a different name for the offensing question. The problemetic question name is {question.question_name}."""
+                f"""Question name '{question.question_name}' already exists in survey. Existing names are {self.question_names}."""
             )
         index = len(self.questions)
         # TODO: This is a bit ugly because the user
@@ -245,6 +602,8 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         # descriptor.
         self._questions.append(question)
 
+        self.pseudo_indices[question.question_name] = index
+
         # using index + 1 presumes there is a next question
         self.rule_collection.add_rule(
             Rule(
@@ -263,6 +622,20 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return self
 
+    def recombined_questions_and_instructions(
+        self,
+    ) -> list[Union[QuestionBase, "Instruction"]]:
+        """Return a list of questions and instructions sorted by pseudo index."""
+        questions_and_instructions = self._questions + list(
+            self.instruction_names_to_instructions.values()
+        )
+        return sorted(
+            questions_and_instructions, key=lambda x: self.pseudo_indices[x.name]
+        )
+
+    # endregion
+
+    # region: Memory plan methods
     def set_full_memory_mode(self) -> Survey:
         """Add instructions to a survey that the agent should remember all of the answers to the questions in the survey.
 
@@ -295,6 +668,75 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
                 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:
+
+        >>> s = Survey.example().add_targeted_memory("q2", "q0")
+        >>> s.memory_plan
+        {'q2': Memory(prior_questions=['q0'])}
+
+        The agent should also remember the answers to prior_questions listed in prior_questions.
+        """
+        focal_question_name = self.question_names[
+            self._get_question_index(focal_question)
+        ]
+        prior_question_name = self.question_names[
+            self._get_question_index(prior_question)
+        ]
+
+        self.memory_plan.add_single_memory(
+            focal_question=focal_question_name,
+            prior_question=prior_question_name,
+        )
+
+        return self
+
+    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.
+
+        Here we have it so that when answering q2, the agent should remember answers to q0 and q1:
+
+        >>> s = Survey.example().add_memory_collection("q2", ["q0", "q1"])
+        >>> s.memory_plan
+        {'q2': Memory(prior_questions=['q0', 'q1'])}
+        """
+        focal_question_name = self.question_names[
+            self._get_question_index(focal_question)
+        ]
+
+        prior_question_names = [
+            self.question_names[self._get_question_index(prior_question)]
+            for prior_question in prior_questions
+        ]
+
+        self.memory_plan.add_memory_collection(
+            focal_question=focal_question_name, prior_questions=prior_question_names
+        )
+        return self
+
+    # endregion
+    # endregion
+    # endregion
+
+    # region: Question groups
     def add_question_group(
         self,
         start_question: Union[QuestionBase, str],
@@ -372,69 +814,24 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         self.question_groups[group_name] = (start_index, end_index)
         return self
 
-    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.
+    # endregion
 
-        :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:
-
-        >>> s = Survey.example().add_targeted_memory("q2", "q0")
-        >>> s.memory_plan
-        {'q2': Memory(prior_questions=['q0'])}
-
-        The agent should also remember the answers to prior_questions listed in prior_questions.
-        """
-        focal_question_name = self.question_names[
-            self._get_question_index(focal_question)
-        ]
-        prior_question_name = self.question_names[
-            self._get_question_index(prior_question)
-        ]
-
-        self.memory_plan.add_single_memory(
-            focal_question=focal_question_name,
-            prior_question=prior_question_name,
-        )
-
-        return self
-
-    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.
-
-        Here we have it so that when answering q2, the agent should remember answers to q0 and q1:
-
-        >>> s = Survey.example().add_memory_collection("q2", ["q0", "q1"])
-        >>> s.memory_plan
-        {'q2': Memory(prior_questions=['q0', 'q1'])}
-        """
-        focal_question_name = self.question_names[
-            self._get_question_index(focal_question)
-        ]
-
-        prior_question_names = [
-            self.question_names[self._get_question_index(prior_question)]
-            for prior_question in prior_questions
-        ]
+    # region: Survey rules
+    def show_rules(self) -> None:
+        """Print out the rules in the survey.
 
-        self.memory_plan.add_memory_collection(
-            focal_question=focal_question_name, prior_questions=prior_question_names
-        )
-        return self
+        >>> s = Survey.example()
+        >>> s.show_rules()
+        ┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
+        ┃ current_q ┃ expression  ┃ next_q ┃ priority ┃ before_rule ┃
+        ┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
+        │ 0         │ True        │ 1      │ -1       │ False       │
+        │ 0         │ q0 == 'yes' │ 2      │ 0        │ False       │
+        │ 1         │ True        │ 2      │ -1       │ False       │
+        │ 2         │ True        │ 3      │ -1       │ False       │
+        └───────────┴─────────────┴────────┴──────────┴─────────────┘
+        """
+        self.rule_collection.show_rules()
 
     def add_stop_rule(
         self, question: Union[QuestionBase, str], expression: str
@@ -444,6 +841,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         :param question: The question to add the stop rule to.
         :param expression: The expression to evaluate.
 
+        If this rule is true, the survey ends.
         The rule is evaluated *after* the question is answered. If the rule is true, the survey ends.
 
         Here, answering "yes" to q0 ends the survey:
@@ -456,10 +854,42 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         >>> s.next_question("q0", {"q0": "no"}).question_name
         'q1'
+
+        >>> s.add_stop_rule("q0", "q1 <> 'yes'")
+        Traceback (most recent call last):
+        ...
+        ValueError: The expression contains '<>', which is not allowed. You probably mean '!='.
         """
+        expression = ValidatedString(expression)
         self.add_rule(question, expression, EndOfSurvey)
         return self
 
+    def clear_non_default_rules(self) -> Survey:
+        """Remove all non-default rules from the survey.
+
+        >>> Survey.example().show_rules()
+        ┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
+        ┃ current_q ┃ expression  ┃ next_q ┃ priority ┃ before_rule ┃
+        ┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
+        │ 0         │ True        │ 1      │ -1       │ False       │
+        │ 0         │ q0 == 'yes' │ 2      │ 0        │ False       │
+        │ 1         │ True        │ 2      │ -1       │ False       │
+        │ 2         │ True        │ 3      │ -1       │ False       │
+        └───────────┴─────────────┴────────┴──────────┴─────────────┘
+        >>> Survey.example().clear_non_default_rules().show_rules()
+        ┏━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
+        ┃ current_q ┃ expression ┃ next_q ┃ priority ┃ before_rule ┃
+        ┡━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
+        │ 0         │ True       │ 1      │ -1       │ False       │
+        │ 1         │ True       │ 2      │ -1       │ False       │
+        │ 2         │ True       │ 3      │ -1       │ False       │
+        └───────────┴────────────┴────────┴──────────┴─────────────┘
+        """
+        s = Survey()
+        for question in self.questions:
+            s.add_question(question)
+        return s
+
     def add_skip_rule(
         self, question: Union[QuestionBase, str], expression: str
     ) -> Survey:
@@ -487,36 +917,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         self._add_rule(question, expression, question_index + 1, before_rule=True)
         return self
 
-    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.
-
-        >>> 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):
-        ...
-        ValueError: 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.question_name_to_index:
-                raise ValueError(
-                    f"""Question name {question_name} not found in survey. The current question names are {self.question_name_to_index}."""
-                )
-            return self.question_name_to_index[question_name]
-
     def _get_new_rule_priority(
         self, question_index: int, before_rule: bool = False
     ) -> int:
@@ -615,9 +1015,9 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return self
 
-    ###################
-    # FORWARD METHODS
-    ###################
+    # endregion
+
+    # region: Forward methods
     def by(self, *args: Union["Agent", "Scenario", "LanguageModel"]) -> "Jobs":
         """Add Agents, Scenarios, and LanguageModels to a survey and returns a runnable Jobs object.
 
@@ -640,34 +1040,63 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return Jobs(survey=self)
 
+    # endregion
+
+    # region: Running the survey
+
+    def __call__(self, model=None, agent=None, cache=None, **kwargs):
+        """Run the survey with default model, taking the required survey as arguments.
+
+        >>> from edsl.questions import QuestionFunctional
+        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
+        >>> q = QuestionFunctional(question_name = "q0", func = f)
+        >>> s = Survey([q])
+        >>> s(period = "morning", cache = False).select("answer.q0").first()
+        'yes'
+        >>> s(period = "evening", cache = False).select("answer.q0").first()
+        'no'
+        """
+        job = self.get_job(model, agent, **kwargs)
+        return job.run(cache=cache)
+
+    async def run_async(self, model=None, agent=None, cache=None, **kwargs):
+        """Run the survey with default model, taking the required survey as arguments.
+
+        >>> from edsl.questions import QuestionFunctional
+        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
+        >>> q = QuestionFunctional(question_name = "q0", func = f)
+        >>> s = Survey([q])
+        >>> s(period = "morning").select("answer.q0").first()
+        'yes'
+        >>> s(period = "evening").select("answer.q0").first()
+        'no'
+        """
+        # TODO: temp fix by creating a cache
+        if cache is None:
+            from edsl.data import Cache
+
+            c = Cache()
+        else:
+            c = cache
+        jobs: "Jobs" = self.get_job(model, agent, **kwargs)
+        return await jobs.run_async(cache=c)
+
     def run(self, *args, **kwargs) -> "Results":
         """Turn the survey into a Job and runs it.
 
-        Here we run a survey but with debug mode on (so LLM calls are not made)
-
         >>> from edsl import QuestionFreeText
         >>> s = Survey([QuestionFreeText.example()])
-        >>> results = s.run(debug = True, cache = False)
-        >>> results.select('answer.*').print(format = "rich")
-        ┏━━━━━━━━━━━━━━┓
-        ┃ answer       ┃
-        ┃ .how_are_you ┃
-        ┡━━━━━━━━━━━━━━┩
-        ...
-        └──────────────┘
+        >>> from edsl.language_models import LanguageModel
+        >>> m = LanguageModel.example(test_model = True, canned_response = "Great!")
+        >>> results = s.by(m).run(cache = False)
+        >>> results.select('answer.*')
+        Dataset([{'answer.how_are_you': ['Great!']}])
         """
         from edsl.jobs.Jobs import Jobs
 
         return Jobs(survey=self).run(*args, **kwargs)
 
-    ########################
-    ## Survey-Taking Methods
-    ########################
-
-    def _first_question(self) -> QuestionBase:
-        """Return the first question in the survey."""
-        return self.questions[0]
-
+    # region: Survey flow
     def next_question(
         self, current_question: Union[str, QuestionBase], answers: dict
     ) -> Union[QuestionBase, EndOfSurvey.__class__]:
@@ -745,9 +1174,15 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         Question('multiple_choice', question_name = \"""q0\""", question_text = \"""Do you like school?\""", question_options = ['yes', 'no'])
         >>> i2.send({"q0": "no"})
         Question('multiple_choice', question_name = \"""q1\""", question_text = \"""Why not?\""", question_options = ['killer bees in cafeteria', 'other'])
+
+
         """
         self.answers = {}
-        question = self._first_question()
+        question = self._questions[0]
+        # should the first question be skipped?
+        if self.rule_collection.skip_question_before_running(0, self.answers):
+            question = self.next_question(question, self.answers)
+
         while not question == EndOfSurvey:
             # breakpoint()
             answer = yield question
@@ -756,34 +1191,9 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
             ## TODO: This should also include survey and agent attributes
             question = self.next_question(question, self.answers)
 
-    @property
-    def scenario_attributes(self) -> list[str]:
-        """Return a list of attributes that admissible Scenarios should have.
-
-        Here we have a survey with a question that uses a jinja2 style {{ }} template:
-
-        >>> from edsl import QuestionFreeText
-        >>> s = Survey().add_question(QuestionFreeText(question_text="{{ greeting }}. What is your name?", question_name="name"))
-        >>> s.scenario_attributes
-        ['greeting']
-
-        >>> s = Survey().add_question(QuestionFreeText(question_text="{{ greeting }}. What is your {{ attribute }}?", question_name="name"))
-        >>> s.scenario_attributes
-        ['greeting', 'attribute']
-
-
-        """
-        temp = []
-        for question in self.questions:
-            question_text = question.question_text
-            # extract the contents of all {{ }} in the question text using regex
-            matches = re.findall(r"\{\{(.+?)\}\}", question_text)
-            # remove whitespace
-            matches = [match.strip() for match in matches]
-            # add them to the temp list
-            temp.extend(matches)
-        return temp
+    # endregion
 
+    # regions: DAG construction
     def textify(self, index_dag: DAG) -> DAG:
         """Convert the DAG of question indices to a DAG of question names.
 
@@ -923,59 +1333,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
             return False
         return self.to_dict() == other.to_dict()
 
-    ###################
-    # SERIALIZATION METHODS
-    ###################
-
-    def _to_dict(self) -> dict[str, Any]:
-        """Serialize the Survey object to a dictionary.
-
-        >>> s = Survey.example()
-        >>> s._to_dict().keys()
-        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups'])
-
-        """
-        return {
-            "questions": [q._to_dict() for q in self._questions],
-            "memory_plan": self.memory_plan.to_dict(),
-            "rule_collection": self.rule_collection.to_dict(),
-            "question_groups": self.question_groups,
-        }
-
-    @add_edsl_version
-    def to_dict(self) -> dict[str, Any]:
-        """Serialize the Survey object to a dictionary.
-
-        >>> s = Survey.example()
-        >>> s.to_dict().keys()
-        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups', 'edsl_version', 'edsl_class_name'])
-
-        """
-        return self._to_dict()
-
-    @classmethod
-    @remove_edsl_version
-    def from_dict(cls, data: dict) -> Survey:
-        """Deserialize the dictionary back to a Survey object.
-
-        :param data: The dictionary to deserialize.
-
-        >>> d = Survey.example().to_dict()
-        >>> s = Survey.from_dict(d)
-        >>> s == Survey.example()
-        True
-
-        """
-        questions = [QuestionBase.from_dict(q_dict) for q_dict in data["questions"]]
-        memory_plan = MemoryPlan.from_dict(data["memory_plan"])
-        survey = cls(
-            questions=questions,
-            memory_plan=memory_plan,
-            rule_collection=RuleCollection.from_dict(data["rule_collection"]),
-            question_groups=data["question_groups"],
-        )
-        return survey
-
     @classmethod
     def from_qsf(
         cls, qsf_file: Optional[str] = None, url: Optional[str] = None
@@ -1002,9 +1359,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         so = SurveyQualtricsImport(qsf_file)
         return so.create_survey()
 
-    ###################
-    # DISPLAY METHODS
-    ###################
+    # region: Display methods
     def print(self):
         """Print the survey in a rich format.
 
@@ -1023,7 +1378,8 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
     def __repr__(self) -> str:
         """Return a string representation of the survey."""
 
-        questions_string = ", ".join([repr(q) for q in self._questions])
+        # questions_string = ", ".join([repr(q) for q in self._questions])
+        questions_string = ", ".join([repr(q) for q in self.raw_passed_questions or []])
         # question_names_string = ", ".join([repr(name) for name in self.question_names])
         return f"Survey(questions=[{questions_string}], memory_plan={self.memory_plan}, rule_collection={self.rule_collection}, question_groups={self.question_groups})"
 
@@ -1032,22 +1388,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return data_to_html(self.to_dict())
 
-    def show_rules(self) -> None:
-        """Print out the rules in the survey.
-
-        >>> s = Survey.example()
-        >>> s.show_rules()
-        ┏━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
-        ┃ current_q ┃ expression  ┃ next_q ┃ priority ┃ before_rule ┃
-        ┡━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
-        │ 0         │ True        │ 1      │ -1       │ False       │
-        │ 0         │ q0 == 'yes' │ 2      │ 0        │ False       │
-        │ 1         │ True        │ 2      │ -1       │ False       │
-        │ 2         │ True        │ 3      │ -1       │ False       │
-        └───────────┴─────────────┴────────┴──────────┴─────────────┘
-        """
-        self.rule_collection.show_rules()
-
     def rich_print(self) -> Table:
         """Print the survey in a rich format.
 
@@ -1083,6 +1423,8 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return table
 
+    # endregion
+
     def codebook(self) -> dict[str, str]:
         """Create a codebook for the survey, mapping question names to question text.
 
@@ -1095,6 +1437,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
             codebook[question.question_name] = question.question_text
         return codebook
 
+    # region: Export methods
     def to_csv(self, filename: str = None):
         """Export the survey to a CSV file.
 
@@ -1137,8 +1480,16 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         res = c.web(self.to_dict(), platform, email)
         return res
 
+    # endregion
+
     @classmethod
-    def example(cls, params: bool = False, randomize: bool = False) -> Survey:
+    def example(
+        cls,
+        params: bool = False,
+        randomize: bool = False,
+        include_instructions=False,
+        custom_instructions: Optional[str] = None,
+    ) -> Survey:
         """Return an example survey.
 
         >>> s = Survey.example()
@@ -1171,6 +1522,18 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
             )
             s = cls(questions=[q0, q1, q2, q3])
             return s
+
+        if include_instructions:
+            from edsl import Instruction
+
+            custom_instructions = (
+                custom_instructions if custom_instructions else "Please pay attention!"
+            )
+
+            i = Instruction(text=custom_instructions, name="attention")
+            s = cls(questions=[i, q0, q1, q2])
+            return s
+
         s = cls(questions=[q0, q1, q2])
         s = s.add_rule(q0, "q0 == 'yes'", q2)
         return s
@@ -1192,43 +1555,6 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         return self.by(s).by(agent).by(model)
 
-    def __call__(self, model=None, agent=None, cache=None, **kwargs):
-        """Run the survey with default model, taking the required survey as arguments.
-
-        >>> from edsl.questions import QuestionFunctional
-        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
-        >>> q = QuestionFunctional(question_name = "q0", func = f)
-        >>> s = Survey([q])
-        >>> s(period = "morning", cache = False).select("answer.q0").first()
-        'yes'
-        >>> s(period = "evening", cache = False).select("answer.q0").first()
-        'no'
-        """
-        job = self.get_job(model, agent, **kwargs)
-        return job.run(cache=cache)
-
-    async def run_async(self, model=None, agent=None, cache=None, **kwargs):
-        """Run the survey with default model, taking the required survey as arguments.
-
-        >>> from edsl.questions import QuestionFunctional
-        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
-        >>> q = QuestionFunctional(question_name = "q0", func = f)
-        >>> s = Survey([q])
-        >>> s(period = "morning").select("answer.q0").first()
-        'yes'
-        >>> s(period = "evening").select("answer.q0").first()
-        'no'
-        """
-        # TODO: temp fix by creating a cache
-        if cache is None:
-            from edsl.data import Cache
-
-            c = Cache()
-        else:
-            c = cache
-        jobs: "Jobs" = self.get_job(model, agent, **kwargs)
-        return await jobs.run_async(cache=c)
-
 
 def main():
     """Run the example survey."""