COGENT Online |

CONTENTS |

COGENT Version 2.2 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 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 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.)

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.

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.

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 |