UBC Wiki - User contributions [en]

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Authoring guide

2016-06-29T23:33:22Z

DavorCubranic: Fix the displayed text for the link to Rserve home page

== WeBWorKiR User Guide ==

The audience for this guide are problem authors who want to use R's
facilities in their WeBWorK questions. We assume that you already know
how to create problems with the PG language (which itself is a subset
of Perl) and are familiar with the concepts of macros in PG. We also
assume that your WeBWorKiR environment has been set up as described in
the [[Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/Installation_guide|installation guide]].

=== Background ===

WeBWorKiR is a system that involves two separate servers: WeBWorK and
R. In a normal operation, when a student accesses WeBWorK via a web
browser to work on homework problems, WeBWorK runs the PG code
defining the problem to compute:

a) values used in the question, for example a random vector of five integers

b) the text of the question, typically given in format resembling LaTeX and optionally displaying values computed in (a)

c) values of the correct answer, for example, the mean of the vector calculated in (a)

WeBWorKiR adds to this the ability to run arbitrary computations in R
and make their results available to the rest of the PG code as if they
were constructed using the standard PG functions. (In our running
example, we could construct the random vector in R with `sample`,
and/or calculate its mean with `mean`.) The reason why one might want
to do this is R's rich library of high-quality statistical functions
as well as its graphical abilities. While in theory these could be
both replicated with PG, it would take a huge effort that can be
better spent by simply using the functionality already available in R.

The way this works is that WeBWorK uses a Perl module that can talk to
a server running the [http://www.rforge.net/Rserve/ Rserve] software,
which allows remote clients to execute R code on the Rserve's server
and returns the execution's result in response. The Perl module
converts this response from R's native values (e.g., a generic vector,
aka "list") to those understandable to Perl (e.g., an array), making
them available to the rest of the PG code.

== Loading the macros ==

To use R code in a problem, include "RserveClient.pl" in the
"loadMacros" call at the start of the question. For example:

<pre>
loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl" # <--- R integration
);
</pre>

== Basic Rserve macros ==

The Rserve software creates an R session for each remote client. This
means that clients' interactions with R are kept separate from each
other, just as if you started R twice on your local computer. A
session persists as long as the client is connected, so that multiple
calls from the client using the same session see the objects created
in previous calls. (This behaviour mirrors what happens in a local
session, where each R command you execute at the console after
pressing ENTER sees the results of earlier commands.) When a sessions
is *closed*, its contents are wiped off without a trace, just like
quitting the R application run locally.

The RserveClient offers macros to start and finish a session, and
execute R commands in the current session:

<ol style="list-style-type: decimal;">
<li><code>rserve_eval("some R code")</code>: this function sends the R code given
as its string argument to Rserve for execution. It returns *an
array* representation of the R code's result. (This means that the
value of <code>rserve_eval("pi")</code> is an array with a single element
3.14159265358979. If you want to keep this value and use it in the
rest of the problem, assign it to an array variable. For example:
<pre>@pi = rserve_eval("pi");</pre>
'''Note:''' Multiple calls within the same problem share the R session and the object workspace, so you can break up your R code in as many <tt>rserve_eval</tt> statements as you'd like.</li>

<li><code>rserve_start()</code>, <code>rserve_finish()</code>: Start up and close the current connection to the Rserve server. In
normal use, these functions are completely optional because the first
call to <code>rserve_eval</code> will call start the Rserve session if one is not
already open. Similarly, the current session will be automatically closed at the end of the problem.
Other than backward compatibility, the only reason for using these
functions is to start a new clean session within a single problem,
which shouldn't be a common occurrence.</li>
</ol>

=== A note on Perl quoting rules ===

Beware of Perl's quoting rules when writing R code. The text in double
quotes gets interpreted for escape sequences (e.g., <code>"\n"</code> represents a
newline) and variables (e.g., <code>"The value of pi is $pi[0]"</code> will be
interpolated into <code>"The value of pi is 3.14159265358979"</code>, given the
code above). This is a problem if you're trying to extract an element
of a list by name using the <code>"$"</code> operator in R because the text
following it will be interpreted as a variable. For instance, running
<code>rserve_eval("cars$speed")</code> will not return the "speed" column of the
standard "cars" dataset, because "$speed" in the string will be
replaced by the value of the PG variable <code>$speed</code>, which if not yet
defined will be empty string, so that the R code that actually gets
executed is simply "cars". Instead, using single quotes, which prevent
variable and escape sequence interpolation and instead keep the string
exactly as entered: <code>rserve_eval('cars$speed')</code>.

On the other hand, some time you actually might want variable
interpolation to be done, for instance to construct the R code that
uses values of variables constructed with PG functions. For instance:

<pre>
Context("Numeric");

$pi = Real("pi");
@difference = rserve_eval("pi - $pi");
</pre>

will calculate the difference between the value between R and PG's
values of "pi" and put the result in the <tt>@difference</tt> array. Note that
the same R code can be constructed using Perl's string concatenation
operator dot ("."): <tt>rserve_eval('pi - ' . $pi)</tt>. Personally, I
recommend sticking with single quotes to prevent unwanted surprises,
and using the dot operator if needing to include the value of a PG
variable.

== Displaying R graphics ==

R has excellent facilities for creating production-quality statistical
graphics, from simple scatterplots to complex spatial visualizatons
overlaid on geographical maps. These graphics can be produced in a
variety of formats (in R parlance, devices), from the user's monitor
to PDF or JPG files. The RserveClient allows the author to present
these graphics in the question by bracketing the R graphing code with
macros <tt>rserve_start_plot</tt> and <tt>rserve_finish_plot</tt>, and then showing
the produced image in the question with PG's macro <tt>image</tt> (see the
WeBWorK [http://webwork.maa.org/wiki/Image documentation]).

The following code is a complete example

<pre>
DOCUMENT();

loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl",
);

# Print problem number and point value (weight) for the problem
TEXT(beginproblem());

# Setup
Context("Numeric");

$mean = random(-2, 2, .5);

$img = rserve_start_plot('png');
rserve_eval('curve(dnorm(x, mean=' . $mean . '), xlim=c(-4, 4)); 0');
$image_path = rserve_finish_plot($img);

# Text
Context()->texStrings;
BEGIN_TEXT

What is the mean of the normal distribution shown in the figure below:
\{ ans_rule(5) \}

$PAR

\{ image($image_path, width=>300, height=>300) \}:
END_TEXT

Context()->normalStrings;

# Answers
ANS(Real($mean)->cmp);

ENDDOCUMENT();
</pre>

The four key lines are as follow:

<ol style="list-style-type: decimal;">
<li><code>$img = rserve_start_plot('png')</code>: sets up R to plot to a 'PNG'
file and returns a unique plot identifier to be used later.</li>

<li><code>rserve_eval('curve(...)')</code>: runs plotting commands on the R server</li>

<li><code>$image_path = rserve_finish_plot($img)</code>: completes the plotting
to the PNG file and transfers it to a location on the WebWork
server. Returns the path of the file, which is stored in Perl variable <code>$image_path</code>
and later used as the first argument to the <code>image</code> macro.</li>

<li><code>\{ image($image_path, width=>300, height=>300) \}</code>: inserts the
image into the web page.</li>
</ol>

== Transferring files from the R server ==

Sometimes it may be convenient to make a file from R server available to the student via a link in Webwork. (For instance, using R to generate a (potentially randomized) data file that the student can download to work on the problem offline.) The macro <code>rserve_get_file REMOTE_NAME [, LOCAL_NAME]</code> can be used to transfer the file ''REMOTE_NAME'' from the R server to WebWork's temporary
file area, and returns the name of the local file that can then be
used by the <code>htmlLink</code> macro. Specifying ''LOCAL_NAME'' is optional; if it is not specified, the
filename portion of the ''REMOTE_NAME'' is used.

The following code is a complete example

<pre>
DOCUMENT();

loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl",
);

# Print problem number and point value (weight) for the problem
TEXT(beginproblem());

# Setup
Context("Numeric");

my ($intercept, $slope) = rserve_eval('coef(lm(log(dist)~log(speed), data = cars))');

my ($remote_file) = rserve_eval('filename <- tempfile(fileext=".csv"); write.csv(cars, filename); filename');
my $local_file = rserve_get_file($remote_file);

($local_url = $local_file) =~ s|$tempDirectory|$tempURL|;

# Text
Context()->texStrings;
BEGIN_TEXT

What is the slope of the linear regression of log-transformed stopping distance vs. car speed in the dataset linked below:
\{ ans_rule(5) \}

$PAR

\{ htmlLink($local_url, "Download") \} the problem data (CSV file).

END_TEXT

Context()->normalStrings;

# Answers
ANS(Real($slope)->cmp);

ENDDOCUMENT();
</pre>

The four key lines are as follow:

<ol style="list-style-type: decimal;">
<li><code>my ($remote_file) = rserve_eval('filename <- tempfile(fileext=".csv"); write.csv(cars, filename); filename')</code>: stores the desired dataset into a temporary CSV file on the R server and returns its path, which is stored in Perl variable <code>$remote_file</code>.</li>

<li><code>my $local_file = rserve_get_file($remote_file)</code>: transfers the file from the R server to WeBWorK's temporary file area and returns its path, which is stored in Perl variable <code>$local_file</code>.</li>

<li><code>($local_url = $local_file) =~ s|$tempDirectory|$tempURL|</code>: converts the local file path into a URL that can be used as an argument to the <code>htmlLink</code> macro, saving it in Perl variable <code>$local_url</code>.</li>

<li><code>\{ htmlLink($local_url, "Download") \}</code>: inserts the
link to the downloaded file into the web page.</li>
</ol>

