Package 'Racmacs'

Description

This function generates a new acmap object, the base object for storing map data in the Racmacs package.

Usage

acmap(
  ag_names = NULL,
  sr_names = NULL,
  titer_table = NULL,
  ag_coords = NULL,
  sr_coords = NULL,
  check_duplicates = TRUE,
  ...
)

Arguments

Details

The fundamental unit of the Racmacs package is the acmap object, short for Antigenic Cartography MAP. This object contains all the information about an antigenic map. You can read in a new acmap object from a file with the function read.acmap() and create a new acmap object within an R session using the acmap() function.

Value

Returns the new acmap object

See Also

See optimizeMap() for generating new optimizations estimating antigen similarity from the acmap titer data.

Other functions for working with map data: addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Functions to get various attributes about an acmap object.

Usage

numAntigens(map)

numSera(map)

numSeraGroups(map)

numPoints(map)

numOptimizations(map)

numLayers(map)

Arguments

Value

A number relating to the attribute

See Also

Other map attribute functions: adjustedLogTiterTable(), adjustedTiterTable(), dilutionStepsize(), logtiterTableLayers(), mapDescription(), mapName(), titerTableFlat(), titerTableLayers(), titerTable()

Description

Function to add a new optimization to an acmap object, with specified values.

Usage

addOptimization(
  map,
  ag_coords = NULL,
  sr_coords = NULL,
  number_of_dimensions = NULL,
  minimum_column_basis = "none",
  fixed_column_bases = NULL,
  ag_reactivity_adjustments = NULL
)

Arguments

Value

Returns the acmap data object with new optimization added (but not selected).

See Also

