compute.session_rates: Compute session rates

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

Description

compute.session_rates is a method for calculating the within-session rate of some variable. Currently, methods are defined for the classes analysis_object and its child class simulation_analysis_object.

Usage

compute.session_rates(data, event_offsets, dims = NULL,
  session_duration = NULL)


  ## S4 method for signature 'formal_event_record,list,character,numeric'
compute.session_rates(data,
  event_offsets, dims = NULL, session_duration = NULL)


  ## S4 method for signature 'formal_event_record,list,missing,numeric'
compute.session_rates(data,
  event_offsets, session_duration)


  ## S4 method for signature 'formal_event_record,list,missing,missing'
compute.session_rates(data,
  event_offsets)


  ## S4 method for signature 'formal_event_record,list,character,missing'
compute.session_rates(data,
  event_offsets, dims = NULL, session_duration = NULL)


  ## S4 method for signature 'ragged_event_record,list,character,numeric'
compute.session_rates(data,
  event_offsets, dims = NULL, session_duration = NULL)


  ## S4 method for signature 'ragged_event_record,list,missing,numeric'
compute.session_rates(data,
  event_offsets, session_duration)


  ## S4 method for signature 'ragged_event_record,list,character,missing'
compute.session_rates(data,
  event_offsets, dims)


  ## S4 method for signature 'ragged_event_record,list,missing,missing'
compute.session_rates(data,
  event_offsets)

Arguments

data	Either an object of class simulation_analysis_object, analysis_object, or dataset.
dims	A character vector of variable names to calculate the rates of. Defaults to NULL. If NULL, the rates of all the events in the data argument are computed.
session_duration	A numeric value specifying the duration of the session over which the rates are calculated. Defaults to NULL. If NULL, the latest time associated with an event is taken as the session duration. See details.
rft_duration	A list with each element being a numeric specifying the reinforcemnt duration and the name of each element corresponding to the reinforcement event.

Details

session_duration = NULL

When data is of class simulation_analysis_object, the session duration is taken as the maximum recorded time for the list of variables for which rates are calculated. Note that the variables associated with reinforcement delivery in rft_duration are automatically included in determining the session duration.

When the data is of class analysis_object, the session duration is taken as the time associated with the last entry in the event_time data frame.

When the datais of class dataset, the compute.session_rates method for the analysis_object is just looped over all the analysis_objects contained in the dataset object.

The computation of the rate

When the rate is calculated, regardless of the method, the number of times that a particular event occurs is divided by the session time. The session time is corrected by the time that is taken up by reinforcement deliveries. The session time taken up by reinforcement is calculated as rft_time * rft_number. A further correction is done when the last event in the simulation or experiment is a reinforcement delivery, where the session time taken by reinforcement is calculated as rft_time * (rft_number-1).

Computing rates for objects of dataset

To calculate the rates for the multiple sessions that are stored in a dataset object, we essentially call lapply over all of the analysis_objcts in the dataset.

With respect to efficiency, the compute.session_rates method for simulation_analysis_object is about 5 times faster than the method for analysis_object. For standard data analysis, where time is not a big concern, either method is fine. In fact, the method using analysis_object may be better because it uses the event_time dataframe in the parent analysis_object class, so it is functionally more convenient. When doing simulations, time is a concern. Hence, the method with simulation_analysis_object should be used. Hopefully, this gives the reader some understanding about the design rationale for this method.

See Also

class.analysis_object For constructing arguments for data parameter.

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