Package {caroline}

Add new levels to the Factors in a DataFrame

Description

This function loops through all of the factor columns in a dataframe and adds new.levs to the factor levels list.

Usage

addFactLevs(x, new.levs=NA)

Arguments

See Also

factor, levels

Find the "best" record within subgroups of a dataframe.

Description

Finding the an extreme record for each group within a dataset is a more challenging routine task in R and SQL. This function provides a easy interface to that functionality either using R (fast for small data frames) or SQL (fastest for large data)

Usage

bestBy(df, by, best, top=1, clmns=names(df), rebind=TRUE, inverse=FALSE, sql=FALSE)

Arguments

Value

A data frame of 'best' records from each factor level.

Author(s)

David Schruth

See Also

groupBy

Examples

blast.results <- data.frame(score=c(1,2,34,4,5,3,23), 
                            query=c('z','x','y','z','x','y','z'), 
                            target=c('a','b','c','d','e','f','g')
                            )
best.hits.R <- bestBy(blast.results, by='query', best='score', inverse=TRUE)
best.hits.R

top3.hits.4ea <- bestBy(blast.results, by='query', best='score', inverse=TRUE, top=3, rebind=FALSE)
top3.hits.4ea

## or using SQLite
best.hits.sql <- bestBy(blast.results, by='query', best='score', inverse=TRUE, sql=TRUE)
best.hits.sql

Data Import Wrapper for dbWriteTable.

Description

This is wrapper for dbWriteTable written with the the primary improvements focusing on database import into an existing table definition schema. The function matches and rearranges columns of the dataframe to database fields and additionally performs checks for NA's in required variables, over-length strings, and type mismatches. There also exists support for updating of the PostgreSQL specific sequence for tables with auto incrementing primary keys.

Usage

dbWriteTable2(con, table.name, df, fill.null = TRUE, add.id=TRUE, 
                   row.names=FALSE, pg.update.seq=FALSE, ...)

Arguments

Value

If successful, the ids of the newly added database records (invisible).

See Also

dbWriteTable

Modify defaults of possible optional ellipsis parameter values passed to a function

Description

Takes the ellipsis function parameter (of optional named arguments) and compares with a internal (named list) of defaults for any non-conflicting user specified inputs.

Usage

ellipsis.defaults(x, nl)

Arguments

Value

a modified ellipsis variable (a named list of optional parameter values).

Examples

domy.xyplot <- function(data, x.name, y.name, ...){

 ellipsis <- ellipsis.defaults(x=list(...), nl=list(ylab=y.name,xlab=x.name))
 do.call( plot,  c(list(x=data[,x.name],y=data[,y.name]),  ellipsis))

}

domy.xyplot(data=mtcars, y.name='mpg', x.name='wt', xlab='weight')

Report a model fit in a single line of text output

Description

This function takes a fit multivariate regression model as input and converts the normal tabular output into a single line using repeated "+"or"-" symbols for significance

Usage

fit.1ln.rprt(fit, method=c('std.dev','p-value')[1], decimal.places=3, 
             name.char.len=6, print.inline=TRUE, rtrn.line=FALSE, R2=TRUE,mn='')

Arguments

Value

A character string of the form "++var1 +var5 var3 | -var2 –var4" indicating significance and direction of regression results.

Examples

# Motor Trend car data
fit.1ln.rprt(lm('mpg ~ cyl + hp + wt + gear + disp', data=mtcars))

# Tooth Growth data
fit.1ln.rprt(lm('len ~ dose + supp', data=ToothGrowth))

# Earthquake attenuation data
fit.1ln.rprt(lm('accel ~ dist + mag', data=attenu))

# Fertility data
fit.1ln.rprt(lm('parity ~ age  + education + spontaneous + induced', data=infert), name.char.len=18)

Calculate the Geometric Mean

Description

A trivial one-line function for exp(mean(log()))

Usage

geomean(x)

Arguments

Value

the geometric mean (a scalar value).

See Also

geometric.mean

Examples

geomean(rnorm(20,5))

Group a datafame by a factor and perform aggregate functions.

Description

The R equvalent of a SQL 'group by' call.

Usage

groupBy(df, by, aggregation,  clmns=names(df), collapse=',',
                distinct=FALSE, sql=FALSE, full.names=FALSE, ...)

Arguments

Value

an summary/aggregate dataframe

See Also

aggregate, bestBy

Examples

df <- data.frame(a=runif(12),b=c(runif(11),NA), 
                 z=rep(letters[13:18],2),w=rep(letters[20:23],3))

groupBy(df=df, by='w', clmns=c(rep(c('a','b'),3),'z','w'), 
 aggregation=c('sum','mean','var','sd','min','max','paste','length'), 
 full.names=TRUE, na.rm=TRUE)
# or using SQLite
groupBy(df=df, by='w', clmns=c(rep(c('a','b'),2),'z','w'), 
        aggregation=c('sum','mean','min','max','paste','length'), 
        full.names=TRUE, sql=TRUE)


## passing a custom function
meantop <- function(x,n=2, ...)
  mean(x[order(x, decreasing=TRUE)][1:n], ...)
  
groupBy(df, by='w', aggregation=rep(c('mean','max','meantop'),2), 
                    clmns=rep(c('a','b'),3), na.rm=TRUE)

Simple Heatmap Plot

Description

This is a very simplified heat-map function–a convenient wrapper around the 'image' function.

Usage

heatmatrix(x, values=TRUE, clp=c('bottom','top'), rlp=c('left','right'), 
  xadj=.05, yadj=1, ylab.cntr=FALSE, cex=1, axis.cex=1, text.col=1, xlab='',ylab='',...)

Arguments

