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

edsl/surveys/SurveyFlowVisualization.py

@@ -0,0 +1,181 @@
+"""A mixin for visualizing the flow of a survey with parameter nodes."""
+
+from typing import Optional, TYPE_CHECKING
+from edsl.surveys.base import RulePriority, EndOfSurvey
+import tempfile
+
+
+class SurveyFlowVisualization:
+    """A mixin for visualizing the flow of a survey with parameter visualization."""
+
+    def __init__(self, survey: "Survey"):
+        self.survey = survey
+
+    def show_flow(self, filename: Optional[str] = None):
+        """Create an image showing the flow of users through the survey and question parameters."""
+        # Create a graph object
+        import pydot
+
+        graph = pydot.Dot(graph_type="digraph")
+
+        # First collect all unique parameters and answer references
+        params_and_refs = set()
+        param_to_questions = {}  # Keep track of which questions use each parameter
+        answer_refs = set()  # Track answer references between questions
+
+        # First pass: collect parameters and their question associations
+        for index, question in enumerate(self.survey.questions):
+            # Add the main question node
+            question_node = pydot.Node(
+                f"Q{index}", label=f"{question.question_name}", shape="ellipse"
+            )
+            graph.add_node(question_node)
+
+            if hasattr(question, "parameters"):
+                for param in question.parameters:
+                    # Check if this is an answer reference (contains '.answer')
+                    if ".answer" in param:
+                        answer_refs.add((param.split(".")[0], index))
+                    else:
+                        params_and_refs.add(param)
+                        if param not in param_to_questions:
+                            param_to_questions[param] = []
+                        param_to_questions[param].append(index)
+
+        # Create parameter nodes and connect them to questions
+        for param in params_and_refs:
+            param_node_name = f"param_{param}"
+            param_node = pydot.Node(
+                param_node_name,
+                label=f"{{{{ {param} }}}}",
+                shape="box",
+                style="filled",
+                fillcolor="lightgrey",
+                fontsize="10",
+            )
+            graph.add_node(param_node)
+
+            # Connect this parameter to all questions that use it
+            for q_index in param_to_questions[param]:
+                param_edge = pydot.Edge(
+                    param_node_name,
+                    f"Q{q_index}",
+                    style="dotted",
+                    color="grey",
+                    arrowsize="0.5",
+                )
+                graph.add_edge(param_edge)
+
+        # Add edges for answer references
+        for source_q_name, target_q_index in answer_refs:
+            # Find the source question index by name
+            source_q_index = next(
+                i
+                for i, q in enumerate(self.survey.questions)
+                if q.question_name == source_q_name
+            )
+            ref_edge = pydot.Edge(
+                f"Q{source_q_index}",
+                f"Q{target_q_index}",
+                style="dashed",
+                color="purple",
+                label="answer reference",
+            )
+            graph.add_edge(ref_edge)
+
+        # Add an "EndOfSurvey" node
+        graph.add_node(
+            pydot.Node("EndOfSurvey", label="End of Survey", shape="rectangle")
+        )
+
+        # Add edges for normal flow through the survey
+        num_questions = len(self.survey.questions)
+        for index in range(num_questions - 1):
+            graph.add_edge(pydot.Edge(f"Q{index}", f"Q{index+1}"))
+
+        graph.add_edge(pydot.Edge(f"Q{num_questions-1}", "EndOfSurvey"))
+
+        relevant_rules = [
+            rule
+            for rule in self.survey.rule_collection
+            if rule.priority > RulePriority.DEFAULT.value
+        ]
+
+        # edge-colors to cycle through
+        colors = [
+            "blue",
+            "red",
+            "orange",
+            "purple",
+            "brown",
+            "cyan",
+            "green",
+        ]
+        rule_colors = {
+            rule: colors[i % len(colors)] for i, rule in enumerate(relevant_rules)
+        }
+
+        for rule in relevant_rules:
+            color = rule_colors[rule]
+            edge_label = f"if {rule.expression}"
+            source_node = f"Q{rule.current_q}"
+            target_node = (
+                f"Q{rule.next_q}"
+                if rule.next_q != EndOfSurvey and rule.next_q < num_questions
+                else "EndOfSurvey"
+            )
+            if rule.before_rule:
+                edge = pydot.Edge(
+                    source_node,
+                    target_node,
+                    label=edge_label,
+                    color=color,
+                    fontcolor=color,
+                    tailport="n",
+                    headport="n",
+                )
+            else:
+                edge = pydot.Edge(
+                    source_node,
+                    target_node,
+                    label=edge_label,
+                    color=color,
+                    fontcolor=color,
+                )
+
+            graph.add_edge(edge)
+
+        if filename is not None:
+            graph.write_png(filename)
+            print(f"Flowchart saved to {filename}")
+            return
+
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".png") as tmp_file:
+            try:
+                graph.write_png(tmp_file.name)
+            except FileNotFoundError:
+                print(
+                    """File not found. Most likely it's because you don't have graphviz installed. Please install it and try again.
+                        It's 
+                        $ sudo apt-get install graphviz 
+                        on Ubuntu.
+                    """
+                )
+            from edsl.utilities.is_notebook import is_notebook
+
+            if is_notebook():
+                from IPython.display import Image, display
+
+                display(Image(tmp_file.name))
+            else:
+                import os
+                import sys
+
+                if os.name == "nt":  # Windows
+                    os.system(f"start {tmp_file.name}")
+                elif os.name == "posix":  # macOS, Linux, Unix, etc.
+                    os.system(
+                        f"open {tmp_file.name}"
+                        if sys.platform == "darwin"
+                        else f"xdg-open {tmp_file.name}"
+                    )

