loa (version 0.3.1.1)

4.8.list.handlers: List manipulation

Description

Workhorse functions for routine list handling in loa and elsewhere.

Usage

listHandler(a, use = NULL, ignore = NULL, 
            drop.dots=TRUE)
listUpdate(a, b, use = NULL, ignore = NULL,
            use.a = use, use.b = use,
            ignore.a = ignore, ignore.b = ignore, 
            drop.dots = TRUE)
listExpand(a, ref = NULL, use = NULL, 
            ignore = NULL, drop.dots = TRUE)
listLoad(..., load = NULL)

Value

By default, all list... functions return results as lists.

listHandler, listUpdate and listExpand functions all return a modified (or updated) version of supplied list a.

listLoad (in-development) returns modified (or updated) version of additional arguments as a list. See Note below.

Arguments

a

A required list. The list to be modified.

b

For listUpdate only, a required second list, the contents of which are used to update a with.

use, use.a, use.b

Vectors, all defaults NULL. If supplied, a vector of the names of list enteries to be used. Other enteries are then discarded. use is applied to all supplied lists, while use.a, use.b, etc. can be used to subset a and b lists individually.

ignore, ignore.a, ignore.b

Vectors, default NULL. As with use, etc, but for enteries to be ignored/not passed on for modification.

ref

For listExpand only, a vector, default NULL. A reference data series, the length of which is used as the expansion length to be applied when wrapping of list enteries.

drop.dots

Logical, default TRUE. If TRUE, this removes "..." entries from list names before updating.

...

For listLoad only, any additional arguments.

load

For listLoad only, a character vector, default NULL. The names of any lists to be automatically generated from the additional arguments supplied as part of the command call.

Author

Karl Ropkins

Details

listHandler is a general function used by other list... functions for routine list preprocessing.

listUpdate is a list handler intended for use when managing user updates for default options (see examples).

listExpand is a list handler that expands vectors to a given reference length, intended for use for data wrapping.

listLoad is a list generator. See Note below.

References

These functions make extensive use of code developed by others.

lattice: Sarkar, Deepayan (2008) Lattice: Multivariate Data Visualization with R. Springer, New York. ISBN 978-0-387-75968-5

See Also

lattice, xyplot,

Examples

## Example 1
## general

#  two lists
list1 <- list(a = 1:10, b = FALSE)
list2 <- list(b = TRUE, c = "new")

#  updating a with b
#  keeps unchanged list1 entry, a
#  updates changed list1 entry, b
#  adds new (list2) entry, c
listUpdate(list1, list2)


## Example2
## use in plot functions
## to simplify formals

if (FALSE) {
#  some data
a <- 1:10
b <- rnorm(10,5,2)

#a bad plot function

badplot <- function(x, ...){

    #setting defaults in xyplot call itself
    xyplot(x = x, pch = 20, col = "red",
                   panel = function(...){
                           panel.grid(-1, -1)
                           panel.xyplot(...)
                           panel.abline(0,1)
                   }, ...)
}

  badplot(a~b)                 #OK

#  compare with 
  badplot(a~b, xlim = c(1,20)) #OK
  badplot(a~b, col = "blue")   #not OK

#  because col hardcoded into badplot function
#  It is duplicated in call and '...'
#  so user cannot update col 


#a standard correction

stdplot <- function(x, pch = 20, col = "red", ...){

    #setting defaults in xyplot call itself
    xyplot(x = x, pch = 20, col = "red",
                   panel = function(x=x, pch=pch, col=col, ...){
                           panel.grid(-1, -1)
                           panel.xyplot(x=x, pch=pch, col=col, ...)
                           panel.abline(0,1)
                   }, ...)
}

  stdplot(a~b)                  #OK
  stdplot(a~b, col = "blue", 
          xlim=c(1:20))         #also OK
 

#  An alternative correction using lists and 
#  listUpdate that removes the need for formal 
#  definition of all modified plot arguments 

myplot <- function(x, ...){

    #defaults I set for myplot form of xyplot
    mylist <- list(x = x, pch = 20, col = "red",
                   panel = function(...){
                           panel.grid(-1, -1)
                           panel.xyplot(...)
                           panel.abline(0,1)
                   })
    #plot
    do.call(xyplot, listUpdate(mylist, list(...)))
}


  myplot(a~b)                 #OK
  myplot(a~b, col = "blue", 
         xlim = c(1,20))      #also OK
}