Plot Falconer Genotype-Specific Quantitative-Trait Distributions

Source: R/plot_falconer_distribution.R

Displays the three normal quantitative-trait distributions implied by a validated single-trait Falconer model. Large QTL variance separates the genotype distributions relative to their residual variation; small QTL variance makes them overlap heavily.

plot_qtl_genotype_distribution(
  qtl_var,
  tau,
  pd,
  type = c("density", "histogram", "binned"),
  scale = c("density", "frequency"),
  n = 3000,
  seed = NULL,
  show_means = TRUE,
  verbose = FALSE,
  title = NULL,
  return_data = FALSE,
  bins = 30L
)

Arguments

qtl_var

QTL variance in (0, 1).

tau

Dominance-to-additivity ratio.

pd

Increaser-allele frequency in (0, 1).

type

One of "density" for theoretical normal curves, "histogram" for a simulated population, or "binned" for a deterministic histogram-style display calculated from Normal CDF differences.

scale

Either "density" or "frequency". For theoretical curves, frequency scaling weights each density by its Hardy–Weinberg genotype frequency. For histograms, it selects normalized densities or counts.

n

Total population size simulated in histogram mode.

seed

Optional non-negative integer used locally for reproducible histogram simulation. The caller's random-number state is restored.

show_means

Logical; mark the three theoretical genotype means.

verbose

Logical; passed to the validated Falconer parameter backend.

title

Optional plot title.

return_data

Logical; return the plotting data frame instead of the ggplot object. The Falconer model is retained in its falconer_model attribute.

bins

Positive integer number of equal-width bins used when type = "binned". This does not affect the existing density or simulated histogram modes.

Value

A ggplot object, or a plotting data frame when return_data = TRUE.

Details

Conditional on genotype j, the plotted trait follows a normal distribution with the corresponding Falconer mean and common residual variance 1 - qtl_var. Genotypes 0, 1, and 2 have Hardy–Weinberg frequencies (1 - pd)^2, 2 * pd * (1 - pd), and pd^2. Genotypes may also be interpreted as bb, Bb, and BB, respectively.

Density and binned modes are analytic and perform no simulation. In binned mode, each conditional bin probability is the difference between Normal CDF values at the upper and lower bin boundaries. Histogram mode first samples genotypes from their Hardy–Weinberg frequencies and then samples trait values from the corresponding conditional normal distributions. The x-axis is the quantitative-trait value. In analytic density mode, the y-axis is genotype-specific density when scale = "density" and population-weighted density when scale = "frequency". Binned mode uses conditional bin probability divided by bin width, with an additional genotype-frequency multiplier under scale = "frequency". In simulated histogram mode, the y-axis is normalized density or bin count for those respective scales.

Examples

# A large QTL effect visibly separates the genotype distributions.
plot_qtl_genotype_distribution(
  qtl_var = 0.5, tau = 0, pd = 0.25, scale = "frequency"
)


# A very small QTL effect produces almost complete overlap.
plot_qtl_genotype_distribution(
  qtl_var = 0.0005, tau = 0, pd = 0.25, scale = "frequency"
)