Other functions for working with map data: acmap(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Return the log titer table plus any antigen reactivity adjustments.

Usage

adjustedLogTiterTable(map, optimization_number = 1)

Arguments

Value

A numeric matrix of adjusted log titers.

See Also

Other map attribute functions: acmapAttributes, adjustedTiterTable(), dilutionStepsize(), logtiterTableLayers(), mapDescription(), mapName(), titerTableFlat(), titerTableLayers(), titerTable()

Description

Return the titer table plus any antigen reactivity adjustments.

Usage

adjustedTiterTable(map, optimization_number = 1)

Arguments

Value

A character matrix of titers.

See Also

htmlAdjustedTiterTable()

Other map attribute functions: acmapAttributes, adjustedLogTiterTable(), dilutionStepsize(), logtiterTableLayers(), mapDescription(), mapName(), titerTableFlat(), titerTableLayers(), titerTable()

Description

These functions get and set the antigen attributes for a map.

Usage

agIDs(map)
agIDs(map) <- value
agDates(map)
agDates(map) <- value
agReference(map)
agReference(map) <- value
agNames(map)
agNames(map) <- value
agExtra(map)
agExtra(map) <- value
agPassage(map)
agPassage(map) <- value
agLineage(map)
agLineage(map) <- value
agReassortant(map)
agReassortant(map) <- value
agStrings(map)
agStrings(map) <- value
agContinent(map)
agContinent(map) <- value

Arguments

Value

Returns either the requested attribute when using a getter function or

the updated acmap object when using the setter function.

See Also

srAttributes()

Other antigen and sera attribute functions: agGroups(), agHomologousSr(), agLabIDs(), agSequences(), ptAnnotations, ptClades, srAttributes, srGroups(), srHomologousAgs(), srSequences()

Description

Checks the vertex connectivity of points in a map (the minimum number of points needed to remove from the map to eliminate all paths from one point to another point). This is for checking for example if after merging maps you only have a small number of points in common between separate groups of points, leading to a situation where groups of points cannot be robustly positioned relative to each other. If the vertex connectivity is smaller than the number of map dimensions + 1 then this will certainly be occurring and will lead to an unstable map solution. mapCohesion() returns the minimum vertex connectivity found between any given points, while agCohesion() and srCohesion() return the vertex connectivity between each pair of antigens and sera as a table helping to diagnose which antigens and sera are forming separate groups. Note that for these purposes only detectable titers count as connections and non-detectable titers are ignored.

Usage

agCohesion(map)

srCohesion(map)

mapCohesion(map)

Arguments

Value

A scalar real value.

See Also

Other map diagnostic functions: bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

These functions get and set the antigen groupings for a map.

Usage

agGroups(map)

agGroups(map) <- value

Arguments

Value

A factor vector of groupings.

See Also

Other antigen and sera attribute functions: agAttributes, agHomologousSr(), agLabIDs(), agSequences(), ptAnnotations, ptClades, srAttributes, srGroups(), srHomologousAgs(), srSequences()

Description

Gets the indices of homologous sera for each antigen in an antigenic map. See also the function srHomologousAgs() for getting and setting the homologous antigens reciprocally.

Usage

agHomologousSr(map)

Arguments

Value

A list, where each entry is a vector of indices for homologous sera, or a length 0 vector where no homologous serum is present

See Also

Other antigen and sera attribute functions: agAttributes, agGroups(), agLabIDs(), agSequences(), ptAnnotations, ptClades, srAttributes, srGroups(), srHomologousAgs(), srSequences()

Description

Getting and setting antigen lab id information

Usage

agLabIDs(map)

agLabIDs(map) <- value

Arguments

Value

A character vector of antigen laboratory IDs

See Also

Other antigen and sera attribute functions: agAttributes, agGroups(), agHomologousSr(), agSequences(), ptAnnotations, ptClades, srAttributes, srGroups(), srHomologousAgs(), srSequences()

Description

Get and set antigen reactivity adjustments

Usage

agReactivityAdjustments(map)

agReactivityAdjustments(map) <- value

Arguments

Value

A numeric vector of antigen reactivity adjustments

See Also

Other functions for working with map data: acmap(), addOptimization(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Getting and setting antigen sequence information

Usage

agSequences(map, missing_value = ".")

agSequences(map) <- value

agNucleotideSequences(map, missing_value = ".")

agNucleotideSequences(map) <- value

Arguments

Value

A character matrix of sequences, where each row represents an antigen.

See Also

Other antigen and sera attribute functions: agAttributes, agGroups(), agHomologousSr(), agLabIDs(), ptAnnotations, ptClades, srAttributes, srGroups(), srHomologousAgs(), srSequences()

Description

Applies the map transformation associated with a selected optimization run to a set of coordinates.

Usage

applyMapTransform(coords, map, optimization_number = 1)

Arguments

Value

An acmap object with transformation applied

See Also

Other functions relating to map transformation: reflectMap(), rotateMap(), translateMap()

Description

Copy point style from matching antigens and sera in another acmap

Usage

applyPlotspec(map, source_map)

Arguments

Value

Returns the acmap object with updated point styles (unmatched point styles unchanged)

See Also

Other map point style functions: ptDrawingOrder(), ptOpacity, ptStyles

Description

Convert map to json format

Usage

as.json(map, pretty = FALSE, round_titers = FALSE)

Arguments

Value

Returns map data as .ace json format

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Plot a blob object such as that return from agBootstrapBlob() using the polygon() function.

Usage

blob(x, col, border, lwd, alpha = 1, ...)

Arguments

Value

No return value, called for the side effect of plotting the blobs.

See Also

Other additional plotting functions: blobsize()

Description

Returns either the area (for 2D blobs) or volume (for 3D blobs)

Usage

blobsize(blob)

Arguments

Value

A numeric vector

See Also

Other additional plotting functions: blob()

Description

This function takes a map for which the function bootstrapMap() has already been applied and draws contour blobs for each point illustrating how point position varies in each bootstrap repeat. The blobs are calculated using kernal density estimates according to these point distribution and drawn so as to encompass a given proportion of this variation according to the parameter conf.level. A conf.level set at 0.95 for example will draw blobs that are calculated to encompass 95% of the positional variation seen in the bootstrap repeats. Note however that the accuracy of these estimates will depend on the number of bootstrap repeats performed, for example whether 100 or 1000 repeats were performed in the initial calculations using bootstrapMap().

Usage

bootstrapBlobs(
  map,
  conf.level = 0.68,
  smoothing = 6,
  gridspacing = 0.25,
  antigens = TRUE,
  sera = TRUE,
  method = "ks"
)

Arguments

Value

Returns an acmap object that will then show the corresponding bootstrap blobs when viewed or plotted.

See Also

Other map diagnostic functions: agCohesion(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

This function takes the map and original titer table, and performs a version of bootstrapping defined by the method argument. For each bootstrap run this process is performed and a record of the coordinates of points in the lowest stress solution is kept. See details for a description of the bootstrapping methods you can apply.

Usage

bootstrapMap(
  map,
  method,
  bootstrap_repeats = 1000,
  bootstrap_ags = TRUE,
  bootstrap_sr = TRUE,
  reoptimize = TRUE,
  optimizations_per_repeat = 100,
  ag_noise_sd = 0.7,
  titer_noise_sd = 0.7,
  options = list()
)

Arguments

Details

Bootstrapping methods

"resample": The resample bootstrap is the most standard bootstrap method, a random resample of the titer table data is taken with replacement. Depending on your specification, resampling is applied across either individual antigens, individual sera or both antigens and sera. In essence this method tries to let you see how robust the map is to inclusion of particular titer measurements or antigens or sera. Like most bootstrapping techniques it will prove give more reliable results the more antigens and sera you have in your map. It won't work very well for a map of 5 sera and antigens for example, in this case a "noisy" bootstrap may be better.

"bayesian": The bayesian bootstrap is akin to the resampling bootstrap, but rather than explicitly resampling data, weights are assigned to each part of the titer table data according to random draws from a dirichilet distribution. Under this scheme, every data point will play at least some role in making the map, even if only weighted slightly. Sometimes this is helpful, if you know for example that the points in your map are highly dependent upon the presence of a few antigens / sera / titers to achieve reasonable triangulation of point positions and you don't really want to risk removing them completely and ending up with bootstrap runs that are under-constrained, you might want to consider this approach. On the other hand this might be exactly what you don't want and you want to know uncertainty that can be generated when certain subsets of the data are excluded completely, in that case you probably want to stick with the "resample" method.

"noisy": The noisy bootstrap, sometimes termed a smooth bootstrap involved adding normally distributed noise to each observation. The distribution of this noise can be parameterised through the ag_noise_sd and titer_noise_sd arguments. titer_noise_sd refers to the standard deviation (on the log scale) of noise added to each individual titer measurement in the table, while antigen_noise_sd refers to the standard deviation of noise applied to titers for each antigen. The reason for this distinction is that we have noticed with repeat measurements of influenza data there is often both a random noise per titer and a random noise per antigen, i.e. in one repeat titers may all be around one 2-fold higher on average, in addition to unbiased additional titer noise. If you wish to only simulate additional noise per titer and not a per antigen effect, simply set antigen_noise_sd to 0. Note that in order to use this most effectively it is best to have an idea of the amount and type of measurement noise you may expect in your data and set these parameters accordingly.

Value

Returns the map object updated with bootstrap information

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

Check for hemisphering or trapped points

Usage

checkHemisphering(
  map,
  optimization_number = 1,
  grid_spacing = 0.25,
  stress_lim = 0.1,
  options = list()
)

Arguments

Value

Returns a data frame with information on any points that were found to be hemisphering or trapped.

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

Functions to get and set column bases specified for an optimization run, either through the minimum column basis or through a vector of specified column bases.

Usage

minColBasis(map, optimization_number = 1)
minColBasis(map, optimization_number = 1) <- value
fixedColBases(map, optimization_number = 1)
fixedColBases(map, optimization_number = 1) <- value

Arguments

Details

In general a map can have column bases that are specified either through a minimum column basis or a vector of fixed column bases for each sera. When you call minColBasis(), it will return the minimum column basis if it has been set, or "fixed" if column bases have instead been fixed directly. The colBases() function will return the column bases as calculated for a given optimization run. Setting column bases through this function with ⁠colBases()<-⁠ will fix the column bases to the supplied vector of values.

Note that although the output from colBases() might be the same in a case where a minimum column basis was set or a case where column bases were set explicitly, when a minimum column basis is set, the column bases will still depend on the log titers recorded against a given sera, so changing the titers may therefore change the actual column bases calculated. For fixed column bases case, column bases will remain fixed at their values independently of measured titers.

Value

Returns either the requested attribute when using a getter function or

the updated acmap object when using the setter function.

See Also

Other map optimization attribute functions: mapComment(), mapDimensions(), mapStress(), mapTransformation(), ptBaseCoords(), ptCoords()

Description

These functions still work but have been deprecated in favour of another function. Arguments will be passed onto the new function with a warning.

Usage

stressBlobs(...)

Arguments

Value

Values from the new function

Description

This defaults to 1 but can be changed using this function with knock-on effects for how < values are treated when maps are optimized or relaxed and the way stress is calculated, see details.

Usage

dilutionStepsize(map)

dilutionStepsize(map) <- value

Arguments

Details

Antigenic cartography was originally developed for HI titers which typically follow a 2-fold dilution series starting from 1/10, then 1/20, 1/40 etc. This represents a "dilution stepsize" of 1 when converted to the log2 scale. When no inhibition was recorded at the highest dilution, the value is typically recorded as <10 but the optimization regime effectively treats this as a <=5, the rationale being that, had the dilution series been continued to higher concentrations, the next lowest titer would have been a 5. Over time the method has also been applied to other neutralization assays that sometimes have a continuous read out with a lower end, in these cases a <10 really means a <10 since any other values like 9.8 or 7.62 would also be possible. To indicate these continuous cases, you can specify the dilution stepsize as 0. Equally, if the dilution regime followed a different pattern, you can also set that here.

Value

A number giving the current dilution stepsize setting for a map.

See Also

Other map attribute functions: acmapAttributes, adjustedLogTiterTable(), adjustedTiterTable(), logtiterTableLayers(), mapDescription(), mapName(), titerTableFlat(), titerTableLayers(), titerTable()

Description

Take a map object and perform cross-validation, seeing how well titers are predicted when they are excluded from the map.

Usage

dimensionTestMap(
  map,
  dimensions_to_test = 1:5,
  test_proportion = 0.1,
  minimum_column_basis = "none",
  fixed_column_bases = rep(NA, numSera(map)),
  number_of_optimizations = 1000,
  replicates_per_dimension = 100,
  options = list()
)

Arguments

Details

For each run, the ag-sr titers that were randomly excluded are predicted according to their relative positions in the map trained without them. An RMSE is then calculated by comparing predicted titers inferred from the map on the log scale to the actual log titers. This is done separately for detectable titers (e.g. 40) and non-detectable titers (e.g. <10). For non-detectable titers, if the predicted titer is the same or lower than the log-titer threshold, the error is set to 0.

Value

Returns a data frame with the following columns. "dimensions" : the dimension tested, "mean_rmse_detectable" : mean prediction rmse for detectable titers across all runs. "var_rmse_detectable" the variance of the prediction rmse for detectable titers across all runs, useful for estimating confidence intervals. "mean_rmse_nondetectable" and "var_rmse_nondetectable" the equivalent for non-detectable titers

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

Edit antigen names in an acmap

Usage

edit_agNames(map, old_names, new_names)

Arguments

Value

Returns the acmap object with antigen names updated.

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Edit sera names in an acmap

Usage

edit_srNames(map, old_names, new_names)

Arguments

Value

Returns the acmap object with sera names updated.

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Export a map in a standalone html viewer

Usage

export_viewer(map, file, selfcontained = TRUE, ...)

Arguments

Value

Called for the side effect of saving the viewer to an html file but invisibly returns the map viewer htmlwidget.

See Also

Other functions to view maps: RacViewer.options(), RacViewer(), ggplot.acmap(), mapGadget(), plot.acmap(), setLegend(), view.acmap(), view.default(), view()

Description

Gets the details associated with the currently selected or specified acmap optimization as a list.

Usage

getOptimization(map, optimization_number = 1)

Arguments

Value

Returns a list with information about the optimization

See Also

See listOptimizations() for getting information about all optimizations.

Description

Method for plotting an antigenic map as a ggplot object

Usage

## S3 method for class 'acmap'
ggplot(
  data = NULL,
  mapping = NULL,
  optimization_number = 1,
  xlim = NULL,
  ylim = NULL,
  plot_ags = TRUE,
  plot_sr = TRUE,
  plot_blobs = TRUE,
  plot_hemisphering = TRUE,
  show_procrustes = TRUE,
  show_error_lines = FALSE,
  plot_stress = FALSE,
  indicate_outliers = "arrowheads",
  grid.col = "grey90",
  grid.lwd = 0.5,
  grid.margin.col = "grey50",
  grid.margin.lwd = grid.lwd,
  fill.alpha = 0.8,
  outline.alpha = 0.8,
  padding = 1,
  arrow_angle = 25,
  arrow_length = 0.2,
  margins = rep(0.5, 4),
  ...,
  environment = NULL
)

Arguments

Value

Returns the ggplot plot

See Also

Other functions to view maps: RacViewer.options(), RacViewer(), export_viewer(), mapGadget(), plot.acmap(), setLegend(), view.acmap(), view.default(), view()

Description

Prints an html formatted titer table, visualising with colors things like which titers are the maximum for each sera.

Usage

htmlAdjustedTiterTable(map, optimization_number = 1)

Arguments

Value

A list() with a Rac_html_merge_report and shiny.tag class that can be converted into an HTML string via as.character() and saved to a file with save_html().

Description

Prints an html formatted table merge report of a set of merged maps, visualising with colors how different titers have been merged together.

Usage

htmlMergeReport(map)

Arguments

Value

A list() with a Rac_html_merge_report and shiny.tag class that can be converted into an HTML string via as.character() and saved to a file with save_html().

See Also

Other map merging functions: RacMerge.options(), mergeMaps(), mergeReport(), splitTiterLayers()

Description

Prints an html formatted titer table, visualising with colors things like which titers are the maximum for each sera.

Usage

htmlTiterTable(map)

Arguments

Value

A list() with a Rac_html_merge_report and shiny.tag class that can be converted into an HTML string via as.character() and saved to a file with save_html().

See Also

htmlAdjustedTiterTable

Description

Keep only the lowest stress map optimization

Usage

keepBestOptimization(map)

Arguments

Value

An acmap object with only the lowest stress optimization kept

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Keep only data from specified optimization runs.

Usage

keepOptimizations(map, optimization_numbers)

Arguments

Value

Returns the updated acmap object

See Also

Other functions to work with map optimizations: optimizationProperties, removeOptimizations(), sortOptimizations()

Description

Keep only a single optimization run

Usage

keepSingleOptimization(map, optimization_number = 1)

Arguments

Value

An acmap object with only one optimization kept

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Get and set map layer names

Usage

layerNames(map)

layerNames(map) <- value

Arguments

Value

A character vector of layer names

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Gets the details associated with the all the optimizations of an acmap object as a list.

Usage

listOptimizations(map)

Arguments

Value

Returns a list of lists with information about the optimizations

See Also

See getOptimization() for getting information about a single optimization.

Description

Converts titers to the log scale via via the transformation $log2(x/10)$, lessthan values are reduced by 1 on the log scale and greater than values are increased by 1, hence <10 => -1 and >1280 => 8

Usage

logtiterTable(map)

Arguments

Value

Returns a matrix of titers converted to the log scale

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Other functions relating to map stress calculation: mapDistances(), mapResiduals(), pointStress, recalculateStress(), stressTable(), tableColbases(), tableDistances()

Description

Return a list of logtiter table layers

Usage

logtiterTableLayers(map)

Arguments

Value

A list of numeric matrices with logtiter values

See Also

Other map attribute functions: acmapAttributes, adjustedLogTiterTable(), adjustedTiterTable(), dilutionStepsize(), mapDescription(), mapName(), titerTableFlat(), titerTableLayers(), titerTable()

Description

This is a wrapper function for first making a map with table data then, running optimizations to make the map otherwise done with acmap() followed by optimizeMap().

Usage

make.acmap(
  titer_table = NULL,
  ag_names = NULL,
  sr_names = NULL,
  number_of_dimensions = 2,
  number_of_optimizations = 100,
  minimum_column_basis = "none",
  fixed_column_bases = NULL,
  sort_optimizations = TRUE,
  check_convergence = TRUE,
  verbose = TRUE,
  options = list(),
  ...
)

Arguments

Value

Returns an acmap object that has optimization run results.

See Also

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

Description

Plot map vs table distances

Usage

plot_map_table_distance(
  map,
  optimization_number = 1,
  xlim,
  ylim,
  line_of_equality = TRUE
)

plotly_map_table_distance(
  map,
  optimization_number = 1,
  xlim,
  ylim,
  line_of_equality = TRUE
)

Arguments

Value

Returns the ggplot2 object

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

This can be used to get information about the bootstrap run results after bootstrapMap() has been run.

Usage

mapBootstrap_ptBaseCoords(map)

mapBootstrap_agCoords(map)

mapBootstrap_srCoords(map)

Arguments

Value

Returns a list of coordinate matrices for the points in each of the bootstrap runs

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

Get or set an optimization run comment

Usage

mapComment(map, optimization_number = 1)
mapComment(map, optimization_number = 1) <- value

Arguments

Value

Gets or sets map comments for the optimization run.

See Also

Other map optimization attribute functions: colBases(), mapDimensions(), mapStress(), mapTransformation(), ptBaseCoords(), ptCoords()

Description

Getting and setting the map description

Usage

mapDescription(map)
mapDescription(map) <- value

Arguments

Value

Returns either the requested attribute when using a getter function or

the updated acmap object when using the setter function.

See Also

Other map attribute functions: acmapAttributes, adjustedLogTiterTable(), adjustedTiterTable(), dilutionStepsize(), logtiterTableLayers(), mapName(), titerTableFlat(), titerTableLayers(), titerTable()

Description

Get the current map dimensions

Usage

mapDimensions(map, optimization_number = 1)

Arguments

Value

Returns the number of dimensions for the optimization run.

See Also

Other map optimization attribute functions: colBases(), mapComment(), mapStress(), mapTransformation(), ptBaseCoords(), ptCoords()

Description

Takes the acmap object and calculates euclidean distances between antigens and sera for the currently selected or specified optimization.

Usage

mapDistances(map, optimization_number = 1)

Arguments

Value

Returns a matrix of map distances with antigens as rows and sera as columns.

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Other functions relating to map stress calculation: logtiterTable(), mapResiduals(), pointStress, recalculateStress(), stressTable(), tableColbases(), tableDistances()

Description

This function is equivalent to running runGUI() and loading a map file, but this takes the acmap object to open as an input argument.

Usage

mapGadget(map)

Arguments

Value

No value returned, called for the side effect of starting the gadget.

See Also

Other functions to view maps: RacViewer.options(), RacViewer(), export_viewer(), ggplot.acmap(), plot.acmap(), setLegend(), view.acmap(), view.default(), view()

Description

Getting and setting the map name

Usage

mapName(map)
mapName(map) <- value

Arguments

Value

Returns either the requested attribute when using a getter function or

the updated acmap object when using the setter function.

See Also

Other map attribute functions: acmapAttributes, adjustedLogTiterTable(), adjustedTiterTable(), dilutionStepsize(), logtiterTableLayers(), mapDescription(), titerTableFlat(), titerTableLayers(), titerTable()

Description

Checks if the map optimization run can be relaxed further.

Usage

mapRelaxed(map, optimization_number = 1, options = list())

Arguments

Value

Returns TRUE or FALSE

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

This is the difference between the table distance and the map distance

Usage

mapResiduals(map, exclude_nd = FALSE, optimization_number = 1)

Arguments

Value

Returns a matrix of residuals, showing the residual error between map distance and table distance for each antigen-sera pair.

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Other functions relating to map stress calculation: logtiterTable(), mapDistances(), pointStress, recalculateStress(), stressTable(), tableColbases(), tableDistances()

Description

Calculate the current map stress

Usage

mapStress(map, optimization_number = 1)

Arguments

Value

A number giving the map stress

See Also

Other map optimization attribute functions: colBases(), mapComment(), mapDimensions(), mapTransformation(), ptBaseCoords(), ptCoords()

Description

These functions can be used to query and if necessary set the map transformation and map translation attributes for a given optimization run.

Usage

mapTransformation(map, optimization_number = 1)
mapTransformation(map, optimization_number = 1) <- value
mapTranslation(map, optimization_number = 1)
mapTranslation(map, optimization_number = 1) <- value

Arguments

Value

Returns either the requested attribute when using a getter function or

the updated acmap object when using the setter function.

See Also

Other map optimization attribute functions: colBases(), mapComment(), mapDimensions(), mapStress(), ptBaseCoords(), ptCoords()

Description

Find matching antigens or sera between 2 maps

Usage

match_mapAntigens(map1, map2)

match_mapSera(map1, map2)

Arguments

Value

Returns the indices of matching strains in map 2, or NA in the position of strains not found.

See Also

Other functions to compare maps: procrustesData(), procrustesMap(), realignMap(), realignOptimizations()

Description

Functions to merge together two tables or maps.

Usage

mergeMaps(
  ...,
  method = "table",
  number_of_dimensions,
  number_of_optimizations,
  minimum_column_basis = "none",
  optimizer_options = list(),
  merge_options = list(),
  verbose = TRUE
)

Arguments

Details

Maps can be merged in a number of ways depending upon the desired result.

Method 'table'

As you would expect, this merges the tables of the two maps but does not attempt to create any new optimizations and any existing optimizations are lost.

Method 'reoptimized-merge'

This merges the tables and then does a specified number of fresh optimizations from random starting coordinates, ignoring any pre-existing optimization runs. It's exactly the same as doing a 'table' merge and running optimizeMap() on the merged table.

Method 'incremental-merge'

This takes the currently selected optimization in the first map and then merges in the additional maps in turn. Each time any points not already found in the first map (or the last map in the incremental merge chain) are randomised and everything is relaxed, this is repeated the specified number of times and the process is repeated.

Method 'frozen-overlay'

This fixes the positions of points in each map and tries to best match them simply through re-orientation. Once the best re-orientation is found, points that are in common between the maps are moved to the average position.

Method 'relaxed-overlay'

This is the same as the frozen-overlay but points in the resulting map are then allowed to relax.

Method 'frozen-merge'

In this version, positions of all points in the first map are fixed and remain fixed, so the original map does not change. The second map is then realigned to the first as closely as possible and then all the new points appearing in the second map are allowed to relax into their new positions. This is a way to merge in new antigens and sera into a map without affecting the first one at all (and was first implemented in lisp).

Value

Returns the merged map object

See Also

Other map merging functions: RacMerge.options(), htmlMergeReport(), mergeReport(), splitTiterLayers()

Description

Prints a raw text merge report from merging two map tables.

Usage

mergeReport(map)

Arguments

Value

Returns a character matrix of information on merged titers.

See Also

Other map merging functions: RacMerge.options(), htmlMergeReport(), mergeMaps(), splitTiterLayers()

Description

Sometimes points in a map optimization run get trapped in local optima, this function tries to combat this by doing a grid search for each point individually moving points if a better optima is found. Note that this only performs grid searches individually so won't find cases where a group of points are trapped together in a local optima.

Usage

moveTrappedPoints(
  map,
  optimization_number = 1,
  grid_spacing = 0.25,
  max_iterations = 10,
  options = list()
)

Arguments

Details

The search is iterative, searching for and moving points that are found to be trapped before relaxing the map and searching again, stopping either when no more trapped points are found or max_iterations is reached.

Value

Returns the acmap object with updated coordinates (if any trapped points found)

See Also

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

Description

Utility functions to get a vector of all the map optimization properties.

Usage

allMapStresses(map)

allMapDimensions(map)

Arguments

Value

A numeric vector of values

See Also

Other functions to work with map optimizations: keepOptimizations(), removeOptimizations(), sortOptimizations()

Description

Usage

optimizeAgReactivity(
  map,
  optimization_number = 1,
  reactivity_stress_weighting = 1,
  fixed_ag_reactivities = rep(NA, numAntigens(map)),
  start_pars = rep(0, numAntigens(map)),
  reoptimize = FALSE,
  number_of_optimizations = 100,
  options = list()
)

Arguments

Value

The acmap object is returned with antigen reactivity adjustments set to the value calculated in the optimizer. This can be queried with agReactivityAdjustments().

Description

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.

Usage

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

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

Value

Returns the acmap object updated with new optimizations.

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

Description

Functions to change the order of antigens and sera in a map

Usage

orderAntigens(map, order)

orderSera(map, order)

Arguments

Value

An acmap object with points reordered

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Method for plotting an antigenic map in two dimensions

Usage

## S3 method for class 'acmap'
plot(
  x,
  optimization_number = 1,
  xlim = NULL,
  ylim = NULL,
  plot_ags = TRUE,
  plot_sr = TRUE,
  plot_labels = FALSE,
  plot_blobs = TRUE,
  point_opacity = "automatic",
  show_procrustes = TRUE,
  show_error_lines = FALSE,
  plot_stress = FALSE,
  indicate_outliers = "arrowheads",
  grid.col = "grey90",
  grid.margin.col = "grey50",
  outlier.arrow.col = grid.col,
  fill.alpha = 0.8,
  outline.alpha = 0.8,
  procrustes.lwd = 2,
  procrustes.col = "black",
  procrustes.arr.type = "triangle",
  procrustes.arr.length = 0.2,
  procrustes.arr.width = 0.15,
  label.offset = 0,
  padding = 1,
  cex = 1,
  margins = rep(0.5, 4),
  ...
)

Arguments

Value

Called for the side effect of plotting the map but invisibly returns the map object.

See Also

Other functions to view maps: RacViewer.options(), RacViewer(), export_viewer(), ggplot.acmap(), mapGadget(), setLegend(), view.acmap(), view.default(), view()

Description

Functions to get stress associated with individual points in a map.

Usage

agStress(map, antigens = TRUE, optimization_number = 1)

srStress(map, sera = TRUE, optimization_number = 1)

srStressPerTiter(map, sera = TRUE, optimization_number = 1)

agStressPerTiter(map, antigens = TRUE, optimization_number = 1)

Arguments

Value

A numeric vector of point stresses

See Also

See mapStress() for getting the total map stress directly.

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Other functions relating to map stress calculation: logtiterTable(), mapDistances(), mapResiduals(), recalculateStress(), stressTable(), tableColbases(), tableDistances()

Description

Returns information about how similar point positions are in two maps, to get an idea of how similar antigenic positions are in for example maps made from two different datasets.

Usage

procrustesData(
  map,
  comparison_map,
  optimization_number = 1,
  comparison_optimization_number = 1,
  antigens = TRUE,
  sera = TRUE,
  translation = TRUE,
  scaling = FALSE
)

Arguments

Value

Returns a list with information on antigenic distances between the aligned maps, and the rmsd of the point differences split by antigen points, serum points and total, or all points. The distances are a vector matching the number of points in the main map, with NA in the position of any points not found in the comparison map.

See Also

Other functions to compare maps: matchStrains, procrustesMap(), realignMap(), realignOptimizations()

Description

Returns information from one map procrusted to another.

Usage

procrustesMap(
  map,
  comparison_map,
  optimization_number = 1,
  comparison_optimization_number = 1,
  antigens = TRUE,
  sera = TRUE,
  translation = TRUE,
  scaling = FALSE,
  keep_optimizations = FALSE
)

Arguments

Value

Returns an acmap object with procrustes information added, which will be shown when the map is plotted. To avoid ambiguity about which optimization run the procrustes was applied to, only the optimization run specified by optimization_number is kept in the map returned.

See Also

Other functions to compare maps: matchStrains, procrustesData(), realignMap(), realignOptimizations()

Description

Getting and setting point annotation information

Usage

agAnnotations(map)

srAnnotations(map)

agAnnotations(map) <- value

srAnnotations(map) <- value

Arguments

Value

A character vector of point annotations.

See Also

Other antigen and sera attribute functions: agAttributes, agGroups(), agHomologousSr(), agLabIDs(), agSequences(), ptClades, srAttributes, srGroups(), srHomologousAgs(), srSequences()

Description

These functions get and set the base coordinates for a given optimization run.

Usage

ptBaseCoords(map, optimization_number = 1)
agBaseCoords(map, optimization_number = 1)
agBaseCoords(map, optimization_number = 1) <- value
srBaseCoords(map, optimization_number = 1)
srBaseCoords(map, optimization_number = 1) <- value

Arguments

Value

Returns either the requested attribute when using a getter function or

the updated acmap object when using the setter function.

See Also

agCoords() srCoords()

Other map optimization attribute functions: colBases(), mapComment(), mapDimensions(), mapStress(), mapTransformation(), ptCoords()

Description

Get antigen or serum bootstrap blob information for plotting with the blob() function.

Usage

agBootstrapBlob(map, antigen, optimization_number = 1)

srBootstrapBlob(map, serum, optimization_number = 1)

agBootstrapBlobs(map, optimization_number = 1)

srBootstrapBlobs(map, optimization_number = 1)

ptBootstrapBlobs(map, optimization_number = 1)

Arguments

Value

Returns an object of class "blob" that can be plotted using the blob() function.

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

Get antigen or serum bootstrap coordinates information

Usage

ptBootstrapCoords(map, point)

agBootstrapCoords(map, antigen)

srBootstrapCoords(map, serum)

Arguments

Value

Returns a matrix of coordinates for the point in each of the bootstrap runs

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptLeverage, ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

Getting and setting point clade information

Usage

agClades(map)

srClades(map)

agClades(map) <- value

srClades(map) <- value

Arguments

Value

A character vector of clade information.

See Also

Other antigen and sera attribute functions: agAttributes, agGroups(), agHomologousSr(), agLabIDs(), agSequences(), ptAnnotations, srAttributes, srGroups(), srHomologousAgs(), srSequences()

Description

Getting and setting of antigen and serum coordinates in a map optimization run (by default the currently selected one).

Usage

agCoords(map, optimization_number = 1)

srCoords(map, optimization_number = 1)

ptCoords(map, optimization_number = 1)

ptCoords(map, optimization_number = 1) <- value

agCoords(map, optimization_number = 1) <- value

srCoords(map, optimization_number = 1) <- value

Arguments

Details

These functions get and set point coordinates in a map. By default these coordinates refer to the currently selected optimization run, unless otherwise specified through the optimization_number argument.

99\ want to use but you should note that the outputs are actually the map base coordinates after the transformation and translation associated with the optimization run has been applied (see mapTransformation() and mapTranslation() for more details). When you set the antigen or serum coordinates through these functions, the transformed coordinates are "baked" in and the map transformation and translation are reset. Consequently if you want to apply a transformation to all coordinates generally, you are better off modifying the map translation and transformation directly, as is done by functions like rotateMap() and translateMap().

Value

Returns a matrix of point coordinates.

See Also

agBaseCoords() srBaseCoords() mapTransformation() mapTranslation()

Other map optimization attribute functions: colBases(), mapComment(), mapDimensions(), mapStress(), mapTransformation(), ptBaseCoords()

Description

Point drawing order is a vector of indices defining the order in which points should be draw when plotting or viewing a map. Points are indexed in the same order as antigens then followed by sera.

Usage

ptDrawingOrder(map)

ptDrawingOrder(map) <- value

Arguments

Value

A numeric vector of point drawing order information

See Also

Other map point style functions: applyPlotspec(), ptOpacity, ptStyles

Description

These functions attempt to estimate leverage of each antigen, sera or titer by removing it from the data, relaxing the map, then calculating the rmsd of the procrustes comparison between the original and newly relaxed map. Column bases will be recalculated unless you have specified them as fixed with fixedColBases().

Usage

agLeverage(map, antigens = TRUE, sera = TRUE)

srLeverage(map, antigens = TRUE, sera = TRUE)

titerLeverage(map, antigens = TRUE, sera = TRUE)

Arguments

Value

Returns a numeric vector of the leverage calculated for each of the points.

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptTriangulationBlob, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

These are helper functions to quickly set the opacity of points in a map, they set both the fill and outline color opacity by modifying the fill and outline colors to include an alpha channel for opacity. If you need more control, for example different opacities for the fill and outline colors, you alter the fill and outline opacities yourself, for example with the grDevices::adjustcolor() function.

Usage

agOpacity(map) <- value

srOpacity(map) <- value

Arguments

Value

A numeric vector of point opacities.

See Also

Other map point style functions: applyPlotspec(), ptDrawingOrder(), ptStyles

Description

These functions get and set the styles to use for each point when plotting.

Usage

agShown(map)
srShown(map)
agShown(map) <- value
srShown(map) <- value
agSize(map)
srSize(map)
agSize(map) <- value
srSize(map) <- value
agFill(map)
srFill(map)
agFill(map) <- value
srFill(map) <- value
agOutline(map)
srOutline(map)
agOutline(map) <- value
srOutline(map) <- value
agOutlineWidth(map)
srOutlineWidth(map)
agOutlineWidth(map) <- value
srOutlineWidth(map) <- value
agRotation(map)
srRotation(map)
agRotation(map) <- value
srRotation(map) <- value
agAspect(map)
srAspect(map)
agAspect(map) <- value
srAspect(map) <- value
agShape(map)
srShape(map)
agShape(map) <- value
srShape(map) <- value

Arguments

Value

Returns either the requested attribute when using a getter function or

the updated acmap object when using the setter function.

See Also

Other map point style functions: applyPlotspec(), ptDrawingOrder(), ptOpacity

Description

Get antigen or serum triangulation blob information for plotting with the blob() function.

Usage

agTriangulationBlob(map, antigen, optimization_number = 1)

srTriangulationBlob(map, serum, optimization_number = 1)

agTriangulationBlobs(map, optimization_number = 1)

srTriangulationBlobs(map, optimization_number = 1)

ptTriangulationBlobs(map, optimization_number = 1)

Arguments

Value

Returns an object of class "blob" that can be plotted using the blob() function.

See Also

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, recalculateStress(), stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Description

This function facilitates setting options for the acmap titer merging process by returning a list of option settings.

Usage

RacMerge.options(sd_limit = NULL, dilution_stepsize = 1, method = NULL)

Arguments

Details

When merging measured titers, the general approach is to take the geometric mean and use that as the merged titer, however in particular when < values are present there are different options that can be employed. In older versions of Racmacs, < values were converted to maximum possible numeric titer after accounting for the dilution_stepsize factor, then the geometric mean was taken. This approach can be used by specifying the method as "likelihood" since, this approach gives a very rough approximation of the most likely mean numeric value. In contrast, the "conservative" method and current default returns the highest < value that satisfies all the values that were measured. As an example merging <10 and 20, (assuming dilution_stepsize = 1) would return a value of 10 with the "likelihood" method and <40 with the "conservative" method.

Value

Returns a named list of merging options

See Also

Other map merging functions: htmlMergeReport(), mergeMaps(), mergeReport(), splitTiterLayers()

Description

This function facilitates setting options for the acmap optimizer process by returning a list of option settings.

Usage

RacOptimizer.options(
  dim_annealing = FALSE,
  method = "L-BFGS",
  maxit = 1000,
  num_basis = 10,
  armijo_constant = 1e-04,
  wolfe = 0.9,
  min_gradient_norm = 1e-06,
  factr = 1e-15,
  max_line_search_trials = 50,
  min_step = 1e-20,
  max_step = 1e+20,
  num_cores = getOption("RacOptimizer.num_cores"),
  report_progress = NULL,
  ignore_disconnected = FALSE,
  progress_bar_length = options()$width
)

Arguments

Details

For more details, for example on "dimensional annealing" see vignette("intro-to-antigenic-cartography"). For details on optimizer settings like maxit see the underlying optimizer documentation at ensmallen.org.

Value

Returns a named list of optimizer options

See Also

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

Description

This creates an html widget for viewing antigenic maps.

Usage

RacViewer(
  map,
  show_procrustes = FALSE,
  show_group_legend = FALSE,
  options = list(),
  width = NULL,
  height = NULL,
  elementId = NULL
)

Arguments

Value

An object of class htmlwidget that will intelligently print itself into HTML in a variety of contexts including the R console, within R Markdown documents, and within Shiny output bindings.

See Also

Other functions to view maps: RacViewer.options(), export_viewer(), ggplot.acmap(), mapGadget(), plot.acmap(), setLegend(), view.acmap(), view.default(), view()

Description

Output and render functions for using RacViewer within Shiny applications and interactive Rmd documents.

Usage

RacViewerOutput(outputId, width = "100%", height = "100%")

renderRacViewer(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

An output or render function that enables the use of the widget within Shiny applications.

See Also

Other shiny app functions: runGUI(), view.acmap()

Description

This function facilitates setting racviewer options by returning a list of option settings.

Usage

RacViewer.options(
  point.opacity = NA,
  viewer.controls = "hidden",
  grid.display = "static",
  grid.col = "#cfcfcf",
  background.col = "#ffffff",
  show.names = FALSE,
  show.errorlines = FALSE,
  show.connectionlines = FALSE,
  show.titers = FALSE,
  xlim = NULL,
  ylim = NULL,
  translation = c(0, 0, 0),
  rotation = c(0, 0, 0),
  zoom = NULL
)

Arguments

Value

Returns a named list of viewer options

See Also

Other functions to view maps: RacViewer(), export_viewer(), ggplot.acmap(), mapGadget(), plot.acmap(), setLegend(), view.acmap(), view.default(), view()

Description

Moves map coordinates back into random starting conditions, as performed before each optimization run. The maximum table distance is calculated then points are randomized in a box with side length equal to maximum table distance multiplied by table_dist_factor

Usage

randomizeCoords(map, optimization_number = 1, table_dist_factor = 2)

Arguments

Value

Returns an updated map object

See Also

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

Description

Reads an antigenic map file and converts it into an acmap data object.

Usage

read.acmap(
  filename,
  optimization_number = NULL,
  sort_optimizations = FALSE,
  align_optimizations = FALSE
)

Arguments

Value

Returns the acmap data object.

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.titerTable(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Reads in a table of titer data, converting it to a matrix of titers with labelled column and row names. Missing titers should be represented by an asterisk character.

Usage

read.titerTable(filepath)

Arguments

Details

Currently supported file formats are .csv and .xls and .txt

Value

Returns a matrix of titers.

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), removePoints, save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Realigns the coordinates of a map to match a target map as closely as possible, based on a procrustes analysis. Note that all optimization runs will be separately aligned to match as closely as possible the first optimization run of the target map.

Usage

realignMap(map, target_map, translation = TRUE, scaling = FALSE)

Arguments

Value

Returns a map object aligned to the target map

See Also

Other functions to compare maps: matchStrains, procrustesData(), procrustesMap(), realignOptimizations()

Description

Realigns all map optimizations through rotation and translation to match point positions as closely as possible to the first optimization run. This is done by default when optimizing a map and makes comparing point positions in each optimization run much easier to do by eye.

Usage

realignOptimizations(map)

Arguments

Value

Returns the map with realigned optimizations

See Also

Other functions to compare maps: matchStrains, procrustesData(), procrustesMap(), realignMap()

Description

Recalculates the stress associated with the currently selected or user-specified optimization.

Usage

recalculateStress(map, optimization_number = 1)

Arguments

Value

Returns the recalculated map stress for a given optimization

See Also

See pointStress() for getting the stress of individual points.

Other map diagnostic functions: agCohesion(), bootstrapBlobs(), bootstrapMap(), checkHemisphering(), dimensionTestMap(), logtiterTable(), map-table-distances, mapBootstrapCoords, mapDistances(), mapRelaxed(), mapResiduals(), pointStress, ptBootstrapBlob, ptBootstrapCoords(), ptLeverage, ptTriangulationBlob, stressTable(), tableColbases(), tableDistances(), triangulationBlobs(), unstableMaps

Other functions relating to map stress calculation: logtiterTable(), mapDistances(), mapResiduals(), pointStress, stressTable(), tableColbases(), tableDistances()

Description

Reflects map coordinates

Usage

reflectMap(map, axis = "x", optimization_number = NULL)

Arguments

Value

An acmap object with reflection applied

See Also

Other functions relating to map transformation: applyMapTransform(), rotateMap(), translateMap()

Description

Optimize antigen and serum positions starting from their current coordinates in the selected or specified optimization.

Usage

relaxMap(
  map,
  optimization_number = 1,
  fixed_antigens = FALSE,
  fixed_sera = FALSE,
  titer_weights = NULL,
  options = list()
)

Arguments

Value

Returns an acmap object with the optimization relaxed.

See Also

See optimizeMap() for performing new optimization runs from random starting coordinates.

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

Description

Relax a map one step in the optimiser

Usage

relaxMapOneStep(
  map,
  optimization_number = 1,
  fixed_antigens = FALSE,
  fixed_sera = FALSE,
  options = list()
)

Arguments

Value

Returns an updated map object

See Also

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

Description

Remove all optimization run data from a map object

Usage

removeOptimizations(map)

Arguments

Value

An acmap object with all optimizations removed

See Also

Other functions to work with map optimizations: keepOptimizations(), optimizationProperties, sortOptimizations()

Description

Functions to remove antigens and sera from a map

Usage

removeAntigens(map, antigens)

removeSera(map, sera)

Arguments

Value

An acmap object with points removed

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), save.acmap(), save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Apply a rotation to an antigenic map

Usage

rotateMap(map, degrees, axis = NULL, optimization_number = NULL)

Arguments

Value

An acmap object with rotation applied

See Also

Other functions relating to map transformation: applyMapTransform(), reflectMap(), translateMap()

Description

This function opens the Racmacs GUI in a new window

Usage

runGUI()

Value

Nothing returned, called only for the side effect of starting the viewer.

See Also

Other shiny app functions: RacViewer-shiny, view.acmap()

Description

Save acmap data to a file. The preferred extension is ".ace", although the format of the file will be a json file of map data compressed using 'xz' compression.

Usage

save.acmap(
  map,
  filename,
  compress = FALSE,
  pretty = !compress,
  round_titers = FALSE
)

Arguments

Value

No return value, called for the side effect of saving the map data to the file.

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.coords(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Saves acmap coordinate data of all or specified antigens and sera to a .csv file.

Usage

save.coords(
  map,
  filename,
  optimization_number = 1,
  antigens = TRUE,
  sera = TRUE
)

Arguments

Value

No return value, called for the side effect of saving the coordinate data.

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.titerTable(), subsetCommonPoints, subsetMap()

Description

Saves titer data of all or specified antigens and sera to a .csv file.

Usage

save.titerTable(map, filename, antigens = TRUE, sera = TRUE)

Arguments

Value

No return value, called for the side effect of saving the titer data to the file.

See Also

Other functions for working with map data: acmap(), addOptimization(), agReactivityAdjustments(), as.json(), edit_agNames(), edit_srNames(), keepBestOptimization(), keepSingleOptimization(), layerNames(), orderPoints, read.acmap(), read.titerTable(), removePoints, save.acmap(), save.coords(), subsetCommonPoints, subsetMap()

Description

This sets the acmap legend used when viewing a map for example.

Usage

setLegend(map, legend, fill, style.bottom = "8px", style.right = "8px")

Arguments

Value

Returns the updated acmap object

See Also

Other functions to view maps: RacViewer.options(), RacViewer(), export_viewer(), ggplot.acmap(), mapGadget(), plot.acmap(), view.acmap(), view.default(), view()

Description

Sorts all the optimization runs for a given map object by stress (lowest to highest). Note that this is done by default when running optimizeMap().

Usage

sortOptimizations(map)

Arguments

Value

An acmap object with optimizations sorted by stress.

See Also

Other functions to work with map optimizations: keepOptimizations(), optimizationProperties, removeOptimizations()

Description

Split a map made up from titer layers into a list of separate maps each with a titer table corresponding to one of the layers

Usage

splitTiterLayers(map)

Arguments

Value

A list of acmap objects

See Also

Other map merging functions: RacMerge.options(), htmlMergeReport(), mergeMaps(), mergeReport()

Description

These functions get and set the sera attributes for a map.

Usage

srIDs(map)
srIDs(map) <- value
srDates(map)
srDates(map) <- value
srReference(map)
srReference(map) <- value
srNames(map)
srNames(map) <- value
srExtra(map)
srExtra(map) <- value
srPassage(map)
srPassage(map) <- value
srLineage(map)
srLineage(map) <- value
srReassortant(map)
srReassortant(map) <- value
srStrings(map)
srStrings(map) <- value
srSpecies(map)
srSpecies(map) <- value

Arguments

Value

Returns either the requested attribute when using a getter function or

the updated acmap object when using the setter function.

See Also

agAttributes()

Other antigen and sera attribute functions: agAttributes, agGroups(), agHomologousSr(), agLabIDs(), agSequences(), ptAnnotations, ptClades, srGroups(), srHomologousAgs(), srSequences()

Description

These functions get and set the sera groupings for a map.

Usage

srGroups(map)

srGroups(map) <- value

Arguments

Value

A factor vector of serum groups

See Also

Other antigen and sera attribute functions: agAttributes, agGroups(), agHomologousSr(), agLabIDs(), agSequences(), ptAnnotations, ptClades, srAttributes, srHomologousAgs(), srSequences()

Description

Get and set indices of homologous antigens to sera in an antigenic map

Usage

srHomologousAgs(map)

srHomologousAgs(map) <- value

Arguments

Value

A list, where each entry is a vector of indices for homologous antigens, or a length 0 vector where no homologous antigen is present.

See Also

Other antigen and sera attribute functions: agAttributes, agGroups(), agHomologousSr(), agLabIDs(), agSequences(), ptAnnotations, ptClades, srAttributes, srGroups(), srSequences()

Description

Getting and setting sera sequence information

Usage

srSequences(map, missing_value = ".")

srSequences(map) <- value

srNucleotideSequences(map, missing_value = ".")

srNucleotideSequences(map) <- value

Arguments

Value

A character matrix of sequences with rows equal to the number of sera.

See Also

Other antigen and sera attribute functions: agAttributes, agGroups(), agHomologousSr(), agLabIDs(), agSequences(), ptAnnotations, ptClades, srAttributes, srGroups(), srHomologousAgs()

Description

This is a utility function to help standardise antigen names into a more consistent format, also attempting to break apart different components of the name.

Usage

standardizeStrainNames(
  names,
  default_species = NA,
  default_virus_type = "A",
  default_virus_subtype = "HXNX"
)

Arguments

Value

Returns a tibble of standardised names and extracted information

Description

Get a stress table from an acmap

Usage

stressTable(map, optimization_number = 1)

Arguments

Value

Returns a matrix of stresses, showing how much each antigen and sera measurement contributes to stress in the selected or specified optimization.