Value

A heat-map plot.

See Also

image, heatmap, heatmap.2

Examples

data(mtcars)
x  <- as.matrix(mtcars)

heatmatrix(x)

Annotate Outliers in a Scatterplot via an HTML Image-Map

Description

This simple function makes R scatter plots interactive by creating an image and wrapping HTML around it: creating a hyperlinked hyperplot. Hover over the points to see what each is. Click to connect to a table below that will tell you more about each point (if browse ==TRUE).

Usage

hyperplot(x, y = NULL, annout = 1:length(x), 
                 name ="hyperplot.imagemap", w = 72 * 8, h = 72 * 6, 
                 link ="internal", browse = TRUE, cex = 1, ...)                 

Arguments

Value

HTML page with annotation mapped image

See Also

browseURL

Examples

if(capabilities()["png"] && interactive()) {

main.hov <- 'Hover over a point to see the name'
main.subsets <- '(annotated subset in red only)'
main.click.in <- 'click on points to visit table'
main.click.out <-  'click on points to visit external site'
cols <- c('black','red')
ext.url <- 'http://cran.r-project.org'

################################
## x and y as numeric vectors ##
################################
x.out <- nv(rnorm(13,2,sd=5),toupper(letters)[1:13])
x.in <- nv(rnorm(13,1,sd=.5),toupper(letters)[14:26])
y.out <- nv(rnorm(13,2,sd=5),toupper(letters)[1:13])
y.in <- nv(rnorm(13,1,sd=.5),toupper(letters)[14:26])
x <- c(x.out, x.in)
y <- c(y.out, y.in)

## simplest version
hyperplot(x,y, main=main.hov)

## same but with annotations being supplied as a parameter (instead of names on x)
names(x) <- NULL
hyperplot(x,y, annout=toupper(letters), main=main.hov)

## annotate only a subset 
hyperplot(x,y, annout=1:13, col=cols[rep(c(T,F), each=13)+1],
  main=paste(main.hov,main.subsets,sep='\n'))


########################
## annout as dataframe #
########################
## x and y as vectors 
x <- nv(x,toupper(letters)) # reinstate the names of x
df <- data.frame(ab=rep(c('a','b'),13),row.names=toupper(letters))
hyperplot(x,y, annout=df, 
                main=paste(main.hov, main.click.in, sep='\n'))

## x and y as names of columns in df
df <- cbind.data.frame(data.frame(x=x, y=y), df)
hyperplot(x='x',y='y', annout=df, 
                main=paste(main.hov, main.click.in, sep='\n'))

## using 'link' column name parameter to specify external links
df <- cbind.data.frame(df, 
            data.frame(url=ext.url, stringsAsFactors=FALSE))
hyperplot(x='x',y='y', annout=df, link='url', 
                main=paste(main.hov, main.click.out,sep='\n'))

## using reserved column name 'out' as a way to annotate a subset
df <- cbind.data.frame(df, data.frame(out=rep(c(TRUE,FALSE), each=13)))
hyperplot(x='x',y='y', annout=df, col=cols[df$out+1], 
                main=paste(main.hov, main.click.in, main.subsets,sep='\n'))



}

Install the next oldest package

Description

This function will recursively search the package archives backwards in time until it finds a version that installs successfully. This function is useful for installing or troubleshooting package dependency trees where one or more packages "require" the very most recent version of R. Rather than upgrading your base R installation, you can use this function to search back in time until you find a version of the package that works with your existing version of R.

Usage

install.prev.pkg(pkg.nm, version=NULL, 
  repo.url='https://cran.r-project.org/src/contrib/Archive/')

Arguments

Value

NULL

Examples

#install.prev.pkg('mnormt')
#install.prev.pkg('mvtnorm')

Buffered Segments for Point Labels

Description

This function is a wrapper for segments which trigonometrically shortens the lines that are near the "1" end so as not to clutter or overplot the text label it is attached to.

Usage

labsegs(x0, y0, x1, y1, buf=.3, ...)

Arguments

See Also

segments

Examples

x <- rnorm(1000,0,.5)
y <- rnorm(1000,-.3,.15)

labdb <- data.frame(x=seq(-.5,.5,by=.5), y=rep(.85,3))
xlims <- c(-1,1)
ylims <- c(-.5,1)

x0.lbd <- x[rev(order(y))][1:3]
y0.lbd <- y[rev(order(y))][1:3]

par(mfrow=c(1,2))
plot(x,y, xlim=xlims, ylim=ylims, main='segments')
segments(x0=x0.lbd, y0=y0.lbd, x1=labdb$x, y1=labdb$y, col=rainbow(3), lwd=3)
text(x=labdb$x, y=labdb$y, labels=letters[1:3], cex=3, col=rainbow(3))

plot(x,y, xlim=xlims, ylim=ylims, main='labsegs')
labsegs(x0=x0.lbd, y0=y0.lbd, x1=labdb$x, y1=labdb$y, col=rainbow(3), lwd=3, buf=.07)
text(x=labdb$x, y=labdb$y, labels=letters[1:3], cex=3, col=rainbow(3))

automatically find an optimal position a plot legend based on point counts in each plot corner

Description

This function assesses four corners of an x vs y plot to find the one with the fewest points. It does so by iterating counting from outward to the middle, performing a sparseness-weighted average across corners.

Usage

legend.position(x,y,xlim=NULL,ylim=NULL,start=.05, end=.5, incr=.01)

Arguments

Value

one of four values ('bottom'/'top' + 'right'/'left') corresponding to the optimal [most white space] position of the legend.

See Also

Hmisc's largest.empty function

Examples

par(mfrow=c(3,3))

for(i in 1:9){
x <- rnorm(50)
y <- rlnorm(50)
clrs <- c('red','blue')
plot(x,y, col=clrs)
legend(x=legend.position(x,y), legend = c('x','y'), pch=1, col=clrs, inset=.1) 
}

Generate a Color Coded Legend dataframe via head and sum.

Description

'leghead' is part 'head' and part 'summary'. It works best on a sorted dataframe where all you are interestesd in only the most (or least) abundant rows. An ideal place to use it is in a legend for ~lognormally distributed data. Additionally, an optional row-wise color coding column is added (the color 'gray' is used for missing row names).

Usage

leghead(x, n=7, tabulate=FALSE, colors=TRUE, na.name='NA', 
        na.col = "white", other.col = "gray",  na.last = TRUE)

Arguments

Value

A truncated dataframe with a new bottom row summarizing all the truncated ones.

See Also

summary, head, sstable

Examples

 e <- data.frame(a=runif(12),b=runif(12), z=rep(letters[13:18],2),w=rep(letters[20:23],3))
tab <- sstable(e, idx.clmns=c('z'), ct.clmns=c('a','b'))
lh <- leghead(tab)
plot(x=lh$a, y=lh$b, cex=lh$sum*3, col=lh$color, pch=20)
legend('topleft',legend=rownames(lh), col=lh$color, pch=20)

Regexp Match Operator

Description

A grep/sub-like function that returns one or more back-referenced pattern matches in the form of a vector or as columns in a dataframe (respectively). Unlike sub, this function is more geared towards data extraction rather than data cleaning. The name is derived from the popular PERL regular expression 'match' operator function 'm' (eg. 'extraction =~ m/sought_text/').

Usage

m(pattern, vect, names="V", types="character", mismatch=NA, ...)

Arguments

Value

Either a vector or a dataframe depending on the number of backreferences in the pattern.

See Also

sub, gsub, regexpr, grep, gregexpr.

Examples

## single vector output examples
m(pattern="asdf.([A-Z]{4}).", 
  vect=c('asdf.AS.fds','asdf.ABCD.asdf', '12.ASDF.asdf','asdf.REWQ.123'))


Rurls <- c('http://www.r-project.org',    'http://cran.r-project.org',
           'http://journal.r-project.org','http://developer.r-project.org')
m(pattern="http://([a-z]+).r-project.org", vect=Rurls)


# dataframe output examples

data(mtcars)
m(pattern="^([A-Za-z]+) ?(.*)$", 
  vect=rownames(mtcars), names=c('make','model'), types=rep('character',2))

Make Ellipse Coordinates

Description

Create x & y coordinates for an ellipse from parameters. save.

Usage

makeEllipseCoords(x0 = 0, y0 = 0, b = 1, a = 1, alpha = 0, pct.range = c(0,1), len = 50)

Arguments

Value

a 2 column (x and y) dataframe with coordinates for drawing an ellipse.

Examples

makeEllipseCoords(x0 = 0, y0 = 0, b = 1, a = 2, alpha = 0)

Move Text Labels Interactively

Description

There is no easy way to move point labels around interactively on an a plot in R. This function allows a point and click way to select (using identify) and move (using locator) points by modifying the underlying dataframe.

Usage

mvlabs(df, n=nrow(df), x='x', y='y', l='lab', cols=colors()[grep("dark",colors())], ...)

Arguments

See Also

locator,identify,labsegs

Examples

  x <- rnorm(20); y <- rnorm(20)
  df <- data.frame(x,y, lab=as.character(letters[1:20]))
  plot(df$x, df$y, pch=''); text(df$x, df$y, df$lab)
  ## df <- mvlabs(df, 'x','y','lab', n=3)  
  plot(df$x, df$y, pch=''); text(df$x, df$y, df$lab)

Named Merge

Description

This function is a wrapper for merge that supports merging multiple vectors and or dataframes

Usage

nerge(l, method=c("rownames", "lookup"), ...)

Arguments

Value

A data frame composed of vectors and dataframes with corresponding rownames (& DB-style lookup ".id" columns).

See Also

merge

Examples

## named vectors and dataframes ('rownames' method)
df <- data.frame(a=c(6,7,8), b=c(9,8,7))
rownames(df) <- c('a','d','c'); print(df)

vector.list <- list(p=nv(c(1.23, 1.423, 2.343), c('z','y','x')), 
                    q=nv(c(6.34,7.34, 12.545),c('z','w','y')))
df.2 <- nerge(vector.list, method='rownames', all=TRUE); print(df.2)

mixed.list <-  list(df=df, z=nv(c(4,1),c('c','d')))
df.3 <- nerge(mixed.list,      method='rownames', all=TRUE); print(df.3)
df.3 <- nerge(mixed.list[2:1], method='rownames', all=TRUE); print(df.3)


vect.x3.list <- c(list(p=vector.list[['p']], q=vector.list[['q']], 
                       r=nv(c(32, 5, 43.2), c('x','y','w'))))
df.4 <- nerge(vect.x3.list, all=TRUE); print(df.4)

# three single column dataframes with unique names
df.P <- data.frame(X=nv(1:3,letters[1:3]))
df.Q <- data.frame(Y=nv(3:5,letters[3:5]))
df.R <- data.frame(Z=nv(5:7,letters[5:7]))
nerge(list(P=df.P,Q=df.Q,R=df.R), method='rownames',all=TRUE)

# ... variation: auto append of list element names for duplicates
df.R <- data.frame(Y=nv(5:7,letters[5:7]))
nerge(list(P=df.P,Q=df.Q,R=df.R), method='rownames',all=TRUE)


