The gl.sim.WF.run() call (about 20 s) in the
examples of gl.sim.WF.run() and
gl.sim.WF.table() is wrapped in \donttest{} to
keep the CRAN example run short.
gl.He() and gl.Ho() are back in
dartR.base (unchanged), where the CRAN release of dartR.sim imports them
from; dartR.sim imports gl.He() from dartR.base
again.
File-backed objects made by gl.sim.mutate() and the
simulation functions place their backing files through
dartR.base::utils.fbm.new()/utils.fbm.copy(),
so they honour getOption("FBM.dir"). Needs dartR.base >=
1.2.7.9000.
gl.He(), gl.Ho(),
gl.report.nall(), gl.sim.ind() (through the
internal allele frequencies),
gl.sim.WF.run(real_freq = TRUE) and the internal
per-population helpers (Hudson Fst, inbreeding) read the genotypes in
blocks of loci with dartR.base::utils.fbm.colwise(), per
population by row indices instead of seppop() copies. A
file-backed object is no longer decoded as a whole; results are
identical to those of the same data held in memory (tested for both
storage types and any block size). The former big_counts()
path of the internal allele frequencies divided counts directly and
could differ from colMeans() in the last digit; it now
gives exactly the in-memory values.
do.call(fun, list(x = gl, ...)) no longer store the whole
input object in @other$history (the calls are compacted
with dartR.base::utils.history.call()), and no longer stop
with “cannot coerce type ‘closure’” at verbose >= 1.
Needs the current dartR.base.gl.sim.mutate(): BUG FIX, stopped on a file-backed
object because it read the empty @gen slot. It now mutates
a copy of the FBM (the input object is not changed) and gives the same
result as for a gen-backed object with the same seed.
gl.sim.ind(), gl.sim.offspring(),
gl.sim.Neconst() and gl.sim.ind.af() now
return objects in the flavour the user works with.
gl.sim.ind() and gl.sim.offspring() return a
file-backed object (genotypes in @fbm) when the input
object (for offspring: fathers or mothers) is file-backed, and a
gen-backed one otherwise. gl.sim.Neconst() and
gl.sim.ind.af() gain an argument fbm (default
getOption("dartR_fbm")). Missing genotypes are stored in
the file-backed matrix as the raw code 3, read back as NA.
For the same seed, both flavours give identical genotypes.
gl.sim.ind() computes the allele frequencies of a
file-backed input without decoding its genotype matrix.
vignette("simulations_tutorial", package = "dartR.sim")):
a complete tutorial of gl.sim.WF.table() and
gl.sim.WF.run(), from the reference table to simulating a
dataset that reproduces a real genlight, with pedigree and
family-structured samples, and checking simulations with
gl.diagnostics.sim().plot.colors.pop with
population names now go to the populations they name. Before, the names
were replaced by the population levels, so the colours were assigned by
position. Unnamed colours and the default palette are unchanged.sample_crosses and
sample_design: planted crosses recreate mating designs with
shared parents (e.g. 4 litters from 2 sires x 2 dams:
sample_families = "5 5 5 5",
sample_design = "2x2"). Parents are drawn from the previous
generation; the offspring are only sampled and do not join the
population. ind.metrics gains sample_cross and
parent_label.sample_families and
sample_parents: stored samples can be made of full-sib
families of given sizes (e.g. clutches), drawn from the offspring pool,
optionally with their parents, from generation 1.
ind.metrics gains sample_role and
family; the pedigree gains in_population,
FALSE for sampled offspring that did not join the population.real_sample_size now stores exactly x’s sample size per
population (it was rounded up to an even number); an odd sample has one
extra individual of a random sex.inbreeding_founders: the founders’ F, one
value or one per population, replacing the F estimated from x (with or
without real_inbreeding). Heterozygote dropout inflates F
in the full locus set, so F can be estimated on high call-rate loci
while x keeps all loci for the frequencies.store_pedigree: each iteration carries the
attribute “pedigree”, every individual of every generation, sampled or
not (id, pat, mat, generation, pop, F_founder), so kinship can be traced
through ancestors that were not stored. Off by default.ne_phase1 and ne_phase2: a
target Ne per population (for example from gl.LDNe());
variance_offspring is set to reach it, using Ne / N = k /
(k + 1), or k / (2k + 1) with replace_parents = TRUE
(checked against the loss of heterozygosity). A target above N (N/2 with
replacement) is capped with a warning.variance_offspring_phase1/2 accept one value per
population.real_sample_size: stored samples have x’s
sample sizes instead of sample_percent, so populations can
be larger than samples.real_migration multiplies the transfers by N / Ne: FST
depends on Ne m, so with replace_parents = TRUE (Ne about
N/2) the old rate held FST near twice x’s value.sim.vars stores ne_expected,
variance_offspring_used and
population_size_used; with real_migration, generation 0
also stores the phase-2 rate.Ne defaults to the expected Ne stored by
gl.sim.WF.run().population_size_used), which differ from
population_size_phase2 with
real_pop_size = TRUE.real_migration: individuals transferred
per pair of populations and generation are set from x’s FST (Hudson’s),
as T = (1 / FST - 1) / (4 n) for the island model with n populations
(dispersal_type = "all_connected"). Fractional T is drawn
per pair and event; T is stored in
sim.vars$migrants_real.real_freq_shrink: with
real_freq = TRUE, population frequencies are shrunk toward
their mean, q’ = mean + lambda (q - mean). "auto" picks
lambda so that sampling noise in x does not inflate FST among founders;
a number sets lambda. NULL (default) does not shrink. The lambda used is
stored in sim.vars$freq_shrink_lambda.store_founders: the founders of the first
phase simulated are stored, before they reproduce, as “generation_0”.
ind.metrics holds F_founder and
F_founder_map, the proportions of loci and of the map
identical by descent (0 unless real_inbreeding = TRUE), and
no parents, so the pedigree of later generations starts from stored
individuals. Off by default; seeded outputs are unchanged.sib_mating_phase1 and
sib_mating_phase2: the proportion of pairs that are full
siblings, one value or one per population. At equilibrium F = b / (4 -
3b). NULL (the default) is random mating, and seeded outputs are
unchanged.real_inbreeding: F = 1 - Ho / He is
estimated in each population of x. The founders are made
inbred (stretches of the chromosome identical by descent, a fraction F
of the map, mean 25 cM), and phases whose sib_mating is
NULL use the proportion of sib matings that keeps F, b = 4F / (1 + 3F).
A sib_mating value that is set wins.sim_variables.csv files without the new variables still
run.number_transfers: 2 or more swap ceiling(n/2)
males and floor(n/2) females in each direction; 1 swaps one individual,
alternating male and female from one dispersal event to the next for
that pair; 0 switches the pair off. Before, two switches set from the
phase’s number_transfers were carried from row to row: a
file row of 3 with the phase at 1 moved 2 males and no females, a row of
1 with the phase at 2 switched the later rows off every other
generation, and with an even number of pairs each pair always swapped
the same sex. Seeded outputs change for runs with one transfer
and more than one pair, and for dispersal files whose values differ from
the phase setting; single-pair runs (the default example) and
runs with 2 or more transfers everywhere are unchanged.gl.sim.ind()), not from subsampling the real
individuals, so it need not reach 1 at the full sample size.verbose = 0 is silent (it printed the messages of
gl.filter.allna() and gl.colors()).reps = 1) no
longer crashes; simlevels, reps and
ncores are validated (reps = 0 ran two
replicates and now stops with an error).ncores = 1 runs without starting a cluster (0.55 s
instead of 3.7 s for the possums.gl example).sim is returned as a data.frame, as
documented (it was a tibble).Arguments are validated: number_pops of 0, 1 or
fractional, transfer_each_gen = 0, negative or fractional
number_transfers and an unknown dispersal_type
now stop with an error. Before, they gave opaque errors or wrote tables
that gl.sim.WF.run() could not use (a pair with population
0; transfer_each_gen = 0 stopped the simulation
later).
A missing outpath falls back to
tempdir() with a warning.
Returns the dispersal table invisibly (it returned
NULL); messages use cat() like other dartR
functions, and the saved path is printed without a trailing “/”. ##
gl.sim.Neconst
Allele counts are drawn on the population’s 2N gene copies, conditioned on polymorphism, and placed at random among individuals. Before, frequencies came from a grid of 4N + 1 points and were resampled, so about 19% of the requested SNPs were monomorphic and singletons were 18% short of the neutral spectrum. Output changes: every locus is polymorphic and the spectrum matches the neutral expectation.
Title and documentation describe the model: theta = 4 * ninds *
mutation_rate, ninds is Ne, and mutation_rate
changes the output only when theta approaches 1.
Inputs are validated (fractional nlocs now stops
with an error).
verbose follows the dartR default: start/end
messages print at the default verbosity. The history records this call;
loc.metrics holds AlleleID and
ind.metrics gains pop. ##
gl.sim.mutate
No mutations are applied when none are drawn. Before, a
1:0 loop applied 1-2 mutations in every such call, so
mut.rate = 0 still mutated and the default rate gave
testset.gl about 1.7 mutations per call instead of 0.13.
Output changes whenever the draw is 0.
SilicoDArT input stops with an error (it got presence/absence scores of 2).
Locus metrics flags are reset after mutation.
Only the mutated individual is converted, not the whole matrix: 40 mutations on 500 individuals x 20,000 loci take 0.04 s instead of 7.9 s. Seeded results are unchanged.
mut.rate is validated; new verbose
argument; history is recorded. ## gl.sim.emigration
emi.m moves individuals from column to row, as
documented. Before, the direction was reversed: a matrix sending the
emigrants of A to B moved B individuals into A. Output of every
emi.m run changes; emi.table runs
keep their direction.
Emigrants are drawn from the residents at the start of the call
and all move at once, so an individual moves at most once (before, a
migrant could move again in the same call). Seeded outputs
change, and the order of individuals changes (still grouped by
population). About 35 times faster (0.39 s -> 0.011 s for the
possums.gl example).
A population can lose all its individuals (before, the function stopped). Asking for more emigrants than a population holds stops with an error naming it.
ind.metrics$pop is updated for moved
individuals.
Inputs are validated: matrices of the wrong dimension and
perc.mig outside 0-1 now stop with an error; data frames
are accepted; an all-zero emi.m column means nobody leaves;
a list of length 1 is handled as a list, and unnamed list elements are
named after their population.
perc.mig is documented as a proportion (it always
was one).
New verbose argument; one history entry per
call.
Frequencies and sizes are matched to populations by name. Before,
a table not sorted alphabetically gave some populations another
population’s frequencies (Z listed before A: Z simulated at 0.10 instead
of 0.90), and a factor popn with named
pop.sizes swapped the sizes. Output changes for
those inputs; sorted tables such as
gl.allele.freq() output are unaffected.
frequency is documented as the alternate-allele
frequency (the allele counted in the genotypes), which is what the code
has always used.
Returns a dartR object; loc.metrics
holds AlleleID (it had a column named
array(NA, nLoc(x))), and ind.metrics gains
id and pop.
Fractional or NA pop.sizes, and
duplicate population-locus rows, stop with an error (they were truncated
or dropped silently).
Genotypes are drawn with rbinom() in R instead of
C++ compiled at run time: no compiler is needed and the first call no
longer takes ~3 s. Seeded outputs change; the genotype
distribution is unchanged.
New verbose argument; history is recorded. ##
gl.sim.offspring
Loci are inherited independently. Before, ifelse()
recycled the random draws, so some pairs of loci were always passed on
together (a mother heterozygous at loci 1 and 11 passed the same allele
at both in every offspring). Seeded outputs change,
including the sibs simulated by
dartR.captive::gl.sim.relatedness().
Each mother has exactly noffpermother offspring
(before, mothers were drawn at random and could get none).
Family sizes change.
Parents must be SNP data with the same loci in the same order; otherwise the function stops.
The offspring are a dartR object with the mothers’
locus metadata, and @other$ind.metrics records sex, mother
and father. @other$sex is kept.
plot, he,
fst) instead of the plot alone; use $plot for
the plot.verbose = 0 is silent.NA genotypes instead of stopping
the function (its own example failed on testset.gl).rbinom(): about 40 times
faster (46 s -> 1.2 s for 1000 individuals x 10,080 loci).
Seeded outputs change; the Hardy-Weinberg genotype
distribution is unchanged.verbose argument; history is recorded;
n is validated.... no longer put quotes
around chromosome_name; before, any ...
override made real_loc = TRUE and the map/targets
chromosome lookups fail unless chromosome_name was also
passed.real_freq = TRUE with real_loc = FALSE now
returns loci typed "real". Before, it stopped with an error
or returned those loci with NA values.from/to is used, and
neutral loci are spread over the whole mapped chromosome. Output
changes for maps whose intervals are not aligned to
chunk_bp from position 1 (including
fly_recom_map.csv). NA in cM now
marks an interval as not recombining instead of breaking the call.loci_deleterious >= chunk_number now returns exactly
the number of loci requested (before, 149 gave 100 and 150 gave 200).
Output changes when loci_deleterious is
not a multiple of chunk_number.q (0.5) and s (0.99, -0.5) now
apply to each locus class according to that class’s own distribution
setting, are documented, and are reported at
verbose >= 1. Output changes when
deleterious and advantageous settings differ.... that are not simulation
variables now stop the function with an error. Before, they were
ignored.stop(error(...))).fly_recom_map.csv and
fly_targets_of_selection.csv now ship in
inst/extdata.With 10 or more populations, individuals are now labelled with the population they belong to. Before, the labels were scrambled: for example, individuals of population 10 were labelled “2” and those of population 2 were labelled “5”. Population labels change for runs with 10 or more populations.
Recombination now follows the map. Each gamete gets a Poisson
number of crossovers with mean equal to the map length, independently of
its siblings. Before, a meiosis had at most one new crossover (none when
the Poisson draw was 1), and crossovers accumulated from one sibling to
the next. Output changes for every run with
recombination = TRUE.
Advantageous selection now acts when local_adap is
NULL. Before, it was silently switched off in every
population. Output changes for runs with selection and
advantageous loci.
Clinal adaptation indexes populations by their position in the
cline; populations outside the cline get advantageous
s = 0; the multiplier is floored at 0. Output
changes for clinal runs.
Returned elements are named by the generation they hold. Before,
names were shifted with phase1 = TRUE and were
NA for iterations after the first.
Extinction is detected at any verbose and for each
population; the iteration stops and the generations stored so far are
returned. Before, it crashed or overwrote the last stored
generation.
Mutation only uses loci of type mutation_neu,
mutation_del and mutation_adv; an empty pool
is skipped. Before, lost neutral and selected loci also received
mutations. Output changes for mutation runs.
Real allele frequencies (real_freq = TRUE) use the
alternative allele, fill missing frequencies from the pooled frequency,
and follow locus position. Before, the coding was flipped.
Output changes for real-frequency runs.
Phase-2 founders are sampled without replacement when phase 1 has
enough individuals. Output changes for runs with
phase1 = TRUE.
Each connected pair of populations now exchanges individuals once
per migration event (it was twice). Migration rate halves for
dispersal types line, circle and
all_connected.
A warning is printed when relative selection is weakened by a small offspring pool.
Names passed through ... that are not simulation
variables now stop the function; local_adap = "1 2" and
clinal_adap work through ....
phase1 = TRUE works with real_pops and
real_pop_size; the interactive route no longer fails on
replace_parents.
The pool of mutation loci is reset at the start of each
iteration, so iterations are independent replicates. Output
changes for mutation runs with
number_iterations > 1.
C++ helpers are compiled once per session.
@details now describes the model.
gl.sim.WF.run() swaps individuals in both directions for
each row. Migration halves for runs that use a newly generated
dispersal file.