Merge pull request #784 from expectedparrot/new_surveys

Updating docs, changelog

CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## [0.1.29] - 2024-TBD [In progress]
+## [0.1.30] - 2024-TBD [In progress]
+### Added
+- [In progress] `ScenarioList.from_sqlite` allows you to create a list of scenarios from a SQLite table.
+
+- [In progress] Added LaTeX support to SQL outputs and ability to write to files: `Results.print(format="latex", filename="example.tex")`
+
+- [In progress] Options that we think of as "terminal", such as `sql()`, `print()`, `html()`, etc., now take a `tee` boolean that causes them to return `self`. This is useful for chaining, e.g., if you run `print(format = "rich", tee = True)` it will return `self`, which allows you do also run `print(format = "rich", tee = True).print(format = "latex", filename = "example.tex")`.
+
+### Changed
+- [In progress] `QuestionMultipleChoice` may be modified to allow combined options and free response "Other" option, as well as non-responsive answers. Previously, an error was thrown if the agent did not select one of the given options. Details TBD.
+
+
+## [0.1.29] - 2024-07-21
 ### Added
 - Prompts visibility: Call `prompts()` on a `Jobs` object for a survey to inspect the prompts that will be used in a survey before running it. For example:
 ```
@@ -9,18 +21,12 @@ j = Survey.example().by(Model())
 j.prompts().print(format="rich")
 ```
 
-- Piping: Use agent traits and components of questions (question_text, answer, etc.) as inputs to other questions in a survey (e.g., `question_text = "What is your last name, {{ agent.first_name }}?"` or `question_text = "Name some examples of {{ prior_q.answer }}"`).
+- Piping: Use agent traits and components of questions (question_text, answer, etc.) as inputs to other questions in a survey (e.g., `question_text = "What is your last name, {{ agent.first_name }}?"` or `question_text = "Name some examples of {{ prior_q.answer }}"` or `question_options = ["{{ prior_q.answer[0]}}", "{{ prior_q.answer[1] }}"]`). Examples: https://docs.expectedparrot.com/en/latest/surveys.html#id2
 
 - Agent traits: Call agent traits directly (e.g., `Agent.example().age` will return `22`).
 
-- [In progress] `ScenarioList.from_sqlite` allows you to create a list of scenarios from a SQLite table.
-
-- [In progress] Added LaTeX support to SQL outputs and ability to write to files: `Results.print(format="latex", filename="example.tex")`
-
-- [In progress] Options that we think of as "terminal", such as `sql()`, `print()`, `html()`, etc., now take a `tee` boolean that causes them to return `self`. This is useful for chaining, e.g., if you run `print(format = "rich", tee = True)` it will return `self`, which allows you do also run `print(format = "rich", tee = True).print(format = "latex", filename = "example.tex")`.
-
-### Changed
-- [In progress] `QuestionMultipleChoice` may be modified to allow combined options and free response "Other" option, as well as non-responsive answers. Previously, an error was thrown if the agent did not select one of the given options. Details TBD.
+### Fixed
+- A bug in piping to allow you to pipe an `answer` into `question_options`. Examples: https://docs.expectedparrot.com/en/latest/surveys.html#id2
 
 
 ## [0.1.28] - 2024-07-09

docs/surveys.rst

@@ -241,26 +241,90 @@ as the name of q1 is "color".
 
 Piping 
 ------
-Piping is a method of referencing the components of a previous question in a later question.
-For example:
+Piping is a method of explicitly referencing components of a question in a later question.
+For example, here we use the answer to q0 in the prompt for q1:
 
 .. code-block:: python
 
-   from edsl.questions import QuestionFreeText
+   from edsl import QuestionFreeText, QuestionList, Survey
 
    q0 = QuestionFreeText(
-      question_text = "What is your favorite color?", 
       question_name = "color"
+      question_text = "What is your favorite color?", 
    )
 
    q1 = QuestionList(
-      question_text = "Name some things that are {{ color.answer }}.", 
       question_name = "examples"
+      question_text = "Name some things that are {{ color.answer }}.", 
    )
 
    survey = Survey([q0, q1])
 
-In this example, q0 will be administered before q1 and the response to q0 is piped into q1, so that the prompt for q1 will be "Name some things that are <response to q0>.".
+   results = survey.run()
+
+   results.select("color", "examples").print(format="rich")
+
+In this example, q0 will be administered before q1 and the response to q0 is piped into q1.
+Output:
+
+.. code-block:: text
+
+   ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+   ┃ answer                                                 ┃ answer                                                 ┃
+   ┃ .color                                                 ┃ .examples                                              ┃
+   ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+   │ Blue is my favorite color. It's calming and reminds me │ ['sky', 'ocean', 'blueberries', 'sapphires', 'blue     │
+   │ of the sky and the ocean.                              │ jay', 'blue whale', 'blue jeans', 'cornflower',        │
+   │                                                        │ 'forget-me-nots', 'bluebells']                         │
+   └────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────┘
+
+
+If an answer is a list, we can index the items to use them as inputs.
+Here we use an answer in question options:
+
+.. code-block:: python
+
+   from edsl import QuestionList, QuestionFreeText, QuestionMultipleChoice, Survey
+
+   q0 = QuestionList(
+      question_name = "colors",
+      question_text = "What are your 3 favorite colors?", 
+      max_list_items = 3
+   )
+
+   q1 = QuestionFreeText(
+      question_name = "examples",
+      question_text = "Name some things that are {{ colors.answer }}", 
+   )
+
+   q2 = QuestionMultipleChoice(
+      question_name = "favorite",
+      question_text = "Which is your #1 favorite color?", 
+      question_options = [
+         "{{ colors.answer[0] }}",
+         "{{ colors.answer[1] }}",
+         "{{ colors.answer[2] }}",
+      ]
+   )
+
+   survey = Survey([q0, q1, q2])
+
+   results = survey.run()
+
+   results.select("colors", "examples", "favorite").print(format="rich")
+
+Output:
+
+.. code-block:: text
+
+   ┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
+   ┃ answer                   ┃ answer                                                                   ┃ answer    ┃
+   ┃ .colors                  ┃ .examples                                                                ┃ .favorite ┃
+   ┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
+   │ ['Blue', 'Green', 'Red'] │ Some things that are blue include the sky, blueberries, and sapphires.   │ Blue      │
+   │                          │ Things that are green are leaves, grass, and emeralds. Red items include │           │
+   │                          │ roses, apples, and rubies.                                               │           │
+   └──────────────────────────┴──────────────────────────────────────────────────────────────────────────┴───────────┘
 
 
 This can also be done with agent traits. For example: