COGENT Online
CONTENTS
COGENT Version 2.2 Help

Data/Sink/Graph

Introduction

Data sinks are generally used to catch the output of a model. There are three forms of data sink: text-based sinks, tabular sinks and graph sinks (described here). In the case of graph sinks, messages are interpreted as data-points to be graphed, and the sink's contents are automatically displayed as a graph.

There is no limit to the number of data sets you can represent in one graph sink, and no limit on the number of graphical data sinks you can have in one model. Multiple data sets within a single graphical data sink will be treated independently, with the limitation that the graph axes and labels are determined by the graph's properties, and are hence shared by all data sets within a graph. Multiple graphical data sinks will behave as independent devices.

Graph Messages

Graph sinks are able to display multiple data sets in a variety of styles. They expect to receive two kinds of messages: type(DataSet, Type, Properties) and data(DataSet, X, Y). A type/3 term specifies the style or type of graph to be drawn for a given data set. The first argument is the name of the data set. The second argument is the graph type (either scatter, line, or bar. The third argument species graph properties such as colour and marker style. Individual data points are added to the graph by sending data/3 messages to the sink. Again, the first argument species the data set. The second and third argument specify a data point in horizontal (X) and vertical (Y) coordinates. (See also Graph Buffer.)

Secondary Properties

The third argument of each type/3 clause within a graph sink specifies secondary properties relating to the appearance of the graph. The secondary properties (similar to secondary properties in analogue buffers) allow specification of colour, fill style, and marker type. Thus, a histogram (using blue filled bars to represent frequency information) may be drawn by sending elements such as the following to a graph sink:

To draw a line graph using red filled square markers (and a red line) may be drawn by replacing the first element with:

Currently only three kinds of secondary property are recognised (colour, filled, and marker). There are four marker types (square, circle, cross and plus).

A graph sink may only contain one type definition for each data set. If a type definition is entered into a graph sink for a previously defined data set, the new definition will over-write the previous definition.

Properties

Graphical data sinks have twelve properties, most of which control the layout of the graph:

Initialise (possible values: Each Trial/Each Block/Each Subject/Each Experiment/Each Session; default: Each Trial)
This property controls re-initialising (i.e., clearing) of data sink contents.

Location [values: Local/IO Directory; default: Local]
This property specifies the location of output files. Data sink output may be stored either locally (with the definition of the sink), or in COGENT's standard OOS I/O directory, from where it may be retrieved (e.g., for inclusion in a document).

File [values: an arbitrary character string]
This property specifies the name of the output file in which data is stored. It is possible to capture data from different runs of the same model in different output files. The property is most useful when the Location property is set to IO Directory.

Title: [values: an arbitrary character string; default: "Title"]
The value of this property is used as the graph's label. When when the graph is viewed in "Current Graph" mode the string is centreed above the graph.

X Label: [values: an arbitrary character string; default: "X"]
The value of this property is used as the label for the graph's horizontal axis when the graph is viewed in "Current Graph" mode.

Y Label: [values: an arbitrary character string; default: "Y"]
The value of this property is used as the label for the graph's vertical axis when the graph is viewed in "Current Graph" mode.

X Min: [values: a real number; default: 0.0]
The value of this property specifies the minimum value of the X coordinate of the graph.

X Max: [values: a real number; default: 10.0]
The value of this property specifies the maximum value of the X coordinate of the graph.

X Units: [values: a positive integer: default: 5]
The value of this property specifies the number of units into which the horizontal axis of the graph will be divided.

Y Min: [values: a real number; default: 0.0]
The value of this property specifies the minimum value of the Y coordinate of the graph.

Y Max: [values: a real number; default: 10.0]
The value of this property specifies the maximum value of the Y coordinate of the graph.

Y Units: [values: a positive integer: default: 5]
The value of this property specifies the number of units into which the vertical axis of the graph will be divided.

The Graph View

Graphical data sinks may be viewed as graphs by selecting the "Current Graph" view. Each data/3 element is used to construct a data point on the graph for a particular data set, with the second and third arguments specifying the coordinates (and the first argument specifying the data set). The standard printing procedures may be used to print these graphs.


COGENT Online
CONTENTS
COGENT Version 2.2 Help