Survey Visualization
Visualize survey structure, flow, and dependencies using Mermaid diagrams.
Mermaid Flowchart
Generate a Mermaid flowchart showing survey structure:
python
from edsl import Survey
from edsl.surveys.survey_helpers.survey_mermaid import SurveyMermaidVisualization
survey = Survey([q1, q2, q3])
survey = survey.add_rule("q1", "{{ q1.answer }} == 'skip'", "q3")
# Create visualization
viz = SurveyMermaidVisualization(survey)
# Get Mermaid markdown code
mermaid_code = viz.to_mermaid()
print(mermaid_code)
Output:
mermaid
flowchart TD
Start(("Start"))
q1["<b>q1</b><br/>Type: free_text<br/>First question?"]
q2["<b>q2</b><br/>Type: free_text<br/>Second question?"]
q3["<b>q3</b><br/>Type: free_text<br/>Third question?"]
EndOfSurvey(("End"))
Start --> q1
q1 --> q2
q2 --> q3
q3 --> EndOfSurvey
%% Skip and navigation rules
q1 -->|"{{ q1.answer }} == 'skip'"| q3
Visualization Options
python
viz = SurveyMermaidVisualization(
survey,
max_text_length=40, # Truncate question text at 40 chars
show_options=True, # Show MC options in nodes
show_piping=True, # Show piping dependency arrows
show_default_flow=True # Show sequential flow arrows
)
In Jupyter Notebooks
The visualization renders automatically in Jupyter:
python
# Just display the visualization object viz = SurveyMermaidVisualization(survey) viz # Renders as HTML with Mermaid diagram # Or get HTML representation directly html = viz._repr_html_()
Diagram Elements
| Element | Appearance | Meaning |
|---|---|---|
| Rounded rectangle | Start, End | Survey boundaries |
| Rectangle | Question nodes | Questions with name, type, text |
Solid arrow --> | Sequential flow | Default question order |
Dashed arrow -.-> | Skip rule | skip: condition label |
| Solid arrow with label | Navigation rule | Condition to jump |
| Dotted arrow | Piping | pipes - text references |
Flow Visualization (Text-based)
For a simpler text representation:
python
# Show rules in table format
survey.show_rules()
# Access rule collection directly
for rule in survey.rule_collection:
print(f"Q{rule.current_q} -> Q{rule.next_q}: {rule.expression}")
DAG Visualization
Visualize the dependency graph:
python
# Get the DAG
dag = survey.dag
# DAG structure: {child_index: {parent_indices}}
print(dag)
# Example: {2: {0, 1}} means question 2 depends on questions 0 and 1
# Check dependencies
print(survey.question_name_to_index) # Name to index mapping
Displaying in Markdown
The Mermaid code can be embedded in markdown:
markdown
```mermaid
flowchart TD
Start(("Start"))
q1["Question 1"]
q2["Question 2"]
EndOfSurvey(("End"))
Start --> q1
q1 --> q2
q2 --> EndOfSurvey
```
Example: Complex Survey Visualization
python
from edsl import Survey, QuestionMultipleChoice, QuestionFreeText
from edsl.surveys.survey_helpers.survey_mermaid import SurveyMermaidVisualization
# Create branching survey
q1 = QuestionMultipleChoice(
question_name="path",
question_text="Choose your path",
question_options=["A", "B"]
)
q2a = QuestionFreeText(question_name="path_a", question_text="Path A question")
q2b = QuestionFreeText(question_name="path_b", question_text="Path B question")
q3 = QuestionFreeText(question_name="conclusion", question_text="Final thoughts?")
survey = (Survey([q1, q2a, q2b, q3])
.add_rule("path", "{{ path.answer }} == 'A'", "path_a")
.add_rule("path", "{{ path.answer }} == 'B'", "path_b")
.add_skip_rule("path_a", "{{ path.answer }} != 'A'")
.add_skip_rule("path_b", "{{ path.answer }} != 'B'"))
# Generate visualization
viz = SurveyMermaidVisualization(survey)
print(viz.to_mermaid())
Saving Mermaid Output
python
# Save to file
mermaid_code = viz.to_mermaid()
with open("survey_flow.md", "w") as f:
f.write("```mermaid\n")
f.write(mermaid_code)
f.write("\n```")
# Or save as standalone .mmd file
with open("survey_flow.mmd", "w") as f:
f.write(mermaid_code)
Quick Reference
| Task | Method |
|---|---|
| Create visualization | SurveyMermaidVisualization(survey) |
| Get Mermaid code | viz.to_mermaid() |
| Display in Jupyter | viz (auto-renders) |
| Get HTML | viz._repr_html_() |
| Show rules (text) | survey.show_rules() |
| Get DAG | survey.dag |