## database style lookup table merges ('lookup' ['.id'] method)
lets.v <- nv(sample(letters[1:26],26),1:26)
nums.v <- nv(sample(1:10,10),1:10)
df.db <- data.frame(cols=sample(colors(),5), 
                  lets.id=sample(1:26,5), nums.id=sample(1:10,5))
join.these <- list(cols=df.db, lets=lets.v, nums=nums.v)
nerge(l=join.these, method='lookup')

Create a named vector from a dataframe, table or vector

Description

The '$' or "[," operators for dataframes and tables do not carry along with them the row names. This function provides a solution for this problem. Additionally this function will accept a vector of values and a corresponding vector of value names–an ideal, in-line way for setting named-vectors as default parameters in new functions. If x is not specified, x will be populated with an integer vector of the same length as name. Now there is also a way to use nv to retrieve named vectors from two-column lookup tables using the new paramter key.clmn, which defaults to 'id').

Usage

nv(x= seq(along = name), name = letters[length(x)], key.clmn = "id")

Arguments

Value

a named vector or factor.

Author(s)

David Schruth

See Also

vector,name

Examples

## example 1: pulling a row.named vector out of a dataframe
df <- data.frame(a=c(1,2,34,4,5,3,23), b=c('z','x','y','z','x','n','p'))
rownames(df) <- letters[1:nrow(df)]
nv(df,'a')
nv(df,'b')

## example 2: a naming vectors from scratch
nv(c(1,2,3), c('a','b','c'))
nv(df$a, df$b)

## using two column names to create: a vector of values and names

## auto-numbering for data named by the same length of 'name'
nv(name=c('a','b','c'))

Create a data frame from a named vector

Description

This function simply takes the values of the input vector and assigns it to the first column of the dataframe. The second column assigned from the names of this input vectors).

Usage

nv2df(x, clmn.names=c('x','name'), ...)

Arguments

Value

a two column dataframe with values of x in the first column and the names of x in the second

Author(s)

David Schruth

See Also

vector,name

Examples

x <- 1:3
nv2df(nv(x,letters[x]), clmn.names=c('x','y'))

Pad a vector of numerical string with zeros.

Description

This function helps to pad numbers on the left side with zeros so that they may be used to create strings used in file-system names (for example).

Usage

pad(vect,np)

Arguments

Value

a (vector of) string(s) with np number of zeros padded on as a prefix.

Author(s)

Jeremy Tantrum

Examples

pad(c(1,10,1000,10000), 4)

Process Command Line Arguments

Description

A generic function for parsing delimited lists from 'BATCH' mode argument strings.

Usage

parseArgString(string, delimiter=',', min.param.ct=2, max.param.ct=2, param.range=NULL)

Arguments

Value

A vector or value that has been check for validity.

Examples

## passes
parseArgString('apple,banana,pear', param.range=c("apple","banana","pear","pineapple"))
parseArgString('1,2,3', param.range=c(1,4))


## fails
## Not run: 
parseArgString('apple,banana,pear', param.range=c("apple","banana"))
parseArgString('1,2,3', param.range=c(1,2))

## End(Not run)

Add Percentage Columns to a Dataframe

Description

This function will add extra columns to an existing dataframe. The second argument 'clmn' should specify which column(s) of the dataframe the percentage should be calculated by dividing each column's row-element by it's sum. If x is not a dataframe, it will attempt to do a simple percentage operation on whatever input was passed to x.

Usage

pct(x, clmns=NA, digits=2, suffix='%')

Arguments

Value

The original dataframe plus extra percentage columns corresponding to original columns in the dataframe.

Examples

df <- data.frame(a=c(1,2,3), b=c('x','y','z'), c=c(5,3,2))
pct(df, c('a','c'))

pct(1:10)

Pie chart scatterplot

Description

Plot pie charts in an XY scatterplot. An overhauled wrapper of the original pie plot function. It is currently very slow: a recommend work around is to plot to something other than the default device (aka png, pdf, etc).

Usage

pies(x, show.labels = FALSE, show.slice.labels = FALSE, color.table = NULL, 
		radii = rep(2,length(x)), x0=NULL, y0=NULL, 
		edges = 200,  clockwise = FALSE, 
                init.angle = if (clockwise) 90 else 0, density = NULL, angle = 45, 
                border = NULL, lty = NULL, 
                other.color='gray', na.color='white', ...)

Arguments

Value

Pie charts as points on a plot.

See Also

pie

Examples

## these examples are to the default plot window, which can be slow
## try instead to plot to png or pdf for example

## example 1
  pies(
       list(
            a=nv(c(1,2,3),c('one','two','three')),
            b=nv(c(2,2,3),c('one','two','three')),
            c=nv(c(1,2,3),c('one','two','three'))
            ),
       x0=c(0,.5,1),
       y0=c(0,.5,1), radii=6, border=c('gray', 'black', 'red')
       )


## example 2
n <- 200
n.groups <- 10
n.subgroups <-  6

grps <- paste('gene',seq(1,n.groups), sep='')[round(runif(n,1,n.groups))]
subgrps <- paste('species',seq(1,n.subgroups), sep='')[round(runif(n,1,n.subgroups))]
group.df <- cbind.data.frame(grps,subgrps)
subgroup.list <- by(group.df, group.df$grps, function(x) x$subgrps)

pie.list <- lapply(subgroup.list, table)
col.tab <- nv(rainbow(6), unique(subgrps))

pies(x=pie.list, x0=rnorm(n.groups), y0=rnorm(n.groups), 
     radii=10, show.labels=TRUE, show.slice.labels=TRUE, color.table=col.tab)


