COGENT Online |

CONTENTS |

COGENT Help |

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 can be displayed as a graph.

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

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

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`, `fill`, 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.

Graphical 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 tables.

Tabular data sinks have twelve properties:

**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.

**Location [values: Local/IO Directory; default: Local]**

This property specifies the location of output files. Sink output may be
stored either locally (with the definition of the sink), or in the standard
I/O directory, from where it may be retrieved (e.g., for inclusion in a
document).

**Initialise (possible values: Each Trial/Each Block/Each Subject/Each Session;
default: Each Trial)**

This property controls reinitialising (i.e., clearing) of
sink contents.

**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.

COGENT Online |

CONTENTS |

COGENT Help |