update experiments_to_dicts

Fix types, use the newer protocol that alays takes a block first and
name that drops "simplify", update API documentation and clean up doc
strings, and add some tests.

acceptance/test_stroop.py

@@ -7,6 +7,7 @@
 from sweetpea import AtMostKInARow, ExactlyKInARow, Exclude
 from sweetpea import IterateGen
 from sweetpea import CrossBlock, synthesize_trials, synthesize_trials
+from sweetpea import experiments_to_dicts, experiments_to_tuples
 
 # Basic setup
 color_list = ["red", "blue"]
@@ -41,6 +42,31 @@ def test_correct_solution_count(design):
 
     assert len(experiments) == 24
 
+@pytest.mark.parametrize('design', permutations([color, text]))
+def test_conversion_to_tuples_and_dicts(design):
+    crossing = [color, text]
+    constraints = []
+
+    block  = CrossBlock(design, crossing, constraints)
+    experiments  = synthesize_trials(block, 100, IterateGen)
+
+    dicts = experiments_to_dicts(block, experiments)
+    tuples = experiments_to_tuples(block, experiments)
+
+    assert len(dicts) == 24
+    assert len(tuples) == 24
+
+    assert isinstance(dicts[0], list)
+    assert isinstance(tuples[0], list)
+
+    assert len(dicts[0]) == 4
+    assert len(tuples[0]) == 4
+
+    assert isinstance(dicts[0][0], dict)
+    assert isinstance(tuples[0][0], tuple)
+
+    assert dicts[0][0]["color"] == "red" or dicts[0][0]["color"] == "blue"
+    assert tuples[0][0][0] == "red" or tuples[0][0][0] == "blue"
 
 @pytest.mark.parametrize('design', permutations([color, text, con_factor]))
 def test_correct_solution_count_with_congruence_factor_but_unconstrained(design):

docs/_build/html/api/constraints.html

@@ -206,7 +206,7 @@
 <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">sweetpea.</span></span><span class="sig-name descname"><span class="pre">MinimumTrials</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">k</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sweetpea.MinimumTrials" title="Permalink to this definition"></a></dt>
 <dd><p>Constrains an experiment to set the specified number of
 minimum trials. See <a class="reference internal" href="main.html#sweetpea.CrossBlock" title="sweetpea.CrossBlock"><code class="xref py py-class docutils literal notranslate"><span class="pre">CrossBlock</span></code></a> and
-<code class="xref py py-class docutils literal notranslate"><span class="pre">Repeat</span></code> for more information.</p>
+<a class="reference internal" href="main.html#sweetpea.Repeat" title="sweetpea.Repeat"><code class="xref py py-class docutils literal notranslate"><span class="pre">Repeat</span></code></a> for more information.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
 <dd class="field-odd"><p><strong>k</strong> (<a class="reference external" href="https://docs.python.org/3.7/library/functions.html#int" title="(in Python v3.7)"><em>int</em></a>) – minimum number of trials</p>

docs/_build/html/api/main.html

@@ -365,7 +365,7 @@ <h1>Experiments<a class="headerlink" href="#experiments" title="Permalink to thi
 dictionary have one item for each trial</p>
 </dd>
 <dt class="field-odd">Return type</dt>
-<dd class="field-odd"><p>List[Dict[<a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)">str</a>, List[<a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)">str</a>]]]</p>
+<dd class="field-odd"><p>List[Dict[<a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)">str</a>, <a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#list" title="(in Python v3.7)">list</a>]]</p>
 </dd>
 </dl>
 </dd></dl>
@@ -379,7 +379,7 @@ <h1>Experiments<a class="headerlink" href="#experiments" title="Permalink to thi
 <dt class="field-odd">Parameters</dt>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>block</strong> (<a class="reference internal" href="#sweetpea.Block" title="sweetpea.Block"><em>Block</em></a>) – the experiment description that was provided to <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
-<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>,</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#list" title="(in Python v3.7)"><em>list</em></a><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
+<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>, </em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#list" title="(in Python v3.7)"><em>list</em></a><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
 </ul>
 </dd>
 </dl>
@@ -404,7 +404,7 @@ <h1>Experiments<a class="headerlink" href="#experiments" title="Permalink to thi
 <dt class="field-odd">Parameters</dt>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>block</strong> (<a class="reference internal" href="#sweetpea.Block" title="sweetpea.Block"><em>Block</em></a>) – the experiment description that was provided to <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
-<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>, </em><em>List</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>]</em><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
+<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>, </em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#list" title="(in Python v3.7)"><em>list</em></a><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
 <li><p><strong>factors</strong> (<em>List</em><em>[</em><a class="reference internal" href="factors.html#sweetpea.Factor" title="sweetpea.Factor"><em>Factor</em></a><em>]</em>) – an alernative to <cite>block</cite> supplying factors to use as a crossing</p></li>
 <li><p><strong>trials</strong> (<em>List</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/functions.html#int" title="(in Python v3.7)"><em>int</em></a><em>]</em>) – the indices of trials to tabulate, defaults to all trials</p></li>
 </ul>
@@ -415,39 +415,62 @@ <h1>Experiments<a class="headerlink" href="#experiments" title="Permalink to thi
 <dl class="py function">
 <dt class="sig sig-object py" id="sweetpea.save_experiments_csv">
 <span class="sig-prename descclassname"><span class="pre">sweetpea.</span></span><span class="sig-name descname"><span class="pre">save_experiments_csv</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">block</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">experiments</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">file_prefix</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sweetpea.save_experiments_csv" title="Permalink to this definition"></a></dt>
-<dd><p>Saves each sequence of <cite>experiments</cite> to a file whoe name is
+<dd><p>Saves each sequence of <cite>experiments</cite> to a file whose name is
 <cite>file_prefix</cite> followed by an underscore, a number counting from
 <cite>0</cite>, and “.csv”.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>block</strong> (<a class="reference internal" href="#sweetpea.Block" title="sweetpea.Block"><em>Block</em></a>) – the experiment description that was provided to <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
-<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>, </em><em>List</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>]</em><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
+<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>, </em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#list" title="(in Python v3.7)"><em>list</em></a><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
 <li><p><strong>file_prefix</strong> (<a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a>) – file-name prefix</p></li>
 </ul>
 </dd>
 </dl>
 </dd></dl>
 
