 |
cmd_newplot |
Function (ROM Call 0x366) |
Executes TI-Basic 'NewPlot' command.
cmd_newplot creates a new statistical plot definition (see TI-Basic manual
for more info).The PlotData parameter must point to a structure on the
expression stack which describes where the actual data is stored (more
precisely, it must point to the last item of it). It is possible to create
five types of statistical plots: scatter plot, X-Y line plot, box plot,
histogram and modified box plot. There is an item called type_id on
the expression stack, which determines the type of the plot. It must be an
integer item, with one of the following values:
1 | Scatter plot |
2 | X-Y line plot |
3 | Box plot |
4 | Histogram |
5 | Modified box plot |
The actual expected layout of the structure on the expression stack depends
on the type of the statistical plot. For scatter and X-Y line plots, this
structure may have one of the following four layouts:
plot_id is an integer item (which must belong to the range from 1 to
9) which represents the identification number of the plot (this number is
used in cmd_plotson and
cmd_plotsoff).
x_list_name is the VAT symbol name (see
SYMSTR and
Tags for more info) of a TI-Basic list
variable which contains the x values. y_list_name is the VAT symbol
name of a TI-Basic list variable which contains the y values.
categories_name (if present) is the VAT symbol name of a TI-Basic list
variable which contains the category code for each item.
categories_list represents a list of integer items which determine
which categories will be included (this makes sense only if
categories_name is used).
In scatter plots, the data points from the lists of x and y items are simply
plotted as unconnected coordinate pairs. In X-Y line plots, the data points
are plotted and connected in the order in which they appear in x and y lists.
The plotted points are shown with the symbol determined by the mark_id
item. It must be an integer item, containing one of the following values (a
default value of 1 is used if it is omitted):
1 | box (a small empty square) |
2 | cross (x) |
3 | plus (+) |
4 | square (a small filled square) |
5 | dot |
For box plots, the structure on the expressions stack may have one of the
following four layouts:
data_list_name is the VAT symbol name of a TI-Basic list variable
which contains the data values. freqs_name (if present) is the VAT
symbol name of a TI-Basic list variable which contains the frequencies (all
frequencies are assumed to be 1 if freqs_name is not present). Other
items have the same meaning as for scatter and X-Y line plots.
Box plots plot the data with respect to the minimum and maximum data points
(minX and maxX) in the set. A drawn box is defined by its first quartile
(Q1), median (Med) and third quartile (Q3). Whiskers extend from minX to Q1
and from Q3 to maxX.
For modified box plots, the structure on the expressions stack may have one
of the following eight layouts:
A modified box plot is very similar to an ordinary box plot, but it excludes
all points outside the interval [Q1-X, Q3+X] where X is defined as
3*(Q3-Q1)/2. These points, called outliers, are plotted individually beyond
the box plot's whiskers, using the mark determined by mark_id (default
of 1 is used if omitted). The possible values of mark_id are the same
as with scatter and X-Y line plots.
For histograms, the structure on the expressions stack may have one of the
following eight layouts:
The meaning of all items (except bck_width) is the same as for box and
modified box plots. bck_width is an integer item which determines the
width of each bar. In histograms, the x axis is divided into equal widths
called buckets or bars. The height of each bar indicates how many data points
fall within the bar's range. See the TI-Basic manual for more info.
If everything written above seems too complicated for you, here is a simple
example. Assuming that two TI-Basic list variables "xdata" and "ydata"
contain the x and y values, and assuming that the Graph window variables are
set accordingly, the following code fragment will create and display the X-Y
line diagram of the given data using cross marks:
push_longint (4);
push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_expression (SYMSTR ("ydata"));
push_expression (SYMSTR ("xdata"));
push_shortint (1);
push_shortint (1);
cmd_newplot (top_estack);
cmd_dispg ();
Note that cmd_newplot only creates a plot. To actually display it, you must
activate the Graph screen (using cmd_dispg,
for example).
The symbol names x_list_name, y_list_name,
data_list_name, freqs_name, and categories_name may also
be "c1".."c99". In this case, they represent columns in the last data
variable shown in the Data/Matrix editor. In all cases, the lists represented
by x_list_name, y_list_name, data_list_name,
freqs_name, and categories_name must have the same dimension.
Uses: GetValue, next_expression_index, TokenizeSymName, top_estack, gr_active, memset, ParseSymName, PlotGet, PlotPut, push1
See also: cmd_plotson, cmd_plotsoff