Use a forward table cache to propagate

An in-memory cache for forward tables, which has already been filled, can be used to move more quickly to a specified locus.

Usage

ForwardUsingTableCache(
  fwd,
  pars,
  cache,
  t = fwd$l - 1,
  nthreads = min(parallel::detectCores(logical = FALSE), fwd$to_recipient -
    fwd$from_recipient + 1)
)

Arguments

fwd

a kalisForwardTable object, as returned by MakeForwardTable().

pars

a kalisParameters object, as returned by Parameters().

cache

a cache of forward tables as generated by CreateForwardTableCache() and filled using FillTableCache().

t

a locus position to move the forward table to, starting the forward propagation from whatever table in the cache variable is immediately before locus t. By default, it simply advances to the previous locus (which is the natural direction to move when using the cache).

nthreads

the number of CPU cores to use. By default no parallelism is used.

Value

There is nothing returned.

NOTE: for performance reasons, fwd is updated in-place.

Details

If the objective is to run the Li and Stephens hidden Markov model both forwards and backwards to the same locus (and to do so for every possible locus), then considerable efficiency can be achieved by first performing a full scan forwards, filling a geometrically spaced cache whilst doing so. Then, by working backwards, the backward propagation moves one locus at a time and the forward propagation can move backwards by moving forward from a recently cached local table.

Memory for a cache can be allocated using CreateForwardTableCache() and should then be filled with FillTableCache(). To use the cache, then instead of using the Forward() function, use this function.

Note that the cache which is passed to this function will be dynamically updated based on the locus requested: the assumption is that the cache is used to propagate in reverse so any cache entries for a locus position past t are taken to be no longer needed and that space will redeployed to more densely fill the cache with earlier locus positions.

References

Christ, R.R., Wang, X., Aslett, L.J.M., Steinsaltz, D. and Hall, I. (2024) "Clade Distillation for Genome-wide Association Studies", bioRxiv 2024.09.30.615852. Available at: doi:10.1101/2024.09.30.615852 .

See also

MakeForwardTable() to make a forward table; CreateForwardTableCache() to generate a cache; FillTableCache() to fill a cache; Forward() for forward function without using a cache.

Alternatively, see ForwardIterator() to create an iterator which internally creates or uses a table cache.

Examples

if (FALSE) { # \dontrun{
# This code assumes you have already:
#  i) cached the haplotypes using CacheHaplotypes function
#  ii) setup parameters in a variable called pars
#  iii) set the number of loci in a variable called L

# Allocate up to 10GB to a cache, with parameters already setup in pars ...
cache <- CreateForwardTableCache(pars, 10)
# ... and fill it
FillTableCache(cache, pars, nthreads = 8)

# Create forward and backward tables
fwd <- MakeForwardTable(pars)
bck <- MakeBackwardTable(pars)

# Then reach every locus faster by iterating backwards, using the cache to
# move the forward table into position faster
for(l in L:1) {
  Backward(bck, pars, l, nthreads = 8)
  ForwardUsingTableCache(fwd, pars, cache, l, nthreads = 8)
  # Do whatever work is required at
  # every locus here using fwd and bck
}
} # }