Package 'jamba'

Description

Adjust axis label margins to accommodate axis labels

Usage

adjustAxisLabelMargins(
  x,
  margin = 1,
  maxFig = 1/2,
  cex = graphics::par("cex"),
  cex.axis = graphics::par("cex.axis"),
  prefix = "-- -- ",
  ...
)

Arguments

Details

This function takes a vector of axis labels, and the margin where they will be used, and adjusts the relevant axis margin to accomodate the label size, up to a maximum fraction of the figure size as defined by maxFig.

Labels are assumed to be perpendicular to the axis, for example argument las=2 when using graphics::text().

Note this function does not render labels in the figure, and therefore does not revert axis margins to their original size. That process should be performed separately.

Value

list named "mai" suitable for use in graphics::par() to adjust margin size using in inches.

See Also

Other jam plot functions: coordPresets(), decideMfrow(), drawLabels(), getPlotAspect(), groupedAxis(), imageByColors(), imageDefault(), minorLogTicksAxis(), nullPlot(), plotPolygonDensity(), plotRidges(), plotSmoothScatter(), shadowText(), shadowText_options(), showColors(), sqrtAxis(), usrBox()

Examples

xlabs <- paste0("item_", (1:20));
ylabs <- paste0("rownum_", (1:20));

# proper adjustment should be done using withr, for example
x_cex <- 0.8;
y_cex <- 1.2;
withr::with_par(adjustAxisLabelMargins(xlabs, 1, cex.axis=x_cex), {
   withr::local_par(adjustAxisLabelMargins(ylabs, 2, cex.axis=y_cex))
   nullPlot(xlim=c(1,20), ylim=c(1,20), doMargins=FALSE);
   graphics::axis(1, at=1:20, labels=xlabs, las=2, cex.axis=x_cex);
   graphics::axis(2, at=1:20, labels=ylabs, las=2, cex.axis=y_cex);
})

withr::with_par(adjustAxisLabelMargins(xlabs, 3, cex.axis=x_cex), {
   withr::local_par(adjustAxisLabelMargins(ylabs, 4, cex.axis=y_cex))
   nullPlot(xlim=c(1,20), ylim=c(1,20), doMargins=FALSE);
   graphics::axis(3, at=1:20, labels=xlabs, las=2);
   graphics::axis(4, at=1:20, labels=ylabs, las=2);
})

par("mar")

Description

Define the alpha transparency per R color

Usage

alpha2col(x, alpha = 1, maxValue = 1, ...)

Arguments

Value

character vector of R colors, with alpha values.

See Also