[[Category:WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2016-01-07T19:58:48Z

DavorCubranic: Add the WeBWorK category

WebWork problems are stored in PG files. These files are typically organized in the following way:

== Tagging and Description ==
The tagging and description section describes the problem for future users and authors. The purpose of the tagging information is to make the problem easier to find by searching or browsing. Each tag must appear on its own line, starting at the first character, and be in the following format: <code>## Tagname(tag value)</code>. There are three required tags, <tt>DBsubject</tt>, <tt>DBchapter</tt>, and <tt>DBsection</tt>, placing the problem in the [http://hobbes.la.asu.edu/Holt/chaps-and-secs.html hierarchy] that's exposed in the Library Browser. Problems should also a <tt>Level</tt>, denoting its difficulty on a predefined [http://webwork.maa.org/wiki/Problem_Levels scale].

Optional tags include <tt>Keywords</tt>, for easier searching, as well as tags to indicate authorship (<tt>Author</tt> and <tt>Institution</tt>), and to link to a specific textbook (<tt>TitleText1</tt>, <tt>EditionText1</tt>, <tt>AuthorText1</tt>, <tt>Section1</tt>, and <tt>Problem1</tt>).

More information on tagging can be found on the [http://webwork.maa.org/wiki/Tagging_Problems WebWork MAA wiki].

<pre>
## DBsubject('Arithmetic')
## DBchapter('Integers')
## DBsection('Addition/subtraction')
## Level(2)
## KEYWORDS('arithmetic', 'adding')
## Author('Davor Cubranic')
## Institution('University of British Columbia')
</pre>

== Initialization ==
The initialization section loads required macros for the problem. It ''must''' begin with the <code>DOCUMENT();</code> command, followed by the <code>loadMacros</code> command that loads additional commands used by the problem. For basic problems, the following is sufficient — template files for specific problem types will tell you if any other macros should be loaded.

<pre>
DOCUMENT();
loadMacros(
"PGstandard.pl",
"MathObjects.pl",
);
</pre>

== Problem Set-up ==
In this section, define variables specific to the problem, for instance various parameters or the correct answer value. These variables are used in subsequent sections either in the text displayed to the student, or to check the answer. You should begin this section with <code>Context</code>, to tell WebWork the type of variables that are used. In this example, we use <code>Context("Numeric")</code> to indicate that the following commands work on scalar numbers.

There are many ways to assign value to variables. The two we show here are:

# by a random draw from a range of values (<code>random</code>, which in this case chooses from a sequence starting at 2, ending at 9, and incrementing by 1, thus choosing integers in the range [2, 9])
# by computing a value (<code>Real</code>) from a math expression, in this case the real number calculated by adding one to the value of <tt>$a</tt>. These are the so-called MathObjects, and they lie at heart of WebWork's functioning. For instance, MathObjects know how to compute or simplify fairly complicated mathematical expressions, how display themselves in a sensible way in the text of the problem, and how to compare themselves to the student's answer . See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_MathObjects introduction to MathObjects] and follow its links to learn additional features as needed.

<pre>
Context("Numeric");

$a = random(2, 9, 1);
$a_plus_1 = Real("$a + 1");
</pre>

See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_Contexts introduction to contexts] and a [http://webwork.maa.org/wiki/ContextList list] of other types of contexts, such as matrices or intervals.

== Text ==
The text section gives the text that is shown to the student. It begins with a line containing <code>TEXT(beginproblem());</code>. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) is shown to the student. These are usually accompanied with a <code>Context()->texStrings</code>, to tell MathObjects (such as <code>$a</code> in the previous example) to display themselves using TeX formatting, and <code>Context()->normalStrings</code> to turn the default behaviour back on.

The text can be formatted with a number of special characters and variables:

* mathematical equations can be typeset with a LaTeX-like formatting macros within <code>$</code> and <code>$</code> delimiters (displayed inline with text) or <code>\[</code> and <code>\]</code> (displayed in their own block).
* line breaks are denoted with <code>$BR</code> and new paragraphs with <code>$PAR</code>.
* additional formatting is done using special variables to typeset text in bold (between <code>$BBOLD</code> and <code>$EBOLD</code>) or italic (<code>$BITALIC</code> and <code>$EITALIC</code>)
* if you need to execute any code in the text section, enclose it with <code>\{</code> and <code>\}</code> delimiters. The resulting value is converted to text and inserted at that point in the section. There are quite a few built-in functions that are used in this manner to, for instance, show images or tables. More fundamentally, this method is used to insert a field for student's answer. In the following example, we use <code>ans_rule(6)</code> to insert a blank text entry field six characters wide:

<pre>
TEXT(beginproblem());
Context()->texStrings;
BEGIN_TEXT
What number is one greater than $ $a $?
$PAR
$ $a + 1 = $ \{ ans_rule(35) \}
END_TEXT
Context()->normalStrings;
</pre>

== Answer and Solution ==
The answer and solution section specifies how the answer(s) to the problem is(are) marked for correctness. Optionally, it can also give a solution that is shown to the student after the problem set is complete.

The student's answer is evaluated with the <code>ANS</code> command, in which we give it an "answer checker" that compares the student's entry with the correct value (here, <code>$a_plus_1->cmp()</code>).

The optional solution is only visible to students after the homework deadline. In it, you are free to explain the correct solution using a combination of text and math formulas just as in the problem text. The only difference is that this section is enclosed in <code>BEGIN_SOLUTION</code> and <code>END_SOLUTION</code> pair, rather than <code>BEGIN_TEXT</code>/<code>END_TEXT</code>.

Finally, your document '''must''' end with a <code>ENDDOCUMENT();</code> as the last command in the file.

<pre>
ANS($a_plus_1->cmp());

Context()->texStrings;
BEGIN_SOLUTION
Because $ $a + 1 = $a_plus_1 $, the correct answer is $ $a_plus_1 $.

END_SOLUTION
Context()->normalStrings;

ENDDOCUMENT();
</pre>

== Note ==

Because PG files are really syntactically correct Perl code, you are free to use all of Perl's standard functionality. (Well, almost: functions that would expose potential security holes, such as accessing files or running processes, are disabled.) In particular, this means that you are free to include comments in your file, starting them with the standard Perl comment character <tt>#</tt>. You will see comments in the attached complete PG file.

== Complete source code ==
Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WebWork expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WebWork browser-based problem editor.

[[Media:Pg structure.pg.txt|Template file source.]]

[[Category: WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric response

2016-01-07T19:58:21Z

DavorCubranic: Add the WeBWorK category

== Goal ==

Your problem has a single correct answer that is a scalar and that the student enters into a text field.

== Solution ==

There are two parts to your code:

# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Problem Set-up|problem set-up]] section, create a <code>Real</code> MathObject with the correct value and assign it to a known variable. E.g, <code>$meaning_of_life = Real(42);</code>.
# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Answer and Solution|answer]] section, call the <code>ANS</code> command with the correct value's <code>cmp</code> method. E.g., <code>ANS($meaning_of_life->cmp)</code>.

== Note ==

The default setting accepts as correct student answers that differ from the correct value by 0.1 percent. If this isn't what you want, you will need to set an alternative value for the answer checker's tolerance. For example, <code>ANS($meaning_of_life->cmp(tolerance => 0))</code>, but in that case be careful of rounding and numerical accuracy issues.

See the page on [[Documentation:WeBWorK/Problem Authoring Templates/Numeric tolerance|numeric tolerance]] for more templates, and the [http://webwork.maa.org/wiki/Context_flags#tolerance MAA wiki] for details.

== Source code ==

Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WebWork expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WebWork browser-based problem editor.

[[Media:Numeric response.pg.txt|Template file source.]]

[[Category: WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric tolerance

2016-01-07T19:58:16Z

DavorCubranic: Add the WeBWorK category

== Goal ==

Your problem has a scalar correct answer that is acceptable within some tolerance limites and that the student enters into a text field.

== Solution ==

There are two parts to your code:

# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Problem Set-up|problem set-up]] section, create a <code>Real</code> MathObject with the correct value and assign it to a known variable. E.g, <code>$meaning_of_life = Real(42);</code>.
# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Answer and Solution|answer]] section, call the <code>ANS</code> command with the correct value's <code>cmp</code> method, specifying the tolerance within it. There are two types of tollerance:
## absolute: student's answer is accepted if the absolute difference with the correct answer is lower than the tolerance. For instance, if the correct value is 42, and absolute tolerance value is 0.5, then students answers in the interval (41.5, 42.5) will be accepted. (Note that the interval is open: 41.5 and 42.5 will not be accepted as correct.) This is done as follows: <code>ANS($meaning_of_life->cmp(tolType => 'absolute', tolerance => 0.5))</code>.
## relative: student's answer is accepted if the absolute difference of the correct value and student's answer divided by the correct value is lower than the tolerance. For instance, if the correct value is 42, and relative tolerance value is 0.1 (10%), then students' answers must be in the interval (37.8, 46.2). This is done as follows: <code>ANS($meaning_of_life->cmp(tolType => 'relative', tolerance => 0.1))</code>.

== Note ==

This method expects the tolerance interval to be symmetric around the correct value. If you want an asymmetric interval, you have to use a custom answer checker and do the comparison yourself. For instance, let's say you want to allow tolerance of -10% and +20% — i.e., if the correct answer is 42, then student answers in the interval (37.8, 50.4) are accepted:

<pre>
ANS($meaning_of_life->cmp(checker => sub {
my ($correct, $student) = @_;
my $cv = $correct->value;
my $sv = $student->value;
return $sv > ($cv * .9) &&
$sv < ($cv * 1.2);
}));
</pre>

See the MAA wiki for details of configuring and using the [http://webwork.maa.org/wiki/Context_flags#tolerance built-in tolerance checking]; and [http://webwork.maa.org/wiki/Custom_Answer_Checkers custom answer checkers].

== Source code ==

Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WebWork expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WebWork browser-based problem editor.

[[Media:Numeric tolerance.pg.txt|Template file source.]]

[[Media:Numeric custom tolerance.pg.txt|Template file using a custom checker.]]

[[Category: WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric from list

2016-01-07T19:58:11Z

DavorCubranic: Add the WeBWorK category

== Goal ==

Your problem has a correct answer that is a scalar entered by the student into a text field, but there may be more than one correct value, any of which is acceptable.

== Solution ==

There are two parts to your code:

# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Problem Set-up|problem set-up]] section, create a <code>List</code> of <code>Real</code> MathObjects with the correct values and assign it to a known variable. E.g, <code>$meaning_of_life = List(Real(0), Real(42));</code>.
# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Answer and Solution|answer]] section, call the <code>ANS</code> command with the correct value's <code>cmp</code> method, giving it a custom '' '''list''' '' answer checker that will give full points if the student's answer is any of the acceptable values. The custom checker in this case receives as arguments a reference to the list of correct values, reference to the student's answer (also a list, even if containing zero or one elements), and a reference to the AnswerHash, a data structure of additional information about the answer checker and the student's answer (see the [http://webwork.maa.org/wiki/Custom_Answer_Checkers MAA wiki] for the full details). Your checker needs to iterate through the list of correct values, compare each one to the student's answer, and award the full points (i.e., the score of length equal to the number of acceptable answers) if any of them match, or zero otherwise. For example:
<pre>
ANS($meaning_of_life->cmp(list_checker => sub {
my ($correct, $student, $ansHash) = @_;
my $score = 0;
my @errors; # stores error messages
if (scalar(@{$student} == 1)) {
my $answer = ${$student}[0];

# iterate through correct values and compare them to
# the student's answer
foreach my $value (@{$correct}) {
# this uses the currently active tolerance value
# (e.g., as set for the context or the specific Real MathObject)
if (($value <=> $answer) == 0) {
# WebWork interprets "score" as the number of correct
# values in the student's answer. In this case, getting
# one value correct should be treated as getting all of
# them correct:
$score = scalar(@{$correct});
last;
}
}
# if we get to here and the score is still 0, the
# student's answer didn't match any of the correct values
if ($score == 0 && ! $ansHash->{isPreview}) {
push @errors, "Not correct";
}
}
elsif (! $ansHash->{isPreview}) {
push @errors, "You have to enter a single number";
}
return ($score, @errors);
}));</pre>

See the [http://webwork.maa.org/wiki/Custom_Answer_Checkers_for_Lists MAA wiki] for details.

== Source code ==

Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WebWork expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WebWork browser-based problem editor.

[[Media:Numeric from list.pg.txt|Template file source.]]

[[Category: WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates

2016-01-07T19:56:41Z

DavorCubranic: Add the WeBWorK category

We have created a number of template files that you can customize to use in your own WebWork problems.

If you are new to WebWork, here is a template for the basic [[Documentation:WeBWorK/Problem_Authoring_Templates/PG_Structure|problem structure]].

The templates are organized by the type of answer they accept:

Short answer:
# Numerical, only one response accepted: [[Documentation:WeBWorK/Problem_Authoring_Templates/Numeric response|template]].
# Numerical, response accepted within specified tolerance: [[Documentation:WeBWorK/Problem_Authoring_Templates/Numeric tolerance|template]].
# Numerical, response accepted from list: [[Documentation:WeBWorK/Problem_Authoring_Templates/Numeric from list|template]].
# String response

Multiple choice:
# One correct answer, no responses anchored.
# One correct answer, one response anchored.
# More than one correct answer (anchoring would be as above, so extra template for anchoring not required).
# Answer selected from pull-down menu.

[[Category: WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R

2016-01-07T00:36:56Z

DavorCubranic: The subpages have been renamed with the correct spelling of "WeBWorK", so we need to update the link to them

[[Documentation:WeBWorK|WeBWorK]] is widely used in math courses
around the world, but its adoption in statistics has been limited. One
reason is that while WebWork implements a broad range of arithmetic
and calculus-type operations, it has little support for statistical
concepts such as probability distributions or statistical models.

The WeBWorKiR (WeBWorK integrating R) project offers a solution in the
form of integration between WeBWorK and the
[http://www.r-project.org statistical computing software R]. The open
source software R is extremely popular in statistical research,
analysis, and education. It provides a huge range of operations for
statistical computation and graphics. The WeBWorKiR project has two
main goals: (i) to allow WeBWorK to communicate with R and (ii) the
creation of a large collection of homework questions for use in
undergraduate instruction in statistics. With the WeBWorKiR project,
instructors can use R code in their WebWorK problems to generate data,
perform analyses, and create figures.

WeBWorKiR has been developed in the Department of Statistics since
June 2012, with the funding from Teaching and Learning Improvement
Fund. It has been used in a number of second- and third-year
Statistics courses at UBC, reaching around 3000 students so far. The
aim is that problems created and tested on students through the
WeBWorKiR project are made available to all educators via WeBWorK's
Open Problem Library.

If you are an instructor, please look at the [[Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/Authoring_guide|authoring]] guide for
information on writing WebWork questions that make use of R. If you
are a WebWork system administrator, you can find setup information in
our [[Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/Installation_guide|installation guide]].

[[Category: WeBWorK]]

== Subpages ==
{{Special:PrefixIndex/Documentation:WeBWorK/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/}}

Documentation:WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Installation guide

2016-01-07T00:35:21Z

DavorCubranic: DavorCubranic moved page Documentation:WeBWork/The WeBWorKiR Project: Integrating WeBWorK with R/Installation guide to Documentation:WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Installation guide: Use correct and consistent spelli...

#REDIRECT [[Documentation:WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Installation guide]]

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Installation guide

2016-01-07T00:35:20Z

== WeBWorKiR Installation Guide ==

The audience for this guide are system administrators who want to set
up R integration in WeBWorK. We assume that you already have, or know
how to set up, a basic WeBWorK server. If not, please see the
[http://webwork.maa.org/wiki/Release_notes_for_WeBWorK_2.8 release notes] on the WeBWorK wiki and the [http://webwork.maa.org/wiki/Installation_Manual_for_2.8_on_Ubuntu_12.04 guide] to installing WeBWorK on an Ubuntu server. You may also find
Jason Aubrey's [https://github.com/aubreyja/ww_install/ ww_install] installation script useful.

== Installation ==

After you have a working WeBWorK server, there are three distinct steps that need to happen:

# set up the R server
# install the Perl module for the Perl-R bridge
# configure WeBWorK to use this module in PG

=== Set up the R server ===

Your R server (which can be on the same server as WeBWorK, but in a real-world scenario will more likely run on its own hardware/VM), is quite easy to set up:

# install R following OS-specific instructions on the project [http://www.r-project.org homepage].
# install the [http://www.rforge.net/Rserve/ Rserve] server, which allows remote clients to execute R code on the Rserve's server and returns the execution's result in response. The easiest way is to run (as an administrative user) <code>Rscript -e 'install.packages("Rserve", repo="http://cran.rstudio.com")'</code>. Note that this package includes C source that needs to be compiled, so you have to have the basic developer tools present on the server.
# run the Rserve service as appropriate to your system. The command you need to run is "R CMD Rserve". This will start the Rserve daemon which will listen on port 6311. The daemon only accepts connections from the localhost; if you run WebWork and Rserve on separate servers, read the final section of this page for additional configuration steps for your system.

=== Install the Perl-R bridge ===

Perl module [http://search.cpan.org/perldoc?Statistics::R::IO Statistics::R::IO] implements Rserve's communication protocol in Perl and provides translation from R data structures to Perl's. It is available on CPAN and can be installed in the standard manner for Perl modules, e.g., by running (as an admin user) <code>cpan Statistics::R::IO</code>.

=== Configure Webwork to use the Perl-R bridge in PG ===

Once the Perl module RserveClient is installed, you can make its functionality available in webwork problems by installing the RserveClient.pl macro and adding the module to the list of modules preloaded by WeBWorK. We use use "${WW_PREFIX}" to indicate the directory where WeBWorK is installed. (This directory will, for instance, contain subdirectories "webwork2" and "pg"; a typical choice is "/opt/webwork", but a different one may be used on your system.)

<ol style="list-style-type: decimal;">
<li>install RserveClient.pl macro into "$WW_PREFIX/pg/macros":
<pre>
wget -q -O ${WW_PREFIX}/pg/macros/RserveClient.pl \
https://raw.githubusercontent.com/cubranic/Statistics-R-IO/release/extras/WebWork/RserveClient.pl
</pre>
perhaps a better solution, but depending on having the Perl module File::ShareDir, ensures that the RserveClient.pl macro matches the version of Statistics::R::IO that you have installed:
<pre>
cp "`perl -MFile::ShareDir -e 'print File::ShareDir::dist_file(\"Statistics-R-IO\", \"WebWork/RserveClient.pl\")'`" \
${WW_PREFIX}/pg/macros/RserveClient.pl
</pre>
</li>
<li>add the RserveClient module(s) to the list of modules preloaded by
WeBWorK, so that it is available to the RserveClient.pl macro. You can
do this by modifying "${WW_PREFIX}/webwork2/conf/defaults.conf",
but since it's a local configuration, you should put it in
localOverrides.conf:
<pre>
cat >> ${WW_PREFIX}/webwork2/conf/localOverrides.conf <<'EOF'
push @{$pg{modules}},
[qw( Statistics::R::IO::Rserve )],
[qw( Statistics::R::IO::ParserState )],
[qw( Statistics::R::REXP::Character )],
[qw( Statistics::R::REXP::Double )],
[qw( Statistics::R::REXP::Environment )],
[qw( Statistics::R::REXP::GlobalEnvironment )],
[qw( Statistics::R::REXP::Integer )],
[qw( Statistics::R::REXP::Language )],
[qw( Statistics::R::REXP::List )],
[qw( Statistics::R::REXP::Logical )],
[qw( Statistics::R::REXP::Null )],
[qw( Statistics::R::REXP::Raw )],
[qw( Statistics::R::REXP::Symbol )],
[qw( Statistics::R::REXP::Unknown )],
[qw( Statistics::R::REXP::Vector )],
[qw( Statistics::R::REXP )],
[qw( IO::File )],
[qw( IO::Handle )],
[qw( Moose )],
[qw( Class::MOP )];
$pg{specialPGEnvironmentVars}{Rserve} = {host => "localhost"};

1;
EOF
</pre>
</li>
</ol>

=== Additional configuration when WeBWorK and R are on separate hosts ===

If you run WeBWorK and R on separate hosts, you can either set up a tunnel to forward port 6311 from WeBWorK to R's host, or do the following:

<ol style="list-style-type: decimal;">
<li>set up Rserve to listen on all network interfaces, not just localhost by adding a line "remote enable" to file "/etc/Rserv.conf":
<pre>cat <'EOF' >> /etc/Rserv.conf
remote enable
EOF
</pre>
</li>
<li>use the correct host name (instead of "localhost") in the "Rserve host" line of "localOverrides.conf". For example:
<pre>$pg{specialPGEnvironmentVars}{Rserve} = {host => "www.example.com"};
</pre>
</li></ol>

Note that in this case you will also want to set up the Rserve host's firewall to only allow connections from the WeBWorK host(s), or otherwise it will happily execute arbitrary code from any Rserve client anywhere on the internet!

[[Category: WeBWorK]]

Documentation:WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Authoring guide

2016-01-07T00:34:44Z

DavorCubranic: DavorCubranic moved page Documentation:WeBWork/The WeBWorKiR Project: Integrating WeBWorK with R/Authoring guide to Documentation:WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Authoring guide: Use correct and consistent spelling of...

#REDIRECT [[Documentation:WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Authoring guide]]

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Authoring guide

2016-01-07T00:34:44Z

== WeBWorKiR User Guide ==

The audience for this guide are problem authors who want to use R's
facilities in their WeBWorK questions. We assume that you already know
how to create problems with the PG language (which itself is a subset
of Perl) and are familiar with the concepts of macros in PG. We also
assume that your WeBWorKiR environment has been set up as described in
the [[Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/Installation_guide|installation guide]].

=== Background ===

WeBWorKiR is a system that involves two separate servers: WeBWorK and
R. In a normal operation, when a student accesses WeBWorK via a web
browser to work on homework problems, WeBWorK runs the PG code
defining the problem to compute:

a) values used in the question, for example a random vector of five integers

b) the text of the question, typically given in format resembling LaTeX and optionally displaying values computed in (a)

c) values of the correct answer, for example, the mean of the vector calculated in (a)

WeBWorKiR adds to this the ability to run arbitrary computations in R
and make their results available to the rest of the PG code as if they
were constructed using the standard PG functions. (In our running
example, we could construct the random vector in R with `sample`,
and/or calculate its mean with `mean`.) The reason why one might want
to do this is R's rich library of high-quality statistical functions
as well as its graphical abilities. While in theory these could be
both replicated with PG, it would take a huge effort that can be
better spent by simply using the functionality already available in R.

The way this works is that WeBWorK uses a Perl module that can talk to
a server running the [[http://www.rforge.net/Rserve/|Rserve]] software,
which allows remote clients to execute R code on the Rserve's server
and returns the execution's result in response. The Perl module
converts this response from R's native values (e.g., a generic vector,
aka "list") to those understandable to Perl (e.g., an array), making
them available to the rest of the PG code.

== Loading the macros ==

To use R code in a problem, include "RserveClient.pl" in the
"loadMacros" call at the start of the question. For example:

<pre>
loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl" # <--- R integration
);
</pre>

== Basic Rserve macros ==

The Rserve software creates an R session for each remote client. This
means that clients' interactions with R are kept separate from each
other, just as if you started R twice on your local computer. A
session persists as long as the client is connected, so that multiple
calls from the client using the same session see the objects created
in previous calls. (This behaviour mirrors what happens in a local
session, where each R command you execute at the console after
pressing ENTER sees the results of earlier commands.) When a sessions
is *closed*, its contents are wiped off without a trace, just like
quitting the R application run locally.

The RserveClient offers macros to start and finish a session, and
execute R commands in the current session:

<ol style="list-style-type: decimal;">
<li><code>rserve_eval("some R code")</code>: this function sends the R code given
as its string argument to Rserve for execution. It returns *an
array* representation of the R code's result. (This means that the
value of <code>rserve_eval("pi")</code> is an array with a single element
3.14159265358979. If you want to keep this value and use it in the
rest of the problem, assign it to an array variable. For example:
<pre>@pi = rserve_eval("pi");</pre>
'''Note:''' Multiple calls within the same problem share the R session and the object workspace, so you can break up your R code in as many <tt>rserve_eval</tt> statements as you'd like.</li>

<li><code>rserve_start()</code>, <code>rserve_finish()</code>: Start up and close the current connection to the Rserve server. In
normal use, these functions are completely optional because the first
call to <code>rserve_eval</code> will call start the Rserve session if one is not
already open. Similarly, the current session will be automatically closed at the end of the problem.
Other than backward compatibility, the only reason for using these
functions is to start a new clean session within a single problem,
which shouldn't be a common occurrence.</li>
</ol>

=== A note on Perl quoting rules ===

Beware of Perl's quoting rules when writing R code. The text in double
quotes gets interpreted for escape sequences (e.g., <code>"\n"</code> represents a
newline) and variables (e.g., <code>"The value of pi is $pi[0]"</code> will be
interpolated into <code>"The value of pi is 3.14159265358979"</code>, given the
code above). This is a problem if you're trying to extract an element
of a list by name using the <code>"$"</code> operator in R because the text
following it will be interpreted as a variable. For instance, running
<code>rserve_eval("cars$speed")</code> will not return the "speed" column of the
standard "cars" dataset, because "$speed" in the string will be
replaced by the value of the PG variable <code>$speed</code>, which if not yet
defined will be empty string, so that the R code that actually gets
executed is simply "cars". Instead, using single quotes, which prevent
variable and escape sequence interpolation and instead keep the string
exactly as entered: <code>rserve_eval('cars$speed')</code>.

On the other hand, some time you actually might want variable
interpolation to be done, for instance to construct the R code that
uses values of variables constructed with PG functions. For instance:

<pre>
Context("Numeric");

$pi = Real("pi");
@difference = rserve_eval("pi - $pi");
</pre>

will calculate the difference between the value between R and PG's
values of "pi" and put the result in the <tt>@difference</tt> array. Note that
the same R code can be constructed using Perl's string concatenation
operator dot ("."): <tt>rserve_eval('pi - ' . $pi)</tt>. Personally, I
recommend sticking with single quotes to prevent unwanted surprises,
and using the dot operator if needing to include the value of a PG
variable.

== Displaying R graphics ==

R has excellent facilities for creating production-quality statistical
graphics, from simple scatterplots to complex spatial visualizatons
overlaid on geographical maps. These graphics can be produced in a
variety of formats (in R parlance, devices), from the user's monitor
to PDF or JPG files. The RserveClient allows the author to present
these graphics in the question by bracketing the R graphing code with
macros <tt>rserve_start_plot</tt> and <tt>rserve_finish_plot</tt>, and then showing
the produced image in the question with PG's macro <tt>image</tt> (see the
WeBWorK [http://webwork.maa.org/wiki/Image documentation]).

The following code is a complete example

<pre>
DOCUMENT();

loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl",
);

# Print problem number and point value (weight) for the problem
TEXT(beginproblem());

# Setup
Context("Numeric");

$mean = random(-2, 2, .5);

$img = rserve_start_plot('png');
rserve_eval('curve(dnorm(x, mean=' . $mean . '), xlim=c(-4, 4)); 0');
$image_path = rserve_finish_plot($img);

# Text
Context()->texStrings;
BEGIN_TEXT

What is the mean of the normal distribution shown in the figure below:
\{ ans_rule(5) \}

$PAR

\{ image($image_path, width=>300, height=>300) \}:
END_TEXT

Context()->normalStrings;

# Answers
ANS(Real($mean)->cmp);

ENDDOCUMENT();
</pre>

The four key lines are as follow:

<ol style="list-style-type: decimal;">
<li><code>$img = rserve_start_plot('png')</code>: sets up R to plot to a 'PNG'
file and returns a unique plot identifier to be used later.</li>

<li><code>rserve_eval('curve(...)')</code>: runs plotting commands on the R server</li>

<li><code>$image_path = rserve_finish_plot($img)</code>: completes the plotting
to the PNG file and transfers it to a location on the WebWork
server. Returns the path of the file, which is stored in Perl variable <code>$image_path</code>
and later used as the first argument to the <code>image</code> macro.</li>

<li><code>\{ image($image_path, width=>300, height=>300) \}</code>: inserts the
image into the web page.</li>
</ol>

== Transferring files from the R server ==

Sometimes it may be convenient to make a file from R server available to the student via a link in Webwork. (For instance, using R to generate a (potentially randomized) data file that the student can download to work on the problem offline.) The macro <code>rserve_get_file REMOTE_NAME [, LOCAL_NAME]</code> can be used to transfer the file ''REMOTE_NAME'' from the R server to WebWork's temporary
file area, and returns the name of the local file that can then be
used by the <code>htmlLink</code> macro. Specifying ''LOCAL_NAME'' is optional; if it is not specified, the
filename portion of the ''REMOTE_NAME'' is used.

The following code is a complete example

<pre>
DOCUMENT();

loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl",
);

# Print problem number and point value (weight) for the problem
TEXT(beginproblem());

# Setup
Context("Numeric");

my ($intercept, $slope) = rserve_eval('coef(lm(log(dist)~log(speed), data = cars))');

my ($remote_file) = rserve_eval('filename <- tempfile(fileext=".csv"); write.csv(cars, filename); filename');
my $local_file = rserve_get_file($remote_file);

($local_url = $local_file) =~ s|$tempDirectory|$tempURL|;

# Text
Context()->texStrings;
BEGIN_TEXT

What is the slope of the linear regression of log-transformed stopping distance vs. car speed in the dataset linked below:
\{ ans_rule(5) \}

$PAR

\{ htmlLink($local_url, "Download") \} the problem data (CSV file).

END_TEXT

Context()->normalStrings;

# Answers
ANS(Real($slope)->cmp);

ENDDOCUMENT();
</pre>

The four key lines are as follow:

<ol style="list-style-type: decimal;">
<li><code>my ($remote_file) = rserve_eval('filename <- tempfile(fileext=".csv"); write.csv(cars, filename); filename')</code>: stores the desired dataset into a temporary CSV file on the R server and returns its path, which is stored in Perl variable <code>$remote_file</code>.</li>

<li><code>my $local_file = rserve_get_file($remote_file)</code>: transfers the file from the R server to WeBWorK's temporary file area and returns its path, which is stored in Perl variable <code>$local_file</code>.</li>

<li><code>($local_url = $local_file) =~ s|$tempDirectory|$tempURL|</code>: converts the local file path into a URL that can be used as an argument to the <code>htmlLink</code> macro, saving it in Perl variable <code>$local_url</code>.</li>

<li><code>\{ htmlLink($local_url, "Download") \}</code>: inserts the
link to the downloaded file into the web page.</li>
</ol>

[[Category:WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric tolerance

2015-09-24T16:36:09Z

DavorCubranic: Clarify the meaning of the absolute difference

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric tolerance

2015-01-31T00:52:09Z

DavorCubranic: Fix code example and add a link to the template using the custom checker

== Goal ==

Your problem has a scalar correct answer that is acceptable within some tolerance limites and that the student enters into a text field.

== Solution ==

There are two parts to your code:

# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Problem Set-up|problem set-up]] section, create a <code>Real</code> MathObject with the correct value and assign it to a known variable. E.g, <code>$meaning_of_life = Real(42);</code>.
# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Answer and Solution|answer]] section, call the <code>ANS</code> command with the correct value's <code>cmp</code> method, specifying the tolerance within it. There are two types of tollerance:
## absolute: the decimal distance from the correct answer that will be allowed. For instance, if the correct value is 42, and absolute tolerance value is 0.5, then students answers in the interval (41.5, 42.5) will be accepted. This is done as follows: <code>ANS($meaning_of_life->cmp(tolType => 'absolute', tolerance => 0.5))</code>.
## relative: student's answer are accepted if the absolute difference of the correct value and student's answer divided by the correct value is lower than the tolerance. For instance, if the correct value is 42, and relative tolerance value is 0.1 (10%), then students' answers must be in the interval (37.8, 46.2). This is done as follows: <code>ANS($meaning_of_life->cmp(tolType => 'relative', tolerance => 0.1))</code>.

== Note ==

This method expects the tolerance interval to be symmetric around the correct value. If you want an asymmetric interval, you have to use a custom answer checker and do the comparison yourself. For instance, let's say you want to allow tolerance of -10% and +20% — i.e., if the correct answer is 42, then student answers in the interval (37.8, 50.4) are accepted:

<pre>
ANS($meaning_of_life->cmp(checker => sub {
my ($correct, $student) = @_;
my $cv = $correct->value;
my $sv = $student->value;
return $sv > ($cv * .9) &&
$sv < ($cv * 1.2);
}));
</pre>

See the MAA wiki for details of configuring and using the [http://webwork.maa.org/wiki/Context_flags#tolerance built-in tolerance checking]; and [http://webwork.maa.org/wiki/Custom_Answer_Checkers custom answer checkers].

== Source code ==

Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WebWork expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WebWork browser-based problem editor.

[[Media:Numeric tolerance.pg.txt|Template file source.]]

[[Media:Numeric custom tolerance.pg.txt|Template file using a custom checker.]]

File:Numeric custom tolerance.pg.txt

2015-01-31T00:51:30Z

DavorCubranic: User created page with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=WebWork problem template for a numeric response accepted within an asymmetric tolerance range using a custom answer checker.}}
|date=2015-01-30 16:48:54
|source={{own}}
|author=[[User:DavorCubranic|DavorCubranic]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Uploaded with UploadWizard]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric tolerance

2015-01-31T00:30:04Z

DavorCubranic: Add an example of a custom checker for asymmetric tolerance interval

== Goal ==

Your problem has a scalar correct answer that is acceptable within some tolerance limites and that the student enters into a text field.

== Solution ==

There are two parts to your code:

# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Problem Set-up|problem set-up]] section, create a <code>Real</code> MathObject with the correct value and assign it to a known variable. E.g, <code>$meaning_of_life = Real(42);</code>.
# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Answer and Solution|answer]] section, call the <code>ANS</code> command with the correct value's <code>cmp</code> method, specifying the tolerance within it. There are two types of tollerance:
## absolute: the decimal distance from the correct answer that will be allowed. For instance, if the correct value is 42, and absolute tolerance value is 0.5, then students answers in the interval (41.5, 42.5) will be accepted. This is done as follows: <code>ANS($meaning_of_life->cmp(tolType => 'absolute', tolerance => 0.5))</code>.
## relative: student's answer are accepted if the absolute difference of the correct value and student's answer divided by the correct value is lower than the tolerance. For instance, if the correct value is 42, and relative tolerance value is 0.1 (10%), then students' answers must be in the interval (37.8, 46.2). This is done as follows: <code>ANS($meaning_of_life->cmp(tolType => 'relative', tolerance => 0.1))</code>.

== Note ==

This method expects the tolerance interval to be symmetric around the correct value. If you want an asymmetric interval, you have to use a custom answer checker and do the comparison yourself. For instance, let's say you want to allow tolerance of -10% and +20% — i.e., if the correct answer is 42, then student answers in the interval (37.8, 50.4) are accepted:

<pre>
ANS($meaning_of_life->cmp(checker => sub {
my ($correct, $student) = @_;
my $cv = $correct->value;
my $sv = $student->value;
return $sv > ($cv * .9) &&
$sv > ($cv * 1.2);
}));
</pre>

See the MAA wiki for details of configuring and using the [http://webwork.maa.org/wiki/Context_flags#tolerance built-in tolerance checking]; and [http://webwork.maa.org/wiki/Custom_Answer_Checkers custom answer checkers].

== Source code ==

Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WebWork expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WebWork browser-based problem editor.

[[Media:Numeric tolerance.pg.txt|Template file source.]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric response

2015-01-29T01:03:00Z

DavorCubranic: Add a link to the template source file

File:Numeric response.pg.txt

2015-01-29T01:02:09Z

DavorCubranic: User created page with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=WebWork problem template for numeric responses.}}
|date=2015-01-28 17:01:32
|source={{own}}
|author=[[User:DavorCubranic|DavorCubranic]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Uploaded with UploadWizard]]

File:Numeric tolerance.pg.txt

2015-01-29T00:00:19Z

DavorCubranic: DavorCubranic uploaded a new version of "File:Numeric tolerance.pg.txt"

=={{int:filedesc}}==
{{Information
|description={{en|1=WebWork problem template for a numeric response accepted within a given tolerance.}}
|date=2015-01-28 15:55:26
|source={{own}}
|author=[[User:DavorCubranic|DavorCubranic]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Uploaded with UploadWizard]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric tolerance

2015-01-28T23:56:43Z

DavorCubranic: Add a link to the complete template source code

File:Numeric tolerance.pg.txt

2015-01-28T23:56:07Z

DavorCubranic: User created page with UploadWizard

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric tolerance

2015-01-28T23:39:49Z

DavorCubranic: Fix missing parentheses in code samples

File:Numeric from list.pg.txt

2015-01-28T21:11:46Z

DavorCubranic: User created page with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=WebWork problem template that for a numerical response accepted from a list.}}
|date=2015-01-28 13:10:52
|source={{own}}
|author=[[User:DavorCubranic|DavorCubranic]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Uploaded with UploadWizard]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric from list

2015-01-28T21:09:49Z

DavorCubranic: Fix the template code

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric from list

2015-01-28T19:59:48Z

DavorCubranic: Add details and an example of the custom list answer checker

== Goal ==

Your problem has a correct answer that is a scalar entered by the student into a text field, but there may be more than one correct value, any of which is acceptable.

== Solution ==

There are two parts to your code:

# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Problem Set-up|problem set-up]] section, create a <code>List</code> of <code>Real</code> MathObjects with the correct values and assign it to a known variable. E.g, <code>$meaning_of_life = List(Real(0), Real(42));</code>.
# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Answer and Solution|answer]] section, call the <code>ANS</code> command with the correct value's <code>cmp</code> method, giving it a custom answer checker that will give full points if the student's answer is any of the acceptable values. The custom checker in this case receives as arguments a reference to the list of correct values, reference to the student's answer (also a list, even if containing zero or one elements), and a reference to the AnswerHash, a data structure of additional information about the answer checker and the student's answer (see the [http://webwork.maa.org/wiki/Custom_Answer_Checkers MAA wiki] for the full details). Your checker needs to iterate through the list of correct values, compare each one to the student's answer, and award the full points (i.e., the score of 1) if any of them match, or zero otherwise. For example:
<pre>
ANS($meaning_of_life->cmp(list_checker => sub {
my ($correct, $student, $ansHash) = @_;
my $score = 0;
my @errors; # stores error messages
if (scalar(@{$student} == 1) {
my $answer = ${$student}[0];
foreach my $x (@{$correct}) {
# this uses the currently active tolerance value
# (e.g., as set for the context or the specific Real MathObject)
if (($x <=> $answer) == 0) {
$score = 1;
break;
}
}
# if we get to here and the score is still 0, the
# student's answer didn't match any of the correct values
if (score == 0 && ! $ansHash->{isPreview}) {
push @errors, "Not correct";
}
}
elsif (! $ansHash->{isPreview}) {
push @errors, "You have to enter a single number";
}
return ($score, @errors);
}));
</pre>

See the [http://webwork.maa.org/wiki/Custom_Answer_Checkers_for_Lists MAA wiki] for details.

== Source code ==

Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WebWork expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WebWork browser-based problem editor.

[[Media:Pg structure.pg.txt|Template file source.]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric from list

2015-01-28T00:56:58Z

DavorCubranic: Create the page

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates

2015-01-28T00:50:30Z

DavorCubranic: Add a link to the "Numeric from list" template

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric response

2015-01-28T00:33:20Z

DavorCubranic: Add an example of changing numeric tolerance

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric tolerance

2015-01-24T00:25:52Z

DavorCubranic: Provide tolerance explanation and examples

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates

2015-01-23T22:17:53Z

DavorCubranic: Add a link to the "Numeric with tolerance" template)

We have created a number of template files that you can customize to use in your own WebWork problems.

If you are new to WebWork, here is a template for the basic [[Documentation:WeBWorK/Problem_Authoring_Templates/PG_Structure|problem structure]].

The templates are organized by the type of answer they accept:

Short answer:
# Numerical, only one response accepted: [[Documentation:WeBWorK/Problem_Authoring_Templates/Numeric response|template]].
# Numerical, response accepted within specified tolerance: [[Documentation:WeBWorK/Problem_Authoring_Templates/Numeric tolerance|template]].
# Numerical, response accepted from list.
# String response

Multiple choice:
# One correct answer, no responses anchored.
# One correct answer, one response anchored.
# More than one correct answer (anchoring would be as above, so extra template for anchoring not required).
# Answer selected from pull-down menu.

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric tolerance

2015-01-23T22:16:30Z

DavorCubranic: Initial outline

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates

2015-01-22T01:02:59Z

DavorCubranic: Add a link to the "Numeric response" template

We have created a number of template files that you can customize to use in your own WebWork problems.

If you are new to WebWork, here is a template for the basic [[Documentation:WeBWorK/Problem_Authoring_Templates/PG_Structure|problem structure]].

The templates are organized by the type of answer they accept:

Short answer:
# Numerical, only one response accepted: [[Documentation:WeBWorK/Problem_Authoring_Templates/Numeric response|template]].
# Numerical, response accepted within specified tolerance.
# Numerical, response accepted from list.
# String response

Multiple choice:
# One correct answer, no responses anchored.
# One correct answer, one response anchored.
# More than one correct answer (anchoring would be as above, so extra template for anchoring not required).
# Answer selected from pull-down menu.

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/Numeric response

2015-01-22T01:01:25Z

DavorCubranic: Initial page content

== Goal ==

Your problem has a single correct answer that is a scalar and that the student enters into a text field.

== Solution ==

There are two parts to your code:

# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Problem Set-up|problem set-up]] section, create a <code>Real</code> MathObject with the correct value and assign it to a known variable. E.g, <code>$meaning_of_life = Real(42);</code>.
# In the [[Documentation:WeBWorK/Problem Authoring Templates/PG Structure#Answer and Solution|answer]] section, call the <code>ANS</code> command with the correct value's <code>cmp</code> method. E.g., <code>ANS($meaning_of_life->cmp)</code>.

== Note ==

The default setting accepts as correct student answers that differ from the correct value by 0.1 percent. If this isn't what you want, you will need to set an alternative value for the answer checker's tolerance. See [http://webwork.maa.org/wiki/Context_flags#tolerance MAA wiki] for details.

== Source code ==

Please download the following attachment to access the code in a single file. Unfortunately, the Wiki restricts filename extensions, so that it couldn't end in ".pg", which is what WebWork expects. You can rename it after downloading, or simply copy-and-paste its contents into the standard WebWork browser-based problem editor.

[[Media:Pg structure.pg.txt|Template file source.]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates

2015-01-21T00:52:34Z

DavorCubranic: Reorganize and add a link to the basic template

We have created a number of template files that you can customize to use in your own WebWork problems.

If you are new to WebWork, here is a template for the basic [[Documentation:WeBWorK/Problem_Authoring_Templates/PG_Structure|problem structure]].

The templates are organized by the type of answer they accept:

Short answer:
# Numerical, only one response accepted.
# Numerical, response accepted within specified tolerance.
# Numerical, response accepted from list.
# String response

Multiple choice:
# One correct answer, no responses anchored.
# One correct answer, one response anchored.
# More than one correct answer (anchoring would be as above, so extra template for anchoring not required).
# Answer selected from pull-down menu.

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2015-01-21T00:50:20Z

DavorCubranic: Attach template file source

File:Pg structure.pg.txt

2015-01-21T00:39:37Z

DavorCubranic: User created page with UploadWizard

=={{int:filedesc}}==
{{Information
|description={{en|1=This is a minimum useful WebWork problem file, showing the required structure and basic functionality.}}
|date=2015-01-20 16:37:54
|source={{own}}
|author=[[User:DavorCubranic|DavorCubranic]]
|permission=
|other_versions=
}}

=={{int:license-header}}==
{{self|cc-by-sa-3.0}}

[[Category:Uploaded with UploadWizard]]
[[Category:WebWork]]

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2015-01-21T00:36:44Z

DavorCubranic: Remove '$SOLUTION' and add a note on comments

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2015-01-21T00:20:26Z

DavorCubranic: Enter appropriate problem tags

WebWork problems are stored in PG files. These files are typically structured in the following way:

== Tagging and Description ==
The tagging and description section describes the problem for future users and authors. The purpose of the tagging information is to make the problem easier to find by searching or browsing. Each tag must appear on its own line, starting at the first character, and be in the following format: <code>## Tagname(tag value)</code>. There are three required tags, <tt>DBsubject</tt>, <tt>DBchapter</tt>, and <tt>DBsection</tt>, placing the problem in the [http://hobbes.la.asu.edu/Holt/chaps-and-secs.html hierarchy] that's exposed in the Library Browser. Problems should also a <tt>Level</tt>, denoting its difficulty on a predefined [http://webwork.maa.org/wiki/Problem_Levels scale].

Optional tags include <tt>Keywords</tt>, for easier searching, as well as tags to indicate authorship (<tt>Author</tt> and <tt>Institution</tt>), and to link to a specific textbook (<tt>TitleText1</tt>, <tt>EditionText1</tt>, <tt>AuthorText1</tt>, <tt>Section1</tt>, and <tt>Problem1</tt>).

More information on tagging can be found on the [http://webwork.maa.org/wiki/Tagging_Problems WebWork MAA wiki].

<pre>
## DBsubject('Arithmetic')
## DBchapter('Integers')
## DBsection('Addition/subtraction')
## Level(2)
## KEYWORDS('arithmetic', 'adding')
## Author('Davor Cubranic')
## Institution('University of British Columbia')
</pre>

== Initialization ==
The initialization section loads required macros for the problem. It ''must''' begin with the <code>DOCUMENT();</code> command, followed by the <code>loadMacros</code> command that loads additional commands used by the problem. For basic problems, the following is sufficient — template files for specific problem types will tell you if any other macros should be loaded.

<pre>
DOCUMENT();
loadMacros(
"PGstandard.pl",
"MathObjects.pl",
);
</pre>

== Problem Set-up ==
In this section, define variables specific to the problem, for instance various parameters or the correct answer value. These variables are used in subsequent sections either in the text displayed to the student, or to check the answer. You should begin this section with <code>Context</code>, to tell WebWork the type of variables that are used. In this example, we use <code>Context("Numeric")</code> to indicate that the following commands work on scalar numbers.

There are many ways to assign value to variables. The two we show here are:

# by a random draw from a range of values (<code>random</code>, which in this case chooses from a sequence starting at 2, ending at 9, and incrementing by 1, thus choosing integers in the range [2, 9])
# by computing a value (<code>Real</code>) from a math expression, in this case the real number calculated by adding one to the value of <tt>$a</tt>. These are the so-called MathObjects, and they lie at heart of WebWork's functioning. For instance, MathObjects know how to compute or simplify fairly complicated mathematical expressions, how display themselves in a sensible way in the text of the problem, and how to compare themselves to the student's answer . See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_MathObjects introduction to MathObjects] and follow its links to learn additional features as needed.

<pre>
Context("Numeric");

$a = random(2, 9, 1);
$a_plus_1 = Real("$a + 1");
</pre>

See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_Contexts introduction to contexts] and a [http://webwork.maa.org/wiki/ContextList list] of other types of contexts, such as matrices or intervals.

== Text ==
The text section gives the text that is shown to the student. It begins with a line containing <code>TEXT(beginproblem());</code>. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) is shown to the student. These are usually accompanied with a <code>Context()->texStrings</code>, to tell MathObjects (such as <code>$a</code> in the previous example) to display themselves using TeX formatting, and <code>Context()->normalStrings</code> to turn the default behaviour back on.

The text can be formatted with a number of special characters and variables:

* mathematical equations can be typeset with a LaTeX-like formatting macros within <code>$</code> and <code>$</code> delimiters (displayed inline with text) or <code>\[</code> and <code>\]</code> (displayed in their own block).
* line breaks are denoted with <code>$BR</code> and new paragraphs with <code>$PAR</code>.
* additional formatting is done using special variables to typeset text in bold (between <code>$BBOLD</code> and <code>$EBOLD</code>) or italic (<code>$BITALIC</code> and <code>$EITALIC</code>)
* if you need to execute any code in the text section, enclose it with <code>\{</code> and <code>\}</code> delimiters. The resulting value is converted to text and inserted at that point in the section. There are quite a few built-in functions that are used in this manner to, for instance, show images or tables. More fundamentally, this method is used to insert a field for student's answer. In the following example, we use <code>ans_rule(6)</code> to insert a blank text entry field six characters wide:

<pre>
TEXT(beginproblem());
Context()->texStrings;
BEGIN_TEXT
What number is one greater than $ $a $?
$PAR
$ $a + 1 = $ \{ ans_rule(35) \}
END_TEXT
Context()->normalStrings;
</pre>

== Answer and Solution ==
The answer and solution section specifies how the answer(s) to the problem is(are) marked for correctness. Optionally, it can also give a solution that is shown to the student after the problem set is complete.

The student's answer is evaluated with the <code>ANS</code> command, in which we give it an "answer checker" that compares the student's entry with the correct value (here, <code>$a_plus_1->cmp()</code>).

The optional solution is only visible to students after the homework deadline. In it, you are free to explain the correct solution using a combination of text and math formulas just as in the problem text. The only difference is that this section is enclosed in <code>BEGIN_SOLUTION</code> and <code>END_SOLUTION</code> pair, rather than <code>BEGIN_TEXT</code>/<code>END_TEXT</code>. You may use the special <code>$SOLUTION</code> variable to create a heading titled "Solution".

Finally, your document '''must''' end with a <code>ENDDOCUMENT();</code> as the last command in the file.

<pre>
ANS($a_plus_1->cmp());

Context()->texStrings;
BEGIN_SOLUTION
$SOLUTION
Because $ $a + 1 = $a_plus_1 $, the correct answer is $ $a_plus_1 $.

END_SOLUTION
Context()->normalStrings;

ENDDOCUMENT();
</pre>

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2015-01-21T00:13:47Z

DavorCubranic: Write the "Text" section

WebWork problems are stored in PG files. These files are typically structured in the following way:

== Tagging and Description ==
The tagging and description section describes the problem for future users and authors. The purpose of the tagging information is to make the problem easier to find by searching or browsing. Each tag must appear on its own line, starting at the first character, and be in the following format: <code>## Tagname(tag value)</code>. There are three required tags, <tt>DBsubject</tt>, <tt>DBchapter</tt>, and <tt>DBsection</tt>, placing the problem in the [[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html|hierarchy]] that's exposed in the Library Browser. Problems should also a <tt>Level</tt>, denoting its difficulty on a predefined [http://webwork.maa.org/wiki/Problem_Levels scale].

Optional tags include <tt>Keywords</tt>, for easier searching, as well as tags to indicate authorship (<tt>Author</tt> and <tt>Institution</tt>), and to link to a specific textbook (<tt>TitleText1</tt>, <tt>EditionText1</tt>, <tt>AuthorText1</tt>, <tt>Section1</tt>, and <tt>Problem1</tt>).

More information on tagging can be found on the [http://webwork.maa.org/wiki/Tagging_Problems WebWork MAA wiki].

<pre>
## DBsubject('WeBWorK')
## DBchapter('Demos')
## DBsection('Problem')
## KEYWORDS('')
## TitleText1('')
## EditionText1('')
## AuthorText1('')
## Section1('')
## Problem1('')
## Author('Gavin LaRose')
## Institution('UMich')
</pre>

== Initialization ==
The initialization section loads required macros for the problem. It ''must''' begin with the <code>DOCUMENT();</code> command, followed by the <code>loadMacros</code> command that loads additional commands used by the problem. For basic problems, the following is sufficient — template files for specific problem types will tell you if any other macros should be loaded.

<pre>
DOCUMENT();
loadMacros(
"PGstandard.pl",
"MathObjects.pl",
);
</pre>

== Problem Set-up ==
In this section, define variables specific to the problem, for instance various parameters or the correct answer value. These variables are used in subsequent sections either in the text displayed to the student, or to check the answer. You should begin this section with <code>Context</code>, to tell WebWork the type of variables that are used. In this example, we use <code>Context("Numeric")</code> to indicate that the following commands work on scalar numbers.

There are many ways to assign value to variables. The two we show here are:

# by a random draw from a range of values (<code>random</code>, which in this case chooses from a sequence starting at 2, ending at 9, and incrementing by 1, thus choosing integers in the range [2, 9])
# by computing a value (<code>Real</code>) from a math expression, in this case the real number calculated by adding one to the value of <tt>$a</tt>. These are the so-called MathObjects, and they lie at heart of WebWork's functioning. For instance, MathObjects know how to compute or simplify fairly complicated mathematical expressions, how display themselves in a sensible way in the text of the problem, and how to compare themselves to the student's answer . See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_MathObjects introduction to MathObjects] and follow its links to learn additional features as needed.

<pre>
Context("Numeric");

$a = random(2, 9, 1);
$a_plus_1 = Real("$a + 1");
</pre>

See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_Contexts introduction to contexts] and a [http://webwork.maa.org/wiki/ContextList list] of other types of contexts, such as matrices or intervals.

== Text ==
The text section gives the text that is shown to the student. It begins with a line containing <code>TEXT(beginproblem());</code>. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) is shown to the student. These are usually accompanied with a <code>Context()->texStrings</code>, to tell MathObjects (such as <code>$a</code> in the previous example) to display themselves using TeX formatting, and <code>Context()->normalStrings</code> to turn the default behaviour back on.

The text can be formatted with a number of special characters and variables:

* mathematical equations can be typeset with a LaTeX-like formatting macros within <code>$</code> and <code>$</code> delimiters (displayed inline with text) or <code>\[</code> and <code>\]</code> (displayed in their own block).
* line breaks are denoted with <code>$BR</code> and new paragraphs with <code>$PAR</code>.
* additional formatting is done using special variables to typeset text in bold (between <code>$BBOLD</code> and <code>$EBOLD</code>) or italic (<code>$BITALIC</code> and <code>$EITALIC</code>)
* if you need to execute any code in the text section, enclose it with <code>\{</code> and <code>\}</code> delimiters. The resulting value is converted to text and inserted at that point in the section. There are quite a few built-in functions that are used in this manner to, for instance, show images or tables. More fundamentally, this method is used to insert a field for student's answer. In the following example, we use <code>ans_rule(6)</code> to insert a blank text entry field six characters wide:

<pre>
TEXT(beginproblem());
Context()->texStrings;
BEGIN_TEXT
What number is one greater than $ $a $?
$PAR
$ $a + 1 = $ \{ ans_rule(35) \}
END_TEXT
Context()->normalStrings;
</pre>

== Answer and Solution ==
The answer and solution section specifies how the answer(s) to the problem is(are) marked for correctness. Optionally, it can also give a solution that is shown to the student after the problem set is complete.

The student's answer is evaluated with the <code>ANS</code> command, in which we give it an "answer checker" that compares the student's entry with the correct value (here, <code>$a_plus_1->cmp()</code>).

The optional solution is only visible to students after the homework deadline. In it, you are free to explain the correct solution using a combination of text and math formulas just as in the problem text. The only difference is that this section is enclosed in <code>BEGIN_SOLUTION</code> and <code>END_SOLUTION</code> pair, rather than <code>BEGIN_TEXT</code>/<code>END_TEXT</code>. You may use the special <code>$SOLUTION</code> variable to create a heading titled "Solution".

Finally, your document '''must''' end with a <code>ENDDOCUMENT();</code> as the last command in the file.

<pre>
ANS($a_plus_1->cmp());

Context()->texStrings;
BEGIN_SOLUTION
$SOLUTION
Because $ $a + 1 = $a_plus_1 $, the correct answer is $ $a_plus_1 $.

END_SOLUTION
Context()->normalStrings;

ENDDOCUMENT();
</pre>

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2015-01-20T23:19:22Z

DavorCubranic: Expand the paragraph on MathObjects

WebWork problems are stored in PG files. These files are typically structured in the following way:

== Tagging and Description ==
The tagging and description section describes the problem for future users and authors. The purpose of the tagging information is to make the problem easier to find by searching or browsing. Each tag must appear on its own line, starting at the first character, and be in the following format: <code>## Tagname(tag value)</code>. There are three required tags, <tt>DBsubject</tt>, <tt>DBchapter</tt>, and <tt>DBsection</tt>, placing the problem in the [[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html|hierarchy]] that's exposed in the Library Browser. Problems should also a <tt>Level</tt>, denoting its difficulty on a predefined [http://webwork.maa.org/wiki/Problem_Levels scale].

Optional tags include <tt>Keywords</tt>, for easier searching, as well as tags to indicate authorship (<tt>Author</tt> and <tt>Institution</tt>), and to link to a specific textbook (<tt>TitleText1</tt>, <tt>EditionText1</tt>, <tt>AuthorText1</tt>, <tt>Section1</tt>, and <tt>Problem1</tt>).

More information on tagging can be found on the [http://webwork.maa.org/wiki/Tagging_Problems WebWork MAA wiki].

<pre>
## DBsubject('WeBWorK')
## DBchapter('Demos')
## DBsection('Problem')
## KEYWORDS('')
## TitleText1('')
## EditionText1('')
## AuthorText1('')
## Section1('')
## Problem1('')
## Author('Gavin LaRose')
## Institution('UMich')
</pre>

== Initialization ==
The initialization section loads required macros for the problem. It ''must''' begin with the <code>DOCUMENT();</code> command, followed by the <code>loadMacros</code> command that loads additional commands used by the problem. For basic problems, the following is sufficient — template files for specific problem types will tell you if any other macros should be loaded.

<pre>
DOCUMENT();
loadMacros(
"PGstandard.pl",
"MathObjects.pl",
);
</pre>

== Problem Set-up ==
In this section, define variables specific to the problem, for instance various parameters or the correct answer value. These variables are used in subsequent sections either in the text displayed to the student, or to check the answer. You should begin this section with <code>Context</code>, to tell WebWork the type of variables that are used. In this example, we use <code>Context("Numeric")</code> to indicate that the following commands work on scalar numbers.

There are many ways to assign value to variables. The two we show here are:

# by a random draw from a range of values (<code>random</code>, which in this case chooses from a sequence starting at 2, ending at 9, and incrementing by 1, thus choosing integers in the range [2, 9])
# by computing a value (<code>Real</code>) from a math expression, in this case the real number calculated by adding one to the value of <tt>$a</tt>. These are the so-called MathObjects, and they lie at heart of WebWork's functioning. For instance, MathObjects know how to compute or simplify fairly complicated mathematical expressions, how display themselves in a sensible way in the text of the problem, and how to compare themselves to the student's answer . See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_MathObjects introduction to MathObjects] and follow its links to learn additional features as needed.

<pre>
Context("Numeric");

$a = random(2, 9, 1);
$a1 = Real("$a + 1");
</pre>

See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_Contexts introduction to contexts] and a [http://webwork.maa.org/wiki/ContextList list] of other types of contexts, such as matrices or intervals.

== Text ==
The text section gives the text that is shown to the student. It begins with a line containing <code>TEXT(beginproblem());</code>. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) is shown to the student. These are usually accompanied with a <code>Context()->texStrings</code>, to tell MathObjects (such as <code>$a</code> in the previous example) to display themselves using TeX formatting, and <code>Context()->normalStrings</code> to turn the default behaviour back on.

The text can be formatted with a number of special characters and variables:

- mathematical equations can be typeset with a LaTeX-like formatting macros within <code>$</code> and <code>$</code> delimiters (displayed inline with text) or <code>\[</code> and <code>\]</code> (displayed in their own block).

- line breaks are denoted with <code>$BR</code> and new paragraphs with <code>$PAR</code>.

- additional formatting is done using special variables to typeset text in bold (between <code>$BBOLD</code> and <code>$EBOLD</code>) or italic (<code>$BITALIC</code> and <code>$EITALIC</code>)

- if you need to execute any code in the text section, enclose it with <code>\{</code> and <code>\}</code> delimiters. The resulting value is converted to text and inserted at that point in the section. There are quite a few built-in functions that are used in this manner to, for instance, show images or tables. More fundamentally, this method is used to insert a field for student's answer. In the following example, we use <code>ans_rule(6)</code> to insert a blank text entry field six characters wide:

<pre>
TEXT(beginproblem());
Context()->texStrings;
BEGIN_TEXT
What number is one greater than $ $a $?
$PAR
$ $a + 1 = $ \{ ans_rule(35) \}
END_TEXT
Context()->normalStrings;
</pre>

== Answer and Solution ==
The answer and solution section specifies how the answer(s) to the problem is(are) marked for correctness. Optionally, it can also give a solution that is shown to the student after the problem set is complete.

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2015-01-20T23:07:44Z

DavorCubranic: Write the "Text" section

WebWork problems are stored in PG files. These files are typically structured in the following way:

== Tagging and Description ==
The tagging and description section describes the problem for future users and authors. The purpose of the tagging information is to make the problem easier to find by searching or browsing. Each tag must appear on its own line, starting at the first character, and be in the following format: <code>## Tagname(tag value)</code>. There are three required tags, <tt>DBsubject</tt>, <tt>DBchapter</tt>, and <tt>DBsection</tt>, placing the problem in the [[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html|hierarchy]] that's exposed in the Library Browser. Problems should also a <tt>Level</tt>, denoting its difficulty on a predefined [http://webwork.maa.org/wiki/Problem_Levels scale].

Optional tags include <tt>Keywords</tt>, for easier searching, as well as tags to indicate authorship (<tt>Author</tt> and <tt>Institution</tt>), and to link to a specific textbook (<tt>TitleText1</tt>, <tt>EditionText1</tt>, <tt>AuthorText1</tt>, <tt>Section1</tt>, and <tt>Problem1</tt>).

More information on tagging can be found on the [http://webwork.maa.org/wiki/Tagging_Problems WebWork MAA wiki].

<pre>
## DBsubject('WeBWorK')
## DBchapter('Demos')
## DBsection('Problem')
## KEYWORDS('')
## TitleText1('')
## EditionText1('')
## AuthorText1('')
## Section1('')
## Problem1('')
## Author('Gavin LaRose')
## Institution('UMich')
</pre>

== Initialization ==
The initialization section loads required macros for the problem. It ''must''' begin with the <code>DOCUMENT();</code> command, followed by the <code>loadMacros</code> command that loads additional commands used by the problem. For basic problems, the following is sufficient — template files for specific problem types will tell you if any other macros should be loaded.

<pre>
DOCUMENT();
loadMacros(
"PGstandard.pl",
"MathObjects.pl",
);
</pre>

== Problem Set-up ==
In this section, define variables specific to the problem, for instance various parameters or the correct answer value. These variables are used in subsequent sections either in the text displayed to the student, or to check the answer. You should begin this section with <code>Context</code>, to tell WebWork the type of variables that are used. In this example, we use <code>Context("Numeric")</code> to indicate that the following commands work on scalar numbers.

There are many ways to assign value to variables. The two we show here are by a random draw from a range of integers (<code>random</code>)

<pre>
Context("Numeric");

$a = random(2, 9, 1);
$a1 = Real("$a + 1");
</pre>

See MAA WebWork wiki for an [http://webwork.maa.org/wiki/Introduction_to_Contexts introduction to contexts] and a [http://webwork.maa.org/wiki/ContextList list] of other types of contexts, such as matrices or intervals.

== Text ==
The text section gives the text that is shown to the student. It begins with a line containing <code>TEXT(beginproblem());</code>. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) is shown to the student. These are usually accompanied with a <code>Context()->texStrings</code>, to tell MathObjects (such as <code>$a</code> in the previous example) to display themselves using TeX formatting, and <code>Context()->normalStrings</code> to turn the default behaviour back on.

The text can be formatted with a number of special characters and variables:

- mathematical equations can be typeset with a LaTeX-like formatting macros within <code>$</code> and <code>$</code> delimiters (displayed inline with text) or <code>\[</code> and <code>\]</code> (displayed in their own block).

- line breaks are denoted with <code>$BR</code> and new paragraphs with <code>$PAR</code>.

- additional formatting is done using special variables to typeset text in bold (between <code>$BBOLD</code> and <code>$EBOLD</code>) or italic (<code>$BITALIC</code> and <code>$EITALIC</code>)

- if you need to execute any code in the text section, enclose it with <code>\{</code> and <code>\}</code> delimiters. The resulting value is converted to text and inserted at that point in the section. There are quite a few built-in functions that are used in this manner to, for instance, show images or tables. More fundamentally, this method is used to insert a field for student's answer. In the following example, we use <code>ans_rule(6)</code> to insert a blank text entry field six characters wide:

<pre>
TEXT(beginproblem());
Context()->texStrings;
BEGIN_TEXT
What number is one greater than $ $a $?
$PAR
$ $a + 1 = $ \{ ans_rule(35) \}
END_TEXT
Context()->normalStrings;
</pre>

== Answer and Solution ==
The answer and solution section specifies how the answer(s) to the problem is(are) marked for correctness. Optionally, it can also give a solution that is shown to the student after the problem set is complete.

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2015-01-20T19:05:47Z

DavorCubranic: Initial outline of the page

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates/PG Structure

2015-01-20T19:04:31Z

DavorCubranic: Initial outline of the page

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R

2015-01-17T00:29:26Z

DavorCubranic: Add a listing of subpages

[[Documentation:WeBWorK|WeBWorK]] is widely used in math courses
around the world, but its adoption in statistics has been limited. One
reason is that while WebWork implements a broad range of arithmetic
and calculus-type operations, it has little support for statistical
concepts such as probability distributions or statistical models.

The WeBWorKiR (WeBWorK integrating R) project offers a solution in the
form of integration between WeBWorK and the
[http://www.r-project.org statistical computing software R]. The open
source software R is extremely popular in statistical research,
analysis, and education. It provides a huge range of operations for
statistical computation and graphics. The WeBWorKiR project has two
main goals: (i) to allow WeBWorK to communicate with R and (ii) the
creation of a large collection of homework questions for use in
undergraduate instruction in statistics. With the WeBWorKiR project,
instructors can use R code in their WebWorK problems to generate data,
perform analyses, and create figures.

WeBWorKiR has been developed in the Department of Statistics since
June 2012, with the funding from Teaching and Learning Improvement
Fund. It has been used in a number of second- and third-year
Statistics courses at UBC, reaching around 3000 students so far. The
aim is that problems created and tested on students through the
WeBWorKiR project are made available to all educators via WeBWorK's
Open Problem Library.

If you are an instructor, please look at the [[Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/Authoring_guide|authoring]] guide for
information on writing WebWork questions that make use of R. If you
are a WebWork system administrator, you can find setup information in
our [[Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/Installation_guide|installation guide]].

[[Category: WeBWorK]]

== Subpages ==
{{Special:PrefixIndex/Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/}}

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates

2015-01-17T00:18:51Z

DavorCubranic:

Multiple choice:
# One correct answer, no responses anchored.
# One correct answer, one response anchored.
# More than one correct answer (anchoring would be as above, so extra template for anchoring not required).
# Answer selected from pull-down menu.

Short answer:
# Numerical, only one response accepted.
# Numerical, response accepted within specified tolerance.
# Numerical, response accepted from list.
# String response

Sandbox:ARCHIVED: WeBWorK/Problem Authoring Templates

2015-01-17T00:17:24Z

DavorCubranic: Created page with " Multiple choice: (i) One correct answer, no responses anchored. (ii) One correct answer, one response anchored. (iii) More than one correct answer (anchoring would be as abov..."

Multiple choice:
(i) One correct answer, no responses anchored.
(ii) One correct answer, one response anchored.
(iii) More than one correct answer (anchoring would be as above, so extra template for anchoring not required).
(iv) Answer selected from pull-down menu.

Short answer:
(i) Numerical, only one response accepted.
(ii) Numerical, response accepted within specified tolerance.
(iii) Numerical, response accepted from list.
(iv) String response

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Installation guide

2015-01-15T22:29:46Z

DavorCubranic: Add specifying Rserve host location in WebWork config file (required since S-R-IO 0.10)

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Authoring guide

2014-08-28T17:59:31Z

DavorCubranic: Add an example for 'rserve_get_file'

== WeBWorKiR User Guide ==

The audience for this guide are problem authors who want to use R's
facilities in their WeBWorK questions. We assume that you already know
how to create problems with the PG language (which itself is a subset
of Perl) and are familiar with the concepts of macros in PG. We also
assume that your WeBWorKiR environment has been set up as described in
the [[Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/Installation_guide|installation guide]].

=== Background ===

WeBWorKiR is a system that involves two separate servers: WeBWorK and
R. In a normal operation, when a student accesses WeBWorK via a web
browser to work on homework problems, WeBWorK runs the PG code
defining the problem to compute:

a) values used in the question, for example a random vector of five integers

b) the text of the question, typically given in format resembling LaTeX and optionally displaying values computed in (a)

c) values of the correct answer, for example, the mean of the vector calculated in (a)

WeBWorKiR adds to this the ability to run arbitrary computations in R
and make their results available to the rest of the PG code as if they
were constructed using the standard PG functions. (In our running
example, we could construct the random vector in R with `sample`,
and/or calculate its mean with `mean`.) The reason why one might want
to do this is R's rich library of high-quality statistical functions
as well as its graphical abilities. While in theory these could be
both replicated with PG, it would take a huge effort that can be
better spent by simply using the functionality already available in R.

The way this works is that WeBWorK uses a Perl module that can talk to
a server running the [[http://www.rforge.net/Rserve/|Rserve]] software,
which allows remote clients to execute R code on the Rserve's server
and returns the execution's result in response. The Perl module
converts this response from R's native values (e.g., a generic vector,
aka "list") to those understandable to Perl (e.g., an array), making
them available to the rest of the PG code.

== Loading the macros ==

To use R code in a problem, include "RserveClient.pl" in the
"loadMacros" call at the start of the question. For example:

<pre>
loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl" # <--- R integration
);
</pre>

== Basic Rserve macros ==

The Rserve software creates an R session for each remote client. This
means that clients' interactions with R are kept separate from each
other, just as if you started R twice on your local computer. A
session persists as long as the client is connected, so that multiple
calls from the client using the same session see the objects created
in previous calls. (This behaviour mirrors what happens in a local
session, where each R command you execute at the console after
pressing ENTER sees the results of earlier commands.) When a sessions
is *closed*, its contents are wiped off without a trace, just like
quitting the R application run locally.

The RserveClient offers macros to start and finish a session, and
execute R commands in the current session:

<ol style="list-style-type: decimal;">
<li><code>rserve_eval("some R code")</code>: this function sends the R code given
as its string argument to Rserve for execution. It returns *an
array* representation of the R code's result. (This means that the
value of <code>rserve_eval("pi")</code> is an array with a single element
3.14159265358979. If you want to keep this value and use it in the
rest of the problem, assign it to an array variable. For example:
<pre>@pi = rserve_eval("pi");</pre>
'''Note:''' Multiple calls within the same problem share the R session and the object workspace, so you can break up your R code in as many <tt>rserve_eval</tt> statements as you'd like.</li>

<li><code>rserve_start()</code>, <code>rserve_finish()</code>: Start up and close the current connection to the Rserve server. In
normal use, these functions are completely optional because the first
call to <code>rserve_eval</code> will call start the Rserve session if one is not
already open. Similarly, the current session will be automatically closed at the end of the problem.
Other than backward compatibility, the only reason for using these
functions is to start a new clean session within a single problem,
which shouldn't be a common occurrence.</li>
</ol>

=== A note on Perl quoting rules ===

Beware of Perl's quoting rules when writing R code. The text in double
quotes gets interpreted for escape sequences (e.g., <code>"\n"</code> represents a
newline) and variables (e.g., <code>"The value of pi is $pi[0]"</code> will be
interpolated into <code>"The value of pi is 3.14159265358979"</code>, given the
code above). This is a problem if you're trying to extract an element
of a list by name using the <code>"$"</code> operator in R because the text
following it will be interpreted as a variable. For instance, running
<code>rserve_eval("cars$speed")</code> will not return the "speed" column of the
standard "cars" dataset, because "$speed" in the string will be
replaced by the value of the PG variable <code>$speed</code>, which if not yet
defined will be empty string, so that the R code that actually gets
executed is simply "cars". Instead, using single quotes, which prevent
variable and escape sequence interpolation and instead keep the string
exactly as entered: <code>rserve_eval('cars$speed')</code>.

On the other hand, some time you actually might want variable
interpolation to be done, for instance to construct the R code that
uses values of variables constructed with PG functions. For instance:

<pre>
Context("Numeric");

$pi = Real("pi");
@difference = rserve_eval("pi - $pi");
</pre>

will calculate the difference between the value between R and PG's
values of "pi" and put the result in the <tt>@difference</tt> array. Note that
the same R code can be constructed using Perl's string concatenation
operator dot ("."): <tt>rserve_eval('pi - ' . $pi)</tt>. Personally, I
recommend sticking with single quotes to prevent unwanted surprises,
and using the dot operator if needing to include the value of a PG
variable.

== Displaying R graphics ==

R has excellent facilities for creating production-quality statistical
graphics, from simple scatterplots to complex spatial visualizatons
overlaid on geographical maps. These graphics can be produced in a
variety of formats (in R parlance, devices), from the user's monitor
to PDF or JPG files. The RserveClient allows the author to present
these graphics in the question by bracketing the R graphing code with
macros <tt>rserve_start_plot</tt> and <tt>rserve_finish_plot</tt>, and then showing
the produced image in the question with PG's macro <tt>image</tt> (see the
WeBWorK [http://webwork.maa.org/wiki/Image documentation]).

The following code is a complete example

<pre>
DOCUMENT();

loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl",
);

# Print problem number and point value (weight) for the problem
TEXT(beginproblem());

# Setup
Context("Numeric");

$mean = random(-2, 2, .5);

$img = rserve_start_plot('png');
rserve_eval('curve(dnorm(x, mean=' . $mean . '), xlim=c(-4, 4)); 0');
$image_path = rserve_finish_plot($img);

# Text
Context()->texStrings;
BEGIN_TEXT

What is the mean of the normal distribution shown in the figure below:
\{ ans_rule(5) \}

$PAR

\{ image($image_path, width=>300, height=>300) \}:
END_TEXT

Context()->normalStrings;

# Answers
ANS(Real($mean)->cmp);

ENDDOCUMENT();
</pre>

The four key lines are as follow:

<ol style="list-style-type: decimal;">
<li><code>$img = rserve_start_plot('png')</code>: sets up R to plot to a 'PNG'
file and returns a unique plot identifier to be used later.</li>

<li><code>rserve_eval('curve(...)')</code>: runs plotting commands on the R server</li>

<li><code>$image_path = rserve_finish_plot($img)</code>: completes the plotting
to the PNG file and transfers it to a location on the WebWork
server. Returns the path of the file, which is stored in Perl variable <code>$image_path</code>
and later used as the first argument to the <code>image</code> macro.</li>

<li><code>\{ image($image_path, width=>300, height=>300) \}</code>: inserts the
image into the web page.</li>
</ol>

== Transferring files from the R server ==

Sometimes it may be convenient to make a file from R server available to the student via a link in Webwork. (For instance, using R to generate a (potentially randomized) data file that the student can download to work on the problem offline.) The macro <code>rserve_get_file REMOTE_NAME [, LOCAL_NAME]</code> can be used to transfer the file ''REMOTE_NAME'' from the R server to WebWork's temporary
file area, and returns the name of the local file that can then be
used by the <code>htmlLink</code> macro. Specifying ''LOCAL_NAME'' is optional; if it is not specified, the
filename portion of the ''REMOTE_NAME'' is used.

The following code is a complete example

<pre>
DOCUMENT();

loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl",
);

# Print problem number and point value (weight) for the problem
TEXT(beginproblem());

# Setup
Context("Numeric");

my ($intercept, $slope) = rserve_eval('coef(lm(log(dist)~log(speed), data = cars))');

my ($remote_file) = rserve_eval('filename <- tempfile(fileext=".csv"); write.csv(cars, filename); filename');
my $local_file = rserve_get_file($remote_file);

($local_url = $local_file) =~ s|$tempDirectory|$tempURL|;

# Text
Context()->texStrings;
BEGIN_TEXT

What is the slope of the linear regression of log-transformed stopping distance vs. car speed in the dataset linked below:
\{ ans_rule(5) \}

$PAR

\{ htmlLink($local_url, "Download") \} the problem data (CSV file).

END_TEXT

Context()->normalStrings;

# Answers
ANS(Real($slope)->cmp);

ENDDOCUMENT();
</pre>

The four key lines are as follow:

<ol style="list-style-type: decimal;">
<li><code>my ($remote_file) = rserve_eval('filename <- tempfile(fileext=".csv"); write.csv(cars, filename); filename')</code>: stores the desired dataset into a temporary CSV file on the R server and returns its path, which is stored in Perl variable <code>$remote_file</code>.</li>

<li><code>my $local_file = rserve_get_file($remote_file)</code>: transfers the file from the R server to WeBWorK's temporary file area and returns its path, which is stored in Perl variable <code>$local_file</code>.</li>

<li><code>($local_url = $local_file) =~ s|$tempDirectory|$tempURL|</code>: converts the local file path into a URL that can be used as an argument to the <code>htmlLink</code> macro, saving it in Perl variable <code>$local_url</code>.</li>

<li><code>\{ htmlLink($local_url, "Download") \}</code>: inserts the
link to the downloaded file into the web page.</li>
</ol>

[[Category:WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Authoring guide

2014-08-28T17:16:26Z

DavorCubranic: Fix page markup for better lists and code

== WeBWorKiR User Guide ==

The audience for this guide are problem authors who want to use R's
facilities in their WeBWorK questions. We assume that you already know
how to create problems with the PG language (which itself is a subset
of Perl) and are familiar with the concepts of macros in PG. We also
assume that your WeBWorKiR environment has been set up as described in
the [[Documentation:WeBWork/The_WeBWorKiR_Project:_Integrating_WeBWorK_with_R/Installation_guide|installation guide]].

=== Background ===

WeBWorKiR is a system that involves two separate servers: WeBWorK and
R. In a normal operation, when a student accesses WeBWorK via a web
browser to work on homework problems, WeBWorK runs the PG code
defining the problem to compute:

a) values used in the question, for example a random vector of five integers

b) the text of the question, typically given in format resembling LaTeX and optionally displaying values computed in (a)

c) values of the correct answer, for example, the mean of the vector calculated in (a)

WeBWorKiR adds to this the ability to run arbitrary computations in R
and make their results available to the rest of the PG code as if they
were constructed using the standard PG functions. (In our running
example, we could construct the random vector in R with `sample`,
and/or calculate its mean with `mean`.) The reason why one might want
to do this is R's rich library of high-quality statistical functions
as well as its graphical abilities. While in theory these could be
both replicated with PG, it would take a huge effort that can be
better spent by simply using the functionality already available in R.

The way this works is that WeBWorK uses a Perl module that can talk to
a server running the [[http://www.rforge.net/Rserve/|Rserve]] software,
which allows remote clients to execute R code on the Rserve's server
and returns the execution's result in response. The Perl module
converts this response from R's native values (e.g., a generic vector,
aka "list") to those understandable to Perl (e.g., an array), making
them available to the rest of the PG code.

== Loading the macros ==

To use R code in a problem, include "RserveClient.pl" in the
"loadMacros" call at the start of the question. For example:

<pre>
loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl" # <--- R integration
);
</pre>

== Basic Rserve macros ==

The Rserve software creates an R session for each remote client. This
means that clients' interactions with R are kept separate from each
other, just as if you started R twice on your local computer. A
session persists as long as the client is connected, so that multiple
calls from the client using the same session see the objects created
in previous calls. (This behaviour mirrors what happens in a local
session, where each R command you execute at the console after
pressing ENTER sees the results of earlier commands.) When a sessions
is *closed*, its contents are wiped off without a trace, just like
quitting the R application run locally.

The RserveClient offers macros to start and finish a session, and
execute R commands in the current session:

<ol style="list-style-type: decimal;">
<li><code>rserve_eval("some R code")</code>: this function sends the R code given
as its string argument to Rserve for execution. It returns *an
array* representation of the R code's result. (This means that the
value of <code>rserve_eval("pi")</code> is an array with a single element
3.14159265358979. If you want to keep this value and use it in the
rest of the problem, assign it to an array variable. For example:
<pre>@pi = rserve_eval("pi");</pre>
'''Note:''' Multiple calls within the same problem share the R session and the object workspace, so you can break up your R code in as many <tt>rserve_eval</tt> statements as you'd like.</li>

<li><code>rserve_start()</code>, <code>rserve_finish()</code>: Start up and close the current connection to the Rserve server. In
normal use, these functions are completely optional because the first
call to <code>rserve_eval</code> will call start the Rserve session if one is not
already open. Similarly, the current session will be automatically closed at the end of the problem.
Other than backward compatibility, the only reason for using these
functions is to start a new clean session within a single problem,
which shouldn't be a common occurrence.</li>
</ol>

=== A note on Perl quoting rules ===

Beware of Perl's quoting rules when writing R code. The text in double
quotes gets interpreted for escape sequences (e.g., <code>"\n"</code> represents a
newline) and variables (e.g., <code>"The value of pi is $pi[0]"</code> will be
interpolated into <code>"The value of pi is 3.14159265358979"</code>, given the
code above). This is a problem if you're trying to extract an element
of a list by name using the <code>"$"</code> operator in R because the text
following it will be interpreted as a variable. For instance, running
<code>rserve_eval("cars$speed")</code> will not return the "speed" column of the
standard "cars" dataset, because "$speed" in the string will be
replaced by the value of the PG variable <code>$speed</code>, which if not yet
defined will be empty string, so that the R code that actually gets
executed is simply "cars". Instead, using single quotes, which prevent
variable and escape sequence interpolation and instead keep the string
exactly as entered: <code>rserve_eval('cars$speed')</code>.

On the other hand, some time you actually might want variable
interpolation to be done, for instance to construct the R code that
uses values of variables constructed with PG functions. For instance:

<pre>
Context("Numeric");

$pi = Real("pi");
@difference = rserve_eval("pi - $pi");
</pre>

will calculate the difference between the value between R and PG's
values of "pi" and put the result in the <tt>@difference</tt> array. Note that
the same R code can be constructed using Perl's string concatenation
operator dot ("."): <tt>rserve_eval('pi - ' . $pi)</tt>. Personally, I
recommend sticking with single quotes to prevent unwanted surprises,
and using the dot operator if needing to include the value of a PG
variable.

== Displaying R graphics ==

R has excellent facilities for creating production-quality statistical
graphics, from simple scatterplots to complex spatial visualizatons
overlaid on geographical maps. These graphics can be produced in a
variety of formats (in R parlance, devices), from the user's monitor
to PDF or JPG files. The RserveClient allows the author to present
these graphics in the question by bracketing the R graphing code with
macros <tt>rserve_start_plot</tt> and <tt>rserve_finish_plot</tt>, and then showing
the produced image in the question with PG's macro <tt>image</tt> (see the
WeBWorK [http://webwork.maa.org/wiki/Image documentation]).

The following code is a complete example

<pre>
DOCUMENT();

loadMacros(
"PGstandard.pl", # Standard macros for PG language
"MathObjects.pl",
"RserveClient.pl",
);

# Print problem number and point value (weight) for the problem
TEXT(beginproblem());

# Setup
Context("Numeric");

$mean = random(-2, 2, .5);

$img = rserve_start_plot('png');
rserve_eval('curve(dnorm(x, mean=' . $mean . '), xlim=c(-4, 4)); 0');
$image_path = rserve_finish_plot($img);

# Text
Context()->texStrings;
BEGIN_TEXT

What is the mean of the normal distribution shown in the figure below:
\{ ans_rule(5) \}

$PAR

\{ image($image_path, width=>300, height=>300) \}:
END_TEXT

Context()->normalStrings;

# Answers
ANS(Real($mean)->cmp);

ENDDOCUMENT();
</pre>

The four key lines are as follow:

<ol style="list-style-type: decimal;">
<li><code>$img = rserve_start_plot('png')</code>: sets up R to plot to a 'PNG'
file and returns a unique plot identifier to be used later.</li>

<li><code>rserve_eval('curve(...)')</code>: runs plotting commands on the R server</li>

<li><code>$image_path = rserve_finish_plot($img)</code>: completes the plotting
to the PNG file and transfers it to a location on the WebWork
server. Returns the path of the file, which is stored in Perl variable <code>$image_path</code>
and later used as the first argument to the <code>image</code> macro.</li>

<li><code>\{ image($image_path, width=>300, height=>300) \}</code>: inserts the
image into the web page.</li>
</ol>

== Transferring files from the R server ==

Sometimes it may be convenient to make a file from R server available to the student via a link in Webwork. (For instance, using R to generate a (potentially randomized) data file that the student can download to work on the problem offline.) The macro <code>rserve_get_file REMOTE_NAME [, LOCAL_NAME]</code> can be used to transfer the file ''REMOTE_NAME'' from the R server to WebWork's temporary
file area, and returns the name of the local file that can then be
used by the <code>htmlLink</code> macro. Specifying ''LOCAL_NAME'' is optional; if it is not specified, the
filename portion of the ''REMOTE_NAME'' is used.

[[Category:WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R/Installation guide

2014-08-28T17:07:55Z

DavorCubranic: Add category WeBWorK

== WeBWorKiR Installation Guide ==

The audience for this guide are system administrators who want to set
up R integration in WeBWorK. We assume that you already have, or know
how to set up, a basic WeBWorK server. If not, please see the
[http://webwork.maa.org/wiki/Release_notes_for_WeBWorK_2.8 release notes] on the WeBWorK wiki and the [http://webwork.maa.org/wiki/Installation_Manual_for_2.8_on_Ubuntu_12.04 guide] to installing WeBWorK on an Ubuntu server. You may also find
Jason Aubrey's [https://github.com/aubreyja/ww_install/ ww_install] installation script useful.

== Installation ==

After you have a working WeBWorK server, there are three distinct steps that need to happen:

# set up the R server
# install the Perl module for the Perl-R bridge
# configure WeBWorK to use this module in PG

=== Set up the R server ===

Your R server (which can be on the same server as WeBWorK, but in a real-world scenario will more likely run on its own hardware/VM), is quite easy to set up:

# install R following OS-specific instructions on the project [http://www.r-project.org homepage].
# install the [http://www.rforge.net/Rserve/ Rserve] server, which allows remote clients to execute R code on the Rserve's server and returns the execution's result in response. The easiest way is to run (as an administrative user) <code>Rscript -e 'install.packages("Rserve", repo="http://cran.rstudio.com")'</code>. Note that this package includes C source that needs to be compiled, so you have to have the basic developer tools present on the server.
# run the Rserve service as appropriate to your system. The command you need to run is "R CMD Rserve". This will start the Rserve daemon which will listen on port 6311. The daemon only accepts connections from the localhost; if you run WebWork and Rserve on separate servers, read the final section of this page for additional configuration steps for your system.

=== Install the Perl-R bridge ===

Perl module [http://search.cpan.org/perldoc?Statistics::R::IO Statistics::R::IO] implements Rserve's communication protocol in Perl and provides translation from R data structures to Perl's. It is available on CPAN and can be installed in the standard manner for Perl modules, e.g., by running (as an admin user) <code>cpan Statistics::R::IO</code>.

=== Configure Webwork to use the Perl-R bridge in PG ===

Once the Perl module RserveClient is installed, you can make its functionality available in webwork problems by installing the RserveClient.pl macro and adding the module to the list of modules preloaded by WeBWorK. We use use "${WW_PREFIX}" to indicate the directory where WeBWorK is installed. (This directory will, for instance, contain subdirectories "webwork2" and "pg"; a typical choice is "/opt/webwork", but a different one may be used on your system.)

<ol style="list-style-type: decimal;">
<li>install RserveClient.pl macro into "$WW_PREFIX/pg/macros":
<pre>
wget -q -O ${WW_PREFIX}/pg/macros/RserveClient.pl \
https://raw.githubusercontent.com/cubranic/Statistics-R-IO/release/extras/WebWork/RserveClient.pl
</pre>
perhaps a better solution, but depending on having the Perl module File::ShareDir, ensures that the RserveClient.pl macro matches the version of Statistics::R::IO that you have installed:
<pre>
cp "`perl -MFile::ShareDir -e 'print File::ShareDir::dist_file(\"Statistics-R-IO\", \"WebWork/RserveClient.pl\")'`" \
${WW_PREFIX}/pg/macros/RserveClient.pl
</pre>
</li>
<li>add the RserveClient module(s) to the list of modules preloaded by
WeBWorK, so that it is available to the RserveClient.pl macro. You can
do this by modifying "${WW_PREFIX}/webwork2/conf/defaults.conf",
but since it's a local configuration, you should put it in
localOverrides.conf:
<pre>
cat >> ${WW_PREFIX}/webwork2/conf/localOverrides.conf <<'EOF'
push @{$pg{modules}},
[qw( Statistics::R::IO::Rserve )],
[qw( Statistics::R::IO::ParserState )],
[qw( Statistics::R::REXP::Character )],
[qw( Statistics::R::REXP::Double )],
[qw( Statistics::R::REXP::Environment )],
[qw( Statistics::R::REXP::GlobalEnvironment )],
[qw( Statistics::R::REXP::Integer )],
[qw( Statistics::R::REXP::Language )],
[qw( Statistics::R::REXP::List )],
[qw( Statistics::R::REXP::Logical )],
[qw( Statistics::R::REXP::Null )],
[qw( Statistics::R::REXP::Raw )],
[qw( Statistics::R::REXP::Symbol )],
[qw( Statistics::R::REXP::Unknown )],
[qw( Statistics::R::REXP::Vector )],
[qw( Statistics::R::REXP )],
[qw( IO::File )],
[qw( IO::Handle )],
[qw( Moose )],
[qw( Class::MOP )];
1;
EOF
</pre>
</li>
</ol>

=== Additional configuration when WeBWorK and R are on separate hosts ===

If you run WeBWorK and R on separate hosts, you can either set up a tunnel to forward port 6311 from WeBWorK to R's host, or do the following:

<ol style="list-style-type: decimal;">
<li>set up Rserve to listen on all network interfaces, not just localhost by adding a line "remote enable" to file "/etc/Rserv.conf":
<pre>cat <'EOF' >> /etc/Rserv.conf
remote enable
EOF
</pre>
</li>
<li>modify RserveClient.pl with the correct Rserve's hostname in line <code>$Rserve_server = 'localhost';</code> (line 98 in the current version).</li></ol>

Note that in this case you will also want to set up the Rserve host's firewall to only allow connections from the WeBWorK host(s), or otherwise it will happily execute arbitrary code from any Rserve client anywhere on the internet!

[[Category: WeBWorK]]

Sandbox:ARCHIVED: WeBWorK/The WeBWorKiR Project: Integrating WeBWorK with R

2014-08-28T17:07:20Z

DavorCubranic: Add category WeBWorK