Title:	Just Analysis Methods Base
Version:	1.0.4
Description:	Just analysis methods ('jam') base functions focused on bioinformatics. Version- and gene-centric alphanumeric sort, unique name and version assignment, colorized console and 'HTML' output, color ramp and palette manipulation, 'Rmarkdown' cache import, styled 'Excel' worksheet import and export, interpolated raster output from smooth scatter and image plots, list to delimited vector, efficient list tools.
Depends:	R (≥ 3.0.0)
Imports:	methods, grDevices, graphics, stats, utils, colorspace, RColorBrewer, KernSmooth, withr
Suggests:	crayon, farver, knitr, rmarkdown, testthat (≥ 3.0.0)
Enhances:	ggplot2, ggridges, IRanges, S4Vectors, openxlsx, kableExtra, matrixStats, viridisLite, ComplexHeatmap, circlize, GenomicRanges, igraph, pryr, rstudioapi, Matrix, sparseMatrixStats
License:	MIT + file LICENSE
Encoding:	UTF-8
URL:	https://jmw86069.github.io/jamba/
BugReports:	https://github.com/jmw86069/jamba/issues
VignetteBuilder:	knitr
RoxygenNote:	7.3.2
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2025-03-23 06:31:56 UTC; wardjm
Author:	James M. Ward [aut, cre, cph]
Maintainer:	James M. Ward <jmw86069@gmail.com>
Repository:	CRAN
Date/Publication:	2025-03-23 16:30:02 UTC

jamba: Jam Base Methods

Description

The jamba package contains several jam base functions which are re-usable for routine R analysis work, and are important dependencies for other Jam R packages.

Details

See the function reference for a complete list of functions.

The goal is to implement methods as lightweight as possible, so so inclusion in an analysis workflow will not incur a noticeable burden.

plot functions

• plotSmoothScatter() smoothScatter() enhanced for more visual detail

• imageDefault() enhanced rasterized image() with fixed aspect ratio

• imageByColors() for data.frame of colors and optional labels centered across repeated values.

• showColors() color display for vector, list, color function, or mixed formats.

• nullPlot() blank plot that labels the current margin sizes

• minorLogTicksAxis() log-scale axis ticks in base R with custom log base, optional offset, e.g. log2(1 + x)

• shadowText() base R text labels with shadow or outline or both, also shadowText_options().

• getPlotAspect(), decideMfrow() convenience base R graphics.

string functions

• mixedSort(), mixedOrder(), mixedSortDF() - efficient alphanumeric "version" sort, with options helpful for gene symbols.

• vgrep(), vigrep(), igrep(), vigrep() fast grep wrappers for value-return, case-insensitive search.

• provigrep(), proigrep() - progressive, ordered grep to use pattern matching to re-order a vector.

• makeNames() create unique, versioned names with custom format

• nameVector() apply names to vector dynamically

• nameVectorN() vector of named names useful with lapply().

• pasteByRow(), pasteByRowOrdered() paste data.frame and matrix values by row, skipping blanks, optional factor order.

• rbindList() convert list to matrix or data.frame.

• tcount() extends table() to sort by size and optional minimum count filter.

color functions

• rgb2col(), col2hcl(), col2hcl(), col2hsv(), hsv2col() color interconversion

• setTextContrastColor() text contrast color per given background color

• getColorRamp() catch-all to get named gradients, or expand one or more colors to gradient.

• makeColorDarker(), color2gradient(), showColors() color manipulation and display

miscellaneous helper functions

• printDebug() colored text output to console, 'Rmarkdown', HTML

• kable_coloring() colored kableExtra::kable() output for 'Rmarkdown'

• setPrompt() colored R prompt

• deg2rad(), rad2deg() interconvert degrees to radians.

• getDate(), asDate(), dateToDaysOld() human-readable, opinionated date formatting

• padString(), padInteger() pad character or integer strings

• rmNA(), rmNULL(), rmInfinite() remove or replace missing or NA values with defined alternatives

export and import functions

• readOpenxlsx() import worksheets from 'xlsx' 'Excel' files.

• writeOpenxlsx() export worksheets to 'xlsx' 'Excel' files with color, formatting, and styling.

Jam options

The jamba package recognizes some global options, but limits these options to include only non-analysis options. For example, no global option should change the numerical manipulation of data.

• jam.lightMode - logical whether the R console or graphical background is light or dark, printDebug() limits the luminance range to maximize visual contrast.

• jam.Crange,jam.Lrange - numerical values used by printDebug() to maximize visual contrast, used with jam.lightMode.

• jam.shadowColor,jam.shadow.r,jam.shadow.n,jam.alphaShadow, jam.outline,jam.alphaOutline to customize details for shadowText(), see shadowText_options() for convenience.

Author(s)

Maintainer: James M. Ward jmw86069@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://jmw86069.github.io/jamba/

• Report bugs at https://github.com/jmw86069/jamba/issues

Adjust axis label margins

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")

set R color alpha value

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));
}
})

Apply CL color range

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);

Add categorical colors to 'Excel' 'xlsx' worksheets

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
   )
}

Xlsx Conditional formatting

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")
   )
}

convert date DDmmmYYYY to Date

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());

convert numeric value or R object to human-readable size

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)

Calculate more detailed density of numeric values

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))

break a vector into groups

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()

paste a list into a delimited vector

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)]))

Safely call a function using ellipsis

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")

ComplexHeatmap cell function to label heatmap cells

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)

check lightMode for light background color

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();

Lightweight method to check if an R package is installed

Description

Lightweight method to check if an R package is installed

Usage

check_pkg_installed(x, useMethod = c("packagedir", "requireNamespace"), ...)

Arguments

Details

There are many methods to test for an installed package. Most approaches incur some time or resource penalty, so check_pkg_installed() is motivated for rapid results without loading the package namespace.

This function also accepts multiple values for x for convenience.

There are two available methods defined by useMethod:

1. useMethod="packagedir" confirms: this function represents possibly the most gentle and rapid approach. It simply calls system.file(package=x), for each entry of x, then checks these requirements:

   • Does the package directory exist via system.file(package=x)

   • Does the package directory contain the file 'DESCRIPTION'?

   • It does not check whether the package can be loaded into the current R session.

2. useMethod="requireNamespace" confirms:

   • requireNamespace(x, quietly=TRUE) returns TRUE

   • It therefore loads the package namespace to confirm, but does not attach the package to the current session. It therefore may take time and resources, despite not altering the R environment search path.

The default behavior first tests by "packagedir", then for any FALSE results it also tests "requireNamespace".

Value

logical vector indicating whether each value in x represents an installed R package. The vector is named by packages provided in x.

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"))

get R color alpha value

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"))

convert R color to HCL color matrix

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")

convert R color to HSL color matrix

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)
}
})

Convert R color to HSV matrix

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));

convert column number to 'Excel' column name

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)

Make a color gradient

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)
))

Make dithered color pattern light-dark

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)

Process coordinate adjustment presets

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))
})

convert date to age in days

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")

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

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));
}
})

Convert degrees to radians

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;

Draw text labels on a base R plot

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")
}
})

exponentiate log2 values with directionality

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))")

Fill blank entries in a vector

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));

Fix yellow color

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));

Fix yellow color hue

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));

Format an integer as a string

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);

Get axis label for minorLogTicks

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))
}

get color ramp by name, color, or function

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()

Examples

# get a gradient using red4
red4 <- getColorRamp("red4");
showColors(getColorRamp(red4));

# make a custom gradient
BuOr <- getColorRamp(c("dodgerblue","grey10","orange"));
showColors(BuOr);
colorList <- list(red4=red4, BuOr=BuOr);

# From RColorBrewer use a brewer name
RdBu <- getColorRamp("RdBu");
RdBu_r <- getColorRamp("RdBu_r");
colorList <- c(colorList, list(RdBu=RdBu, RdBu_r=RdBu_r));
showColors(RdBu);

if (requireNamespace("viridisLite", quietly=TRUE)) {
   viridisV <- getColorRamp("viridis");
   colorList <- c(colorList, list(viridis=viridisV));
}

# for fun, put a few color ramps onto one plot
showColors(colorList, cexCellnote=0.7);

showColors(list(`white background\ncolor='red'`=getColorRamp("red"),
   `black background\ncolor='red'`=getColorRamp("red", defaultBaseColor="black"),
   `white background\ncolor='gold'`=getColorRamp("gold"),
   `black background\ncolor='gold'`=getColorRamp("gold", defaultBaseColor="black")))

get simple date string

Description

get simple date string in the format DDmonYYYY such as 17jul2018.

Usage

getDate(t = Sys.time(), trim = TRUE, dateFormat = "%d%b%Y", ...)

Arguments

Details

Gets the current date in a simplified text string. Use asDate() to convert back to Date object.

Value

character vector with simplified date string

See Also

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

Examples

getDate();

Get aspect ratio for coordinates, plot, or device

Description

Get aspect ratio for coordinates, plot, or device

Usage

getPlotAspect(
  type = c("coords", "plot", "device"),
  parUsr = graphics::par("usr"),
  parPin = graphics::par("pin"),
  parDin = graphics::par("din"),
  ...
)

Arguments

Value

numeric plot aspect ratio for a plot device, of the requested type, see the type argument.

See Also

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

Examples

withr::with_par(list("mfrow"=c(2, 4), "mar"=c(1, 1, 1, 1)), {
for (i in 1:8) {
   nullPlot(plotAreaTitle=paste("Plot", i), xlim=c(1,100), ylim=c(1,10),
      doMargins=FALSE);
   graphics::axis(1, las=2);
   graphics::axis(2, las=2);
}
# device aspect inside the 2x4 layout
getPlotAspect("plot");
})
# device aspect outside the 2x4 layout
getPlotAspect("plot");

Search for objects in the environment

Description

Search for objects in the environment

Usage

grepls(
  x,
  where = "all",
  ignore.case = TRUE,
  searchNames = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Details

This function searches the active R environment for an object name using vigrep() (value, case-insensitive grep). It is helpful when trying to find an object using a substring, for example grepls("statshits").

Value

character vector of matching object names, or if where="all" it returns a named list whose names indicate the search environment name, and whose entries are matching object names within each environment.

See Also

Other jam grep functions: igrep(), igrepHas(), igrepl(), provigrep(), unigrep(), unvigrep(), vgrep(), vigrep()

Examples

# Find all objects named "grep", which should find
# base grep() and jamba::vigrep() among other results.
grepls("grep");

# Find objects in the local environment
allStatsHits <- c(1:12);
someStatsHits <- c(1:3);
grepls("statshits");
# shortcut way to search only the .GlobalEnv, the active local environment
grepls("statshits", 1);

# return objects with "raw" in the name
grepls("raw");

# Require "Raw" to be case-sensitive
grepls("Raw", ignore.case=FALSE)

Draw grouped axis labels

Description

Draw grouped axis labels given a character vector.

Usage

groupedAxis(
  side = 1,
  x,
  group_style = c("partial_grouped", "grouped", "centered"),
  las = 2,
  returnFractions = TRUE,
  nudge = 0.2,
  do_abline = FALSE,
  abline_lty = "solid",
  abline_col = "grey40",
  do_plot = TRUE,
  ...
)

Arguments

Details

This function extends breaksByVector() specifically for axis labels. It is intended where character labels are spaced at integer steps, and some labels are expected to be repeated.

Value

data.frame invisibly, which contains the relevant axis coordinates, labels, and whether the coordinate should appear with a tick mark.

See Also

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

Examples

withr::with_par(list("mar"=c(4,4,6,6)), {
b <- rep(LETTERS[1:5], c(2,3,5,4,3));
b2 <- c(b[1:2], makeNames(b[3:5]), b[6:16]);
nullPlot(doBoxes=FALSE,
   doUsrBox=TRUE,
   xlim=c(0,18),
   ylim=c(0,18));

groupedAxis(1, b);
groupedAxis(2, b, group_style="grouped");
groupedAxis(2, b, group_style="centered");
groupedAxis(3, b2, do_abline=TRUE);
groupedAxis(4, b2, group_style="grouped");
graphics::mtext(side=1, "group_style='partial_grouped'", line=2, las=0);
graphics::mtext(side=2, "group_style='grouped'", line=2, las=0);
graphics::mtext(side=3, "group_style='partial_grouped'", line=2, las=0);
graphics::mtext(side=4, "group_style='grouped'", line=2, las=0);
})

Global substitution into ordered factor

Description

Global substitution into ordered factor

Usage

gsubOrdered(
  pattern,
  replacement,
  x,
  ignore.case = FALSE,
  perl = FALSE,
  fixed = FALSE,
  useBytes = FALSE,
  sortFunc = mixedSort,
  ...
)

Arguments

Details

This function is an extension of base::gsub() that returns an ordered factor output. When input is also a factor, the output factor levels are retained in the same order, after applying the string substitution.

This function is very useful when making changes via base::gsub() to a factor with ordered levels, because it retains the the order of levels after modification.

Tips:

• To convert a character vector to a factor, whose levels are sorted, use sortFunc=sort.

• To convert a character vector to a factor, whose levels are the order they appear in the input x, use sortFunc=c.

• To convert a character vector to a factor, whose levels are sorted alphanumerically, use sortFunc=mixedSort.

Value

factor whose levels are based upon the order of input levels when the input x is a factor; or if the input x is not a factor, it is converted to a factor using the provided sort function sortFunc.

See Also

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

Examples

x <- c(paste0(
   rep(c("first", "second", "third"), 2),
   rep(c("Section", "Choice"), each=3)),
   "Choice");
f <- factor(x, levels=x);
f;

# default gsub() will return a character vector
gsub("(first|second|third)", "", f)
# converting to factor resets the factor level order
factor(gsub("(first|second|third)", "", f))

## gsubOrdered() maintains the factor level order
gsubOrdered("(first|third)", "", f)
gsubOrdered("(first)", "", f)

# to convert character vector to factor, levels in order they appear
gsubOrdered("", "", x, sortFunc=c)

# to convert character vector to factor, levels alphanumeric sorted
gsubOrdered("", "", x, sortFunc=mixedSort)

Pattern replacement with multiple patterns

Description

Pattern replacement with multiple patterns

Usage

gsubs(
  pattern,
  replacement,
  x,
  ignore.case = TRUE,
  replaceMultiple = rep(TRUE, length(pattern)),
  ...
)

Arguments

Details

This function is a simple wrapper around base::gsub() when considering a series of pattern-replacement combinations. It applies each pattern match and replacement in order and is therefore not vectorized.

When x input is a list each vector in the list is processed, somewhat differently than processing one vector.

1. When the list contains another list, or when length(x) < 100, each value in x is iterated calling gsubs(). This process is the slowest option, however not noticeble until x has length over 10,000.

2. When the list does not contain another list and all values are non-factor, or all values are factor, they are unlisted, processed as a vector, then relisted. This process is nearly the same speed as processing one single vector, except the time it takes to confirm the list element classes.

3. When values contain a mix of non-factor and factor values, they are separately unlisted, processed by gsubs(), then relisted and combined afterward. Again, this process is only slightly slower than option 2 above, given that it calls gsubs() twice, with two vectors.

4. Note that factor values at input are replaced with character values at output, consistent with gsub().

Value

character vector when input x is an atomic vector, or list when input x is a list.

See Also

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

Examples

gsubs(c("one", "two"), c("three", "four"), "one two five six")
gsubs(c("one", "two"), c("three"), "one two five six")

Handle function arguments as text

Description

Handles a list or list of lists, converting to human-readable text format

Usage

handleArgsText(
  argTextA,
  name = "",
  col1 = "mediumpurple2",
  col2 = "mediumaquamarine",
  colT = "dodgerblue3",
  colF = "red1",
  colNULL = "grey60",
  lightMode = NULL,
  Crange = getOption("jam.Crange"),
  Lrange = getOption("jam.Lrange"),
  adjustRgb = getOption("jam.adjustRgb"),
  indent = "",
  useCollapseList = ",\n      ",
  useCollapseBase = ", ",
  level = 1,
  debug = 0,
  useColor = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Details

This function is a rare non-exported function intended to be called by jargs(), but separated in order to help isolate the logical steps required.

Value

character vector including ANSI coloring when available.

See Also

Other jam internal functions: jamCalcDensity(), make_html_styles(), make_styles(), smoothScatterJam()

Examples

cat(paste0(handleArgsText(formals(graphics::hist.default)), "\n"), sep="")

convert HCL to R color

Description

Convert an HCL color matrix to vector of R hex colors

Usage

hcl2col(
  x = NULL,
  H = NULL,
  C = NULL,
  L = NULL,
  ceiling = 255,
  maxColorValue = 255,
  alpha = NULL,
  fixup = TRUE,
  model = getOption("jam.model", c("hcl", "polarLUV", "polarLAB")),
  verbose = FALSE,
  ...
)

Arguments

Details

This function takes an HCL matrix,and converts to an R color using the colorspace package colorspace::polarLUV() and colorspace::hex().

When model="hcl" this function uses farver::encode_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

vector of R colors, or where the input was NA, then NA values are returned in the same order.

See Also

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

Examples

# Prepare a basic HCL matrix
hclM <- col2hcl(c(red="red",
   blue="blue",
   yellow="yellow",
   orange="#FFAA0066"));
hclM;

# Now convert back to R hex colors
colorV <- hcl2col(hclM);
colorV;

showColors(colorV);

Apply head() across each element in a list of vectors

Description

Apply head() across each element in a list of vectors

Usage

heads(x, n = 6, ...)

Arguments

Details

Note that this function currently only operates on a list of vectors. This function is notably faster than lapply(x, head, n) because it operates on the entire vector in one step.

Also the input n can be a vector so that each element in the list has a specific number of items returned.

Value

list with at most n elements per vector.

See Also

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

Examples

l <- list(a=1:10, b=2:5, c=NULL, d=1:100);
heads(l, 1);

heads(l, 2);

heads(l, n=c(2, 1, 3, 5))

Return Heatmap column order from ComplexHeatmap heatmap object

Description

Return Heatmap column order from ComplexHeatmap heatmap object

Usage

heatmap_column_order(hm, which_heatmap = NULL)

Arguments

Details

This function is a helpful utility to return the fully qualified list of colnames in a ComplexHeatmap::Heatmap object.

The core intention is for the output to be usable with the original data matrix used in the heatmap. Therefore, the vector values are colnames() when present, or integer column index values when there are no colnames(). If heatmap column_labels are defined, they are returned as names().

Note that names() are assigned inside try() to allow the case where column_labels, or column_title labels cannot be coerced to character values, for example using gridtext for markdown formatting.

Value

output depends upon the heatmap:

• When heatmap columns are grouped using column_split, and when the data matrix contains colnames, returns a character vector of colnames in the order they appear in the heatmap. When there are no colnames, integer column index values are returned. If the heatmap has column labels, they are returned as vector names.

• When columns are grouped using column_split, it returns a list of vectors as described above. The list is named using the column_title labels only when there is an equal number of column labels.

See Also

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

Examples

if (check_pkg_installed("ComplexHeatmap")) {
   set.seed(123);

   mat <- matrix(stats::rnorm(18 * 24),
      ncol=24);
   rownames(mat) <- paste0("row", seq_len(18))
   colnames(mat) <- paste0("column", seq_len(24))

   # obtaining row order first causes a warning message
   hm1 <- ComplexHeatmap::Heatmap(mat);

   # best practice is to draw() and store output in an object
   # to ensure the row orders are absolutely fixed
   hm1_drawn <- ComplexHeatmap::draw(hm1);
   print(heatmap_row_order(hm1_drawn))
   print(heatmap_column_order(hm1_drawn))

   # row and column split
   hm1_split <- ComplexHeatmap::Heatmap(mat,
      column_split=3, row_split=3, border=TRUE);
   hm1_split_drawn <- ComplexHeatmap::draw(hm1_split);
   print(heatmap_row_order(hm1_split_drawn))
   print(heatmap_column_order(hm1_split_drawn))

   # display two heatmaps side-by-side
   mat2 <- mat + stats::rnorm(18*24);
   hm2 <- ComplexHeatmap::Heatmap(mat2, border=TRUE, row_split=4);

   hm1hm2_drawn <- ComplexHeatmap::draw(hm1_split + hm2,
      ht_gap=grid::unit(1, "cm"));
   print(heatmap_row_order(hm1hm2_drawn))
   print(heatmap_row_order(hm1hm2_drawn, which_heatmap=2))
   # by default the order uses the first heatmap
   print(heatmap_column_order(hm1hm2_drawn))
   # the second heatmap can be returned
   print(heatmap_column_order(hm1hm2_drawn, which_heatmap=2))
   # or a list of heatmap orders can be returned
   print(heatmap_column_order(hm1hm2_drawn, which_heatmap=1:2))

   # stacked vertical heatmaps
   hm1hm2_drawn_tall <- ComplexHeatmap::draw(
      ComplexHeatmap::`%v%`(hm1_split, hm2),
      ht_gap=grid::unit(1, "cm"));
   print(heatmap_row_order(hm1hm2_drawn))
   print(heatmap_row_order(hm1hm2_drawn, which_heatmap=2))
   print(heatmap_row_order(hm1hm2_drawn, which_heatmap=1:2))
   print(heatmap_row_order(hm1hm2_drawn,
      which_heatmap=names(hm1hm2_drawn@ht_list)))

   # annotation heatmap
   ha <- ComplexHeatmap::rowAnnotation(left=rownames(mat))
   ha_drawn <- ComplexHeatmap::draw(ha + hm1)
   print(sdim(ha_drawn@ht_list))
   print(heatmap_row_order(ha_drawn))
   print(heatmap_column_order(ha_drawn))

   # stacked vertical heatmaps with top annotation
   ta <- ComplexHeatmap::HeatmapAnnotation(top=colnames(mat))
   hm1_ha <- ComplexHeatmap::Heatmap(mat,
      left_annotation=ha,
      column_split=3, row_split=3, border=TRUE);
   hm1hm2_drawn_tall <- ComplexHeatmap::draw(
      ComplexHeatmap::`%v%`(ta,
         ComplexHeatmap::`%v%`(hm1_ha, hm2)),
      ht_gap=grid::unit(1, "cm"));
   print(sdim(hm1hm2_drawn_tall@ht_list))
   print(heatmap_row_order(hm1hm2_drawn_tall))
   print(heatmap_row_order(hm1hm2_drawn_tall, 2))
}

Return Heatmap row order from ComplexHeatmap heatmap object

Description

Return Heatmap row order from ComplexHeatmap heatmap object

Usage

heatmap_row_order(hm, which_heatmap = NULL)

Arguments

Details

This function is a helpful utility to return the fully qualified list of rownames in a ComplexHeatmap::Heatmap object.

The core intention is for the output to be usable with the original data matrix used in the heatmap. Therefore, the vector values are rownames() when present, or integer row index values when there are no rownames(). If heatmap row_labels are defined, they are returned as names().

Note that names() are assigned inside try() to allow the case where row_labels, or row_title labels cannot be coerced to character values, for example using gridtext for markdown formatting.

Final note: It is best practice to draw the heatmap first with ComplexHeatmap::draw() then store the output in a new object. This step creates the definitive clustering and therefore the row order is absolutely final, not subject to potential randomness during clustering.

Value

output depends upon the heatmap:

• When heatmap rows are grouped using row_split, and when the data matrix contains rownames, returns a character vector of rownames in the order they appear in the heatmap. When there are no rownames, integer row index values are returned. If the heatmap has row labels, they are returned as vector names.

• When rows are grouped using row_split, it returns a list of vectors as described above. The list is named using the row_title labels only when there is an equal number of row labels.

See Also

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

Examples

# See heatmap_column_order() for examples

convert HCL to R color

Description

Convert an HCL color matrix to vector of R hex colors

Usage

hsl2col(
  x = NULL,
  H = NULL,
  S = NULL,
  L = NULL,
  alpha = NULL,
  verbose = FALSE,
  ...
)

Arguments

Details

This function takes an HCL matrix,and converts to an R color using the colorspace package colorspace::polarLUV() and colorspace::hex().

When model="hcl" this function uses farver::encode_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

vector of R colors, or where the input was NA, then NA values are returned in the same order.

See Also

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

Examples

# See col2hcl() for more extensive examples

# Prepare a basic HSL matrix
x_colors <- c(red="red",
   blue="blue",
   yellow="yellow",
   orange="#FFAA0066");
hslM <- col2hsl(x_colors);
hslM;

# Now convert back to R hex colors
colorV <- hsl2col(hslM);
colorV;

showColors(list(x_colors=x_colors,
   colorV=nameVector(colorV)));

Convert HSV matrix to R color

Description

Converts a HSV color matrix to R hex color

Usage

hsv2col(hsvValue, ...)

Arguments

Details

This function augments the grDevices::hsv() function in that it handles output from grDevices::rgb2hsv() or col2hsv(), sufficient to run a series of conversion functions, e.g. hsv2col(col2hsv("red")). This function also maintains alpha transparency, which is not maintained by the grDevices::hsv() function.

Value

character vector of R colors.

See Also

Other jam color functions: alpha2col(), applyCLrange(), col2alpha(), col2hcl(), col2hsl(), col2hsv(), color2gradient(), fixYellow(), fixYellowHue(), getColorRamp(), hcl2col(), hsl2col(), 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));

