cmd_newplot Function (ROM Call 0x366)

AMS 1.01 or higher bascmd.h

void cmd_newplot (ESI PlotData);

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:

1Scatter plot
2X-Y line plot
3Box plot
4Histogram
5Modified 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:

END_TAG y_list_name x_list_name type_id plot_no
END_TAG mark_id NOTHING_TAG NOTHING_TAG NOTHING_TAG y_list_name x_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG y_list_name x_list_name type_id plot_no
END_TAG mark_id END_TAG categories_list LIST_TAG categories_name NOTHING_TAG y_list_name x_list_name type_id plot_no

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):

1box (a small empty square)
2cross (x)
3plus (+)
4square (a small filled square)
5dot

For box plots, the structure on the expressions stack may have one of the following four layouts:

END_TAG data_list_name type_id plot_no
END_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no

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:

END_TAG data_list_name type_id plot_no
END_TAG mark_id NOTHING_TAG NOTHING_TAG NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG mark_id NOTHING_TAG NOTHING_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG mark_id END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG mark_id END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no

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:

END_TAG data_list_name type_id plot_no
END_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG bck_width NOTHING_TAG NOTHING_TAG NOTHING_TAG NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG bck_width NOTHING_TAG NOTHING_TAG NOTHING_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG bck_width NOTHING_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG bck_width NOTHING_TAG END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no

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