edsl/surveys/SurveyQualtricsImport.py

@@ -0,0 +1,284 @@
+import json
+import html
+import re
+
+from edsl import Question
+from edsl import Survey
+
+qualtrics_codes = {
+    "TE": "free_text",
+    "MC": "multiple_choice",
+    "Matrix": "matrix",
+    "DB": "instruction",  # not quite right, but for now
+    "Timing": "free_text",  # not quite right, but for now
+}
+# TE (Text Entry): Allows respondents to input a text response.
+# MC (Multiple Choice): Provides respondents with a list of options to choose from.
+# DB (Descriptive Text or Information): Displays text or information without requiring a response.
+# Matrix: A grid-style question where respondents can evaluate multiple items using the same set of response options.
+
+
+def clean_html(raw_html):
+    # Unescape HTML entities
+    clean_text = html.unescape(raw_html)
+    # Remove HTML tags
+    clean_text = re.sub(r"<.*?>", "", clean_text)
+    # Replace non-breaking spaces with regular spaces
+    clean_text = clean_text.replace("\xa0", " ")
+    # Optionally, strip leading/trailing spaces
+    clean_text = clean_text.strip()
+    return clean_text
+
+
+class QualtricsQuestion:
+    def __init__(self, question_json, debug=False):
+        self.debug = debug
+        self.question_json = question_json
+        if self.element != "SQ":
+            raise ValueError("Invalid question element type")
+
+    @property
+    def element(self):
+        return self.question_json["Element"]
+
+    @property
+    def selector(self):
+        return self.question_json.get("Selector", None)
+
+    @property
+    def question_name(self):
+        return self.question_json["PrimaryAttribute"]
+
+    @property
+    def question_text(self):
+        return clean_html(self.question_json["Payload"]["QuestionText"])
+
+    @property
+    def raw_question_type(self):
+        return self.question_json["Payload"]["QuestionType"]
+
+    @property
+    def question_type(self):
+        q_type = qualtrics_codes.get(self.raw_question_type, None)
+        if q_type is None:
+            print(f"Unknown question type: {self.raw_question_type}")
+            return None
+        return q_type
+
+    @property
+    def choices(self):
+        if "Choices" in self.question_json["Payload"]:
+            return [
+                choice["Display"]
+                for choice in self.question_json["Payload"]["Choices"].values()
+            ]
+        return None
+
+    @property
+    def answers(self):
+        if "Answers" in self.question_json["Payload"]:
+            return [
+                choice["Display"]
+                for choice in self.question_json["Payload"]["Choices"].values()
+            ]
+        return None
+
+    def to_edsl(self):
+        if self.question_type == "instruction":
+            from edsl import Instruction
+
+            return [Instruction(text=self.question_text, name=self.question_name)]
+
+        if self.question_type == "free_text":
+            try:
+                q = Question(
+                    **{
+                        "question_type": self.question_type,
+                        "question_text": self.question_text,
+                        "question_name": self.question_name,
+                    }
+                )
+                return [q]
+            except Exception as e:
+                return []
+
+        if self.question_type == "multiple_choice":
+            # Let's figure of it it's actually a checkbox question
+            if self.selector == "MAVR" or self.selector == "MULTIPLE":
+                try:
+                    q = Question(
+                        **{
+                            "question_type": "checkbox",
+                            "question_text": self.question_text,
+                            "question_name": self.question_name,
+                            "question_options": self.choices,
+                        }
+                    )
+                    return [q]
+                except Exception as e:
+                    return []
+
+            # maybe it's a linear scale!
+            if "<br>" in self.choices[0]:
+                option_labels = {}
+                question_options = []
+                for choice in self.choices:
+                    if "<br>" in choice:
+                        option_label, question_option = choice.split("<br>")
+                        option_labels[int(question_option)] = option_label
+                        question_options.append(int(question_option))
+                    else:
+                        question_options.append(int(choice))
+                try:
+                    q = Question(
+                        **{
+                            "question_type": "linear_scale",
+                            "question_text": self.question_text,
+                            "question_name": self.question_name,
+                            "question_options": question_options,
+                            "option_labels": option_labels,
+                        }
+                    )
+                    return [q]
+                except Exception as e:
+                    if self.debug:
+                        raise e
+                    else:
+                        print(e)
+                        return []
+
+            try:
+                q = Question(
+                    **{
+                        "question_type": self.question_type,
+                        "question_text": self.question_text,
+                        "question_name": self.question_name,
+                        "question_options": self.choices,
+                    }
+                )
+                return [q]
+            except Exception as e:
+                return []
+
+        if self.question_type == "matrix":
+            questions = []
+            for index, choice in enumerate(self.choices):
+                try:
+                    q = Question(
+                        **{
+                            "question_type": "multiple_choice",
+                            "question_text": self.question_text + f" ({choice})",
+                            "question_name": self.question_name + f"_{index}",
+                            "question_options": self.answers,
+                        }
+                    )
+                    questions.append(q)
+                except Exception as e:
+                    continue
+
+            return questions
+
+        raise ValueError(f"Invalid question type: {self.question_type}")
+
+
+class SurveyQualtricsImport:
+    def __init__(self, qsf_file_name: str):
+        self.qsf_file_name = qsf_file_name
+        self.question_data = self.extract_questions_from_json()
+
+    def create_survey(self):
+        questions = []
+        for qualtrics_questions in self.question_data:
+            questions.extend(qualtrics_questions.to_edsl())
+        return Survey(questions)
+
+    @property
+    def survey_data(self):
+        with open(self.qsf_file_name, "r") as f:
+            survey_data = json.load(f)
+        return survey_data
+
+    def extract_questions_from_json(self):
+        questions = self.survey_data["SurveyElements"]
+
+        extracted_questions = []
+
+        for question in questions:
+            if question["Element"] == "SQ":
+                extracted_questions.append(QualtricsQuestion(question))
+
+        return extracted_questions
+
+    def extract_blocks_from_json(self):
+        blocks = []
+
+        for element in self.survey_data["SurveyElements"]:
+            if element["Element"] == "BL":
+                for block_payload in element["Payload"]:
+                    block_elements = [
+                        BlockElement(be["Type"], be["QuestionID"])
+                        for be in block_payload["BlockElements"]
+                    ]
+                    options_data = block_payload.get("Options", {})
+                    options = BlockOptions(
+                        options_data.get("BlockLocking", "false"),
+                        options_data.get("RandomizeQuestions", "false"),
+                        options_data.get("BlockVisibility", "Collapsed"),
+                    )
+
+                    block = SurveyBlock(
+                        block_payload["Type"],
+                        block_payload["Description"],
+                        block_payload["ID"],
+                        block_elements,
+                        options,
+                    )
+                    blocks.append(block)
+
+        return blocks
+
+
+class SurveyBlock:
+    def __init__(self, block_type, description, block_id, block_elements, options):
+        self.block_type = block_type
+        self.description = description
+        self.block_id = block_id
+        self.block_elements = block_elements
+        self.options = options
+
+    def __repr__(self):
+        return f"SurveyBlock(type={self.block_type}, description={self.description}, id={self.block_id})"
+
+
+class BlockElement:
+    def __init__(self, element_type, question_id):
+        self.element_type = element_type
+        self.question_id = question_id
+
+    def __repr__(self):
+        return f"BlockElement(type={self.element_type}, question_id={self.question_id})"
+
+
+class BlockOptions:
+    def __init__(self, block_locking, randomize_questions, block_visibility):
+        self.block_locking = block_locking
+        self.randomize_questions = randomize_questions
+        self.block_visibility = block_visibility
+
+    def __repr__(self):
+        return (
+            f"BlockOptions(block_locking={self.block_locking}, "
+            f"randomize_questions={self.randomize_questions}, "
+            f"block_visibility={self.block_visibility})"
+        )
+
+
+if __name__ == "__main__":
+    survey_creator = SurveyQualtricsImport("example.qsf")
+    # print(survey_creator.question_data)
+    # survey = survey_creator.create_survey()
+    # info = survey.push()
+    # print(info)
+    # questions = survey.extract_questions_from_json()
+    # for question in questions:
+    #    print(question)