## example 3  reading from external flat file
## salt.df <- read.delim('/path/to/my/file.tab')
## create a dummy dataset that might live inside the above file
salt.df <- data.frame(salinity=rnorm(25,5), temperature=rnorm(25,25),spec_a=rpois(25,4), 
							   spec_b=rpois(25,4), 
							   spec_c=rpois(25,4), 
							   spec_d=rpois(25,4),
							   spec_e=rpois(25,4)
							   )
## pull out the colnumn names that are specific to pie wedge numbers	
salt.spec.nms <- names(salt.df)[grep('spec',names(salt.df))]
## turn them into a list
pie.list <- lapply(1:nrow(salt.df), 
 function(i) as.table(nv(as.vector(as.matrix(salt.df[i,salt.spec.nms])),salt.spec.nms)))
names(pie.list)<- letters[1:25]
with(salt.df, pies(x=pie.list, x0=salinity, y0=temperature, radii=2))

Plot a grid of x y plots split by a confounder z

Description

Plot a grid of x y plots showing how a third confounding variable 'z' changes the slope.

Usage

## S3 method for class 'confound.grid'
plot(x, f, breaks=4, mains=NA,...)

Arguments

Value

A confounding diagnostic grid of plots.

References

Simpson, E.H. (1951). "The Interpretation of Interaction in Contingency Tables". Journal of the Royal Statiatical Soceity, Series B. 13(2) p. 238-241.

Examples

# Swiss Fertility dataset confounding example
plot.confound.grid(x=swiss, f="Infant.Mortality ~ Fertility | Education", breaks=4)

# Intertility dataset confounding example
infert$parity <- as.factor(infert$parity)
plot.confound.grid(x=infert, f="spontaneous ~ age |  parity")

Visually compare all points from different univariate distributions

Description

Visually compare continuous univariate distributions using narrow jittered strips of transparently overlapping points (with optional orthogonal trend-line overlays). This type of diagram plots positions of raw numerical data of comparable univariate distributions with a boxplot overlay (indicating quartiles and medians of the underlying points). The distributions are stacked (between) and jittered (within) as well as translucent in order to reduce overlapping points on larger-N datasets. Lines connecting between (or within) these strips (or groups of them) can be added using the appropriate function call to lines.sparge() following a corresponding preceding call to plot.sparge().

Usage

## S3 method for class 'sparge'
plot(x, f=NULL, cat.names=if(is.factor(f)){levels(f)}else{NULL}, 
          out.range=range(unlist(x)), cpd=0, cpw=.4, jit.f=1, horiz=TRUE, add=FALSE,  
          lgnd='auto', zl=FALSE, pt.cols=1, boxol='gray',alpha=.2, whiskers=1.5, ...)

## S3 method for class 'sparge'
lines(x, f=NULL, pds, cat.order=1:2, 
         horiz=TRUE, rb=nv(rainbow(length(pds)),names(pds)),  pt.pch="+", pt.cex=1.5, ...)

Arguments

Details

