annotation_transparent_text: Layer for Transparent Text
In plothelper: New Plots Based on 'ggplot2' and Functions to Create Regular Shapes

Description Usage Arguments Details Examples

View source: R/annotation_transparent_text.R

Suppose there is a colored rectangle with some texts and you want the texts to be transparent so that the colors of the background can be seen. Now you can use this function. The function can be used as a ggplot layer or a generator of image. NOTE: when the function is used as a layer, it uses ggplot2::annotation_raster to do the drawing, so you must set limits for the x axis and the y axis. See examples.

annotation_transparent_text(
  label,
  xmin,
  xmax,
  ymin,
  ymax,
  bg = "black",
  alpha = 0.5,
  operator = "out",
  interpolate = TRUE,
  result_interpolate = TRUE,
  expand = c(0.05, 0.05),
  family = "SimHei",
  fontface = 1,
  reflow = FALSE,
  place = "center",
  label_trim = NULL,
  bg_trim = NULL,
  result = c("layer", "magick"),
  width = 800,
  height = NULL,
  res = 72,
  ...
)

`label`	the text.
`xmin`	the left side of the rectangle.
`xmax`	the right side of the rectangle.
`ymin`	the bottom side of the rectangle.
`ymax`	the top side of the rectangle.
`bg`	the colors of the rectangle. It can be a character vector of colors, a matrix of colors, an object of raster class or even a image read into R through `magick::image_read`. Default is color black.
`alpha`	it is only used when `bg` is a character vector. Default is 0.5.
`operator`	the argument used by `magick::image_composite`. It should be "out" (default) or "in". The former makes the texts transparent, the latter creates shading texts.
`interpolate`	when `bg` is a matrix, a image or a raster, this parameter is used and will be passed to `ggplot2::annotation_raster` to draw a colored rectangle. Default is TRUE.
`result_interpolate`	whether to use interpolate in the final result. Default is TRUE.
`expand`	sometimes it is needed to slightly expand the x position and y position to put the text so that they can be shown nicely. It should be two values used by x and y respectively. Default is 0.05 and 0.05.
`family`	family of text. Default is SimHei which ensures that Chinese texts can be shown. However, you can change it to others, e. g., sans, serif, mono.
`fontface`	fontface.
`reflow`	whether to change lines automatically. It will be passed to `ggfittext::geom_fit_text`. Default is FALSE.
`place`	position adjustment used by `ggfittext:;geom_fit_text`. The value is one of "center", "middle" (= "center"), "topleft", "top", "topright", "right", "bottomright", "bottom", "bottomleft", "left".
`label_trim`	whether to trim `label`. The default is NULL which means no trimming. But if you want to remove all edges around label, you should give `label_trim` a value which will be passed to `magick::image_trim`. However, most of the time you do not need this parameter.
`bg_trim`	whether to trim `bg`. Most of the time we do want to trim it. However, the `magick::image_trim` function sometimes trims wrongly. So you can turn it off. NOTE: the default value of `bg_trim` is NULL, which means DO NOT TRIM.
`result`	when it is "layer", the function can be used as a ggplot layer. When it is "magick", the result is only an image which is created by the magick package.
`width`	the width of the text rectangle. It will be passed to `magick::image_graph`. Most of the time you do not need to modify this. Default is 800.
`height`	the height of the text rectangle. It will be passed to `magick::image_graph`. Default is NULL, which means it will be computed automatically. DO SEE Details below to learn how to handle this parameter.
`res`	resolution in pixels which will be passed to `magick::image_graph`. Default is 72.
`...`	arguments which will be passed to `ggfittex::geom_fit_text`. Most often used are `angle` (0 to 360), `lineheight`.

height can be used in the following ways:

(1) an integer which will be directly passed to magick::image_graph.
(2) a character-like integer, e.g., height = "0.5". Suppose width = 400, the height that will be used is 400*0.5 = 200. This effectively prevents the image from becoming too large.
(3) height = "coord_fixed". the ratio between height and width will be (ymax-ymin)/(xmax-xmin).
(4) height = "image". the width and height will be the width and height of bg when the latter is a magick object.
(5) height = NULL, the default. Now height is computed automatically. If bg is a magick object, the width and height of the image will be used. If bg is not a magick object, a ratio is computed first, ratio = (ymax-ymin)/(xmax-xmin). if the ratio is larger than 5 or smaller than 0.2, then height will be width*5 or width*0.2; else, the height will be treated in the same way as in (3) above. All these works are needed to prevent the image from becoming too large.

# Example 1
m=matrix(rainbow(7), nrow=1)
ggplot()+coord_fixed()+
	xlim(0, 7)+ylim(-2, 4)+theme_void()+
	annotation_raster(
		raster=m, 
		xmin=0, ymin=-3, 
		xmax=7, ymax=5, 
		interpolate=TRUE
	)+
	annotation_transparent_text(
		label="R\nDATA\nVISUALIZATION", 
		xmin=0, xmax=7, 
		ymin=-1, ymax=3, 
		family="sans", fontface=2, alpha=0.8, 
		place="left", expand=c(0.08, 0.02)
	)
# 
# Example 2, this time the result is only an image.
tt=annotation_transparent_text(
	label="abcdefg", 
	xmin=1, xmax=8, 
	ymin=1, ymax=4, 
	alpha=0.6, 
	result="magick"
)
#
# Example 3, the rectangle is a matrix.
m=colorRampPalette(c("yellow", "purple"))(10)
ggplot()+coord_fixed(expand=FALSE)+
	theme(panel.background=element_rect(fill="red"))+
	annotation_transparent_text(
		label="hehehaha", 
		xmin=1, xmax=8, 
		ymin=1, ymax=4, 
		bg=m, alpha=1
	)
#
# Example 4, height is too large.
# Now you should explicitly set 
# width and height, otherwise, the 
# characters will become too flat.
x=c(0, 5, 10)
y=c(0, 500, 1000)
ggplot()+ylim(0, 4000)+
	geom_point(aes(x, y))+
	annotation_transparent_text(label="ha ha\nhe he", 
		xmin=0, xmax=10, ymin=1000, ymax=4000, bg="black", 
		width=300, height=150
	) # do not set height=NULL here