case-insensitive grep

Description

case-insensitive grep

Usage

igrep(..., ignore.case = TRUE)

Arguments

Details

This function is a simple wrapper around base::grep() which runs in case-insensitive mode. It is mainly used to save keystrokes, but is consistently named alongside vgrep and vigrep.

Value

vector of matching indices

See Also

Other jam grep functions: grepls(), igrepHas(), igrepl(), provigrep(), unigrep(), unvigrep(), vgrep(), vigrep()

Examples

V <- paste0(LETTERS[1:5], LETTERS[4:8]);
igrep("D", V);
igrep("d", V);
vigrep("d", V);

vector contains any case-insensitive grep match

Description

vector contains any case-insensitive grep match

Usage

igrepHas(
  pattern,
  x = NULL,
  ignore.case = TRUE,
  minCount = 1,
  naToBlank = FALSE,
  ...
)

Arguments

Details

This function checks the input vector for any elements matching the grep pattern. The grep is performed case-insensitive (igrep). This function is particularly useful when checking function arguments or object class, where the class(a) might return multiple values, or where the name of the class might be slightly different than expected, e.g. data.frame, data_frame, DataFrame.

Value

logical indicating whether the grep match criteria were met, TRUE indicates the grep pattern was present in minCount or more number of entries.

See Also