+<dl class="py function">
+<dt class="sig sig-object py" id="sweetpea.experiments_to_dicts">
+<span class="sig-prename descclassname"><span class="pre">sweetpea.</span></span><span class="sig-name descname"><span class="pre">experiments_to_dicts</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">block</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">experiments</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sweetpea.experiments_to_dicts" title="Permalink to this definition"></a></dt>
+<dd><p>Converts a result from <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a>, where each
+generated sequence is represented as a dictionary of lists, so that
+each generated sequence is instead represented as a list of dictionaries.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>block</strong> (<a class="reference internal" href="#sweetpea.Block" title="sweetpea.Block"><em>Block</em></a>) – the experiment description that was provided to <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
+<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>, </em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#list" title="(in Python v3.7)"><em>list</em></a><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
+</ul>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p>a list of lists of dictionaries, where each dictionary maps each
+factor name to the string name for the levels of the trial</p>
+</dd>
+<dt class="field-odd">Return type</dt>
+<dd class="field-odd"><p>List[List[Dict[<a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)">str</a>, Any]]]</p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py function">
 <dt class="sig sig-object py" id="sweetpea.experiments_to_tuples">
-<span class="sig-prename descclassname"><span class="pre">sweetpea.</span></span><span class="sig-name descname"><span class="pre">experiments_to_tuples</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">block</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">experiments</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">file_prefix</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sweetpea.experiments_to_tuples" title="Permalink to this definition"></a></dt>
+<span class="sig-prename descclassname"><span class="pre">sweetpea.</span></span><span class="sig-name descname"><span class="pre">experiments_to_tuples</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">block</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">experiments</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sweetpea.experiments_to_tuples" title="Permalink to this definition"></a></dt>
 <dd><p>Converts a result from <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a>, where each
-generated sequence is represented as a dictory of lists, so that
+generated sequence is represented as a dictionary of lists, so that
 each generated sequence is instead represented as a list of tuples.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>block</strong> (<a class="reference internal" href="#sweetpea.Block" title="sweetpea.Block"><em>Block</em></a>) – the experiment description that was provided to <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
-<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>, </em><em>List</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>]</em><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
+<li><p><strong>experiments</strong> (<em>List</em><em>[</em><em>Dict</em><em>[</em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)"><em>str</em></a><em>, </em><a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#list" title="(in Python v3.7)"><em>list</em></a><em>]</em><em>]</em>) – sequences generated by <a class="reference internal" href="#sweetpea.synthesize_trials" title="sweetpea.synthesize_trials"><code class="xref py py-func docutils literal notranslate"><span class="pre">synthesize_trials()</span></code></a></p></li>
 </ul>
 </dd>
 <dt class="field-even">Returns</dt>
 <dd class="field-even"><p>a list of lists of tuples, where each tuple contains the string
 names of levels selected for one trial</p>
 </dd>
 <dt class="field-odd">Return type</dt>
-<dd class="field-odd"><p>List[List[Tuple[<a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#str" title="(in Python v3.7)">str</a>, …]]]</p>
+<dd class="field-odd"><p>List[List[<a class="reference external" href="https://docs.python.org/3.7/library/stdtypes.html#tuple" title="(in Python v3.7)">tuple</a>]]</p>
 </dd>
 </dl>
 </dd></dl>

docs/_build/html/genindex.html

@@ -169,6 +169,8 @@ <h2 id="B">B</h2>
     built-in function
 
       <ul>
+        <li><a href="api/main.html#sweetpea.experiments_to_dicts">sweetpea.experiments_to_dicts()</a>
+</li>
         <li><a href="api/main.html#sweetpea.experiments_to_tuples">sweetpea.experiments_to_tuples()</a>
 </li>
         <li><a href="api/main.html#sweetpea.print_experiments">sweetpea.print_experiments()</a>
@@ -319,6 +321,13 @@ <h2 id="S">S</h2>
       <li><a href="api/constraints.html#sweetpea.Exclude">sweetpea.Exclude (built-in class)</a>
 </li>
       <li>
+    sweetpea.experiments_to_dicts()
+
+      <ul>
+        <li><a href="api/main.html#sweetpea.experiments_to_dicts">built-in function</a>
+</li>
+      </ul></li>
+      <li>
     sweetpea.experiments_to_tuples()
 
       <ul>
@@ -332,11 +341,11 @@ <h2 id="S">S</h2>
       <li><a href="api/sampling_strategies.html#sweetpea.IterateGen">sweetpea.IterateGen (built-in class)</a>
 </li>
       <li><a href="api/sampling_strategies.html#sweetpea.IterateILPGen">sweetpea.IterateILPGen (built-in class)</a>
-</li>
-      <li><a href="api/sampling_strategies.html#sweetpea.IterateSATGen">sweetpea.IterateSATGen (built-in class)</a>
 </li>
   </ul></td>
   <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="api/sampling_strategies.html#sweetpea.IterateSATGen">sweetpea.IterateSATGen (built-in class)</a>
+</li>
       <li><a href="api/factors.html#sweetpea.Level">sweetpea.Level (built-in class)</a>
 </li>
       <li><a href="api/constraints.html#sweetpea.MinimumTrials">sweetpea.MinimumTrials (built-in class)</a>