Calculate triangulation blobs data for an antigenic map

Source: R/map_diagnostics_triangulation_blobs.R

This function is to help give an idea of how well coordinated each point is in a map, and to give some idea of uncertainty in it's position. It works by moving each point in a grid search and seeing how the total map stress changes, see details.

triangulationBlobs(
  map,
  optimization_number = 1,
  stress_lim = 1,
  grid_spacing = 0.25,
  antigens = TRUE,
  sera = TRUE,
  .check_relaxation = TRUE,
  .options = list()
)

Arguments

map

The acmap data object

optimization_number

The optimization number to check

stress_lim

The blob stress limit

grid_spacing

Grid spacing to use when searching map space and inferring the blob

antigens

Should triangulation blobs be calculated for antigens

sera

Should triangulation blobs be calculated for sera

.check_relaxation

Should a check be performed that the map is fully relaxed (all points in a local optima) before the search is performed

.options

List of named optimizer options to use when checking map relaxation, see RacOptimizer.options()

Value

Returns the acmap data object with triangulation blob information added, which will be shown when the map is plotted

Details

The region or regions of the plot where total map stress is not increased above a certain threshold (stress_lim) are shown when the map is plotted. This function is really to check whether point positions are clearly very uncertain, for example the underlying titers may support an antigen being a certain distance away from a group of other points but due to the positions of the sera against which it was titrated the direction would be unclear, and you might see a blob that forms an arc or "banana" that represents this. Note that it is not really a confidence interval since a point may be well coordinated in terms of the optimization but it's position may still be defined by perhaps only one particular titer which is itself uncertain. For something more akin to confidence intervals you can use other diagnostic functions like bootstrapMap().