base::grep()

Other jam grep functions: grepls(), igrep(), igrepl(), provigrep(), unigrep(), unvigrep(), vgrep(), vigrep()

Examples

a <- c("data.frame","data_frame","tibble","tbl");
igrepHas("Data.*Frame", a);
igrepHas("matrix", a);

case-insensitive logical grepl

Description

case-insensitive logical grepl

Usage

igrepl(..., ignore.case = TRUE)

Arguments

Details

This function is a simple wrapper around base::grepl() which runs in case-insensitive mode simply by adding default ignore.case=TRUE. It is mainly used for convenience.

Value

logical vector indicating pattern match

See Also

Other jam grep functions: grepls(), igrep(), igrepHas(), provigrep(), unigrep(), unvigrep(), vgrep(), vigrep()

Examples

V <- paste0(LETTERS[1:5], LETTERS[4:8]);
ig1 <- grepl("D", V);
ig2 <- igrepl("D", V);
ig3 <- grepl("d", V);
ig4 <- igrepl("d", V);
data.frame(V,
   grepl_D=ig1,
   grepl_d=ig3,
   igrepl_D=ig2,
   igrepl_d=ig4);

Display color raster image using a matrix of colors

Description

Display color raster image using a matrix of colors

Usage

imageByColors(
  x,
  useRaster = FALSE,
  fixRasterRatio = TRUE,
  maxRatioFix = 100,
  xaxt = "s",
  yaxt = "s",
  doPlot = TRUE,
  cellnote = NULL,
  cexCellnote = 1,
  srtCellnote = 0,
  fontCellnote = 1,
  groupCellnotes = TRUE,
  groupBy = c("column", "row"),
  groupByColors = TRUE,
  adjBy = c("column", "row"),
  adjustMargins = FALSE,
  interpolate = getOption("interpolate", TRUE),
  verbose = FALSE,
  xpd = NULL,
  bty = graphics::par("bty"),
  flip = c("none", "y", "x", "xy"),
  keepTextAlpha = FALSE,
  doTest = FALSE,
  add = FALSE,
  ...
)

Arguments

Details

This function is similar to image except that it takes a matrix which already has colors defined for each cell. This function calls imageDefault which enables updated use of the useRaster functionality.

Additionally, if cellnote is supplied, which contains a matrix of labels for the image cells, those labels will also be displayed. By default, labels are grouped, so that only one label is displayed whenever two or more labels appear in consecutive cells. This behavior can be disabled with groupCellnotes=FALSE.

The groupCellnotes behavior uses breaksByVector() to determine where to place consecutive labels, and it applies this logic starting with rows, then columns. Note that labels are only grouped when both the cell color and the cell label are identical for consecutive cells.

In general, if a large rectangular set of cells contains the same label, and cell colors, the resulting label will be positioned in the center. However, when the square is not symmetric, the label will be grouped only where consecutive columns contain the same groups of consecutive rows for a given label.

It is helpful to rotate labels partially to prevent overlaps, e.g. srtCellnote=10 or srtCellnote=80.

To do:

• Detect the size of the area being labeled and determine whether to rotate the label sideways.

• Detect the size of the label, compared to its bounding box, and resize the label to fit the available space.

• Optionally draw border around contiguous colored and labeled polygons. Whether to draw border based only upon color, or color and label, or just label... it may get confusing.

• Label proper contiguous polygons based upon color and label, especially when color and label are present on multiple rows and columns, but not always the same columns per row.

Value

list invisibly, with elements sufficient to create an image plot. This function is called for the byproduct of creating an image visualization.

See Also

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

Examples

a1 <- c("red4","blue")[c(1,1,2)];
b1 <- c("yellow","orange")[c(1,2,2)];
c1 <- c("purple","orange")[c(1,2,2)];
d1 <- c("purple","green4")[c(1,2,2)];
df1 <- data.frame(a=a1, b=b1, c=c1, d=d1);

# default using polygons
imageByColors(df1, cellnote=df1);

# using useRaster, edges are slightly blurred with small tables
imageByColors(df1, cellnote=df1, useRaster=TRUE);

# some text features, rotation, font size, etc
imageByColors(df1, cellnote=df1, useRaster=TRUE, adjBy="column",
   cexCellnote=list(c(1.5,1.5,1), c(1,1.5), c(1.6,1.2), c(1.6,1.5)),
   srtCellnote=list(c(90,0,0), c(0,45), c(0,0,0), c(0,90,0)));

Display a color raster image

Description

Display a color raster image

Usage

