geom_body: Add normal body map to your 'humap'
In benskov/humapr: Visualise Topographic Human Data

Description Usage Arguments Details Value

Use this function to draw a choropleth on a human body map.

geom_body(
  mapping = NULL,
  data = NULL,
  body_halves = NULL,
  annotate = "freq",
  bridge_side = NULL,
  bridge_loc = NULL,
  combine = NULL,
  controls = NULL,
  type = "simple",
  proj = "neutral",
  stat = "count",
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE,
  ...
)

`mapping`	`aes()` object, just like other `ggplot2` functions, with two aesthetics: `loc` is the name of the data frame column containing localisation codes for observations; and `side` the column holding the laterality data (must be either "left" or "right, but see `bridge_side`). It is possible to supply a `fill` argument to use pre-computed summary statistics (see below).
`data`	data frame, like the type you'd feed into `ggplot()` when producing a histogram. Is expected to be tidy, but can contain a summary statistic; in that case, you must specify a `fill` aesthetic and set `stat = "identity"` in the call to the `geom`.
`body_halves`	character string defining how to deal with body halves. `"separate"` (default with side aesthetic) discriminates the left half from the right; `"join"` (default without side aesthetic) merges observations in, e.g., right and left side of the chest.
`annotate`	`"freq"` (defaults) shows only absolute and relative frequencies, `"all"` includes region names, and `NA` omits labels altogether. See Details for ways to fine-tune the apperance of annotations.
`bridge_side`	named list, specyfing the bridge from your laterality values for each of the native values of `geom_body`, e.g. `list(left = c("left", "l"), right = c("right", "r"), mid = c("mid", "m"))`. The `mid` element is only required if mid-line observation are included, see the `controls` argument.
`bridge_loc`	named list specifying the bridge from your data format to the native format of `geom_body`, e.g., `list(head = c("head", "face", "scalp"))`. See Details.
`combine`	named list of vectors naming the regions to be combined and mapped as one, e.g., `list(arm = c("shoulder", "arm", "elbow", "wrist"))`. See Details for behaviour.
`controls`	named list of more specific parameters for fine-tuning the appereance of the humap. Currently, these controls are available (more will follow in the future): `na_fill`: should be a string or function specifying the fill of zero-count regions (default: "black") `label_pad`: a numeric defining the padding between labels, in percent of map height (default: `3.5`) `mid_include`: a logical defining whether to include mid-line observations and split them equally between left and right (default: `FALSE`) `round_counts`: a logical indicating whether to round (up) half-counts in annotation labels when splitting mid-line observations between left and right (default: `FALSE`)
`type`	currently, only `"simple"` is available, but we're working on more natural-looking and sex-specific maps as well.
`proj`	`"front"` or `"back"`. Ignored if `type = "simple"`, so currently not in use.
`stat`	either `"count"` (default) or `"identity"`. Use the former with tidy data, and the latter when you supply a column with a pre-computed summary statistic. When using `stat = "identity"`, you must supply the name of the column with the summary statistic as the `fill` aesthetic.
`na.rm`	logical indicating whether to remove missing data. Default is `FALSE`.
`show.legend, inherit.aes, ...`	passed on to the underlying machinery of the `geom`.

The annotate argument may be a named list with any combination of the following four elements:

details: a character string, and may be any of the valid values of the simple argument ("freq", "all", NA)
gp: must be a gpar object (see ?grid::gpar). If only gp is specified, it is applied to both annotation text and lines.
gp_text: must be a gpar object, and is applied to annotation text.
gp_lines: must be a gpar object, and is applied to annotation lines

The bridge argument allows you to use your own localisation values, and bridge them to those of geom_body. The idea is simple: you supply a named list, each element of which corresponds one region in the geom_body map; the name of the element should be the name of the region, and the element value a character vector of values in your data that correspond to that region. See vignette [add reference to vignette here] for examples.

If you want to combine several regions and map them as one, supply a named list in combine, following this logic: the name of each element will be printed as the annotation text (if you so desire), and the element must be a character vector specifying the names of geom_body regions to map as one. Underscores in the list element names will be converted to spaces. Make sure to not use a name for a merged region that is already used for another region; e.g., this is not allowed, because hand is already the name of another region: list(hand = c("shoulder", "arm", "elbow", "wrist")). You may, however, use a name of a region inside the group, e.g., list(hand = c("wrist", "hand")).

A layer object to be added to a humap object.

benskov/humapr documentation built on April 3, 2021, 6:52 a.m.