commandr (version 1.0.1)

Pipeline-class: Pipeline: A Sequence of Protocols

Description

A Pipeline represents a sequence of Protocols. When executed, it executes each of the protocols in turn, where each protocol is passed the output of the previous protocol. Pipeline extends list, so, in general, it can be treated as one when it comes to subsetting, etc.

Constructor

Pipeline(..., displayName = NULL): Constructs a Pipeline object with the protocols named in .... The arguments in ... should be named and be either a Protocol object or a role name for which a default Protocol is constructed. Optionally, a user-readable display name can be specified as displayName.

Execution

perform(object, data, ...): Executes the protocols in order, with the output of each pipeline passed as input to the next. Takes data as input to the first protocol and returns the output of the last protocol.

Accessors

inType(object): Get the input type of the first protocol in the pipeline, or NULL if there are no protocols.

outType(object): Get the input type of the first protocol in the pipeline, or NULL if there are no protocols.

parameters(object): Obtains a list, each element of which is a list of the parameters for the corresponding protocol.

protocol(object, role, method = character()): Gets the first protocol with the matching role and method.

protocol(object, role) <- value: Replace the first protocol with the role given by role with value.

Subsetting

pipeline(object, intype = "ANY", outtype = "ANY"): Gets the sub-pipeline that spans from the first protocol with the input type derived from intype and the last protocol with the output type derived from outtype.

head(x, n = 6L, role, method = character(), outtype): Like ordinary head, takes a prefix of the pipeline. If outtype is provided, this returns the pipeline through the first protocol with outtype as its output type. Otherwise, if role is specified, the result is the pipeline through the first protocol performing that role. This can optionally be qualified by method. If neither role nor outtype are specified, the first n elements are returned, as usual.

tail(x, n = 6L, role, method = character(), intype): Like ordinary tail, takes a suffix of the pipeline. If intype is provided, this returns the pipeline starting at the last protocol with intype as its input type. Otherwise, if role is specified, the result is the pipeline starting at the last protocol performing that role. This can optionally be qualified by method. If neither role nor outtype are specified, the last n elements are returned, as usual.

Pipeline extends list, so, in general, it can be treated as one when it comes to subsetting, etc. For example, [ method works for subsetting of Pipeline object.

Utilities

findProtocols(object, role, method = character()): Get the indices of the protocols in the pipeline with the specified role and method.

Examples

setStage("average", intype = "numeric")
setProtocol("mean", fun = mean, parent = "average")
setProtocol("quantile", representation = list(probs = "numeric"),
            fun = quantile, parent = "average")
setProtocol("range", representation = list(low = "numeric", high = "numeric"), 
            fun = function(x, low = 0, high = Inf) x[x >= low & x <= high],
            parent = setStage("trim", intype = "numeric"))

d <- c(1, 2, 4)
p <- Pipeline("trim", "average")
perform(p, d)

p <- Pipeline(Protocol("trim", low = 2), "average")
perform(p, d)

p <- Pipeline(Protocol("trim", low = 2),
              Protocol("average", "quantile", probs = 0.75),
              displayName = "Filter and Average")
perform(p, d)

## accessor
inType(p)
outType(p)
parameters(p)
protocol(p, "average")
protocol(p, "average", "quantile")
displayName(p)

## utils
findProtocols(p, "average")

## subsetting
# make a new example
setStage("DemoCastN2C", intype = "numeric", outtype = "character")
setProtocol("cast", fun = function(x){
               message("Convert from numeric to character")
               as.character(x)
            },
            parent = "DemoCastN2C")

setStage("DemoCastC2F", intype = "character", outtype = "factor")
setProtocol("cast", fun = function(x){
               message("Convert from character to factor")
               as.factor(x)
            },
            parent = "DemoCastC2F")

setStage("DemoCastF2L", intype = "factor", outtype = "list")
setProtocol("cast", fun = function(x){
               message("Convert from factor to list")
               as.list(x)
            },
            parent = "DemoCastF2L")

d <- 1:3
p <- Pipeline(Protocol("DemoCastN2C"),
              Protocol("DemoCastC2F"),
              Protocol("DemoCastF2L"))
p
perform(p, d)
# subsetting
# convert to a factor
p12 <- p[1:2]
p12
perform(p12, d)

#
p23 <- pipeline(p, intype = "character")
p23
perform(p23, as.character(d))

#
p12 <- head(p, 2)
p12
#or
head(p, outtype = "factor")
head(p, role = "DemoCastC2F")

tail(p, 2)
tail(p, intype = "character")
tail(p, intype = "factor")
tail(p, role = "DemoCastC2F")

#combination
p1 <- Pipeline(Protocol("DemoCastN2C"))
p2 <- Pipeline(Protocol("DemoCastC2F"))
p3 <- Pipeline(Protocol("DemoCastF2L"))
c(p1 ,p2)
p[2] <- p2

setClass("ExChar", contains = "character")

setStage("DemoCastC2FV2", intype = "ExChar", outtype = "factor")
setProtocol("cast", fun = function(x){
               as.factor(x)
            },
            parent = "DemoCastC2FV2")

p4 <- Pipeline(Protocol("DemoCastC2FV2"))

## Not run: 
# ## doesn't work, input 'charcter' is super class of output 'ExChar'.
# p[2] <- p4
# ## End(Not run)
p

## as a subclass, works.
setStage("DemoCastN2CV2", intype = "numeric", outtype = "ExChar")
setProtocol("cast", fun = function(x){
               new("ExChar", as.character(x))
            },
            parent = "DemoCastN2CV2")
p5 <- Pipeline(Protocol("DemoCastN2CV2"))
p[1] <- p5
p

## Not run: 
# ## won't work, because the outtype doesn't match the intype.
# c(p1, p3, p2)
# p[c(1, 3)]
# p[2] <- p3
# ## End(Not run)