imageDefault(
  x = seq_len(nrow(z) + 1) - 0.5,
  y = seq_len(ncol(z) + 1) - 0.5,
  z,
  zlim = range(z[is.finite(z)]),
  xlim = range(x),
  ylim = range(y),
  col = grDevices::hcl.colors(12, "YlOrRd", rev = TRUE),
  add = FALSE,
  xaxs = "i",
  yaxs = "i",
  xaxt = "n",
  yaxt = "n",
  xlab,
  ylab,
  breaks,
  flip = c("none", "x", "y", "xy"),
  oldstyle = TRUE,
  useRaster = NULL,
  fixRasterRatio = TRUE,
  maxRatioFix = 10,
  minRasterMultiple = NULL,
  rasterTarget = 200,
  interpolate = getOption("interpolate", TRUE),
  verbose = FALSE,
  ...
)

Arguments

Details

This function augments the image function, in that it handles the useRaster parameter for non-symmetric data matrices, in order to minimize the distortion from image-smoothing when pixels are not square.

The function also by default creates the image map using coordinates where each integer represents the center point of one column or row of data, known in the default image function as oldstyle=TRUE. For consistency, imageDefault will only accept oldstyle=TRUE.

Value

list composed of elements suitable to call graphics::image.default().

See Also

image

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

Examples

ps <- plotSmoothScatter(doTest=TRUE)

detect valid R color

Description

detect valid R color

Usage

isColor(x, makeNamesFunc = c, ...)

Arguments

Details

This function determines whether each element in a vector is a valid R color, based upon the R color names, valid hex color format, and the word "transparent" which is valid as an R color.

Value

logical vector with length(x).

See Also

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

Examples

isColor(c("red", "blue", "beige", "#99000099", "#aa00ff", "#AAE", "bleh"))

Vectorized isFALSE

Description

Vectorized isFALSE

Usage

isFALSEV(x, ...)

Arguments

Details

This function applies three criteria to an input vector, to determine if each entry in the vector is FALSE:

1. It must be class logical.

2. It must not be NA.

3. It must evaluate as FALSE.

Value

logical vector with length matching x.

See Also

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

Examples

isFALSEV(c(TRUE, FALSE, NA, TRUE))

Vectorized isTRUE

Description

Vectorized isTRUE

Usage

isTRUEV(x, ...)

Arguments

Details

This function applies three criteria to an input vector, to determine if each entry in the vector is TRUE:

1. It must be class logical.

2. It must not be NA.

3. It must evaluate as TRUE.

Value

logical vector with length matching x.

See Also

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

Examples

isTRUEV(c(TRUE, FALSE, NA, TRUE))

Calculate scatter plot point density

Description

Calculate scatter plot point density

Usage

jamCalcDensity(x, nbin, bandwidth = NULL, range.x)

Arguments

Details

This function is called internally by plotSmoothScatter(), and is an equivalent replacement for grDevices non-exported function .smoothScatterCalcDensity(), understandably a requirement by CRAN. A package should not rely on another package hidden function.

Value

list with elements used internally by plotSmoothScatter(), with: x1, x2, fhat, bandwidth.

See Also

Other jam internal functions: handleArgsText(), make_html_styles(), make_styles(), smoothScatterJam()

Examples

sdim(jamCalcDensity(cbind(x=rnorm(1000) + 4, y=rnorm(1000) + 4), nbin=30))

Jam-specific recursive apply

Description

Jam-specific recursive apply

Usage

jam_rapply(x, FUN, how = c("unlist", "list"), ...)

Arguments

Details

This function is a very lightweight customization to base::rapply(), specifically that it does not remove NULL entries.

Value

vector or list based upon argument how.

See Also

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

Examples

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)
rapply(L, length)
jam_rapply(L, length)

L0 <- list(A=1:3, B=list(C=1:3, D=4:5, E=NULL));
rapply(L0, length)
jam_rapply(L0, length)

Show R function arguments jam-style

Description

Show R function arguments jam-style

Usage

jargs(
  x,
  grepString = NULL,
  sortVars = FALSE,
  useMessage = TRUE,
  asList = TRUE,
  useColor = TRUE,
  lightMode = NULL,
  Crange = getOption("jam.Crange"),
  Lrange = getOption("jam.Lrange"),
  adjustRgb = getOption("jam.adjustRgb"),
  useCollapseBase = ", ",
  verbose = FALSE,
  debug = 0,
  ...
)

Arguments

Details

This function displays R function arguments, organized with one argument per line, and colorized using the crayon package if installed.

Output is nicely spaced to help visual alignment of argument names and argument values.

Output can be filtered by character pattern. For example the function ComplexHeatmap::Heatmap() is amazing, and offers numerous arguments. To find arguments relevant to dendrograms, use "dend":

jargs(ComplexHeatmap::Heatmap, "dend")

NOTE: This function has edge case issues displaying complex function argument values such as nested lists and custom functions. In that case the argument name is printed as usual, and the argument value is displayed as a partial snippet of the default argument value.

Generic functions very often contain no useful parameters, making it difficult to discover required parameters without reading the function documentation from the proper dispatched function and calling package. In that case, try using jargs(functionname.default) for example compare:

jargs(barplot)

to:

jargs(barplot.default)

Value

NULL this function called for the byproduct of printing its output.

See Also

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

Examples

args(jargs)
jargs(jargs)

# retrieve parameters involving notes from imageByColors
jargs(imageByColors, "note")

Extend kableExtra colorization of 'Rmarkdown' tables

Description

Extend kableExtra colorization of 'Rmarkdown' tables

Usage

kable_coloring(
  df,
  colorSub = NULL,
  background_as_tile = TRUE,
  color_cells = TRUE,
  row_color_by = NULL,
  sep = "_",
  border_left = "1px solid #DDDDDD",
  border_right = FALSE,
  extra_css = "white-space: nowrap;",
  format = "html",
  format.args = list(trim = TRUE, big.mark = ","),
  row.names = NA,
  align = NULL,
  return_type = c("kable", "data.frame"),
  verbose = FALSE,
  ...
)

Arguments

Details

This function extends the kableExtra package, and is only available for use if the kableExtra package is installed. It is intended to allow specific color assignment of elements in a data.frame, but otherwise uses the kableExtra functions to apply those colors.

The use case is to provide colorized HTML output for 'Rmarkdown', it has not been tested with other format output.

The argument colorSub accepts:

• character vector input where names should match column values

• function that accepts column values and returns a character vector of colors of equal length

• list input where names should match colnames(df), and where each list element should contain either a character vector, or function as described above.

Value

object with class c("kableExtra", "knitr_kable") by default when return_type="kable", suitable to render inside an 'Rmarkdown' or HTML context. Or returns data.frame when return_type="data.frame".

See Also

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

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

Examples

expt_df <- data.frame(
   Sample_ID="",
   Treatment=rep(c("Vehicle", "Dex"), each=6),
   Genotype=rep(c("Wildtype", "Knockout"), each=3),
   Rep=paste0("rep", c(1:3)))
expt_df$Sample_ID <- pasteByRow(expt_df[, 2:4])

# define colors
colorSub <- c(Vehicle="palegoldenrod",
   Dex="navy",
   Wildtype="gold",
   Knockout="firebrick",
   nameVector(
      color2gradient("grey48", n=3, dex=10),
      rep("rep", 3),
      suffix=""),
   nameVector(
      color2gradient(n=3,
         c("goldenrod1", "indianred3", "royalblue3", "darkorchid4")),
      expt_df$Sample_ID))
kbl <- kable_coloring(
   expt_df,
   caption="Experiment design table showing categorical color assignment.",
   colorSub)
# Note that the HTML table is rendered in 'Rmarkdown', not pkgdown
kbl

# return_type="data.frame" is a data.frame with HTML contents
kdf3 <- kable_coloring(
   return_type="data.frame",
   df=expt_df,
   colorSub=colorSub)
kdf3;

Convert list of vectors to data.frame with item, value, name

Description

Convert list of vectors to data.frame with item, value, name

Usage

list2df(x, makeUnique = TRUE, useVectorNames = TRUE, ...)

Arguments

Details

This function converts a list of vectors to a tall data.frame with colnames item to indicate the list name, value to indicate the vector value, and name to indicate the vector name if useVectorNames=TRUE and if names exist.

Value

data.frame with two columns, or three columns when useVectorNames=TRUE and the input x contains names.

See Also

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

Examples

list2df(list(lower=head(letters, 5), UPPER=head(LETTERS, 10)))

list2df(list(lower=nameVector(head(letters, 5)),
   UPPER=nameVector(head(LETTERS, 10))))

list2df(list(lower=nameVector(head(letters, 5)),
   UPPER=nameVector(head(LETTERS, 10))),
   useVectorNames=FALSE)

Long listing of R session objects

Description

Long listing of R session objects

Usage

lldf(
  n = Inf,
  envir = -1L,
  items = NULL,
  use_utils_objectsize = TRUE,
  all.names = TRUE,
  ...
)

Arguments

Details

This function expands base::ls() by also determining the object size, and sorting to display the top n objects by size, largest first.

This package will call pryr::object_size if available, otherwise falls back to utils::object.size().

Value

data.frame with summary of objects and object sizes, sorted by decreasing object size.

See Also

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

Examples

lldf(10);

# custom environment
newenv <- new.env();
newenv$A <- 1:10;
newenv$df <- data.frame(A=1:10, B=11:20);
lldf(envir=newenv);
rm(newenv);

log2 transformation with directionality

Description

log2 transformation with directionality

Usage

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

Arguments

Details

This function applies a log2 transformation but maintains the sign of the input data, allowing for log2 transformation of negative values.

The method applies an offset to the absolute value abs(x), in order to handle values between zero and 1, then applies log2 transformation, then multiplies by the original sign from sign(x).

The argument offset is used to adjust values, for example offset=1 will apply log2 transformation log2(1 + x), except using the absolute value of x. This method allows for positive and negative input data to contain values between 0 and 1, and between -1 and 0.

This function could be described as applying a log2 transformation of the "magnitude" of values in x, while maintaining the positive or negative directionality.

If any abs(x) are less than offset this function will raise an error.

Value

numeric vector of log-transformed magnitudes.

See Also

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

Examples

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

make R colors darker (or lighter)

Description

Makes R colors darker or lighter based upon darkFactor

Usage

makeColorDarker(
  hexColor,
  darkFactor = 2,
  sFactor = 1,
  fixAlpha = NULL,
  verbose = FALSE,
  keepNA = FALSE,
  useMethod = 1,
  ...
)

Arguments

Details

This function was originally intended to create border colors, or to create slightly darker colors used for labels. It is also useful for for making colors lighter, in adjusting color saturation up or down, or applying alpha transparency during the same step.

Note when colors are brightened beyond value=1, the saturation is gradually reduced in order to produce a visibly lighter color. The saturation minimu is set to 0.2, to maintain at least some amount of color.

Value

character vector of R colors.

See Also

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

Examples

colorV <- c("red","orange","purple","blue");
colorVdark2 <- makeColorDarker(colorV, darkFactor=2);
colorVlite2 <- makeColorDarker(colorV, darkFactor=-2);
showColors(cexCellnote=0.7,
   list(
   `darkFactor=2`=colorVdark2,
   `original colors`=colorV,
   `darkFactor=-2`=colorVlite2
   ));

# these adjustments work really well inside a network diagram
# when coloring nodes, and providing an outline of comparable
# color.
plot(x=c(1,2,1,2), y=c(1,2,2,1), pch=21,
   xaxt="n", yaxt="n", xlab="", ylab="",
   xlim=c(0.5,2.5), ylim=c(0.5,2.5),
   bg=colorV, col=colorVdark2, cex=4, lwd=2);
graphics::points(x=c(1,2,1,2), y=c(1,2,2,1), pch=20, cex=4,
   col=colorVlite2);

# Making a color lighter can make it easier to add labels
# The setTextContrastColor() function also helps.
graphics::text(x=c(1,2,1,2), y=c(1,2,2,1), 1:4,
   col=setTextContrastColor(colorVlite2));

make unique vector names

Description

make unique vector names

Usage

makeNames(
  x,
  unique = TRUE,
  suffix = "_v",
  renameOnes = FALSE,
  doPadInteger = FALSE,
  startN = 1,
  numberStyle = c("number", "letters", "LETTERS"),
  useNchar = NULL,
  renameFirst = TRUE,
  keepNA = TRUE,
  ...
)

Arguments

Details

This function extends the basic goal from make.names which is intended to make syntactically valid names from a character vector. This makeNames function makes names unique, and offers configurable methods to handle duplicate names. By default, any duplicated entries receive a suffix _v# where # is s running count of entries observed, starting at 1. The make.names function, by contrast, renames the second observed entry starting at .1, leaving the original entry unchanged. Optionally, makeNames can rename all entries with a numeric suffix, for consistency.

