COGENT Online
 CONTENTS
 COGENT Version 2.4 Help

# Buffer/Graph

## Introduction

Graph buffers provide the functionality of a buffer with an option to view and print the buffer contents as a graph or chart. Elements of a graph buffer may take one of two forms: type(DataSet, Type, Properties) or data(DataSet, X, Y), where DataSet identifies a particular data set, Type specifies the type of graph required for that data set (see below), Properties is a list of secondary properties specifying aspects of the appearance of the particular data set (see below), and X and Y are numeric values for the data set. Graph buffer elements may be matched, added or deleted, in a way analogous to elements from other sub-types of buffer.

There is no limit to the number of data sets that may be stored in one graph buffer. Normally there will be one type/3 element and several data/3 elements for each data set. Multiple data sets within a single graph buffer are treated independently, with the limitation that the graph axes and labels are determined by graph properties (see below), and are hence shared by all data sets within a graph.

## Element Types

A type/3 term specifies the style or type of graph to be drawn for a given data set. The second argument must be one of scatter, line, or bar. The third argument specifies graph properties such as colour and marker style, in the form of a list of secondary properties. Thus, the following type/3 element:

type(frequency, bar, [colour(blue), filled(true)])

specifies that the graph associated with frequency should be a bar-chart drawn with blue filled bars. This could be changed to a line graph using red filled square markers (and a red line) by replacing the above element with:

type(frequency, line, [colour(red), marker(square), filled(true)])

Three kinds of secondary property are recognised: colour, filled, and marker. There are four marker types: square, circle, cross and plus.

## Properties

Graph buffers inherit all of the properties associated with the parent buffer class, plus additional properties for controlling the appearance of the graph. The full set of properties of a graph buffer are:

Initialise (possible values: Each Trial/Each Block/Each Subject/Each Experiment/Each Session; default: Each Trial)
The timing of buffer initialisation is determined by this property. When the value is Each Trial, the buffer will automatically initialise itself at the beginning of each trial. When the value is Each Block, the buffer will initialise itself at the beginning of each block of trials (i.e., contents will be preserved across trials within a block). Similarly, when the value is Each Subject, contents will be preserved across simulated blocks, when the value is Each Experiment, contents will be preserved across simulated subjects, and when the value is Each Session, the contents will be preserved across experiments.

Decay (possible values: None/Half-Life/Linear/Fixed; default: None)
This property specifies whether the elements of a buffer decay with time, and if so what pattern of decay is observed.
When the value is None, elements will remain in a buffer until they are either explicitly deleted or are forced out by the buffer overflowing.
When the value is Half-Life, elements decay in a random fashion, but with the probability of decay begin constant on each cycle. This probability is specified in terms of a half life (specified by the Decay Constant property). The half life is the number of cycles it takes on average for half of the elements to decay.
When the value is Linear, elements decay in a probabilistic fashion, but with the probability of an element decay increasing linearly with each cycle it remains in the buffer. The maximum number of cycles an element can spend in the buffer is given by the value of the Decay Constant property. (So if decay is Linear and the decay constant is 10, the probability of an element decaying on the first cycle will be 0.1, the probability of it decaying within two cycles will be 0.2, and so on, with the probability of it decaying in 10 cycles being 1.0.)
When the value is Fixed, elements remain in the buffer for a fixed number of cycles (specified by the Decay Constant property).

Decay Constant (possible values: 1 -- 9999; default: 20)
This property determines the decay rate if decay is specified for the buffer. In the case of Half-Life decay, the constant specifies the half-life (in cycles) of buffer elements. A larger number will result in a longer half-life and so a slower decay. In the case of Linear decay, the constant specifies the maximum number of cycles an element may remain in the buffer. In the case of Fixed decay, the constant specifies the number of cycles an element will remain present in the buffer after the element is added to the buffer (provided it is not ``refreshed'' via Duplicates: No, as discussed above). Again, a larger number will lead to slower decay.

Limited Capacity (possible values: on/off; default: off)
This property determines whether the buffer has limited or unlimited capacity. If the value is Yes then the buffer's capacity is limited to the value specified by the Capacity property, and its behaviour when that capacity is exceeded is governed by the On Excess property; if the value is No, these two properties are ignored.

Capacity (possible values: 1 -- 9999; default: 7)
This property specifies the capacity of a buffer in terms of the number of items it may hold. If Limited Capacity is not selected, this property has no effect.

On Excess (possible values: Random/Youngest/Oldest/Ignore; default: Random)
The value of this property determines how the buffer behaves when its capacity is exceeded. If the value is Random, then a random element will be deleted from the buffer to make way for the new element. If the value is Youngest, then the most recently added element will be deleted to make way for the new element. If the value is Oldest, then the least recently added element will be deleted to make way for the new element. If the value is Ignore, then the new element will be discarded and the buffer contents will not be altered. If Limited Capacity is not selected, this property has no effect.

Grounded (Boolean; default: TRUE)
If this property is set, attempts to add ungrounded terms (i.e., terms containing variables) to the buffer will result in an error message. The rationale for this property is that in most applications adding ungrounded terms to a buffer is probably results from a bug in the model, so flagging such occurrences is useful. In some applications, however, it may be reasonable to have ungrounded terms in buffers (e.g., where the terms represent production-like rules). In these cases, the property should not be set.

Access (values: Random/FIFO/LIFO; default: Random):
The order in which the buffer's elements are accessed by match operations. Interpretation of the property's values follows that of propositional buffers.

Title (values: an arbitrary character string; default: ``Title''):
The graph's title, which is centred above the graph when the graph is viewed in the Current Graph page or when the graph is printed.

X Label (values: an arbitrary character string; default: ``X''):
The label drawn beside the graph's horizontal axis.

Autoscale X (Boolean; default: FALSE):
If this property is set, COGENT will automatically select suitable values for the minimum and maximum coordinates on the X axis (based on the data present on the graph). If the property is not set, the values of the X Min and X Max properties will be used instead.

X Min (values: a real number; default: 0.0):
The minimum value of the horizontal coordinate of the graph.

X Max (values: a real number; default: 10.0):
The maximum value of the horizontal coordinate of the graph.

X Units (values: a positive integer: default: 5):
The number of units into which the horizontal axis of the graph is divided.

Y Label (values: an arbitrary character string; default: ``Y''):
The label drawn beside the graph's vertical axis.

Autoscale Y (Boolean; default: FALSE):
If this property is set, COGENT will automatically select suitable values for the minimum and maximum coordinates on the Y axis (based on the data present on the graph). If the property is not set, the values of the Y Min and Y Max properties will be used instead.

Y Min (values: a real number; default: 0.0):
The minimum value of the vertical coordinate of the graph.

Y Max (values: a real number; default: 100.0):
The maximum value of the vertical coordinate of the graph.

Y Units (values: a positive integer: default: 5):
The number of units into which the vertical axis of the graph is divided.

## The Graph View

Graphical buffers may be viewed as graphs by selecting the Current Graph page of the box's notebook. 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.

## The Buffer Element Editor

Recall that all information must be represented in COGENT via Prolog terms. Buffer elements are no exception, but they are perhaps the simplest sorts of box elements in COGENT. This is reflected in the simplicity of the buffer element editor. Apart from the comment line, it contains a single text field into which the buffer element should be typed. The contents of this field should be a valid Prolog term. If not, however, COGENT does automatic syntax checking (and attempted correction) of editor elements, and so any error will be noted and (possibly) corrected.

 COGENT Online
 CONTENTS
 COGENT Version 2.4 Help