Skip to content
Snippets Groups Projects
Commit 444b291e authored by Chris Sangwin's avatar Chris Sangwin
Browse files

Clarify the docs and add example questions.

parent 195c922e
No related branches found
No related tags found
No related merge requests found
......@@ -21,7 +21,7 @@ Here is a basic example of use:
[[/parsons]]
````
Assume the question author writes a list of strings in Maxima, `proof_steps` in the question variables with both the correct and incorrect strings.
Assume the question author writes a list `proof_steps` of pairs `["key", "string"]` in Maxima (as in the examples), in the question variables with both the correct and incorrect strings.
````
[parsons input="ans1" ]]
......@@ -31,12 +31,12 @@ Assume the question author writes a list of strings in Maxima, `proof_steps` in
or they can avoid strings going via Maxima at all by writing JSON directly
Both these approaches can be combined
Both these approaches can be combined, assuming `proof_steps` is a list of pairs `["key", "string"]` as in previous examples.
````
[[parsons input="ans1"]]
{
"1":{#proof_steps[1]#},
"1":{#proof_steps[1][2]#},
"2":"Then there exists an \\(m\\in\\mathbb{Z}\\) such that \\(n=2m+1\\).",
"3":"\\[ n^2 = (2m+1)^2 = 2(2m^2+2m)+1.\\]",
"4":"Define \\(M=2m^2+2m\\in\\mathbb{Z}\\) then \\(n^2=2M+1\\).",
......@@ -100,13 +100,13 @@ Functionality and styling can be customised through the use of block parameters.
To track which random variants of a question a student sees, and make sure they return to the same variant, we need to perform all randomisation at the Maxima level.
You must define steps as Maxima objects using a `proof_steps` list (see the documentation of for [CAS libraries for representing text-based proofs](../Proof/Proof_CAS_library.md)) then you can randomly order the `proof_steps` as follows.
To create a random order, you must define steps as Maxima objects using a `proof_steps` list (see the documentation of for [CAS libraries for representing text-based proofs](../Proof/Proof_CAS_library.md)) then you can randomly order the `proof_steps` as follows.
1. Define `proof_steps` as normal.
1. Define a variable `proof_steps` as normal.
2. Add in `proof_steps:random_permutation(proof_steps);` to the question variables.
3. Add in a question note `{@map(first, proof_steps)@}` to create a meaningful, minimal, question note giving the order of steps.
3. Add in a question note such as `{@map(first, proof_steps)@}` to create a meaningful, minimal, question note giving the order of steps.
Note, if you randomly generate random variants it is _strongly recommended_ you use text-based keys. Keeping track of permuted numerical keys will be impossible!
Note, if you randomly generate random variants it is _strongly recommended_ you use text-based keys. Keeping track of permuted numerical keys will be very difficult!
## Block connection with Maxima
......
......@@ -37,7 +37,7 @@ sa:proof_parsons_interpret(ans1);
[pd, saa]:proof_assessment(sa, proof_alternatives(ta));
```
The variable `pd` now contains the edit distance from the student's proof to the closest teacher's. The teacher can decide if this is close enough (zero, of course means exact match) and whether to display the feedback. If the number of edits required is at least the length of the teacher's proof then everything needs editing and there is little point displaying feedback!
The variable `pd` now contains the edit distance from the student's proof to the closest teacher's. The teacher can decide if this is close enough (zero, of course means exact match) and whether to display the feedback. For example, use `ATAlgEquiv(pd,0)` to check if the student's proof matches one of the teacher's proofs. If the number of edits required is at least the length of the teacher's proof then everything needs editing and there is little point displaying feedback!
To display feedback use `{@proof_assessment_display(saa, proof_steps)@}` in a PRT feedback (or other castext).
......
......@@ -122,7 +122,10 @@ proof_steps: [
["conc_even", "Hence \\(n^2\\) is even."]
];
/* Generate the alternative proofs. */
tal:proof_alternatives(ta);
/* Create a set of flattened proofs. */
tas:setify(map(proof_flatten, tal));
````
The complete question text is
......
<?xml version="1.0" encoding="UTF-8"?>
<quiz>
<!-- question: 36690 -->
<question type="stack">
<name>
<text>irrational-power-irrational (illustrates re-use of strings)</text>
</name>
<questiontext format="html">
<text><![CDATA[<p>Prove: {@thm@}</p>
[[parsons input="ans1" clone="true" height="550px"]]
{# stackjson_stringify(proof_steps) #}
[[/parsons ]]
<p style="display:none">[[input:ans1]] [[validation:ans1]]</p>
<p style="display:none">[[input:ans2]] [[validation:ans2]]</p>]]></text>
</questiontext>
<generalfeedback format="html">
<text><![CDATA[This is the proof, written with some structure
{@proof_display(tal[2], proof_steps)@}
Notice this proof has two sub-proofs, which can occur in any order. Therefore we have two correct versions of this proof.
<table><tr>
<td><div class="proof">{@proof_display_para(tal[1], proof_steps)@}</div></td>
<td><div class="proof">{@proof_display_para(tal[2], proof_steps)@}</div></td>
</tr></table>
Can you see the differences between these proofs?]]></text>
</generalfeedback>
<defaultgrade>1.0000000</defaultgrade>
<penalty>0.1000000</penalty>
<hidden>0</hidden>
<idnumber></idnumber>
<stackversion>
<text>2023111600</text>
</stackversion>
<questionvariables>
<text><![CDATA[stack_include("contribl://prooflib.mac");
stack_include("contribl://proofsamples/irrational-power-irrational.mac");
ta:proof_ans;
/* Make sure we use string keys. */
ta:proof_keys_sub(ta, proof_steps);
proof_steps:random_permutation(proof_steps);
tal:proof_alternatives(ta);
]]></text>
</questionvariables>
<specificfeedback format="html">
<text>[[feedback:prt1]]</text>
</specificfeedback>
<questionnote>
<text>{@map(first, proof_steps)@}</text>
</questionnote>
<questiondescription format="moodle_auto_format">
<text></text>
</questiondescription>
<questionsimplify>1</questionsimplify>
<assumepositive>0</assumepositive>
<assumereal>0</assumereal>
<prtcorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:green;"><i class="fa fa-check"></i></span> Correct answer, well done.]]></text>
</prtcorrect>
<prtpartiallycorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:orange;"><i class="fa fa-adjust"></i></span> Your answer is partially correct.]]></text>
</prtpartiallycorrect>
<prtincorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:red;"><i class="fa fa-times"></i></span> Incorrect answer.]]></text>
</prtincorrect>
<decimals>.</decimals>
<multiplicationsign>dot</multiplicationsign>
<sqrtsign>1</sqrtsign>
<complexno>i</complexno>
<inversetrig>cos-1</inversetrig>
<logicsymbol>lang</logicsymbol>
<matrixparens>[</matrixparens>
<variantsselectionseed></variantsselectionseed>
<input>
<name>ans1</name>
<type>string</type>
<tans>proof_parsons_key_json(ta, [])</tans>
<boxsize>15</boxsize>
<strictsyntax>1</strictsyntax>
<insertstars>0</insertstars>
<syntaxhint></syntaxhint>
<syntaxattribute>0</syntaxattribute>
<forbidwords></forbidwords>
<allowwords></allowwords>
<forbidfloat>1</forbidfloat>
<requirelowestterms>0</requirelowestterms>
<checkanswertype>0</checkanswertype>
<mustverify>0</mustverify>
<showvalidation>0</showvalidation>
<options>hideanswer</options>
</input>
<input>
<name>ans2</name>
<type>string</type>
<tans>proof_display(ta, proof_steps)</tans>
<boxsize>15</boxsize>
<strictsyntax>1</strictsyntax>
<insertstars>0</insertstars>
<syntaxhint></syntaxhint>
<syntaxattribute>0</syntaxattribute>
<forbidwords></forbidwords>
<allowwords></allowwords>
<forbidfloat>1</forbidfloat>
<requirelowestterms>0</requirelowestterms>
<checkanswertype>0</checkanswertype>
<mustverify>0</mustverify>
<showvalidation>0</showvalidation>
<options></options>
</input>
<prt>
<name>prt1</name>
<value>1.0000000</value>
<autosimplify>1</autosimplify>
<feedbackstyle>1</feedbackstyle>
<feedbackvariables>
<text>sa:proof_parsons_interpret(ans1);
[pd,saa]:proof_assessment(sa, proof_alternatives(ta));
</text>
</feedbackvariables>
<node>
<name>0</name>
<description></description>
<answertest>AlgEquiv</answertest>
<sans>pd</sans>
<tans>0</tans>
<testoptions></testoptions>
<quiet>0</quiet>
<truescoremode>=</truescoremode>
<truescore>1</truescore>
<truepenalty></truepenalty>
<truenextnode>-1</truenextnode>
<trueanswernote>prt1-1-T</trueanswernote>
<truefeedback format="html">
<text></text>
</truefeedback>
<falsescoremode>=</falsescoremode>
<falsescore>0</falsescore>
<falsepenalty></falsepenalty>
<falsenextnode>-1</falsenextnode>
<falseanswernote>prt1-1-F</falseanswernote>
<falsefeedback format="html">
<text>{@proof_assessment_display(saa, proof_steps)@}</text>
</falsefeedback>
</node>
</prt>
<deployedseed>77</deployedseed>
<qtest>
<testcase>1</testcase>
<description>Test case assuming the teacher's input gets full marks.</description>
<testinput>
<name>ans1</name>
<value>proof_parsons_key_json(ta, [])</value>
</testinput>
<testinput>
<name>ans2</name>
<value>proof_display(ta, proof_steps)</value>
</testinput>
<expected>
<name>prt1</name>
<expectedscore>1.0000000</expectedscore>
<expectedpenalty>0.0000000</expectedpenalty>
<expectedanswernote>prt1-1-T</expectedanswernote>
</expected>
</qtest>
</question>
<!-- question: 35561 -->
<question type="stack">
<name>
<text>log-two-three-irrational</text>
</name>
<questiontext format="html">
<text><![CDATA[<p>Prove: {@thm@}</p>
<p>Drag those strings needed to construct a correct proof.</p>
[[parsons input="ans1" height="650px"]]
{# stackjson_stringify(proof_steps) #}
[[/parsons ]]
<p>(You can drag to re-order or remove strings. Double tap to add at the end, or remove.)
<p style="display:none">[[input:ans1]] [[validation:ans1]]</p>
<p style="display:none">[[input:ans2]] [[validation:ans2]]</p>]]></text>
</questiontext>
<generalfeedback format="html">
<text><![CDATA[This is the proof, written with some structure
<p>Prove: {@thm@}</p>
{@proof_display(first(tal), proof_steps)@}]]></text>
</generalfeedback>
<defaultgrade>1.0000000</defaultgrade>
<penalty>0.1000000</penalty>
<hidden>0</hidden>
<idnumber></idnumber>
<stackversion>
<text>2023111600</text>
</stackversion>
<questionvariables>
<text><![CDATA[stack_include("contribl://prooflib.mac");
stack_include("contribl://proofsamples/log-two-three-irrational.mac");
ta:proof_ans;
/* wrong_steps are now part of the .mac file, as is some narrative. */
proof_steps:append(proof_steps,wrong_steps);
proof_steps:random_permutation(proof_steps);
tal:proof_alternatives(ta);
]]></text>
</questionvariables>
<specificfeedback format="html">
<text>[[feedback:prt1]]</text>
</specificfeedback>
<questionnote>
<text>{@map(first, proof_steps)@}</text>
</questionnote>
<questiondescription format="moodle_auto_format">
<text></text>
</questiondescription>
<questionsimplify>1</questionsimplify>
<assumepositive>0</assumepositive>
<assumereal>0</assumereal>
<prtcorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:green;"><i class="fa fa-check"></i></span> Correct answer, well done.]]></text>
</prtcorrect>
<prtpartiallycorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:orange;"><i class="fa fa-adjust"></i></span> Your answer is partially correct.]]></text>
</prtpartiallycorrect>
<prtincorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:red;"><i class="fa fa-times"></i></span> Incorrect answer.]]></text>
</prtincorrect>
<decimals>.</decimals>
<multiplicationsign>dot</multiplicationsign>
<sqrtsign>1</sqrtsign>
<complexno>i</complexno>
<inversetrig>cos-1</inversetrig>
<logicsymbol>lang</logicsymbol>
<matrixparens>[</matrixparens>
<variantsselectionseed></variantsselectionseed>
<input>
<name>ans1</name>
<type>string</type>
<tans>proof_parsons_key_json(ta, proof_steps)</tans>
<boxsize>15</boxsize>
<strictsyntax>1</strictsyntax>
<insertstars>0</insertstars>
<syntaxhint></syntaxhint>
<syntaxattribute>0</syntaxattribute>
<forbidwords></forbidwords>
<allowwords></allowwords>
<forbidfloat>1</forbidfloat>
<requirelowestterms>0</requirelowestterms>
<checkanswertype>0</checkanswertype>
<mustverify>0</mustverify>
<showvalidation>0</showvalidation>
<options>hideanswer</options>
</input>
<input>
<name>ans2</name>
<type>string</type>
<tans>proof_display(ta, proof_steps_prune(proof_steps))</tans>
<boxsize>15</boxsize>
<strictsyntax>1</strictsyntax>
<insertstars>0</insertstars>
<syntaxhint></syntaxhint>
<syntaxattribute>0</syntaxattribute>
<forbidwords></forbidwords>
<allowwords></allowwords>
<forbidfloat>1</forbidfloat>
<requirelowestterms>0</requirelowestterms>
<checkanswertype>0</checkanswertype>
<mustverify>0</mustverify>
<showvalidation>0</showvalidation>
<options></options>
</input>
<prt>
<name>prt1</name>
<value>1.0000000</value>
<autosimplify>1</autosimplify>
<feedbackstyle>1</feedbackstyle>
<feedbackvariables>
<text>sa:proof_parsons_interpret(ans1);
[pd,saa]:proof_assessment(sa, proof_alternatives(ta));
</text>
</feedbackvariables>
<node>
<name>0</name>
<description></description>
<answertest>AlgEquiv</answertest>
<sans>pd</sans>
<tans>0</tans>
<testoptions></testoptions>
<quiet>0</quiet>
<truescoremode>=</truescoremode>
<truescore>1</truescore>
<truepenalty></truepenalty>
<truenextnode>-1</truenextnode>
<trueanswernote>prt1-1-T</trueanswernote>
<truefeedback format="html">
<text></text>
</truefeedback>
<falsescoremode>=</falsescoremode>
<falsescore>0</falsescore>
<falsepenalty></falsepenalty>
<falsenextnode>-1</falsenextnode>
<falseanswernote>prt1-1-F</falseanswernote>
<falsefeedback format="html">
<text>{@proof_assessment_display(saa, proof_steps)@}</text>
</falsefeedback>
</node>
</prt>
<deployedseed>1326674135</deployedseed>
<deployedseed>487104984</deployedseed>
<deployedseed>737200307</deployedseed>
<deployedseed>1172493662</deployedseed>
<deployedseed>897001585</deployedseed>
<deployedseed>1561808185</deployedseed>
<deployedseed>1927179470</deployedseed>
<deployedseed>2007574041</deployedseed>
<deployedseed>581975935</deployedseed>
<deployedseed>1734890149</deployedseed>
<qtest>
<testcase>1</testcase>
<description>Test case assuming the teacher's input gets full marks.</description>
<testinput>
<name>ans1</name>
<value>proof_parsons_key_json(ta, [])</value>
</testinput>
<testinput>
<name>ans2</name>
<value>proof_display(ta, proof_steps)</value>
</testinput>
<expected>
<name>prt1</name>
<expectedscore>1.0000000</expectedscore>
<expectedpenalty>0.0000000</expectedpenalty>
<expectedanswernote>prt1-1-T</expectedanswernote>
</expected>
</qtest>
</question>
<!-- question: 36692 -->
<question type="stack">
<name>
<text>Parsons plot</text>
</name>
<questiontext format="html">
<text><![CDATA[Arrange the plots in order of increasing algebraic degree.
[[ parsons input="ans1" height="1000px"]]
{# stackjson_stringify(proof_steps) #}
[[/parsons]]
<p style="display:none">[[input:ans1]] [[validation:ans1]]</p>]]></text>
</questiontext>
<generalfeedback format="moodle_auto_format">
<text></text>
</generalfeedback>
<defaultgrade>1.0000000</defaultgrade>
<penalty>0.1000000</penalty>
<hidden>0</hidden>
<idnumber></idnumber>
<stackversion>
<text>2023111600</text>
</stackversion>
<questionvariables>
<text><![CDATA[stack_include("contribl://prooflib.mac");
ta:proof("A","B","C","D");
proof_steps:[
[ "A", plot(sqrt(x),[x,-1,1],[size,180,180],[margin,1.7],[yx_ratio, 1],[plottags,false])],
[ "B", plot(x,[x,-1,1],[size,180,180],[margin,1.7],[yx_ratio, 1],[plottags,false])],
[ "C", plot(x^2,[x,-1,1],[size,180,180],[margin,1.7],[yx_ratio, 1],[plottags,false])],
[ "D", plot(x^3,[x,-1,1],[size,180,180],[margin,1.7],[yx_ratio, 1],[plottags,false])]
];
proof_steps:random_permutation(proof_steps);
]]></text>
</questionvariables>
<specificfeedback format="html">
<text>[[feedback:prt1]]</text>
</specificfeedback>
<questionnote>
<text>{@map(first, proof_steps)@}</text>
</questionnote>
<questiondescription format="html">
<text></text>
</questiondescription>
<questionsimplify>1</questionsimplify>
<assumepositive>0</assumepositive>
<assumereal>0</assumereal>
<prtcorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:green;"><i class="fa fa-check"></i></span> Correct answer, well done.]]></text>
</prtcorrect>
<prtpartiallycorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:orange;"><i class="fa fa-adjust"></i></span> Your answer is partially correct.]]></text>
</prtpartiallycorrect>
<prtincorrect format="html">
<text><![CDATA[<span style="font-size: 1.5em; color:red;"><i class="fa fa-times"></i></span> Incorrect answer.]]></text>
</prtincorrect>
<decimals>.</decimals>
<multiplicationsign>dot</multiplicationsign>
<sqrtsign>1</sqrtsign>
<complexno>i</complexno>
<inversetrig>cos-1</inversetrig>
<logicsymbol>lang</logicsymbol>
<matrixparens>[</matrixparens>
<variantsselectionseed></variantsselectionseed>
<input>
<name>ans1</name>
<type>string</type>
<tans>proof_parsons_key_json(ta, [])</tans>
<boxsize>15</boxsize>
<strictsyntax>1</strictsyntax>
<insertstars>0</insertstars>
<syntaxhint></syntaxhint>
<syntaxattribute>0</syntaxattribute>
<forbidwords></forbidwords>
<allowwords></allowwords>
<forbidfloat>1</forbidfloat>
<requirelowestterms>0</requirelowestterms>
<checkanswertype>0</checkanswertype>
<mustverify>0</mustverify>
<showvalidation>0</showvalidation>
<options>hideanswer</options>
</input>
<prt>
<name>prt1</name>
<value>1.0000000</value>
<autosimplify>1</autosimplify>
<feedbackstyle>1</feedbackstyle>
<feedbackvariables>
<text>sa:proof_parsons_interpret(ans1);
[pd,saa]:proof_assessment(sa, proof_alternatives(ta));
</text>
</feedbackvariables>
<node>
<name>0</name>
<description></description>
<answertest>AlgEquiv</answertest>
<sans>pd</sans>
<tans>0</tans>
<testoptions></testoptions>
<quiet>0</quiet>
<truescoremode>=</truescoremode>
<truescore>1</truescore>
<truepenalty></truepenalty>
<truenextnode>-1</truenextnode>
<trueanswernote>prt1-1-T</trueanswernote>
<truefeedback format="html">
<text></text>
</truefeedback>
<falsescoremode>=</falsescoremode>
<falsescore>0</falsescore>
<falsepenalty></falsepenalty>
<falsenextnode>-1</falsenextnode>
<falseanswernote>prt1-1-F</falseanswernote>
<falsefeedback format="html">
<text>{@proof_assessment_display(saa, proof_steps)@}</text>
</falsefeedback>
</node>
</prt>
<deployedseed>1733122457</deployedseed>
<deployedseed>1657629229</deployedseed>
<deployedseed>2099022223</deployedseed>
<deployedseed>1441581320</deployedseed>
<deployedseed>1603372470</deployedseed>
<qtest>
<testcase>1</testcase>
<description>Test case assuming the teacher's input gets full marks.</description>
<testinput>
<name>ans1</name>
<value>proof_parsons_key_json(ta, [])</value>
</testinput>
<expected>
<name>prt1</name>
<expectedscore>1.0000000</expectedscore>
<expectedpenalty>0.0000000</expectedpenalty>
<expectedanswernote>prt1-1-T</expectedanswernote>
</expected>
</qtest>
</question>
</quiz>
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment