Graphing functions                                            [STB-16: ssi5.1]
------------------

	^fcnplot^ fcnmask ^from^ exp_0 ^to^ exp_1 [^obs^ exp_o] 
		[^, replace sl^ow graph_options]


where exp_0, exp_1, and exp_o are expressions (but are tpically specified as
numbers) and where fcnmask is either:


	(1)    an expression containing ^X^

	(2)    progname [args] ^X^ [args] ^returns^ {^exp^|^macro^} name


If ^obs^ is not specified, ^obs 101^ is assumed if fcnmask is specified using the
first syntax and slow is not specified; otherwise, ^obs 21^ is assumed.  ^obs^
may be specified as any integer between 2 and 350.



Description
-----------

^fcnplot^ graphs the specified function -- which may be specified by a user-
written program and so be quite complicated -- and optionally leaves behind
the the data set of values x and f(x) just graphed.








Options
-------

^replace^ specifies hat the data just graphed, x and f(x), be left in memory at
    the conclusion of the command.  If ^replace^ is not specified, the original
    data in memory, if any, remains unchanged.  If ^replace^ is specified, the
    original data is discarded and a data set of the variables ^x^ and ^y^ is left
    in its place.


Options, continued
------------------

^slow^ is an option only when fcnmask is specified using the first syntax -- an
    expression containing ^X^.  If the second syntax is used, ^slow^ is the default
    and therefore need not be specified.  Say the first syntax is used and ^slow^
    is not specified.  Then ^fcnplot^ preserves the original data (if necessary,
    see ^replace^ above), discards the data, and generates x and f(x) with two
    ^generate^ statements.  The data is graphed and finally the original data is
    restored if ^replace^ was not specified.

    In ^slow^ mode, the data is preserved (if necessary) but it is then left in
    place during the calculation of f(x).  The function or user-written program
    is asked to calculate function values on at a time.  The function or user-
    written program can make use of the existing data in memory or even change
    it if it so desires.  Once all the function values have been calculated,
    the data is discarded, the values of x and f(x) loaded, the graph drawn,
    and then, if ^replace^ was not specified, the original data restored.

graph_options refers to any of the optoins of the ^graph, twoway^ command.




Example 1
---------


Graph chiprob(2,x) over then 0 <= x <= 10:

	. ^fcnplot chiprob(2,X) from 0 to 10^

Any data you have in memory remains unchanged.  If you typed

	. ^fcnplot chiprob(2,X) from 0 to 10, replace^

any data you have in memory would be discarded and left behind would be a data
set of the points plotted.  You could then redraw the graph by typing "^graph^
^y x, c(l) s(i)^" or you might make a dressier version by typing "^graph y x,^
^c(l) s(i) ylab xlab border^".  You could have made the dressier version at the
outset, with or without the replace option:

	. ^fcnplot chiprob(2,X) from 0 to 10, s(i) ylab xlab border^

You do not need to specify the ^c(l)^ option because ^fcnplot^ assumes it, but you
could unnecessarily specify it if you wished.


Example 2
---------

Graph the function y = exp(-x/6)sin(x) over the range 0 to 4*pi:

	. ^program define myfcn^
	.        ^global S_1 = exp(-`1')/6)*sin(`1')^
	. ^end^

	. ^fcnplot myfcn X returns macro S_1 from 0 to 4*_pi^

The graph will be drawn using 21 points.  If we wanted it drawn using a 101
points, we would type: 

	. ^fcnplot myfcn X returns macro S_1 from 0 to 4*_pi obs 101^


Note that our program stored the result of its calculation in a macro called
S_1.  If ^myfcn^ read "^scalar answer - exp(-`1')/*sin(`1')^", we would type:

	. ^fcnplot myfcn X returns exp answer from 0 to 4*_pi^



Also see
--------

    STB:  ssi5.1 (STB-16)
On-line:  ^help^ for ^bisect^