For example: A, A, A, B, B, C becomes: A_v1, A_v2, A_v3, B_v1, B_v2, C

Also, makeNames always allows "_".

This makeNames function is similar to make.unique which also converts a vector into a unique vector by adding suffix values, however the make.unique function intends to allow repeated operations which recognize duplicated entries and continually increment the suffix number. This makeNames function currently does not handle repeat operations. The recommended approach to workaround having pre-existing versioned names would be to remove suffix values prior to running this function. One small distinction from make.unique is that makeNames does version the first entry in a set.

Value

character vector of unique names

See Also

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

Examples

V <- rep(LETTERS[1:3], c(2,3,1));
makeNames(V);
makeNames(V, renameOnes=TRUE);
makeNames(V, renameFirst=FALSE);
exons <- makeNames(rep("exon", 3), suffix="");
makeNames(rep(exons, c(2,3,1)), numberStyle="letters", suffix="");

vectorized make_styles for html span output

Description

vectorized make_styles for html span output

Usage

make_html_styles(
  style = NULL,
  text,
  bg = FALSE,
  bg_style = NULL,
  grey = FALSE,
  Cgrey = getOption("jam.Cgrey"),
  lightMode = NULL,
  Crange = getOption("jam.Crange"),
  Lrange = getOption("jam.Lrange"),
  adjustRgb = getOption("jam.adjustRgb"),
  adjustPower = 1.5,
  fixYellow = TRUE,
  alphaPower = 2,
  setOptions = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

Note this function is experimental.

Value

character vector with the same length as text input vector, where entries are surrounded by the relevant HTML consistent with the style defined at input. In short, a character vector as input, colorized HTML character vector as output.

See Also

Other jam internal functions: handleArgsText(), jamCalcDensity(), make_styles(), smoothScatterJam()

Examples

make_html_styles(style=c("red", "orange"), text=c("one ", "two"))

vectorized make_styles for crayon output

Description

vectorized make_styles for crayon output

Usage

make_styles(
  style = NULL,
  text,
  bg = FALSE,
  bg_style = NULL,
  grey = FALSE,
  colors = NULL,
  Cgrey = getOption("jam.Cgrey", 5),
  lightMode = NULL,
  Crange = getOption("jam.Crange"),
  Lrange = getOption("jam.Lrange"),
  adjustRgb = getOption("jam.adjustRgb"),
  adjustPower = 1.5,
  fixYellow = TRUE,
  colorTransparent = "grey45",
  alphaPower = 2,
  setOptions = c("ifnull", "FALSE", "TRUE"),
  verbose = FALSE,
  ...
)

Arguments

Details

This function is essentially a vectorized version of crayon::make_style() in order to style a vector of character strings with a vector of foreground and background styles.

Value

character vector with the same length as text input vector, where entries are surrounded by the relevant encoding consistent with the style defined at input. In short, a character vector as input, a colorized character vector as output.

See Also

Other jam internal functions: handleArgsText(), jamCalcDensity(), make_html_styles(), smoothScatterJam()

Examples

cat(make_styles(style=c("red", "yellow"), text=c("one ", "two")), "\n")

Merge list of data.frames retaining all rows

Description

Merge list of data.frames retaining all rows

Usage

mergeAllXY(...)

Arguments

Details

This function is a wrapper around base::merge.data.frame() except that it allows more than two data.frame objects, and applies default arguments all.x=TRUE and all.y=TRUE for each merge operation to ensure that all rows are kept.

Value

data.frame after iterative calls to base::merge.data.frame().

See Also

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

Examples

df1 <- data.frame(City=c("New York", "Los Angeles", "San Francisco"),
   State=c("New York", "California", "California"))
df2 <- data.frame(Team=c("Yankees", "Mets", "Giants", "Dodgers"),
   City=c("New York", "New York", "San Francisco", "Los Angeles"))
df3 <- data.frame(State=c("New York", "California"),
   `State Population`=c(39.24e9, 8.468e9),
   check.names=FALSE)
mergeAllXY(df1, df3, df2)

df4 <- data.frame(check.names=FALSE,
   CellLine=rep(c("ul3", "dH1A", "dH1B"), each=2),
   Treatment=c("Vehicle", "Dex"))
df4$CellLine <- factor(df4$CellLine,
   levels=c("ul3", "dH1A", "dH1B"))
df4$Treatment <- factor(df4$Treatment,
   levels=c("Vehicle", "Dex"))
df5 <- data.frame(
   Treatment=rep(c("Vehicle", "Dex"), each=3),
   Time=c("0h", "12h", "24h"))
df6 <- data.frame(check.names=FALSE,
   CellLine=c("ul3", "dH1A", "dH1B"),
   Type=c("Control", "KO", "KO"))
mergeAllXY(df4, df5, df6)

# note the factor order is maintained
mergeAllXY(df4, df5, df6)$CellLine
mergeAllXY(df4, df5)$Treatment

# merge "all" can append rows to a data.frame
df4b <- data.frame(check.names=FALSE,
   CellLine=rep("dH1C", 2),
   Treatment=c("Vehicle", "Dex"))
mergeAllXY(df4, df4b)

# factor order is maintained, new levels are appended
mergeAllXY(df4, df4b)$CellLine

# merge proceeds except shows missing data
mergeAllXY(df4, df4b, df5, df6)

# note that appending rows is tricky, the following is incorrect
df6b <- data.frame(check.names=FALSE,
   CellLine="dH1C",
   Type="KO")
mergeAllXY(df4, df4b, df5, df6, df6b)

# but it can be resolved by merging df6 and df6b
mergeAllXY(df4, df4b, df5, mergeAllXY(df6, df6b))

# it may be easier to recognize by sorting with mixedSortDF()
mixedSortDF(honorFactor=TRUE,
   mergeAllXY(df4, df4b, df5, mergeAllXY(df6, df6b)))

# again, factor order is maintained
mergeAllXY(df4, df4b, df5, sort=FALSE, mergeAllXY(df6, df6b))$CellLine

# the result can be sorted properly
mixedSortDF(honorFactor=TRUE,
   mergeAllXY(df4, df4b, df5, mergeAllXY(df6, df6b)))

Return the middle portion of data similar to head and tail