edsl/surveys/SurveyToApp.py

@@ -0,0 +1,141 @@
+from fastapi import FastAPI
+from pydantic import BaseModel, create_model
+from typing import Callable, Optional, Type, Dict, Any, List, Union
+
+
+class SurveyToApp:
+    def __init__(self, survey):
+        self.survey = survey
+        self.app = FastAPI()
+
+    def parameters(self):
+        return self.survey.parameters
+
+    def create_input(self) -> Type[BaseModel]:
+        """
+        Creates a Pydantic model based on the survey parameters.
+        Returns:
+            Type[BaseModel]: A dynamically created Pydantic model class
+        """
+        # Get parameters from survey - now calling the method
+        params = self.parameters()
+
+        # Create field definitions dictionary
+        fields: Dict[str, Any] = {}
+
+        # Since params is a set, we'll handle each parameter directly
+        # Assuming each parameter in the set has the necessary attributes
+        for param in params:
+            # You might need to adjust these based on the actual parameter object structure
+            param_name = getattr(param, "name", str(param))
+            param_type = getattr(param, "type", "string")
+            is_required = getattr(param, "required", True)
+
+            # Map survey parameter types to Python types
+            type_mapping = {
+                "string": str,
+                "integer": int,
+                "float": float,
+                "boolean": bool,
+                "array": List,
+                # Add more type mappings as needed
+            }
+
+            # Get the Python type from mapping
+            python_type = type_mapping.get(param_type, str)
+
+            if is_required:
+                fields[param_name] = (python_type, ...)
+            else:
+                fields[param_name] = (Optional[python_type], None)
+
+        # Add the template variable 'name' that's used in the question text
+        fields["name"] = (str, ...)
+
+        # Create and return the Pydantic model
+        model_name = f"{self.survey.__class__.__name__}Model"
+        return create_model(model_name, **fields)
+
+    def create_route(self) -> Callable:
+        """
+        Creates a FastAPI route handler for the survey.
+        Returns:
+            Callable: A route handler function
+        """
+        input_model = self.create_input()
+
+        async def route_handler(input_data: input_model):
+            """
+            Handles the API route by processing the input data through the survey.
+            Args:
+                input_data: The validated input data matching the created Pydantic model
+            Returns:
+                dict: The processed survey results
+            """
+            # Convert Pydantic model to dict
+            data = input_data.dict()
+            print(data)
+            from edsl.scenarios.Scenario import Scenario
+
+            # Process the data through the survey
+            try:
+                s = Scenario(data)
+                results = self.survey.by(s).run()
+                return {
+                    "status": "success",
+                    "data": results.select("answer.*").to_scenario_list().to_dict(),
+                }
+            except Exception as e:
+                return {"status": "error", "message": str(e)}
+
+        return route_handler
+
+    def add_to_app(
+        self, app: FastAPI, path: str = "/survey", methods: List[str] = ["POST", "GET"]
+    ):
+        """
+        Adds the survey route to a FastAPI application.
+        Args:
+            app (FastAPI): The FastAPI application instance
+            path (str): The API endpoint path
+            methods (List[str]): HTTP methods to support
+        """
+        route_handler = self.create_route()
+        input_model = self.create_input()
+
+        app.add_api_route(
+            path, route_handler, methods=methods, response_model=Dict[str, Any]
+        )
+
+    def create_app(self, path: str = "/survey", methods: List[str] = ["POST", "GET"]):
+        """
+        Creates a FastAPI application with the survey route.
+        Args:
+            path (str): The API endpoint path
+            methods (List[str]): HTTP methods to support
+        Returns:
+            FastAPI: The FastAPI application instance
+        """
+        app = FastAPI()
+        self.add_to_app(app, path=path, methods=methods)
+        return app
+
+
+from edsl import QuestionFreeText, QuestionList
+
+# q = QuestionFreeText(
+#     question_name="name_gender",
+#     question_text="Is this customarily a boy's name or a girl's name: {{ name}}",
+# )
+
+q = QuestionList(
+    question_name="examples",
+    question_text="Give me {{ num }} examples of {{ thing }}",
+)
+
+survey_app = SurveyToApp(q.to_survey())
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(survey_app.create_app(path="/examples"), host="127.0.0.1", port=8000)

