addExtraMarkers: Add extra markers
In rohan-shah/mpMap2: Genetic Analysis of Multi-Parent Recombinant Inbred Lines

Description Usage Arguments Details Value Examples

Add extra markers to a map, using a QTL-mapping style approach.

addExtraMarkers(
  mpcrossMapped,
  newMarkers,
  useOnlyExtraImputationPoints = TRUE,
  reorderRadius = 103,
  maxOffset = 50,
  knownChromosome,
  imputationArgs = NULL,
  onlyStatistics = FALSE,
  orderCrossArgs = list(),
  verbose = TRUE,
  reorder = TRUE
)

`mpcrossMapped`	An object of class `mpcrossMapped` (dataset with a map), which must include imputed IBD genotypes and recombination fraction data.
`newMarkers`	An object of class `mpcross` containing the new markers to add.
`useOnlyExtraImputationPoints`	Should we only attempt to add the new marker at points at which imputation data has been generated, which are not markers? Currently this must be `TRUE`. In future `FALSE` may be allowed.
`reorderRadius`	The width of the region (in terms of number of markers) in which to attempt to reorder, after the extra markers are added.
`maxOffset`	The maxOffset parameter for the call to `estimateMap`, which is used to re-estimate the map (locally), after the additional markers are added.
`knownChromosome`	The name of a chromosome, if the extra markers are known to go on a specific chromosome
`imputationArgs`	A list containing additional arguments to `imputeFounders`.
`onlyStatistics`	If this argument is `TRUE`, then only the chi-squared test statistic values are computed, and the markers are not added.
`orderCrossArgs`	A list containing additional arguments to `orderCross`.
`verbose`	Should extra logging output be generated?
`reorder`	Should local reordering be performed after the extra markers are added?

This function uses a QTL-mapping style approach to add extra markers to an existing map. The code uses the imputation data at a collection of points, and the marker alleles for the first marker of the extra markers. If the imputed genotype at a point is independent from the genotype at the new marker, then the new marker probably should not be mapped to that point. If the imputed genotype at a point and the marker allele are strongly dependent, then the new marker should probably be mapped to that point. Dependence and independence are measured using a chi-squared test stastistic for independence. All the extra markers are then mapped to the position where the test statistic is largest. It is recommended that only single markers be added at a time, unless you are extremely confident that all the extra markers should be located at the same position.

Currently the set of points at which the new markers are considered for addition is the set of points at which imputation data is available, which are not markers. The intention is that this set of points should be an equally spaced grid of points; this reduced the number of tests that are performed, as generally there are far fewer points in the grid, than there are markers. After the new marker is added, local reordering will need to be performed anyway, making any loss in accuracy by using the grid of points largely irrelevant. In future it may be possible to use the set of all marker positions as the set of points at which tests are performed, by setting useOnlyExtraImputationPoints to FALSE.

Once the extra markers have added, local reordering is optionally performed, depending on argument reordering. The radius of the region on which reordering is performed, in terms of the number of markers, is reorderRadius.

Once the optional reordering step has been performed, the map is recomputed locally, to account for the addition of the extra markers. The argument maxOffset is passed through to estimateMap. Finally, the imputation data will be recomputed if imputationArgs is not NULL; in that case, imputationArgs should contain a list of arguments to imputeFounders. It is recommended that the imputation data be recomputed if further markers are to be added.

In some cases the user will want to apply a threshold to the maximum value of the test statistics, and only add the marker if the test statistics exceed the threshold. In this case the function should be called twice. For the first call, onlyStatistics should be set to FALSE. If the resulting test statistics exceed the threshold, then addExtrMarkers should be called again with onlyStatistics set to TRUE.

If onlyStatistics was set to TRUE, an object of class addExtraMarkersStatistics containing the test statistic values. If onlyStatistics was set to FALSE, a list containing the test statistic values in entry statistics and in entry object, a new object containing the input object with the new markers added.

data(simulatedFourParentData)
#Create object that includes the correct map
mapped <- new("mpcrossMapped", simulatedFourParentData, map = simulatedFourParentMap)
#Remove marker number 50. Normally the map is discarded, but we specify to keep it. 
removedMiddle <- subset(mapped, markers = (1:101)[-50], keepMap = TRUE)
#Compute imputation data, at all the markers, and an equally spaced grid of points
removedMiddle <- imputeFounders(removedMiddle, errorProb = 0.02, 
	extraPositions = generateGridPositions(1))
#Estimate recombination fractions
removedMiddle <- estimateRF(removedMiddle)
#Get out the extra marker to add
extraMarker <- subset(simulatedFourParentData, markers = 50)
#Add the extra marker, without doing any local reordering. After the marker is added, 
#	recompute the imputation data, using the same arguments as previously. 
withExtra <- addExtraMarkers(mpcrossMapped = removedMiddle, newMarkers = extraMarker, 
	reorder = FALSE, imputationArgs = list(errorProb = 0.02, 
	extraPositions = generateGridPositions(1)))$object