class.event_record: 'event_record' class

In Don-Li/CAB: The Computational Analysis of Behaviour

Description

When a simulation is run in the CAB package, events, such as the time of a response, can be stored in an event_record object. The event_record is a virtual class with two children classes: the ragged_event_record class and the formal_event_record class.

Usage

make.formal_event_record(variables, len)

## S4 method for signature 'ragged_event_record'
show(object)

## S4 method for signature 'formal_event_record'
show(object)

e_set(event_record, variable, index = NULL, values = NULL, counts = NULL)

reset_event(event_record)

get_event(event_record, variable, index = NULL, counts = F)

trim_event_record(event_record)

Details

The ragged_event_record class holds the data in a list where each element in the list is a vector of response times for a given type of event. This is called "ragged" because it is a ragged matrix. In contrast, the formal_event_record is an n x 2 matrix, where the first column is a vector of times and the second column is a vector of events at the corresponding times.

The construction of an event_record object requires the specification of the names of the events to be recorded. An event_record object has two slots.

The first slot, called events is an environment that contains two lists. The first list is a list of vectors, where each vector contains the times of the associated events. For example, if we wished to record the response times and the reinforcement times, this could be a list containing a vector named "response_times" and a vector named "reinforcement_times". The second list is a list of counts for how many of each type of recorded event has occurred. It follows then instead of the typical time-event format for data, we have the times of each event with different vectors for each event.

The second slot, variables is a vector that contains the names of the variables to be recorded. This is just for easy access.

The ragged_event_record class

The ragged_event_record can be used for recording events that occur during a simulation. This is preferred because it is typically faster to calculate descriptive statistics with the ragged_event_record than with a formal_event_record.

Slots

events

An environment that contains n+1 elements, where n is the number of variables that are to be recorded. One element in the environment will be counts, which is a list where each element contains the number of events of each type. The other elements are vectors that store the time at which the events associated with a specific variable occurred.

variables

A character vector containing the types of events to be recorded.

lengths

A named vector containing the base lengths of the vectors for containing the events associated with each variable.

make.event_record

For making a event_record object.

Usage

make.event_record( variables, len )

Arguments

variables

A character vector containing the types of events to be recorded.

len

A numeric vector containing the length of the vectors for storing each variable type. len is recycled if the length of len is smaller than the number of variables specified.

Value

Returns a event_record object.

e_set

For changing events and counts in an event_record.

Usage

e_set( event_record, variable, index, values, counts )

Arguments

event_record

A object of class event_record.

variable

A character string specifying the variable to change.

index

A numeric vector of indices for the events to change for the specified variable. May also be "next" for which events at indices after the index specified by the counts are changed. Defaults to NULL and no values are changed. See example.

values

Values of the new events. Defaults to NULL and no values are changed.

counts

New counts for the variable events being changed.

Value

Modifies the event_record object in place.

get_event

Extract event values.

Usage

get_event{ event_record, variable, index, counts }

Arguments

event_record

An object of class event_record.

variable

A character string specifying the variable to change.

index

A numeric vector of indices. Defaults to NULL for which no events are returned.

counts

A logical indicating whether or not to return the counts for the variable. Defaults to FALSE

Value

Returns the counts for the specified variable if counts is TRUE. Returns the event values if counts is FALSE and index is not NULL

reset_event

Reset all variables in an event_record.

Usage

reset_event{ event_record }

Arguments

event_record

A object of class event_record.

Value

Modifies the event_record object in place. All values for each variable are reset to NaN.

See Also

convert_event_record

Examples

# Create an "event_record" for storing the variables: "resp_time" and "rft_time"
# Record a maximum of 100 of each type of event
my_record = make.ragged_event_record( variables = c( "resp_time", "rft_time" ), len = 100 )
my_record

# Imagine an organism that emits responses every 1 time unit. Suppose that the experiment ran for 90 seconds
# The "resp_time" in "my_record" should contain 1:90, so there should be 90 counts
e_set( event_record = my_record, variable = "resp_time", index = 1:90, values = 1:90, counts = 90 )
my_record

# Suppose the organism took a break for 2 time units and then made 3 responses. The next response times should then be 93:95.
e_set( event_record = my_record, variable = "resp_time", index = "next", values = 93:95 )
my_record

# Get the value of an event at a given index:
get_event( event_record = my_record, variable = "resp_time", index = 1 )
get_event( event_record = my_record, variable = "resp_time", index = 1:10 )
# get the counts for a variable:
get_event( event_record = my_record, variable = "resp_time", counts = T )

# Reset "my_record"
reset_event( my_record )

Don-Li/CAB documentation built on May 6, 2019, 2:52 p.m.