Annotation of loncom/html/adm/help/tex/Problem_LON-CAPA_Functions.tex, revision 1.36
1.1 bowersj2 1: \label{Problem_LON-CAPA_Functions}
2:
3: \begin{longtable}{|p{8.5cm}|p{8.5cm}|}
4: \hline
5: \textbf{LON-CAPA Function }
6: &\textbf{Description }
7: \endhead
8: \hline
9:
10: \&sin(\$x), \&cos(\$x), \&tan(\$x) & Trigonometric functions where x is in radians. \$x can be a pure number, i.e., you can call \&sin(3.1415) \\
11: \hline
12:
13: \&asin(\$x), \&acos(\$x), \&atan(\$x), \&atan2(\$y,\$x) & Inverse trigonometric functions. Return value is in radians. For asin and acos the value of x must be between -1 and 1. The atan2 returns a value between -pi and pi the sign of which is determined by y. \$x and \$y can be pure numbers \\
14: \hline
15:
16: \&log(\$x), \&log10(\$x) & Natural and base-10 logarithm. \$x can be a pure number \\
17: \hline
18:
19: \&exp(\$x), \&pow(\$x,\$y), \&sqrt(\$x) & Exponential, power and square root, i.e.,ex, xy and /x. \$x and \$y can be pure numbers \\
20: \hline
21:
22: \&abs(\$x), \&sgn(\$x) & Abs takes the absolute value of x while sgn(x) returns 1, 0 or -1 depending on the value of x. For x$>$0, sgn(x) = 1, for x=0, sgn(x) = 0 and for x$<$0, sgn(x) = -1. \$x can be a pure number \\
23: \hline
24:
1.6 www 25: \&erf(\$x), \&erfc(\$x) & Error function.
26: erf = 2/sqrt(pi) integral (0,x) et-sq and \emph{ erfx(x)}
27: = 1.0 - \emph{erf(x)}. \$x can be a pure number \\
1.1 bowersj2 28: \hline
29:
30: \&ceil(\$x), \&floor(\$x) & Ceil function returns an integer rounded up whereas floor function returns and integer rounded down. If x is an integer than it returns the value of the integer. \$x can be a pure number \\
31: \hline
32:
33: \&min(...), \&max(...) & Returns the minimum/ maximum value of a list of arguments if the arguments are numbers. If the arguments are strings then it returns a string sorted according to the ASCII codes \\
34: \hline
35:
36: \&factorial(\$n) & Argument (n) must be an integer else it will round down. The largest value for n is 170. \$n can be a pure number \\
37: \hline
38:
39: \$N\%\$M & N and M are integers and returns the remainder (in integer) of N/M. \$N and \$M can be pure numbers \\
40: \hline
41:
42: \&sinh(\$x), \&cosh(\$x), \&tanh(\$x) & Hyperbolic functions. \$x can be a pure number \\
43: \hline
44:
45: \&asinh(\$x), \&acosh(\$x), \&atanh(\$x) & Inverse hyperbolic functions. \$x can be a pure number \\
46: \hline
47:
1.5 albertel 48: \&format(\$x,'nn') & Display or format \$x as nn where nn is nF or nE or nS and n is an integer. \\
1.1 bowersj2 49: \hline
1.33 raeburn 50:
1.36 ! raeburn 51: \$expr=\&math\_calculus\_expression() & Creates Math::Calculus::Expression object. Methods are: \$expr->addVariable('x'), \$expr->setExpression('f(x)'), \$expr->simplify, \$expr->getExpression -- see Math::Calculus::Expression documentation at cpan.org for details.\\
1.33 raeburn 52: \hline
1.35 raeburn 53:
1.36 ! raeburn 54: (\$a,\$u)=\&conv\_eng\_format(\$x,\$b) & Converts numerical value \$x and base unit \$b to answer \$a and corresponding unit \$u in engineering format, i.e.,
1.35 raeburn 55: the answer is scaled by powers of ten, and an appropriate prefix from: m u n p f a z y k M G T P E Z Y precedes the base unit. Called in a script block to generate variables to assign to answer and unit attributes of numericalresponse tag. \\
56: \hline
1.1 bowersj2 57:
1.7 albertel 58: \&prettyprint(\$x,'nn','optional target') & Note that that tag $<$num$>$ can be used to do the same thing. Display or format \$x as nn where nn is nF or nE or nS and n is an integer. Also supports the first character being a \$, it then will format the result with a a call to \&dollarformat() described below. If the first character is a , it will format it with commas grouping the thousands. In S mode it will fromat the number to the specified number of significant figures and display it in F mode. In E mode it will attempt to generate a pretty x10\^{}3 rather than a E3 following the number, the 'optional target' argument is optional but can be used to force \&prettyprint to generate either 'tex' output, or 'web' output, most people do not need to specify this argument and can leave it blank.\\
1.1 bowersj2 59: \hline
60:
1.6 www 61: \&dollarformat(\$x,'optional target') & Reformats \$x to have a \$ (or $\backslash$\$ if in tex mode) and to have , grouping thousands. The 'optional target' argument is optional but can be used to force \&prettyprint to generate either 'tex' output, or 'web' output, most people do not need to specify this argument and can leave it blank.\\
1.1 bowersj2 62: \hline
1.11 albertel 63:
64: \parbox{6.49cm}{
65: Option 1 - \$best = \&languages() \\
66: Option 2 - @all = \&languages() \\
67: Option 3 - \$best = \&languages($\backslash$@desired\_languages) \\
68: Option 4 - @all = \&languages($\backslash$@desired\_languages) \\
1.12 bisitz 69: }& Returns the best language to use, in the first two options returns the languages codes in the preference order of the user. In the second two examples returns the best matches from a list of desired language possibilities. \\
1.11 albertel 70: \hline
71:
1.1 bowersj2 72: \&roundto(\$x,\$n) & Rounds a real number to n decimal points. \$x and \$n can be pure numbers \\
73: \hline
74:
1.24 bisitz 75: \&cas(\$s,\$e,\$l)&Evaluates the expression \$e inside the symbolic algebra system \$s. Currently, the Maxima symbolic math system ('maxima') and the R statistical computing system ('R') are implemented.
76: \$l is an optional comma-separated list of libraries. Example: \&cas('maxima','diff(sin(x)/cos(x),x,2)')\\
1.9 albertel 77: \hline
78:
1.15 www 79: \&implicit\_multiplication(\$f)&Adds mathematical multiplication operators to the formula expression \$f where only implicit multiplication is used. Example: \&implicit\_multiplication('2(b+3c)') returns 2*(b+3*c) \\
1.12 bisitz 80: \hline
81:
1.1 bowersj2 82: \&web(``a'',''b'',''c'') or \&web(\$a,\$b,\$c) & Returns either a, b or c depending on the output medium. a is for plain ASCII, b for tex output and c for html output \\
83: \hline
84:
85: \&html(``a'') or \&html(\$a) & Output only if the output mode chosen is in html format \\
86: \hline
87:
88: \&j0(\$x), \&j1(\$x), \&jn(\$m,\$x), \&jv(\$y,\$x) & Bessel functions of the first kind with orders 0, 1 and m respectively. For jn(m,x), m must be an integer whereas for jv(y,x), y is real. \$x can be a pure number. \$m must be an integer and can be a pure integer number. \$y can be a pure real number \\
89: \hline
90:
91: \&y0(\$x), \&y1(\$x), \&yn(\$m,\$x), \&yv(\$y,\$x) & Bessel functions of the second kind with orders 0, 1 and m respectively. For yn(m,x), m must be an integer whereas for yv(y,x), y is real. \$x can be a pure number. \$m must be an integer and can be a pure integer number. \$y can be a pure real number \\
92: \hline
93:
1.24 bisitz 94: \&random(\$l,\$u,\$d) & Returns a uniformly distributed random number between the lower bound, l and upper bound, u in steps of d. d is optional. If omitted, a step of 1 is used. \$l, \$u and \$d can be pure numbers. \\
1.1 bowersj2 95: \hline
96:
97: \&choose(\$i,...) & Choose the ith item from the argument list. i must be an integer greater than 0 and the value of i should not exceed the number of items. \$i can be a pure integer \\
98: \hline
99:
100: \parbox{6.49cm}{
1.2 bowersj2 101: Option 1 - \&map(\$seed,[$\backslash$\$w,$\backslash$\$x,$\backslash$\$y,$\backslash$\$z],[\$a,\$b,\$c,\$d]) or \\
102: Option 2 - \&map(\$seed,$\backslash$@mappedArray,[\$a,\$b,\$c,\$d]) \\
103: Option 3 - @mappedArray = \&map(\$seed,[\$a,\$b,\$c,\$d]) \\
104: Option 4 - (\$w,\$x,\$y,\$z) = \&map(\$seed,$\backslash$@a) \\
1.4 albertel 105: Option 5 - @Z = \&map(\$seed,$\backslash$@a) \\
1.2 bowersj2 106: where \$a='A'\\
107: \$b='B'\\
108: \$c='B'\\
109: \$d='B'\\
1.13 www 110: \$w, \$x, \$y, and \$z are variables } & Assigns to the variables \$w, \$x, \$y and \$z the values of the \$a, \$b, \$c and \$c (A, B, C and D). The precise value for \$w .. depends on the seed. (Option 1 of calling map). In option 2, the values of \$a, \$b .. are mapped into the array, @mappedArray. The two options illustrate the different grouping. Options 3 and 4 give a consistent way (with other functions) of mapping the items. For each option, the group can be passed as an array, for example, [\$a,\$b,\$c,\$d] =$>$ $\backslash$@a. And Option 5 is the same as option 4, where the array of results is saved into a single array rather than an array of scalar variables.\\
1.1 bowersj2 111: \hline
112:
1.2 bowersj2 113: \parbox{6.49cm}{Option 1 - \&rmap(\$seed,[$\backslash$\$w,$\backslash$\$x,$\backslash$\$y,$\backslash$\$z],[\$a,\$b,\$c,\$d]) or \\
114: Option 2 - \&rmap(\$seed,$\backslash$@rmappedArray,[\$a,\$b,\$c,\$d]) \\
115: Option 3 - @rmapped\_array = \&rmap(\$seed,[\$a,\$b,\$c,\$d]) \\
116: Option 4 - (\$w,\$x,\$y,\$z) = \&rmap(\$seed,$\backslash$@a) \\
1.4 albertel 117: Option 5 - @Z = \&map(\$seed,$\backslash$@a) \\
1.2 bowersj2 118: where \$a='A'\\
119: \$b='B'\\
120: \$c='B'\\
121: \$d='B'\\
1.1 bowersj2 122: \$w, \$x, \$y, and \$z are variables } & The rmap functions does the reverse action of map if the same seed is used in calling map and rmap. \\
123: \hline
124:
1.7 albertel 125: \$a=\&xmlparse(\$string) & You probably should use the tag $<$parse$>$ instead of this function. Runs the internal parser over the argument parsing for display. \textbf{Warning}
1.1 bowersj2 126: This will result in different strings in different targets. Don't use the results of this function as an answer. \\
127: \hline
128:
129: \&tex(\$a,\$b), \&tex(``a'',''b'') & Returns a if the output mode is in tex otherwise returns b \\
130: \hline
131:
132: \&var\_in\_tex(\$a) & Equivalent to tex(``a'',''``) \\
133: \hline
134:
135: \&to\_string(\$x), \&to\_string(\$x,\$y) & If x is an integer, returns a string. If x is real than the output is a string with format given by y. For example, if x = 12.3456, \&to\_string(x,''.3F'') = 12.345 and \&to\_string(x,''.3E'') = 1.234E+01. \\
136: \hline
137:
1.20 www 138: \&class(), \&sec(), \&classid() & Returns null string, class descriptive name, section number, class id, set number and null string. \\
1.1 bowersj2 139: \hline
140:
1.20 www 141: \&name(), \&student\_number(), \&firstname(), \&middlename(), \&lastname() & Return the full name in the following format: lastname, firstname initial. Student\_number returns the student 9-alphanumeric string. The functions firstname, middlename, and lastname return just that part of the name. If undefined, the functions return null. \\
1.1 bowersj2 142: \hline
1.34 raeburn 143: \&check\_status(\$partid) &Returns a number identifying the current status of a part. True values mean that a part is ``done'': either unanswerable because of tries exhaustion, or fully correct, or only partially correct (and retries not permitted). A false value means that a part can still be attempted. If \$part is unspecified, it will check either the current $<$part$>$'s status or if outside of a $<$part$>$, check the status of previous $<$part$>$. The full set of return codes are: 'undef' means it is unattempted, 0 means it is attempted but still has tries, and is either wrong (or partially correct, retries allowed), 1 means it is fully correct or partially correct (no retries), 2 means they have exceeded maximum number of tries, 3 means it is after the answer date.\\
1.5 albertel 144: \hline
1.17 www 145: \&open\_date(\$partid), \&due\_date(\$partid), \&answer\_date(\$partid) & Problem open date, due date and answer date in local human-readable format. Part 0 is chosen if \$partid is omitted.\\
1.1 bowersj2 146: \hline
1.17 www 147: \&open\_date\_epoch(\$partid), \&due\_date\_epoch((\$partid), \&answer\_date\_epoch((\$partid) & Problem open date, due date and answer date in seconds after the
148: epoch (UTC), which can be used in calculations.\\
149: \hline
150:
1.30 raeburn 151: \&submission(\$partid,\$responseid,\$version,
1.31 raeburn 152: \$encode,\$cleanupnum,\$mapalias) & Returns what the student submitted for response \$responseid in part \$partid. You can get these IDs from the XML-code of the problem. Use 0 as \$partid for problems without parts. \$version is optional and returns the \$version-th submission of the student that was graded. If \$version is 0 or omitted, the latest submission is returned.
1.30 raeburn 153: \$encode is also optional and allows the author to explicitly encode the returned string. It's up to the author to take care of properly escaping all characters which might be interpreted by the browser.
154: \$cleanupnum is also optional, and supports clean-up of the retrieved submission.
155: It is a reference to a hash, with one or more of the following:
156: exponent =$>$ 1,
157: comma =$>$ 1,
158: letterforzero =$>$ 1,
159: spaces =$>$ 1,
160: format =$>$ 'ns'
161: (where n is an integer, i.e., number of significant digits). For example, to convert a student submission of
1.31 raeburn 162: 11,300 to 11300 include \{ comma =$>$ 1, \} as the fifth arg.
163: \$mapalias is also optional, and supports retrieval of the submission for a response item in a different problem in the course, for which a (unique) mapalias has been set.
164: The default (mapalias not defined) is to retrieve the submission for the specified part and response IDs in the current problem.\\
1.17 www 165: \hline
166:
1.21 www 167: \¶meter\_setting(\$name,\$partid) & Returns the parameter setting \$name. Partid is optional.\\
168: \hline
169:
170: \&stored\_data(\$name,\$partid) & Returns the stored data \$name. Partid is optional.\\
171: \hline
1.23 raeburn 172: \&wrong\_bubbles(\$correct,\$lower,\$upper,\$step,@given) & Returns an array that can be used for wrong answers in numerical responses. The first argument is the correct answer, the next arguments are the lower and upper boundaries for the bubbles, as well as the step size. The next argument is an
1.22 www 173: optional array of wrong answers that should be included.\\
174: \hline
1.21 www 175:
1.17 www 176: \¤tpart() &
177: Returns the ID of the current part.\\
178: \hline
179:
1.32 damieng 180: \&input\_id(part\_id, response\_id, textline\_id) &
181: Returns the HTML id of the input field. This is useful in Javascript scripts to get a safe reference to a response textline field with \texttt{document.getElementById()}.\\
182: \hline
183:
1.1 bowersj2 184:
185: Not implemented & Get and set the random seed. \\
186: \hline
187:
188: \&sub\_string(\$a,\$b,\$c)
1.6 www 189: perl substr function. However, note the differences & Retrieve a portion of string a starting from b and length c. For example, \$a = ``Welcome to LON-CAPA''; \$result=\&sub\_string(\$a,4,4); then \$result is ``come'' \\
1.1 bowersj2 190: \hline
191:
192: @arrayname
193: Array is intrinsic in perl. To access a specific element use \$arrayname[\$n] where \$n is the \$n+1 element since the array count starts from 0 & ``xx'' can be a variable or a calculation. \\
194: \hline
195:
196: @B=\&array\_moments(@A) & Evaluates the moments of an array A and place the result in array B[i] where i = 0 to 4. The contents of B are as follows: B[0] = number of elements, B[1] = mean, B[2] = variance, B[3] = skewness and B[4] = kurtosis. \\
197: \hline
198:
1.6 www 199: \&min(@Name), \&max(@Name) & In LON-CAPA to find the maximum value of an array, use \&max(@arrayname) and to find the minimum value of an array, use \&min(@arrayname) \\
1.1 bowersj2 200: \hline
201:
202: undef @name & To destroy the contents of an array, use \\
203: \hline
204:
205: @return\_array=\&random\_normal (\$item\_cnt,\$seed,\$av,\$std\_dev) & Generate \$item\_cnt deviates of normal distribution of average \$av and standard deviation \$std\_dev. The distribution is generated from seed \$seed \\
206: \hline
207:
208: @return\_array=\&random\_beta (\$item\_cnt,\$seed,\$aa,\$bb)
209: NOTE: Both \$aa and \$bb MUST be greater than 1.0E-37. & Generate \$item\_cnt deviates of beta distribution. The density of beta is: X\^{}(\$aa-1) *(1-X)\^{}(\$bb-1) /B(\$aa,\$bb) for 0$<$X$<$1. \\
210: \hline
211:
212: @return\_array=\&random\_gamma (\$item\_cnt,\$seed,\$a,\$r)
213: NOTE: Both \$a and \$r MUST be positive. & Generate \$item\_cnt deviates of gamma distribution. The density of gamma is: (\$a**\$r)/gamma(\$r) * X**(\$r-1) * exp(-\$a*X). \\
214: \hline
215:
216: @return\_array=\&random\_exponential (\$item\_cnt,\$seed,\$av)
217: NOTE: \$av MUST be non-negative. & Generate \$item\_cnt deviates of exponential distribution. \\
218: \hline
219:
220: @return\_array=\&random\_poisson (\$item\_cnt,\$seed,\$mu)
221: NOTE: \$mu MUST be non-negative. & Generate \$item\_cnt deviates of poisson distribution. \\
222: \hline
223:
224: @return\_array=\&random\_chi (\$item\_cnt,\$seed,\$df)
225: NOTE: \$df MUST be positive. & Generate \$item\_cnt deviates of chi\_square distribution with \$df degrees of freedom. \\
226: \hline
227:
228: @return\_array=\&random\_noncentral\_chi (\$item\_cnt,\$seed,\$df,\$nonc)
229: NOTE: \$df MUST be at least 1 and \$nonc MUST be non-negative. & Generate \$item\_cnt deviates of noncentral\_chi\_square distribution with \$df degrees of freedom and noncentrality parameter \$nonc. \\
230: \hline
231:
232: @return\_array=\&random\_f (\$item\_cnt,\$seed,\$dfn,\$dfd)
233: NOTE: Both \$dfn and \$dfd MUST be positive. & Generate \$item\_cnt deviates of F (variance ratio) distribution with degrees of freedom \$dfn (numerator) and \$dfd (denominator). \\
234: \hline
235:
236: @return\_array=\&random\_noncentral\_f (\$item\_cnt,\$seed,\$dfn,\$dfd,\$nonc)
237: NOTE: \$dfn must be at least 1, \$dfd MUST be positive, and \$nonc must be non-negative. & Generate \$item\_cnt deviates of noncentral F (variance ratio) distribution with degrees of freedom \$dfn (numerator) and \$dfd (denominator). \$nonc is the noncentrality parameter. \\
238: \hline
239:
240: @return\_array=\&random\_multivariate\_normal (\$item\_cnt,\$seed,$\backslash$@mean,$\backslash$@covar)
241: NOTE: @mean should be of length p array of real numbers. @covar should be a length p array of references to length p arrays of real numbers (i.e. a p by p matrix. & Generate \$item\_cnt deviates of multivariate\_normal distribution with mean vector @mean and variance-covariance matrix. \\
242: \hline
243:
244: @return\_array=\&random\_multinomial (\$item\_cnt,\$seed,@p)
245: NOTE: \$item\_cnt is rounded with int() and the result must be non-negative. The number of elements in @p must be at least 2. & Returns single observation from multinomial distribution with \$item\_cnt events classified into as many categories as the length of @p. The probability of an event being classified into category i is given by ith element of @p. The observation is an array with length equal to @p, so when called in a scalar context it returns the length of @p. The sum of the elements of the obervation is equal to \$item\_cnt. \\
246: \hline
247:
248: @return\_array=\&random\_permutation (\$seed,@array) & Returns @array randomly permuted. \\
249: \hline
250:
251: @return\_array=\&random\_uniform (\$item\_cnt,\$seed,\$low,\$high)
252: NOTE: \$low must be less than or equal to \$high. & Generate \$item\_cnt deviates from a uniform distribution. \\
253: \hline
254:
255: @return\_array=\&random\_uniform\_integer (\$item\_cnt,\$seed,\$low,\$high)
256: NOTE: \$low and \$high are both passed through int(). \$low must be less than or equal to \$high. & Generate \$item\_cnt deviates from a uniform distribution in integers. \\
257: \hline
258:
259: @return\_array=\&random\_binomial (\$item\_cnt,\$seed,\$nt,\$p)
260: NOTE: \$nt is rounded using int() and the result must be non-negative. \$p must be between 0 and 1 inclusive. & Generate \$item\_cnt deviates from the binomial distribution with \$nt trials and the probabilty of an event in each trial is \$p. \\
261: \hline
262:
263: @return\_array=\&random\_negative\_binomial (\$item\_cnt,\$seed,\$ne,\$p)
264: NOTE: \$ne is rounded using int() and the result must be positive. \$p must be between 0 and 1 exclusive. & Generate an array of \$item\_cnt outcomes generated from negative binomial distribution with \$ne events and the probabilty of an event in each trial is \$p. \\
265: \hline
266: \end{longtable}
1.25 lira 267:
1.26 raeburn 268: The \&EXT() \index{\&EXT}external function is extremely powerful, and is used to access parameters
269: and submission values. It can be
270: used within scripts and also within cell formulas in the grading spreadsheet.
1.25 lira 271: Some examples can be found by browsing in the repository to /res/msu/albertel/test/ext\_examples.html.
1.26 raeburn 272: The \&EXT() function can be used to obtain values for the same parameters as are retrived by some of the other (newer) helper functions
1.25 lira 273: summarized in the table above, such as \&firstname() which is equivalent to \&EXT(`environment.firstname'),
1.26 raeburn 274: and \¶meter\_setting(\$name,\$partid) is equivalent to \&EXT(`resource.'.\$partid.`.'.\$name).
1.27 lira 275: In such cases the newer (specialized) functions are preferred to \&EXT() on the basis of ease of use.
1.25 lira 276:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to Problem_LON-CAPA_Functions.tex CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [LON-CAPA] / loncom / html / adm / help / tex