Optimize an acmap

Take an acmap object with a table of titer data and perform optimization runs to try and find the best arrangement of antigens and sera to represent their antigenic similarity. Optimizations generated from each run with different random starting conditions will be added to the acmap object.

optimizeMap(
  map,
  number_of_dimensions,
  number_of_optimizations,
  minimum_column_basis = "none",
  fixed_column_bases = NULL,
  titer_weights = NULL,
  sort_optimizations = TRUE,
  check_convergence = TRUE,
  verbose = TRUE,
  options = list()
)

Arguments

map

The acmap data object

number_of_dimensions

The number of dimensions for the new map

number_of_optimizations

The number of optimization runs to perform

minimum_column_basis

The minimum column basis to use (see details)

fixed_column_bases

A vector of fixed values to use as column bases directly, rather than calculating them from the titer table.

titer_weights

An optional matrix of weights to assign each titer when optimizing

sort_optimizations

Should optimizations be sorted by stress afterwards?

check_convergence

Should a basic check for convergence of lowest stress optimization runs onto a similar solution be performed.

verbose

Should progress messages be reported, see also RacOptimizer.options()

options

List of named optimizer options, see RacOptimizer.options()

Value

Returns the acmap object updated with new optimizations.

Details

This is the core function to run map optimizations. In essence, for each optimization run, points are randomly distributed in n-dimensional space, the L-BFGS gradient-based optimization algorithm is applied to move points into an optimal position. Depending on the map, this may not be a trivial optimization process and results will depend upon the starting conditions so multiple optimization runs may be required. For a full explanation see vignette("intro-to-antigenic-cartography").

Minimum column basis and fixed column bases

Fixed column bases is a vector of fixed column bases for each sera, where NA is specified (the default) column bases will be calculated according to the minimum_column_basis setting. Again for a full explanation of column bases and what they mean see vignette("intro-to-antigenic-cartography").

See also

See relaxMap() for optimizing a given optimization starting from its current coordinates.

Other map optimization functions: RacOptimizer.options(), make.acmap(), moveTrappedPoints(), randomizeCoords(), relaxMapOneStep(), relaxMap()