commandr (version 1.0.1)

setProtocol: Define a Protocol Type

Description

This function defines new derivatives of the Protocol class. It is a wrapper around setClass and thus has a very similar interface.

Usage

setProtocol(method, dispname = method, representation = list(), fun, parent, prototype = list(), validity = NULL, where = topenv(parent.frame()))

Arguments

method

The name of the method performed by protocols of this type

dispname

The display name for protocols of this type

representation

A list declaring the names and types of the parameters, implemented as slots in the S4 class

fun

The function implementing the protocol. If omitted, this protocol type will be virtual. This function will be passed the input data, any parameters named in its formals, and any arguments passed to perform. Default values for its arguments override values in prototype. Use callNextProtocol to chain up to the implementation of a parent protocol.

parent

The single parent/super class for this protocol class. Usually, this is the role, i.e., the name of the Stage for this protocol type. Also could be the name of a class inheriting from Protocol, or the concantenation of the role and method names.

prototype

As in setClass, the list indicating initial values for the parameters/slots. Usually not necessary, because it is derived from the formals of fun.

validity

The function for checking the validity of an object, see setClass.

where

The environment in which this protocol class is defined.

Value

The name of the class

Details

Every type of protocol in a pipeline is implemented as an S4 class, ultimately derived from Protocol. The parameters controlling the execution of the protocol are represented by slots in that S4 class.

Through S4 inheritance, each protocol is associated with a Stage, which represents the role a protocol plays in the pipeline. For example, a protocol might have an “average” stage, with two protocols: “mean” and “median”. Here, “average” would be the role name and would have an associated Stage derivative. Meanwhile, “mean” and “median” are method names and would each have a corresponding Protocol derivative. Protocols that have the same stage all derive from a common, virtual Protocol derivative corresponding to that stage. In our example, we would have two protocol classes: ProtoAverageMean and ProtoAverageMedian. Both would inherit from ProtoAverage, which in turn inherits from Protocol.

Another side effect of this function is that a generic is defined, named of the form role.Method, that performs this protocol, given the data and additional arguments. There is a method for the inType of the stage. Thus, in our example, we would have generics average.mean and average.median.

See Also

Protocol for constructing protocol objects, setStage for defining Stage classes.

Examples

  setStage("average")
  setProtocol("mean", fun = mean, parent = "average")
  setProtocol("median", fun = median, parent = "average")
  d <- c(1, 2, 4)
  average(d)
  average(d, "median")
  average.median(d)