edsl/surveys/__init__.py

@@ -1,3 +1,5 @@
 from edsl.surveys.Survey import Survey
-from edsl.surveys.Rule import Rule
-from edsl.surveys.RuleCollection import RuleCollection
+from edsl.surveys.instructions.Instruction import Instruction
+
+# from edsl.surveys.Rule import Rule
+# from edsl.surveys.RuleCollection import RuleCollection

edsl/surveys/base.py

@@ -1,33 +1,49 @@
+"""Base classes and enumerations for the surveyor package."""
+
 from enum import Enum
 
 
 class RulePriority(Enum):
+    """Enumeration of the priority of a rule."""
+
     DEFAULT = -1
 
 
 class EndOfSurveyParent:
-    "A named object that represents the end of the survey."
+    """A named object that represents the end of the survey."""
+
     pass
 
     def __repr__(self):
+        """Return a string representation of the object."""
         return "EndOfSurvey"
 
     def __str__(self):
+        """Return a string representation of the object."""
         return "EndOfSurvey"
 
     def __bool__(self):
+        """Return False."""
         return False
 
     def __add__(self, other):
-        """
+        """Add the object to another object.
+
+        Example:
         >>> e = EndOfSurveyParent()
         >>> e + 1
         EndOfSurvey
         """
         return self
 
+    def __deepcopy__(self, memo):
+        # Return the same instance when deepcopy is called
+        return self
+
     def __radd__(self, other):
-        """
+        """Add the object to another object.
+
+        Example:
         >>> 1 + EndOfSurveyParent()
         EndOfSurvey
         """