l_copyStates {loon}

A generic function to transfer the values of the states of one 'loon' structure to another.

Description

l_copyStates reads the values of the states of the 'source' and assigns them to the states of the same name on the 'target'.

Usage

l_copyStates(
  source,
  target,
  states = NULL,
  exclude = NULL,
  excludeBasicStates = TRUE,
  returnNames = FALSE
)

Arguments

source

the 'loon' object providing the values of the states.

target

the 'loon' object whose states are assigned the values of the 'sources' states of the same name.

states

a character vector of the states to be copied. If 'NULL' (the default), then all states in common (excluding those identified by exclusion parameters) are copied from the 'source' to the 'target'.

exclude

a character vector naming those common states to be excluded from copying. Default is NULL.

excludeBasicStates

a logical indicating whether certain basic states are to be excluded from the copy (if 'TRUE', the default). These states include those derived from data variables (like "x", "xTemp", "zoomX", "panX", "deltaX", "xlabel", and the "y" counterparts) since these values determine coordinates in the plot and so are typically not to be copied. Similarly "swapAxes" is one of these basic states because in l_compound plots such as l_pairs() swapping axes can wreak havoc if unintended. Finally, an important pair of basic states to exclude are "linkingKey" and "linkingGroup" since such changes require proper synchronization.

Setting 'excludeBasicStates = TRUE' is a simple way to avoid copying the values of these basic states. Setting 'excludeBasicStates = FALSE' will allow these to be copied as well.

returnNames

a logical to indicate whether to return the names of all states successfully copied for all plots. Default is 'FALSE'

Value

a character vector of the names of the states successfully copied (for each plot whose states were affected), or NULL if none were copied or 'returnNames == FALSE'.

See Also

l_saveStates l_info_states saveRDS

Examples

if(interactive()){
# Source and target are `l_plots`
   p <- with(iris,
         l_plot(x = Sepal.Width, y = Petal.Width,
                color = Species, glyph = "ccircle",
                size = 10, showGuides = TRUE,
                title = "Edgar Anderson's Iris data"
               )
           )

   p2 <- with(iris,
          l_plot(x = Sepal.Length, y = Petal.Length,
                 title = "Fisher's Iris data"
                 )
              )
# Copy the states of p to p2
# First just the size and title
   l_copyStates(source = p, target = p2,
                states = c("size", "title")
                )
# Copy all but those associated with the variables
   l_copyStates(source = p, target = p2)

# Suppose p had a linkingGroup, say "Edgar"
   l_configure(p, linkingGroup = "Edgar", sync = "push")

# To force this linkingGroup to be copied to a new plot
   p3 <- with(iris,
          l_plot(x = Sepal.Length, y = Petal.Length,
                 title = "Fisher's Iris data"
                 )
              )
   l_copyStates(source = p, target = p3,
                states = c("linkingGroup"),
                # To allow this to happen:
                excludeBasicStates = FALSE
                )

   h <- with(iris,
             l_hist((Petal.Width * Petal.Length),
                    showStackedColors = TRUE,
                    yshows = "density")
                    )
   l_copyStates(source = p, target = h)

   sa <- l_serialaxes(iris, axes = "parallel")
   l_copyStates(p, sa)

   pp <- l_pairs(iris, showHistograms = TRUE)
   suppressWarnings(l_copyStates(p, pp))

   pp2 <- l_pairs(iris,
                  color = iris$Species,
                  showGuides = TRUE,
                  title ="Iris data",
                  glyph = "ctriangle")
   l_copyStates(pp2, pp)
   l_copyStates(pp2, p)
}