The function can currently take three different forms of input. First, x can be a list of numeric vectors with no need for f. Second, x can be a single vector that is to be split by factor f, of the same length. Third, x can be a dataframe and f specifies a model formula in the form of "outcome ~ predictor" (simple plot) or "out ~ predictor | control" (nested series plot with legend). The only extra points that are added to the plot are via the output of the boxplot() overlay: those outliers (outside of the normal probability range, as demarcated by the default whisker length) appearing as 'x' annotations as opposed to the 'o's of raw data points. Various parameters set to NULL can suppress different parts of the boxplot overlay (eg, boxol=NULL, whiskers=NULL) or alternatively other parameters can be passed via '...' directly to boxplot [as staplelty=0 and whisklty=0]. Aside from the normal passing of parameters to plot itself, many other parameters relevant to other underlying plotting functions (boxplot and legend plus mtext and axis) can also be passed in the following prefixed ways. For boxplot: boxplot.notch, boxplot.col, boxplot.border, boxplot.lty, boxplot.lwd and others work well–although default logic uses boxplot(range)=sparge(whiskers) with defaults of whisker.lty=1, staple.lty=1 and additionally with a pch of 'x' to mark outliers–but these can all be overidden. Nearly all of the legend params can be passed using a prefixed version of param names like so: legend.x, legend.y, legend.inset, legend.xjust, legend.border, legend.yjust, legend.box.col, legend.box.lwd legend.lty, legend.title, legend.title.col, legend.title.adj, legend legend=pt.bg, legend.cex, legend.ncol, legent.text.col, legend.text.font. X and Y axis labels are currently handled via mtext where text and side are handled automatically by xlab & ylab inputs and line is determined by the first integer in par('mgp') [=axis(line)]), however, cex can be controled by setting a value for "lab.cex". Likewise, the only way, currently, to customize the underlying call to 'axis()' is by assigning a value to axis.cex (but this also just defaults to par('cex').

lines.sparge() is an accessory function that, like it's big brothe, plot.sparge(), primarily relys upon data [x], a formula [f], and a point dodge factor [cpd], as well as an indication of which direction the plot is facing: sideways [horiz=TRUE] or upwards [horiz=FALSE]. There are many params of plot.sparge() that lines.sparge() does not use (out.range, cpw, jit.f, add, lgnd, zl, boxol, alpha, whiskers) but only a few ones that are completely unique to lines.sparge(): cat.order, which determines if lines should connect across groups [=1:2] or within groups [2:1], as well as cols and pds (similar to cpd, but vectorized on either side of 0 for two term models). lines.sparge() must be run after plot.sparge() and it adds a series of lines corresponding to the groups plotted using x as data.frame and f as formula.

Value

A 'sparge' [sprinkler/smear] plot of point distributions & the categorical variable dodge positions (only for the control variables) [invisble].

See Also

See also build-in functions boxplot(), stripchart(), stem(), and rug() in base-package 'graphics' as well as sina(), vioplot(), beanplot(), beeswarm(), and raincloud() plots (in other extension packages).

Examples

print('RNORM EXAMPLE (f=NULL)')
x <- lapply(sample(1:5), function(avg) (rnorm(500,avg)))
names(x) <- letters[1:length(x)]
plot.sparge(x, pt.cols=rep('blue',length(x)), main='sparge plots:\nfor distributional comparison')

## four random distributrions (from the 'boxplot' examples)
print('BOXPLOT EXAMPLE DISTROS')
N.rds <- 1000
distros <- list(Uniform = runif(N.rds, min=.01, max=3), Normal = rnorm(N.rds), 
                                                         `T.df5` = rt(N.rds, df = 5), 
                                                      Gamma.s2 = rgamma(N.rds, shape = 2))
plot.sparge(distros, ylab='Distribution')
points(sapply(distros, median), 1:length(distros), col=gray(.6), pch="+", cex=2)
lines(sapply(distros, median), 1:length(distros), col='green')

# three more random distributions (from the 'sinaplot' examples)
print('MORE RANDOM DISTRIBUTIONS')
uniform <- runif(500, -4, 4)
bimodal <- c(rnorm(300, -2, 0.6), rnorm(300, 2, 0.6))
normal <- rnorm(800,0,3)
distributions <- list(uniform = uniform, bimodal = bimodal, normal = normal)
plot.sparge(distributions, ylab='more distributions', 
  boxplot.border='lightgreen', boxplot.lwd=2.3)


## using 'f' [as a factor] argument as grouping factor on just one treatment

# Orchard spray by treatment (compare with 'strip chart' plot)
print('ORCHARD')
OS <- with(OrchardSprays, split(decrease, treatment))
plot.sparge(OS, log = "x", main = "Orchard Sprays", xlab='Decrease',ylab='Treatment')

# Tooth Growth
print('TOOTH GROWTH 1')
plot.sparge(x=ToothGrowth$len, f=ToothGrowth$supp, xlab='Length', ylab='Supplement')


# multi-predictor using model-based parsing of 'f' [as a formula] and 'x' as a dataset

print('TOOTH GROWTH 2')
plot.sparge(x=ToothGrowth, f="len ~ dose",  horiz=FALSE, boxplot.notch=TRUE,
             ylab='Tooth Length', main='Tooth Growth')  #xlab='Dose')


print('TOOTH GROWTH 3')
plot.sparge(x=ToothGrowth, f="len ~ dose | supp", horiz=FALSE,
            ylab='Tooth length', main='Tooth Growth', xlab='Dose')

# CO2 dataset
print('CO2')
plot.sparge(CO2, 'uptake ~ Type | Treatment', horiz=FALSE,
            ylab='Uptake', main='CO2', xlab='Type', boxplot.lty=4)

# Joyner-Boore earthquake data (heavily rounded)
print('EARTHQUAKE')
attenu$magnitude <- as.factor(round(attenu$mag))
attenu$distance <- as.factor(round(log10(attenu$dist)))
plot.sparge(x=attenu, f="accel ~ distance | magnitude", horiz=FALSE, 
  xlab='log10(Distance)',ylab='Acceleration', main='Earthquake Attenuation', 
  boxplot.lwd=1.5, cpw=.7, boxplot.col=rgb(.8,.5,0,.15))

# Motor Trend cars data (rounded)
print('CARS')
mtcars$cylinders <- as.factor(mtcars$cyl)
plot.sparge(x=mtcars, f="qsec ~ gear | cylinders", horiz=FALSE, 
         xlab='# of Gears', ylab='Seconds', main='Motor Trend Cars',
         boxplot.lwd=2.3, boxplot.lty=2)


# NPK Yeilds
print('NPK YIELDS')
npk$N <- factor(npk$N, labels=c('<none>','Nitrogen'))
npk$P <- factor(npk$P, labels=c('<none>','Phosphorus'))
npk$K <- factor(npk$K, labels=c('<none>','Potasium'))
plot.sparge(npk, f="yield ~ N | K", xlab="Yield, pounds per (1/70) acre plot")

# Wool (warp breaks per loom)
print('WOOLOOM BREAKS')
plot.sparge(warpbreaks, f="breaks ~ wool | tension", boxplot.col=rgb(1, 1, 0, 0.15),
                    xlab="# of Breaks", ylab='Wool')

# US states
print('STATES')
states <- data.frame(region=state.region, area=state.area, division=state.division)
plot.sparge(x=states, f="area ~ region | division", ylab="Region", xlab='Area', cpw=1)

# Michelson Speed of Light Data
print('LIGHT')
morley$run <- cut(morley$Run, breaks=0:4*5)
plot.sparge(x=morley, f="Speed ~ Expt | run", main="Michelson Speed of Light Experiment",
            xlab='Speed',  ylab='Experiment', boxplot.lwd=1.4, boxplot.col=rgb(.7,.7,0,.2))

# Penguins
#plot.sparge(penguins, f="body_mass ~ island | species")

# Fertility  
print('FERTILITY')
infert$education <- as.factor(infert$education)
infert$ages <- jitter(infert$age, amount=1/2)
infert$spontaneous <- factor(infert$spontaneous, labels=c(0,1,2))
infertilty.model <- "ages ~ spontaneous | education "
pds <- plot.sparge(x=infert, f=infertilty.model, horiz=FALSE, cpw=.6, legend.inset=.05, 
       ylab='Ages, yrs (jittered)', xlab='# of Prior Miscarriages' , main='[in]Fertility', 
       boxplot.lty=2, boxplot.lwd=1.4, boxplot.col=rgb(.6,0,.4,.2), boxplot.varwidth=TRUE)
lines.sparge(x=infert, f=infertilty.model, pds=pds, horiz=FALSE, cat.order=2:1, pt.cex=3, lty=3)
lines.sparge(x=infert, f=infertilty.model, pds=pds, horiz=FALSE, cat.order=1:2, lwd=2, pt.cex=2)

An x/y scatterplot with a linear regression line and p-value

Description

This function performs a simple scatter plot but also superimposes a linear regression trend (abline) and optionally also the p-value of this line.

Usage

## S3 method for class 'xy.ab.p'
plot(x, x.var, y.var, 
fit.line=TRUE, p.value=TRUE, slope=TRUE, p.col=c('red','gray','green'), 
               plot.labels=TRUE, verbose=TRUE, xlab=x.var, ylab=y.var, ...)

Arguments

Value

An x/y scatterplot with regression line

Examples

par(mfrow=c(6,5), mar=c(2,2,0,0), mgp=c(-1,.5,0))

eg.df <- expand.grid(names(swiss), names(swiss))
for(i in 1:nrow(eg.df)){
  print(i)
  xv <- as.character(eg.df[i,1]); print(xv)
  yv <- as.character(eg.df[i,2]); print(yv)
  if(yv != xv)
    plot.xy.ab.p(x=swiss, x.var=xv, y.var=yv, p.value=FALSE, slope=FALSE) 
}

Plot a simple clock.

Description

Used to create a clock on a plot as a way to keep track of the additional parameter of time for use in animated movies of multiple plots.

Usage

plotClock(hour, minute, x0 = 0, y0 = 0, r = 1)

Arguments

Value

a plot of a clock

Add Arms to a RA plot.

Description

.

Usage

raAddArms(epsilon=.55, start=1, end=6, A.shift=0, R.shift=0, ...)

Arguments

See Also

raPlot

Add axis labels to an RA plot.

Description

.

Usage

raAddAxLabs(conditions=nv(c('a','b'),c('ref','obs')), normalize=T, add=TRUE, line=2)

Arguments

See Also

raPlot

Add Significance Lines to an RA plot.

Description

.

Usage

raAddSigLines(n, end=20, alpha=1e-3, nr=0, A.shift=0, plot=FALSE, ...)

Arguments

See Also

raPlot

Generate a Ratio Average [RAy] Plot.

Description

A plot which turns two vectors of count data into log scaled fold change ratio and average abundance. The plot derives from a Bland-Altman plot and is also very similar to an MA plot. The RA plot is unique, however, in it's creative inclusion of the vector-unique 'arms' which are artificially introduced into the plot by adding a <1 epsilon factor before the log function is applied. The name RAy comes from the fact that the aforementioned 'uniques' arms addition makes it strongly resemble a geometric ray. Many of the parameters to the function play off of this convenient anatomical analogy.

Usage

raPlot(a, b=NULL, uniques=5, normalize=FALSE,  
        nr=0, alpha = 0.01, jitter=FALSE, jit.wgts=NULL,
        rex=1, flat=TRUE, tail=.5, arms=.5, spine=1, border=NULL, plot=TRUE,  ...)

Arguments

Value

a RAy plot

See Also

limma::plotMA, edgeR::maPlot

Examples

a <- rnbinom(n=10000, mu=5, size=2)
b <- rnbinom(n=10000, mu=5, size=2)

## the alternative 
plot(a,b)
## the raPlot version
raPlot(a, b) 

## highlight the condition unique points in the same way as  edgeR's "maPlot"
RA <- raPlot(a, b, pch='')
cond.unique <- apply(cbind(a,b), 1, function(d) any(d==0))
points(RA$A,RA$R, col=c('black','orange')[cond.unique+1])

## try playing with jittering over plotted points
raPlot(a, b, jitter=.3)

Read in a Tab Delimited File.

Description

This function is a slight (genome annotation friendly) variant of the built-in read.delim function in R. Two non-standard defaults have been set: stringsAsFactors=TRUE, quote="". An additional parameter "check.row.ct", triggering a count.fields call, has been added to further ensure the integrity of large data files.

Usage

read.tab(file, check.row.ct = TRUE, stringsAsFactors = FALSE, 
               quote = "", header=TRUE, ...)

Arguments

Value

a dataframe.

Regroup a dataframe.

Description

Used to group a dataframe of numbers by a factor that need not be the same length. Find the a factor in the old df and use it to group by the new trumping factor (NA's allowed).

Usage

regroup(df, old, new, clmns, funcs=rep('sum',length(clmns)), combine=TRUE)

Arguments

Value

A dataframe with number of rows equal to the number of factor levels in 'new'.

Examples

df <- data.frame(a=rnorm(20),b=rpois(20,1))

mapping <- data.frame(old=rownames(df), new=rep(c('a','b'),10))
regroup(df, old=mapping$old, new=mapping$new)

Rename select rows of a dataframe

Description

Used to easily rename the rows of a dataframe.

Usage

rerowname(df, old='NA', new='unknown')

Arguments

Value

A dataframe with one new rowname.

Examples

df <- data.frame(a=c(1,2,3), b=c('x','y','z'), c=c(5,3,2))
rownames(df) <- c('p','q','NA')
rerowname(df)

Spie charts

Description

Spie Chart

Usage

 
 spie(p1, p2, init.angle=pi, multi, col = rainbow(length(x$radii)), bg=col, lwd=2, 
              pie.labs=TRUE, grid=TRUE, grid.labs=TRUE, scale=TRUE, p1.circle=TRUE)

Arguments

Author(s)

Romain Francois francoisromain@free.fr & David Schruth code@anthropoidea.org

References

D. G. Feitelson (2003), "Comparing Partitions with Spie Charts". School of Computer Science and Engineering, The Hebrew University of Jerusalem.

Michael Friendly (2022), Spie chart – a comparison of two pie charts.

See Also

pie

Examples

  p1  <- c(0.12, 0.3, 0.26, 0.16, 0.04, 0.12)
  p2<- c(0.06, 0.15, 0.52, 0.14, 0.08, 0.05)
  plot(p1, p2, multi=c(.5, 1, 1.5, 2))

Sum Sorted Tabulation

Description

A wrapper for the "table()" function that also calculates the row-wise sum and sorts by the new column.

Usage

sstable(x, idx.clmns, ct.clmns = NULL, na.label = "NA")

Arguments

Value

A dataframe sorted by the count columns.

Author(s)

David Schruth

See Also

ledghead, table, order, sort

Examples

  e <- data.frame(a=runif(12),b=runif(12), z=rep(letters[13:18],2),w=rep(letters[20:23],3))
  e <- data.frame(a=runif(10),b=runif(10), z=rep(letters[12:16],2),w=rep(letters[20:24],2))
  sstable(e, idx.clmns=c('z','w'), ct.clmns='a')
  sstable(e, idx.clmns=c('z'), ct.clmns=c('a','b'))
  sstable(e, idx.clmns=c('z','w'))
  e <- data.frame(a=10,b=0, z=as.factor(NA))
  sstable(e, 'z', c('a','b'))
  e <- data.frame(a=10,b=0, z=NA, w=NA)
  sstable(e, 'z', c('a','b'))
  e <- data.frame(a=runif(10),b=runif(10),m=rep(c('one','two'),5), 
                  z=factor(rep('z',10), levels=c('z','x')))
  sstable(e, idx.clmns=c('m','z'))
  
  

Table to Data Frame

Description

Convert a table to a dataframe while preserving the same number of columns and rows and names of each.

Usage

tab2df(x, ...)

Arguments

Details

[[consider using check.names=F to underlying data.frame() function when converting the cross-tabulation out put from a factor produced by cut() and used by table() ]])

Value

A dataframe.

See Also

table

Examples

  x <- data.frame(a=runif(10),b=runif(10), z=rep(letters[1:5],2))
  as.data.frame(x)
  tab2df(x)
  x <- nv(rnorm(10), letters[1:10])
    as.data.frame(x)
  tab2df(x)
  x <- nv(rnorm(2), c('x.b','y.b'))
    as.data.frame(x)
  tab2df(x)
  x <- nv(rnorm(2), c('b.x','b.y'))
    as.data.frame(x)
  tab2df(x)
  e <- data.frame(a=runif(10),b=runif(10), z=rep(letters[13:17],2))
  x <- as.table(sapply(c('a','b'),function(cc) by(e[,'a'],list(e$z), sum)))
    as.data.frame(x)
  tab2df(x)
  x <- as.table(by(1:10, list(a=rep(1:5,2),b=rep(1:2,5)), sum))
    as.data.frame(x)
  tab2df(x)
  x <- as.table(nv(c(54,34), c('a','b')))
    as.data.frame(x)
  tab2df(x)

  x <- table(a='x',b='y')
  tab2df(x)
  
  

A Text-Only Plot

Description

Generate a new plot window with just text centered in the middle. This is ideally used in conjunction with the 'layout' command to label columns and rows of the grid.

Usage

textplot(..., x=1, y=1)

Arguments

Value

A new plot window with just text.

See Also

layout, text

Examples

layout(rbind(c(1,1,1),c(2,3,4), c(5, 6,7)),
       widths=c(5, 10,10) , heights=c(5, 10,10))
textplot('title', cex=2)
textplot('row 1', srt=90, cex=2)
plot(1,2)
hist(c(1,2,34,4,3,2,2))
textplot('row 2', srt=90, cex=2)
pie(c(1,23,3,1,1,2,3,4,54,5))
plot(c(1,2,4,4,23,2), c(1,2,4,3,2,2))

Grab and adjust the current plot dimensions

Description

This is a simple function which grabs the current plot dimentions and adjusts them by shrinking them by 4

Usage

usr2lims(adj=.04)

Arguments

Value

A 2 item (x and y) list of 2 item (min and max) vectors for x and y limits of the current plot area.

See Also

par

Examples

plot(c(0,1), c(0,1))
usr2lims()

Create a Venn Ready Matrix out of a List of Factors

Description

The limma package has great functions for making Venn diagrams from a matrix. This function is provides upstream functionality to turn a list of factors into this required input format.

Usage

vennMatrix(l)

Arguments

Value

A matrix with columns for list elements and rows with globally unique factor levels.

See Also

venCounts

Examples

l <- list(a=factor(c('x','y','z')), b=factor(c('w','x','v')))

vennMatrix(l)

Weighted Jitter

Description

Use weights to jitter values away from their current value.

Usage

wjitter(x, w, amount=.43)

Arguments

Value

A weighted jittered vector of the same length as x.

Examples

x <- seq(1,20)
w <- runif(20, 0,1)
plot(x,wjitter(w,x))

Write a (tab) delimited text file.

Description

A simple wrapper for write.table with the same options as read.delim.

Usage

write.delim(df, file, quote = FALSE, row.names = FALSE, sep = "\t", ...)

Arguments

Value

A tab delimited text file

See Also

read.delim

Examples

## Not run: 
x <- data.frame(a = I("a \" quote"), b = pi)
write.delim(x, file = "foo.tab")

## End(Not run)