Other jam color functions: applyCLrange(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

withr::with_par(list("mfrow"=c(2,2)), {
for (alpha in c(1, 0.8, 0.5, 0.2)) {
   nullPlot(plotAreaTitle=paste0("alpha=", alpha),
      doMargins=FALSE);
   usrBox(fill=alpha2col("yellow",
      alpha=alpha));
}
})

Description

Restrict chroma (C) and luminance (L) ranges for a vector of R colors

Usage

applyCLrange(
  x,
  lightMode = NULL,
  Crange = getOption("jam.Crange"),
  Lrange = getOption("jam.Lrange"),
  Cgrey = getOption("jam.Cgrey", 5),
  fixYellow = TRUE,
  CLmethod = c("scale", "floor", "expand"),
  fixup = TRUE,
  ...
)

Arguments

Details

This function is primarily intended to restrict the range of brightness values so they contrast with a background color, particularly when the background color may be bright or dark.

Note that output is slightly different when supplying one color, compared to supplying a vector of colors. One color is simply restricted to the Crange and Lrange. However, a vector of colors is scaled within the ranges so that relative C and L values are maintained, for visual comparison.

The C and L values are defined by colorspace::polarLUV(), where C is typically restricted to ⁠0..100⁠ and L is typically ⁠0..100⁠. For some colors, values above 100 are allowed.

Values are restricted to the given numeric range using one of three methods, set via the CLmethod argument.

As an example, consider what should be done when Crange <- c(10,70) and the C values are Cvalues <- c(50, 60, 70, 80).

1. "floor" uses jamba::noiseFloor() to apply fixed cutoffs at the minimum and maximum range. This method has the effect of making all values outside the range into an equal final value.

2. "scale" will apply jamba::normScale() to rescale only values outside the given range. For example, c(Crange, Cvalues) as the initial range, it constrains values to c(Crange). This method has the effect of maintaining the relative difference between values.

3. "expand" will simply apply jamba::normScale() to fit the values to the minimum and maximum range values. This method has the effect of forcing colors to fit the full numeric range, even when the original differences between values were small.

In case (1) above, Cvalues will become c(50, 60, 70, 70). In case (2) above, Cvalues will become c(44, 53, 61, 70) In case (3) above, Cvalues will become c(10, 30, 50, 70)

Note that colors with C (chroma) values less than Cgrey will not have the C value changed, in order to maintain colors at a greyscale, without colorizing them. Particularly for pure grey, which has C=0, but is still required to have a hue H, it is important not to increase C.

Value

vector of colors after applying the chroma (C) and luminance (L) ranges.

See Also

Other jam color functions: alpha2col(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

cl <- c("red", "blue", "navy", "yellow", "orange");
cl_lite <- applyCLrange(cl, lightMode=TRUE);
cl_dark <- applyCLrange(cl, lightMode=FALSE);

# individual colors
cl_lite_ind <- sapply(cl, applyCLrange, lightMode=TRUE);
cl_dark_ind <- sapply(cl, applyCLrange, lightMode=FALSE);

# display colors
showColors(list(`input colors`=cl,
   `lightMode=TRUE, vector`=cl_lite,
   `lightMode=TRUE, individual`=cl_lite_ind,
   `lightMode=FALSE, vector`=cl_dark,
   `lightMode=FALSE, individual`=cl_dark_ind))
printDebug(cl, lightMode=TRUE);

Description

Add categorical colors to 'Excel' 'xlsx' worksheets

Usage

applyXlsxCategoricalFormat(
  xlsxFile,
  sheet = 1,
  rowRange = NULL,
  colRange = NULL,
  colorSub = NULL,
  colorSubText = setTextContrastColor(colorSub),
  trimCatNames = TRUE,
  overwrite = TRUE,
  wrapText = FALSE,
  stack = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Details

This function is a convenient wrapper for applying categorical color formatting to cell background colors, and applies a contrasting color to the text in cells using setTextContrastColor(). It uses a named character vector of colors supplied as colorSub to define cell background colors, and optionally colorSubText to define a specific color for the cell text.

Value

Workbook object as defined by the openxlsx package is returned invisibly with invisible(). This Workbook can be used in argument wb to provide a speed boost when saving multiple sheets to the same file.

See Also

Other jam export functions: applyXlsxConditionalFormat(), readOpenxlsx(), set_xlsx_colwidths(), set_xlsx_rowheights(), writeOpenxlsx()

Examples

# write to tempfile for examples
if (check_pkg_installed("openxlsx")) {
   out_xlsx <- tempfile(pattern="writeOpenxlsx_", fileext=".xlsx")
   df <- data.frame(a=LETTERS[1:5], b=1:5);
   writeOpenxlsx(x=df,
      file=out_xlsx,
      sheetName="jamba_test");

   colorSub <- nameVector(
      rainbow2(5, s=c(0.8, 1), v=c(0.8, 1)),
      LETTERS[1:5]);
   applyXlsxCategoricalFormat(out_xlsx,
      sheet="jamba_test",
      colorSub=colorSub
   )
}

Description

Xlsx Conditional formatting

Usage

applyXlsxConditionalFormat(
  xlsxFile,
  sheet = 1,
  fcColumns = NULL,
  fcGrep = NULL,
  fcStyle = c("#4F81BD", "#EEECE1", "#C0504D"),
  fcRule = c(-6, 0, 6),
  fcType = "colourScale",
  lfcColumns = NULL,
  lfcGrep = NULL,
  lfcStyle = c("#4F81BD", "#EEECE1", "#C0504D"),
  lfcRule = c(-3, 0, 3),
  lfcType = "colourScale",
  hitColumns = NULL,
  hitGrep = NULL,
  hitStyle = c("#4F81BD", "#EEECE1", "#C0504D"),
  hitRule = c(-1.5, 0, 1.5),
  hitType = "colourScale",
  intColumns = NULL,
  intGrep = NULL,
  intStyle = c("#EEECE1", "#FDC99B", "#F77F30"),
  intRule = c(0, 100, 10000),
  intType = "colourScale",
  numColumns = NULL,
  numGrep = NULL,
  numStyle = c("#F2F0F7", "#B4B1D4", "#938EC2"),
  numRule = c(1, 10, 20),
  numType = "colourScale",
  pvalueColumns = NULL,
  pvalueGrep = NULL,
  pvalueStyle = c("#F77F30", "#FDC99B", "#EEECE1"),
  pvalueRule = c(0, 0.01, 0.05),
  pvalueType = "colourScale",
  verbose = FALSE,
  startRow = 2,
  overwrite = TRUE,
  ...
)

Arguments

Details

This function is a convenient wrapper for applying conditional formatting to 'Excel' 'xlsx' worksheets, with reasonable settings for commonly used data types.

Note that this function does not apply cell formatting, such as numeric formatting as displayed in 'Excel'.

A description of column types follows:

"fc"

Fold change, typically positive and negative values, which are formatted to show one decimal place, and use commas to separate thousands places, e.g. 1,020.1. Colors are applied with a neutral midpoint, coloring values which are above and below zero.

"lfc"

log fold change, typically positive and negative values, which are formatted to show one decimal place, and use commas to separate thousands places, e.g. 12.1. Colors are applied with a neutral midpoint, coloring values which are above and below zero. Log fold changes have slightly different color thresholds than fold changes.

"hit"

Hit columns, often just values like c(-1,0,1), but which could be fold changes for statistical hits for example. They are formatted to show one decimal place, and use commas to separate thousands places, e.g. 1.5. Colors are applied with a neutral midpoint, coloring values which are above and below zero, typically with a fairly low threshold.

"int"

Integer columns, which are formatted to hide decimal place values even if present, which can help clean up visible tabular data. They are formatted to use commas to separate thousands places, e.g. 1,020. Colors are applied with a baseline of zero, intended for highlighting two thresholds of values above zero.

"num"

Numeric columns, which are formatted to display 2 decimal places, and to use commas to separate thousands places, e.g. 1,020.1. Colors are applied with a baseline of zero, intended for highlighting two thresholds of values above zero.

"pvalue"

P-value columns, which are formatted to display scientific notation always, for consistency, with two decimal places, e.g. 1.02e-02. Colors are applied starting at white for P-value of 1 (non-significant) and becoming more red as the P-value approaches 0.01, then 0.0001.

For each column type, one can describe the column using integer indices, or colnames, or optionally use the Grep parameters. The Grep parameters are intended for pattern matching, and may contain a vector of grep patterns which are used by provigrep() to match to colnames. The Grep method is particularly useful when applying conditional formatting for multiple worksheets in the same 'xlsx' file, where the colnames are not identical in each worksheet.

Each column type has an associated 3-threshold rule, and three associated colors. In order to apply different thresholds, one would need to call this function multiple times, specifying different subsets of columns corresponding to each set of thresholds. The same process is required in order to apply different color gradients to different columns. Note that styles are by default "stacked", which maintains font and cell border styles without removing them. However, it this "stacking" means that applying two rules to the same cell will not work, since only the first rule will be applied by 'Microsoft Excel'. Interestingly, if multiple conditional rules are applied to the same cell, they will be visible in order inside the 'Microsoft Excel' application.

Value

Workbook object as defined by the openxlsx package is returned invisibly with invisible(). This Workbook can be used in argument wb to provide a speed boost when saving multiple sheets to the same file.

See Also

Other jam export functions: applyXlsxCategoricalFormat(), readOpenxlsx(), set_xlsx_colwidths(), set_xlsx_rowheights(), writeOpenxlsx()

Examples

# write to tempfile for examples
if (check_pkg_installed("openxlsx")) {
   out_xlsx <- tempfile(pattern="writeOpenxlsx_", fileext=".xlsx")
   df <- data.frame(a=LETTERS[1:5], b=1:5);
   writeOpenxlsx(x=df,
      file=out_xlsx,
      sheetName="jamba_test");

   applyXlsxConditionalFormat(out_xlsx,
      sheet="jamba_test",
      intColumns=2,
      intRule=c(0,3,5),
      intStyle=c("#FFFFFF", "#1E90FF", "#9932CC")
   )
}

Description

convert date DDmmmYYYY to Date

Usage

asDate(getDateValues, dateFormat = "%d%b%Y", ...)

Arguments

Details

This function converts a text date string to Date object, mainly to allow date-related math operations, for example difftime.

Value

Date object

See Also

Other jam date functions: dateToDaysOld(), getDate()

Examples

asDate(getDate());

Description

convert numeric value or R object to human-readable size

Usage

asSize(
  x,
  digits = 3,
  abbreviateUnits = TRUE,
  unitType = "bytes",
  unitAbbrev = gsub("^(.).*$", "\\1", unitType),
  kiloSize = 1024,
  sep = " ",
  ...
)

Arguments

Details

This function returns human-readable size based upon numeric input. Alternatively, when input is any other R object, it calls utils::object.size() to produce a single numeric value which is then used to produce human-readable size.

The default behavior is to report computer size in bytes, where 1024 is considered "kilo", however argument kiloSize can be used to produce values where kiloSize=1000 which is suitable for monetary and other scientific values.

Value

character vector representing human-friendly size, based upon the kiloSize argument to determine whether to report byte (1024) or scientific (1000) units.

See Also

Other jam string functions: breaksByVector(), fillBlanks(), formatInt(), gsubOrdered(), gsubs(), makeNames(), nameVector(), nameVectorN(), padInteger(), padString(), pasteByRow(), pasteByRowOrdered(), sizeAsNum(), tcount(), ucfirst()

Examples

asSize(c(1, 10,2010,22000,52200))
#> "1 byte"   "10 bytes" "2 kb"     "21 kb"    "51 kb"

# demonstration of straight numeric units
asSize(c(1, 100, 1000, 10000), unitType="", kiloSize=100)

Description

Calculate more detailed density of numeric values

Usage

breakDensity(
  x,
  breaks = length(x)/3,
  bw = NULL,
  width = NULL,
  densityBreaksFactor = 3,
  weightFactor = 1,
  addZeroEnds = TRUE,
  baseline = 0,
  floorBaseline = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

This function is a drop-in replacement for stats::density(), simply to provide a quick alternative that defaults to a higher level of detail. Detail can be adjusted using densityBreaksFactor, where higher values will use a wider step size, thus lowering the detail in the output.

Note that the density height is scaled by the total number of points, and can be adjusted with weightFactor. See Examples for how to scale the y-axis range similar to stats::density().

Value

list output equivalent to stats::density():

• x: The n coordinates of the points where the density is estimated.

• y: The estimated density values, non-negative, but can be zero.

• bw: The bandidth used.

• n: The sample size after elimination of missing values.

• call: the call which produced the result.

• data.name: the deparsed name of the x argument.

• has.na: logical for compatibility, and always FALSE.

See Also

Other jam practical functions: call_fn_ellipsis(), checkLightMode(), check_pkg_installed(), colNum2excelName(), color_dither(), exp2signed(), getAxisLabel(), isFALSEV(), isTRUEV(), jargs(), kable_coloring(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()

Examples

x <- c(stats::rnorm(15000),
   stats::rnorm(5500)*0.25 + 1,
   stats::rnorm(12500)*0.5 + 2.5)
plot(stats::density(x))

plot(breakDensity(x))

plot(breakDensity(x, densityBreaksFactor=200))

# trim values to show abrupt transitions
x2 <- x[x > 0 & x < 4]
plot(stats::density(x2), lwd=2)
lines(breakDensity(x2, weightFactor=1/length(x2)/10), col="red")
graphics::legend("topright", c("stats::density()", "breakDensity()"),
   col=c("black", "red"), lwd=c(2, 1))

Description

breaks a vector into groups

Usage

breaksByVector(x, labels = NULL, returnFractions = FALSE, ...)

Arguments

Details

This function takes a vector of values, determines "chunks" of identical values, from which it defines where breaks occur. It assumes the input vector is ordered in the way it will be displayed, with some labels being duplicated consecutively. This function defines the breakpoints where the labels change, and returns the ideal position to put a single label to represent a duplicated consecutive set of labels.

It can return fractional coordinates, for example when a label represents two consecutive items, the fractional coordinate can be used to place the label between the two items.

This function is useful for things like adding labels to imageDefault() color image map of sample groupings, where it may be ideal to label only unique elements in a contiguous set.

Value

list with the following named elements:

• "breakPoints": The mid-point coordinate between each break. These midpoints would be good for drawing dividing lines for example.

• "labelPoints": The ideal point to place a label to represent the group.

• "newLabels": A vector of labels the same length as the input data, except using blank values except where a label should be drawn. This output is good for text display.

• "useLabels": The unique set of labels, without blanks, corresponding to the coordinates supplied by labelPoints.

• "breakLengths": The integer size of each set of labels.

See Also

Other jam string functions: asSize(), fillBlanks(), formatInt(), gsubOrdered(), gsubs(), makeNames(), nameVector(), nameVectorN(), padInteger(), padString(), pasteByRow(), pasteByRowOrdered(), sizeAsNum(), tcount(), ucfirst()

Examples

b <- rep(LETTERS[c(1:5, 1)], c(2,3,5,4,3,4));
bb <- breaksByVector(b);
# Example showing how labels can be minimized inside a data.frame
data.frame(b,
   newLabels=bb$newLabels);

# Example showing how to reposition text labels
# so duplicated labels are displayed in the middle
# of each group
bb2 <- breaksByVector(b, returnFractions=TRUE);
ylabs <- c("minimal labels", "all labels");
withr::with_par(adjustAxisLabelMargins(ylabs, 2), {
   withr::local_par(adjustAxisLabelMargins(bb2$useLabels, 1))
   nullPlot(xlim=range(seq_along(b)), ylim=c(0,3),
      doBoxes=FALSE, doUsrBox=TRUE);
   graphics::axis(2, las=2, at=c(1,2), ylabs);
   graphics::text(y=2, x=seq_along(b), b);
   graphics::text(y=1, x=bb2$labelPoints, bb2$useLabels);

## Print axis labels in the center of each group
graphics::axis(3,
   las=2,
   at=bb2$labelPoints,
   labels=bb2$useLabels);

## indicate each region
for (i in seq_along(bb2$breakPoints)) {
   graphics::axis(1,
      at=c(c(0, bb2$breakPoints)[i]+0.8, bb2$breakPoints[i]+0.2),
      labels=c("", ""));
}
## place the label centered in each region without adding tick marks
graphics::axis(1,
   las=2,
   tick=FALSE,
   at=bb2$labelPoints,
   labels=bb2$useLabels);
## abline to indicate the boundaries, if needed
graphics::abline(v=c(0, bb2$breakPoints) + 0.5,
   lty="dashed",
   col="blue");

})
# The same process is used by imageByColors()

Description

Safely call a function using ellipsis

Usage

call_fn_ellipsis(FUN, ...)

Arguments

Details

This function is a wrapper function intended to help pass ellipsis arguments ... from a parent function to an external function in a safe way. It will only include arguments from ... that are recognized by the external function.

The logic is described as follows:

• When the external function FUN arguments formals() include ellipsis ..., then the ellipsis ... will be passed as-is without change. In this way, any arguments inside the original ellipsis ... will either match arguments in FUN, or will be ignored in that function ellipsis ....

• When the external function FUN arguments formals() do not include ellipsis ..., then named arguments in ... are passed to FUN only when the arguments names are recognized by FUN.

Note that arguments therefore must be named.

Value

output from FUN() when called with relevant named arguments from ellipsis ...

See Also

Other jam practical functions: breakDensity(), checkLightMode(), check_pkg_installed(), colNum2excelName(), color_dither(), exp2signed(), getAxisLabel(), isFALSEV(), isTRUEV(), jargs(), kable_coloring(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()

Examples

new_mean <- function(x, trim=0, na.rm=FALSE) {
   mean(x, trim=trim, na.rm=na.rm)
}
x <- c(1, 3, 5, NA);
new_mean(x, na.rm=TRUE);
# throws an error as expected (below)
tryCatch({
   new_mean(x, na.rm=TRUE, color="red")
}, error=function(e){
   print("Error is expected, shown below:");
   print(e)
})

call_fn_ellipsis(new_mean, x=x, na.rm=TRUE, color="red")

Description

ComplexHeatmap cell function to label heatmap cells

Usage

cell_fun_label(
  m,
  prefix = "",
  suffix = "",
  cex = 1,
  col_hm = NULL,
  outline = FALSE,
  abbrev = FALSE,
  show = NULL,
  rot = 0,
  sep = "\n",
  verbose = FALSE,
  ...
)

Arguments

Details

This function serves as a convenient method to add text labels to each cell in a heatmap produced by ComplexHeatmap::Heatmap(), via the argument cell_fun.

Note that this function requires re-using the specific color function used for the heatmap in the call to ComplexHeatmap::Heatmap().

This function is slightly unique in that it allows multiple labels, if m is supplied as a list of matrix objects. In fact, some matrix objects may contain character values with custom labels.

Cell labels are colored based upon the heatmap cell color, which is passed to jamba::setTextContrastColor() to determine whether to use light or dark text color for optimum contrast.

TODO: Option to supply a logical matrix to define a subset of cells to label, for example only labels that meet a filter criteria. Alternatively, the matrix data supplied in m can already be filtered.

TODO: Allow some matrix values that contain character data to use gridtext for custom markdown formatting. That process requires a slightly different method.

Value

function sufficient to use as input to ComplexHeatmap::Heatmap() argument cell_fun.

See Also

Other jam heatmap functions: heatmap_column_order(), heatmap_row_order()

Examples

m <- matrix(stats::rnorm(16)*2, ncol=4)
colnames(m) <- LETTERS[1:4]
rownames(m) <- letters[1:4]
col_hm <- circlize::colorRamp2(breaks=(-2:2) * 2,
   colors=c("navy", "dodgerblue", "white", "tomato", "red4"))

# the heatmap can be created in one step
hm <- ComplexHeatmap::Heatmap(m,
   col=col_hm,
   heatmap_legend_param=list(
      color_bar="discrete",
      border=TRUE,
      at=-4:4),
   cell_fun=cell_fun_label(m,
      col_hm=col_hm))
ComplexHeatmap::draw(hm)

# the cell label function can be created first
cell_fun <- cell_fun_label(m,
   outline=TRUE,
   cex=1.5,
   col_hm=col_hm)
hm2 <- ComplexHeatmap::Heatmap(m,
   col=col_hm,
   cell_fun=cell_fun)
ComplexHeatmap::draw(hm2)

Description

Lightweight method to check if an R package is installed

Usage

check_pkg_installed(x, ...)

Arguments

Details

There are many methods to test for an installed package, this function represents possibly the most gentle and rapid approach. It simply calls system.file(package=""), which checks in the context of the active R session and uses the relevant .libPaths().

This approach does not use require() because that actually loads the package, which can take time and resources.

This approach also does not use installed.packages() which can also take substantial time if many packages are installed on a system.

Value

logical indicating whether each value in x represents an installed R package.

See Also

Other jam practical functions: breakDensity(), call_fn_ellipsis(), checkLightMode(), colNum2excelName(), color_dither(), exp2signed(), getAxisLabel(), isFALSEV(), isTRUEV(), jargs(), kable_coloring(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()

Examples

check_pkg_installed("methods")

check_pkg_installed(c("jamba",
   "multienrichjam",
   "venndir",
   "methods",
   "blah"))

Description

check lightMode for light background color

Usage

checkLightMode(lightMode = NULL, ...)

Arguments

Details

Check the lightMode status through function parameter, options, or environment variable. If the function defines lightMode, it is used as-is. If lightMode is NULL, then options("jam.lightMode") is used if defined. Otherwise, it tries to detect whether the R session is running inside Rstudio using the environmental variable "RSTUDIO", and if so it assumes lightMode==TRUE.

To set a default lightMode, add options("jam.lightMode"=TRUE) to .Rprofile, or to the relevant R script.

Value

logical or length=1, indicating whether lightMode is defined

See Also

Other jam practical functions: breakDensity(), call_fn_ellipsis(), check_pkg_installed(), colNum2excelName(), color_dither(), exp2signed(), getAxisLabel(), isFALSEV(), isTRUEV(), jargs(), kable_coloring(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()

Examples

checkLightMode(TRUE);
checkLightMode();

Description

Return the alpha transparency per R color

Usage

col2alpha(x, maxValue = 1, ...)

Arguments

Value

numeric vector of alpha values

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

col2alpha(c("red", "#99004499", "beige", "transparent", "#FFFFFF00"))

Description

convert R color to HCL color matrix

Usage

col2hcl(
  x,
  maxColorValue = 255,
  model = getOption("jam.model", c("hcl", "polarLUV", "polarLAB")),
  ...
)

Arguments

Details

This function takes an R color and converts to an HCL matrix, using the colorspace package, and RGB and polarLUV functions. It is also used to maintain alpha transparency, to enable interconversion via other color manipulation functions as well.

When model="hcl" this function uses farver::decode_colour() and bypasses colorspace. In future the colorspace dependency will likely be removed in favor of using farver. In any event, model="hcl" is equivalent to using model="polarLUV" and fixup=TRUE, except that it should be much faster.

Value

numeric matrix with H, C, L values.

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

col2hcl("#FF000044")

Description

convert R color to HSL color matrix

Usage

col2hsl(x, ...)

Arguments

Details

This function takes an R color and converts to an HSL matrix, using the farver package farver::decode_colour() the colorspace package, and RGB and polarLUV functions. It is also used to maintain alpha transparency, to enable interconversion via other color manipulation functions as well.

When model="hsl" this function uses farver::decode_colour() and bypasses colorspace. In future the colorspace dependency will likely be removed in favor of using farver. In any event, model="hsl" is equivalent to using model="polarLUV" and fixup=TRUE, except that it should be much faster.

Value

numeric matrix of H, S, L color values.

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

x <- c("#FF000044", "#FF0000", "firebrick");
names(x) <- x;
showColors(x)
xhsl <- col2hsl(x)
xhsl

xhex <- hsl2col(xhsl)
showColors(list(x=x,
   xhex=xhex),
   groupCellnotes=FALSE)

withr::with_par(list("mfrow"=c(4, 4), "mar"=c(0.2, 1, 4, 1)), {

for (H in seq(from=0, to=360, length.out=17)[-17]) {
S <- 75;
Lseq <- seq(from=15, to=95, by=10);
hsl_gradient <- hsl2col(
   H=H,
   S=85,
   L=Lseq);
hcl_gradient <- hcl2col(
   H=H,
   C=85,
   L=Lseq);
names(hsl_gradient) <- Lseq;
names(hcl_gradient) <- Lseq;
showColors(xaxt="n",
   list(
      hsl=hsl_gradient,
      hcl=hcl_gradient),
   main=paste0("Hue: ", round(H),
      "\nSat: ", S,
      "\nLum: (as labeled)"),
   groupCellnotes=FALSE)
}
})

Description

Convert R color to HSV matrix

Usage

col2hsv(x, ...)

Arguments

Details

This function takes a valid R color and converts to a HSV matrix. The output can be effectively returned to R color with hsv2col, usually after manipulating the HSV color matrix.

Value

matrix of HSV colors

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsl(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

# start with a color vector
# red and blue with partial transparency
colorV <- c("#FF000055", "#00339999");

# confirm the hsv matrix maintains transparency
col2hsv(colorV);

# convert back to the original color
hsv2col(col2hsv(colorV));

Description

convert column number to 'Excel' column name

Usage

colNum2excelName(x, useLetters = LETTERS, zeroVal = "a", ...)

Arguments

Details

The purpose is to convert an integer column number into a valid 'Excel' column name, using LETTERS starting at A. This function implements an arbitrary number of digits, which may or may not be compatible with each version of 'Excel'. 18,278 columns would be the maximum for three digits, "A" through "ZZZ".

This function is useful when referencing 'Excel' columns via another interface such as via openxlsx. It is also used by makeNames() when the numberStyle="letters", in order to provide letter suffix values.

One can somewhat manipulate the allowed column names via the useLetters argument, which by default uses the entire 26-letter Western alphabet.

Value

character vector with length(x)

See Also

Other jam practical functions: breakDensity(), call_fn_ellipsis(), checkLightMode(), check_pkg_installed(), color_dither(), exp2signed(), getAxisLabel(), isFALSEV(), isTRUEV(), jargs(), kable_coloring(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()

Examples

colNum2excelName(1:30)

Description

Make dithered color pattern light-dark

Usage

color_dither(
  x,
  L_diff = 4,
  L_max = 90,
  L_min = 30,
  min_contrast = 1.25,
  direction = 1,
  returnType = c("vector", "list", "matrix"),
  debug = FALSE,
  ...
)

Arguments

Details

This function serves a very simple purpose, mainly for printDebug() to use subtle alternating light/dark colors for vector output. It takes a color and returns two colors which are slightly lighter and darker than each other, to a minimum contrast defined by colorspace::contrast_ratio().

Value

format defined by argument returnType:

• vector: two colors for every input color in x

• matrix: two rows, input colors on first row, output colors on second row

• list: a list with two colors in each element, with input and output colors together in each vector.

See Also

Other jam practical functions: breakDensity(), call_fn_ellipsis(), checkLightMode(), check_pkg_installed(), colNum2excelName(), exp2signed(), getAxisLabel(), isFALSEV(), isTRUEV(), jargs(), kable_coloring(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()

Examples

x <- "firebrick1";
showColors(color_dither(x))

showColors(color_dither(x, direction=-1))

x <- vigrep("^green[0-9]", grDevices::colors())
showColors(color_dither(x))
showColors(color_dither(x, direction=-1, returnType="list"))

x <- c("green1", "cyan", "blue", "red", "gold", "yellow", "pink")
showColors(color_dither(x))

color_dither(x, debug=TRUE)

Description

Make a color gradient

Usage

color2gradient(
  col,
  n = NULL,
  gradientWtFactor = NULL,
  dex = 1,
  reverseGradient = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Details

This function converts a single color into a color gradient by expanding the initial color into lighter and darker colors around the central color. The amount of gradient expansion is controlled by gradientWtFactor, which is a weight factor scaled to the maximum available range of bright to dark colors.

As an extension, the function can take a vector of colors, and expand each into its own color gradient, each with its own number of colors. If a vector with supplied that contains repeated colors, these colors are expanded in-place into a gradient, bypassing the value for n.

If a list is supplied, a list is returned of the same length, where each vector inside the list is a color gradient of length specified by n. If the input list contains multiple values, only the first color is used to define the color gradient.

Value

character vector of R colors.

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

# given a list, it returns a list
x <- color2gradient(list(Reds=c("red"), Blues=c("blue")), n=c(4,7));
showColors(x);

# given a vector, it returns a vector
xv <- color2gradient(c(red="red", blue="blue"), n=c(4,7));
showColors(xv);

# Expand colors in place
# This process is similar to color jittering
colors1 <- c("red","blue")[c(1,1,2,2,1,2,1,1)];
names(colors1) <- colors1;
colors2 <- color2gradient(colors1);
showColors(list(`Input colors`=colors1, `Output colors`=colors2));

# You can do the same using a list intermediate
colors1L <- split(colors1, colors1);
showColors(colors1L);
colors2L <- color2gradient(colors1L);
showColors(colors2L);

# comparison of fixed gradientWtFactor with dynamic gradientWtFactor
showColors(list(
   `dynamic\ngradientWtFactor\ndex=1`=color2gradient(
      c("yellow", "navy", "firebrick", "orange"),
      n=3,
      gradientWtFactor=NULL,
      dex=1),
   `dynamic\ngradientWtFactor\ndex=2`=color2gradient(
      c("yellow", "navy", "firebrick", "orange"),
      n=3,
      gradientWtFactor=NULL,
      dex=2),
   `fixed\ngradientWtFactor=2/3`=color2gradient(
      c("yellow", "navy", "firebrick", "orange"),
      n=3,
      gradientWtFactor=2/3,
      dex=1)
))

Description

Process coordinate adjustment presets

Usage

coordPresets(
  preset = "default",
  x = 0,
  y = 0,
  adjPreset = "default",
  adjX = 0.5,
  adjY = 0.5,
  adjOffsetX = 0,
  adjOffsetY = 0,
  preset_type = c("plot"),
  verbose = FALSE,
  ...
)

Arguments

Details

This function is intended to be a convenient way to define coordinates using preset terms like "topleft", "bottom", "center".

Similarly, it is intended to help define corresponding text adjustments, using adj compatible with graphics::text(), using preset terms like "bottomright", "center".

When preset is "default", the original ⁠x,y⁠ coordinates are used. Otherwise the ⁠x,y⁠ coordinates are defined using the plot region coordinates, where "left" uses graphics::par("usr")[1], and "top" uses graphics::par("usr")[4].

When adjPreset is "default" it will use the preset to define a reciprocal text placement. For example when preset="topright" the text placement will be equivalent to adjPreset="bottomleft". The adjPreset terms "top", "bottom", "right", "left", and "center" refer to the text label placement relative to ⁠x,y⁠ coordinate.

If both preset="default" and adjPreset="default" the original ⁠adjX,adjY⁠ values are returned.

The function is vectorized, and uses the longest input argument, so one can supply a vector of preset and it will return coordinates and adjustments of length equal to the input preset vector. The preset value takes priority over the supplied ⁠x,y⁠ coordinates.

Value

data.frame after adjustment, where the number of rows is determined by the longest input argument, with colnames:

• x

• y

• adjX

• adjY

• preset

• adjPreset

See Also

Other jam plot functions: adjustAxisLabelMargins(), decideMfrow(), drawLabels(), getPlotAspect(), groupedAxis(), imageByColors(), imageDefault(), minorLogTicksAxis(), nullPlot(), plotPolygonDensity(), plotRidges(), plotSmoothScatter(), shadowText(), shadowText_options(), showColors(), sqrtAxis(), usrBox()

Examples

# determine coordinates
presetV <- c("top",
   "bottom",
   "left",
   "right",
   "topleft");
cp1 <- coordPresets(preset=presetV);
cp1;

# make sure to prepare the plot region first
jamba::nullPlot(plotAreaTitle="");
graphics::points(cp1$x, cp1$y, pch=20, cex=2, col="red");

# unfortunately graphics::text() does not have vectorized adj
# so it must iterate each row
graphics::title(main="graphics::text() is not vectorized, text is adjacent to edges")
for (i in seq_along(presetV)) {
   graphics::text(cp1$x[i], cp1$y[i],
      labels=presetV[i],
      adj=c(cp1$adjX[i], cp1$adjY[i]));
}

# drawLabels() will be vectorized for unique adj subsets
# and adds a small buffer around text
jamba::nullPlot(plotAreaTitle="");
graphics::title(main="drawLabels() is vectorized, includes small buffer")
drawLabels(txt=presetV,
   preset=presetV)

jamba::nullPlot(plotAreaTitle="");
graphics::title(main="drawLabels() can place labels outside plot edges")
drawLabels(txt=presetV,
   preset=presetV,
   adjPreset=presetV)

# drawLabels() is vectorized for example
jamba::nullPlot(plotAreaTitle="");
graphics::title(main="Use adjPreset to position labels at a center point")
presetV2 <- c("topleft",
   "topright",
   "bottomleft",
   "bottomright");
cp2 <- coordPresets(preset="center",
   adjPreset=presetV2,
   adjOffsetX=0.1,
   adjOffsetY=0.4);
graphics::points(cp2$x,
   cp2$y,
   pch=20,
   cex=2,
   col="red");
drawLabels(x=cp2$x,
   y=cp2$y,
   adjX=cp2$adjX,
   adjY=cp2$adjY,
   txt=presetV2,
   boxCexAdjust=c(1.15,1.6),
   labelCex=1.3,
   lx=rep(1.5, 4),
   ly=rep(1.5, 4))

# demonstrate margin coordinates
withr::with_par(list("oma"=c(1, 1, 1, 1)), {
nullPlot(xlim=c(0, 1), ylim=c(1, 5));
cpxy <- coordPresets(rep(c("top", "bottom", "left", "right"), each=2),
   preset_type=rep(c("plot", "figure"), 4));
drawLabels(preset=c("top", "top"),
   txt=c("top label relative to figure",
      "top label relative to plot"),
   preset_type=c("figure", "plot"))
graphics::points(cpxy$x, cpxy$y, cex=2,
   col="red4", bg="red1", xpd=NA,
   pch=rep(c(21, 23), 4))
})

Description

Paste a list of vectors into a character vector, with values delimited by default with a comma.

Usage

cPaste(
  x,
  sep = ",",
  doSort = FALSE,
  makeUnique = FALSE,
  na.rm = FALSE,
  keepFactors = FALSE,
  checkClass = TRUE,
  useBioc = TRUE,
  useLegacy = FALSE,
  honorFactor = TRUE,
  verbose = FALSE,
  ...
)

cPasteS(
  x,
  sep = ",",
  doSort = TRUE,
  makeUnique = FALSE,
  na.rm = FALSE,
  keepFactors = FALSE,
  checkClass = TRUE,
  useBioc = TRUE,
  ...
)

cPasteSU(
  x,
  sep = ",",
  doSort = TRUE,
  makeUnique = TRUE,
  na.rm = FALSE,
  keepFactors = FALSE,
  checkClass = TRUE,
  useBioc = TRUE,
  ...
)

cPasteUnique(
  x,
  sep = ",",
  doSort = FALSE,
  makeUnique = TRUE,
  na.rm = FALSE,
  keepFactors = FALSE,
  checkClass = TRUE,
  useBioc = TRUE,
  ...
)

cPasteU(
  x,
  sep = ",",
  doSort = FALSE,
  makeUnique = TRUE,
  na.rm = FALSE,
  keepFactors = FALSE,
  checkClass = TRUE,
  useBioc = TRUE,
  ...
)

Arguments

Details

• cPaste() concatenates vector values using a delimiter.

• cPasteS() sorts each vector using mixedSort().

• cPasteU() applies uniques() to retain unique values per vector.

• cPasteSU() applies mixedSort() and uniques().

This function is essentially a wrapper for S4Vectors::unstrsplit() except that it also optionally applies uniqueness to each vector in the list, and sorts values in each vector using mixedOrder().

The sorting and uniqueness is applied to the unlisted vector of values, which is substantially faster than any apply family function equivalent. The uniqueness is performed by uniques(), which itself will use S4Vectors::unique() if available.

Value

character vector with the same names and in the same order as the input list x.

See Also

Other jam list functions: heads(), jam_rapply(), list2df(), mergeAllXY(), mixedSorts(), rbindList(), relist_named(), rlengths(), sclass(), sdim(), uniques(), unnestList()

Examples

L1 <- list(CA=LETTERS[c(1:4,2,7,4,6)], B=letters[c(7:11,9,3)]);

cPaste(L1);
#               CA                 B
# "A,B,C,D,B,G,D,F"   "g,h,i,j,k,i,c"

cPaste(L1, doSort=TRUE);
#               CA                 B
# "A,B,B,C,D,D,F,G"   "c,g,h,i,i,j,k"

## The sort can be done with convenience function cPasteS()
cPasteS(L1);
#               CA                 B
# "A,B,B,C,D,D,F,G"   "c,g,h,i,i,j,k"

## Similarly, makeUnique=TRUE and cPasteU() are the same
cPaste(L1, makeUnique=TRUE);
cPasteU(L1);
#           CA             B
# "A,B,C,D,G,F" "g,h,i,j,k,c"

## Change the delimiter
cPasteSU(L1, sep="; ")
#                CA                  B
# "A; B; C; D; F; G" "c; g; h; i; j; k"

# test mix of factor and non-factor
L2 <- c(
   list(D=factor(letters[1:12],
      levels=letters[12:1])),
   L1);
L2;
cPasteSU(L2, keepFactors=TRUE);

# tricky example with mix of character and factor
# and factor levels are inconsistent
# end result: factor levels are defined in order they appear
L <- list(entryA=c("miR-112", "miR-12", "miR-112"),
   entryB=factor(c("A","B","A","B"),
      levels=c("B","A")),
   entryC=factor(c("C","A","B","B","C"),
      levels=c("A","B","C")),
   entryNULL=NULL)
L;
cPaste(L);
cPasteU(L);

# by default keepFactors=FALSE, which means factors are sorted as characters
cPasteS(L);
cPasteSU(L);
# keepFactors=TRUE will keep unique factor levels in the order they appear
# this is the same behavior as unlist(L[c(2,3)]) on a list of factors
cPasteSU(L, keepFactors=TRUE);
levels(unlist(L[c(2,3)]))

Description

convert date to age in days

Usage

dateToDaysOld(testDate, nowDate = Sys.Date(), units = "days", ...)

Arguments

Value

integer value with the number of calendar days before the current date, or the nowDate if supplied.

See Also

Other jam date functions: asDate(), getDate()

Examples

dateToDaysOld("23aug2007")

Description

Decide plot panel rows, columns for graphics::par(mfrow)

Usage

decideMfrow(
  n,
  method = c("aspect", "wide", "tall"),
  doTest = FALSE,
  xyratio = 1,
  trimExtra = TRUE,
  ...
)

Arguments

Details

This function returns the recommended rows and columns of panels to be used in graphics::par("mfrow") with R base plotting. It attempts to use the device size and plot aspect ratio to keep panels roughly square. For example, a short-wide device would have more columns of panels than rows; a tall-thin device would have more rows than columns.

The doTest=TRUE argument will create n number of panels with the recommended layout, as a visual example.

Note this function calls getPlotAspect(), therefore if no plot device is currently open, the call to graphics::par() will open a new graphics device.

Value

numeric vector length=2, with the recommended number of plot rows and columns, respectively. It is intended to be used directly in this form: graphics::par("mfrow"=decideMfrow(n=5))

See Also

Other jam plot functions: adjustAxisLabelMargins(), coordPresets(), drawLabels(), getPlotAspect(), groupedAxis(), imageByColors(), imageDefault(), minorLogTicksAxis(), nullPlot(), plotPolygonDensity(), plotRidges(), plotSmoothScatter(), shadowText(), shadowText_options(), showColors(), sqrtAxis(), usrBox()

Examples

# display a test visualization showing 6 panels
withr::with_par(list("mar"=c(2, 2, 2, 2)), {
decideMfrow(n=6, doTest=TRUE);
})

# use a custom target xyratio of plot panels
withr::with_par(list("mar"=c(2, 2, 2, 2)), {
decideMfrow(n=3, xyratio=3, doTest=TRUE);
})

# a manual demonstration creating 6 panels
n <- 6;
withr::with_par(list(
   "mar"=c(2, 2, 2, 2),
   "mfrow"=decideMfrow(n)), {
for(i in seq_len(n)){
   nullPlot(plotAreaTitle=paste("Plot", i));
}
})

Description

Convert degrees to radians

Usage

deg2rad(x, ...)

Arguments

Details

This function simply converts degrees which range from 0 to 360, into radians which range from zero to pi*2.

Value

numeric vector after coverting degrees to radians.

See Also

Other jam numeric functions: noiseFloor(), normScale(), rad2deg(), rowGroupMeans(), rowRmMadOutliers(), warpAroundZero()

Examples

deg2rad(rad2deg(c(pi*2, pi/2)))/pi;

Description

Draw text labels on a base R plot

Usage

drawLabels(
  txt = NULL,
  newCoords = NULL,
  x = NULL,
  y = NULL,
  lx = NULL,
  ly = NULL,
  segmentLwd = 1,
  segmentCol = "#00000088",
  drawSegments = TRUE,
  boxBorderColor = "#000000AA",
  boxColor = "#FFEECC",
  boxLwd = 1,
  drawBox = TRUE,
  drawLabels = TRUE,
  font = 1,
  labelCex = 0.8,
  boxCexAdjust = 1.9,
  labelCol = alpha2col(alpha = 0.8, setTextContrastColor(boxColor)),
  doPlot = TRUE,
  xpd = NA,
  preset = "default",
  adjPreset = "default",
  preset_type = "plot",
  adjX = 0.5,
  adjY = 0.5,
  panelWidth = "default",
  trimReturns = TRUE,
  text_fn = getOption("jam.text_fn", graphics::text),
  verbose = FALSE,
  ...
)

Arguments

Details

This function takes a vector of coordinates and text labels, and draws the labels with colored rectangles around each label on the plot. Each label can have unique font, cex, and color, and are drawn using vectorized operations.

To enable shadow text include argument: text_fn=jamba::shadowText

TODO: In future allow rotated text labels. Not that useful within a plot panel, but sometimes useful when draw outside a plot, for example axis labels.

Value

invisible data.frame containing label coordinates used to draw labels. This data.frame can be manipulated and provided as input to drawLabels() for subsequent customized label positioning.

See Also

Other jam plot functions: adjustAxisLabelMargins(), coordPresets(), decideMfrow(), getPlotAspect(), groupedAxis(), imageByColors(), imageDefault(), minorLogTicksAxis(), nullPlot(), plotPolygonDensity(), plotRidges(), plotSmoothScatter(), shadowText(), shadowText_options(), showColors(), sqrtAxis(), usrBox()

Examples

nullPlot(plotAreaTitle="");
dl_topleft <- drawLabels(x=graphics::par("usr")[1],
   y=graphics::par("usr")[4],
   txt="Top-left\nof plot",
   preset="topleft",
   boxColor="blue4");

drawLabels(x=graphics::par("usr")[2],
   y=graphics::par("usr")[3],
   txt="Bottom-right\nof plot",
   preset="bottomright",
   boxColor="green4");

drawLabels(x=mean(graphics::par("usr")[1:2]),
   y=mean(graphics::par("usr")[3:4]),
   txt="Center\nof plot",
   preset="center",
   boxColor="purple3");

graphics::points(x=c(graphics::par("usr")[1], graphics::par("usr")[2],
      mean(graphics::par("usr")[1:2])),
   y=c(graphics::par("usr")[4], graphics::par("usr")[3],
      mean(graphics::par("usr")[3:4])),
   pch=20,
   col="red",
   xpd=NA);

nullPlot(plotAreaTitle="");
graphics::title(main="place label across the full top plot panel", line=2.5)
dl_top <- drawLabels(
   txt=c("preset='topright', adjPreset='topright', \npanelWidth='force'",
      "preset='topright',\nadjPreset='bottomleft'",
      "preset='bottomleft', adjPreset='topright',\npanelWidth='force'"),
   preset=c("topright", "topright", "bottomleft"),
   adjPreset=c("topleft", "bottomleft", "topright"),
   panelWidth=c("force", "none", "force"),
   boxColor=c("red4",
      "blue4",
      "purple3"));
graphics::box(lwd=2);

withr::with_par(list("mfrow"=c(1, 3), "xpd"=TRUE), {

isub <- c(force="Always full panel width",
   minimum="At least full panel width or larger",
   maximum="No larger than panel width");
for (i in c("force", "minimum", "maximum")) {
nullPlot(plotAreaTitle="", doMargins=FALSE);
graphics::title(main=paste0("panelWidth='", i, "'\n",
   isub[i]));
drawLabels(labelCex=1.2,
   txt=c("Super-wide title across the top\npanelWidth='force'",
   "bottom label"),
   preset=c("top", "bottom"),
   panelWidth=i,
   boxColor="red4")
}
})

Description

exponentiate log2 values with directionality

Usage

exp2signed(x, offset = 1, base = 2, ...)

Arguments

Details

This function is the reciprocal to log2signed().

It #' exponentiates the absolute values of x, then subtracts the offset, then multiplies results by the sign(x).

The offset is typically used to maintain directionality of values during log transformation by requiring all absolute values to be 1 or larger, thus by default offset=1.

Value

numeric vector of exponentiated values.

See Also

Other jam practical functions: breakDensity(), call_fn_ellipsis(), checkLightMode(), check_pkg_installed(), colNum2excelName(), color_dither(), getAxisLabel(), isFALSEV(), isTRUEV(), jargs(), kable_coloring(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()

Examples

x <- c(-100:100)/10;
z <- log2signed(x);
#plot(x=x, y=z, xlab="x", ylab="log2signed(x)")
plot(x=x, y=exp2signed(z), xlab="x", ylab="exp2signed(log2signed(x))")
plot(x=z, y=exp2signed(z), xlab="log2signed(x)", ylab="exp2signed(log2signed(x))")

Description

Fill blank entries in a vector

Usage

fillBlanks(x, blankGrep = c("[ \t]*"), first = "", ...)

Arguments

Details

This function takes a character vector and fills any blank (missing) entries with the last non-blank entry in the vector. It is intended for situations like imported 'Excel' data, where there may be one header value representing a series of cells.

The method used does not loop through the data, and should scale fairly well with good efficiency even for extremely large vectors.

Value

character vector where blank entries are filled with the most recent non-blank value.

See Also

Other jam string functions: asSize(), breaksByVector(), formatInt(), gsubOrdered(), gsubs(), makeNames(), nameVector(), nameVectorN(), padInteger(), padString(), pasteByRow(), pasteByRowOrdered(), sizeAsNum(), tcount(), ucfirst()

Examples

x <- c("A", "", "", "", "B", "C", "", "", NA,
   "D", "", "", "E", "F", "G", "", "");
data.frame(x, fillBlanks(x));

Description

Fix yellow color to be less green than default "yellow"

Usage

fixYellow(col, Hrange = c(70, 100), Hshift = -20, fixup = TRUE, ...)

Arguments

Details

This function "fixes" the color yellow, which by default appears green especially when darkened. The effect of this function is to make yellows appear more red, which appears more visibly yellow even when the color is darkened.

This function is intended to be tolerant to missing values. For example if any of the values col, Hrange, or Hshift are length 0, the original col is returned unchanged.

Value

returns a vector of R colors the same length as input col. In the event col, Hrange, or Hshift have length 0, or if any step in the conversion produces length 0, then the original col is returned.

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

yellows <- vigrep("yellow", grDevices::colors());
fixedYellows <- fixYellow(yellows);
showColors(list(yellows=yellows,
   fixedYellows=fixedYellows));

Description

Fix yellow color hue to be less green than default "yellow"

Usage

fixYellowHue(HCL, Hrange = c(80, 90), Hshift = -15, ...)

Arguments

Details

This function "fixes" the color yellow, which by default appears green especially when darkened. The effect of this function is to make yellows appear more red, which appears more visibly yellow even when the color is darkened.

This function is intended to be tolerant to missing values. For example if any of the values HCL, Hrange, or Hshift are length 0, the original HCL is returned unchanged.

Value

returns the input HCL data where rowname "H" has hue values adjusted accordingly. In the event HCL, Hrange, or Hshift have length 0, the original HCL is returned. If input data does not meet the expected format, the input HCL is returned unchanged.

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), getColorRamp(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()

Examples

yellows <- vigrep("yellow", grDevices::colors());
yellowsHCL <- col2hcl(yellows);
fixedYellowsHCL <- fixYellowHue(yellowsHCL);
fixedYellows <- hcl2col(fixedYellowsHCL);
showColors(list(yellows=yellows,
   fixedYellows=fixedYellows));

Description

Format an integer as a string

Usage

formatInt(
  x,
  big.mark = ",",
  trim = TRUE,
  forceInteger = TRUE,
  scientific = FALSE,
  ...
)

Arguments

Details

This function is a quick wrapper function around base::format() to display integer values as text strings. It will also return a matrix if the input is a matrix.

Value

character vector if x is a vector, or if x is a matrix a matrix will be returned.

See Also

Other jam string functions: asSize(), breaksByVector(), fillBlanks(), gsubOrdered(), gsubs(), makeNames(), nameVector(), nameVectorN(), padInteger(), padString(), pasteByRow(), pasteByRowOrdered(), sizeAsNum(), tcount(), ucfirst()

Examples

x <- c(1234, 1234.56, 1234567.89);
## By default, commas are used for big.mark, and decimal values are hidden
formatInt(x);

## By default, commas are used for big.mark
formatInt(x, forceInteger=FALSE);

Description

Get axis label for minorLogTicks

Usage

getAxisLabel(
  i,
  asValues,
  logAxisType = c("normal", "flip", "pvalue"),
  logBase,
  base_limit = 2,
  offset = 0,
  symmetricZero = (offset > 0),
  ...
)

Arguments

Details

This function is intended to be called internally by jamba::minorLogTicks().

Value

character or expression axis label as appropriate.

See Also

Other jam practical functions: breakDensity(), call_fn_ellipsis(), checkLightMode(), check_pkg_installed(), colNum2excelName(), color_dither(), exp2signed(), isFALSEV(), isTRUEV(), jargs(), kable_coloring(), lldf(), log2signed(), middle(), minorLogTicks(), newestFile(), printDebug(), reload_rmarkdown_cache(), renameColumn(), rmInfinite(), rmNA(), rmNAs(), rmNULL(), setPrompt()

Examples

x <- log10(c(1, 2, 5, 10, 20, 50, 100, 200, 500))
getAxisLabel(x, asValues=TRUE, logBase=10)

x1exp <- c(1, 2, 3, 4, 5)
plot(1:6, main="exponential values")
for (i in seq_along(x1exp)) {
   text(x=i, y=i + 0.2,
      getAxisLabel(x1exp[i], asValues=FALSE, logBase=10))
}

x1exp <- c(-3:3)
plot(-3:3, main="log2 fold change values")
for (i in seq_along(x1exp)) {
   text(x=i, y=i + 0.3 - 4,
      getAxisLabel(x1exp[i],
         logAxisType="flip",
         asValues=TRUE, logBase=2))
}

x1exp <- c(1, 2, 3, 4, 5)
plot(1:6, main="P-value style")
for (i in seq_along(x1exp)) {
   text(x=i, y=i + 0.2,
      getAxisLabel(x1exp[i],
      logAxisType="pvalue", asValues=FALSE, logBase=10))
}

Description

get color ramp by name, color, or function

Usage

getColorRamp(
  col,
  n = 15,
  trimRamp = c(0, 0),
  gradientN = 15,
  defaultBaseColor = "grey99",
  reverseRamp = FALSE,
  alpha = TRUE,
  gradientWtFactor = NULL,
  dex = 1,
  lens = 0,
  divergent = NULL,
  verbose = FALSE,
  ...
)

Arguments

Details

This function accepts a color ramp name, a single color, a vector of colors, or a function names, and returns a simple vector of colors of the appropriate length, suitable as input to a number of plotting functions.

When n is NULL, this function returns a color function, wrapped by grDevices::colorRampPalette(). The colors used are defined by gradientN, so the grDevices::colorRampPalette() function actually uses a starting palette of gradientN number of colors.

When n is an integer greater than 0, this function returns a vector of colors with length n.

When col is a single color value, a color gradient is created by appending defaultColorBase to the output of color2gradient(..., n=3, gradientWtFactor=gradientWtFactor). These 4 colors are used as the internal palette before applying grDevices::colorRampPalette() as appropriate. In this case, gradientWtFactor is used to adjust the strength of the color gradient. The intended use is: getColorRamp("red", n=5). To remove the leading white color, use getColorRamp("red", n=5, trimRamp=c(1,0)).

When col contains multiple color values, they are used to define a color ramp directly.

When col is not a color value, it is compared to known color palettes from RColorBrewer::RColorBrewer and viridisLite, and will use the corresponding color function or color palette.

When col refers to a color palette, the suffix "_r" may be used to reverse the colors. For example, getColorRamp(col="RdBu_r", n=9) will recognize the RColorBrewer color palette "RdBu", and will reverse the colors to return blue to red, more suitable for heatmaps where high values associated with heat are colored red, and low values associated with cold are colored blue.

The argument reverseRamp=TRUE may be used to reverse the returned colors.

Color functions from viridisLite are recognized: "viridis", "cividis", "inferno", "magma", "plasma".

The argument trimRamp is used to trim colors from the beginning and end of a color ramp, respectively. This mechanism is useful to remove the first or last color when those colors may be too extreme. Note that internally, colors are expanded to length gradientN, then trimmed, then the corresponding n colors are returned.

The trimRamp argument is also useful when returning a color function, which occurs when n=NULL. In this case, colors are expanded to length gradientN, then are trimmed using the values from trimRamp, then the returned function can be used to create a color ramp of arbitrary length.

Note that when reverseRamp=TRUE, colors are reversed before trimRamp is applied.

By default, alpha transparency will be maintained if supplied in the input color vector. Most color ramps have no transparency, in which case transparency can be added after the fact using alpha2col().

Value

character vector of R colors, or when N is NULL, function sufficient to create R colors.

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), hcl2col(), hsl2col(), hsv2col(), isColor(), kable_coloring(), makeColorDarker(), rainbow2(), rgb2col(), setCLranges(), setTextContrastColor(), showColors(), unalpha(), warpRamp()