Package 'heritable'

Parametric bootstrap for an asreml model.

Description

Simulate $\hat{y} \sim N(X\hat{\beta}, V)$ according to the current asreml fit and then refit to obtain the targeted statistics.

Usage

bootstrap_asreml(
  model,
  FUN,
  nsim = 1,
  use.u = FALSE,
  source = list(),
  seed = NULL,
  ...
)

Arguments

model	An asreml fitted model. Must be fitted with model.frame = TRUE.
FUN	A function with signature ⁠function(fit)⁠ returning a scalar (the statistic to bootstrap).
nsim	Integer. Number of bootstrap replicates.
use.u	A logical indicating whether to resample random effects, or only resample residuals.
source	The known genomic relationship matrix (GRM) used in model fitted using asreml::vm(), provided as a named list. When not provided (an empty list by default), the GRM variable used for vm calling will be searched in the global environment.
seed	Optional integer seed for reproducibility.
...	Additional arguments passed to boot::boot().

Details

Fits parametric bootstrap replicates for an asreml model by:

• Extracting the fixed-effect fit yhat = X * beta.

• Extracting V = Var(y) on the observation scale,

• Simulating new responses y* = yhat + L %*% z where L is a Cholesky factor of V,

• Refitting the same asreml call on each simulated dataset,

• Returning a boot object.

Value

A boot object.

Examples

## Not run: 
  lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
  lettuce_asreml <- asreml(
    fixed = y ~ rep * pseudo_var1,
    random = ~gen,
    sparse = ~pseudo_var2,
    data = lettuce_subset,
    trace = FALSE
  )

  b <- bootstrap_asreml(
    lettuce_asreml,
    R = 200,
    statistic = function(fit) coef(fit)$fixed["(Intercept)", "effect"],
    seed = 1
  )
  boot::boot.ci(b, type = "perc")
 
## End(Not run)

---

Bootstrap confidence interval for heritability

Description

Computes a confidence interval for a heritability estimate using parametric bootstrap of the underlying mixed model. Parallel computing is supported through boot::boot()

Usage

## S3 method for class 'heritable'
confint(
  object,
  parm = NULL,
  level = 0.95,
  B = 100,
  random_effect = c("resample", "conditional"),
  type = c("basic", "norm", "perc"),
  return_model = TRUE,
  seed = NULL,
  ...
)

Arguments

object	A heritability object returned by H2() (broad-sense) h2() (narrow-sense). The object must store the fitted model as an attribute.
parm	a specification of which methods are to be given confidence intervals, either a vector of numbers or a vector of names. If missing, all methods are considered.
level	Confidence level.
B	Integer. Number of bootstrap replicates.
random_effect	Character. Strategy for handling random effects. "resample" Resample random effects to propagate uncertainty. "conditional" Condition on estimated random effects.
type	Character. Bootstrap interval type; one of "basic", "norm", or "perc".
return_model	Logical. Whether to return to the boot object.
seed	Optional random seed.
...	Additional arguments passed to the bootstrap routine. Check boot::boot(), as well as the examples below for parallel computation

Value

A matrix of confidence intervals.

See Also

boot::boot(), H2()

Examples

## Not run: 
  lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
  lettuce_asreml <- asreml(
    fixed = y ~ rep * pseudo_var1,
    random = ~gen,
    sparse = ~pseudo_var2,
    data = lettuce_subset,
    trace = FALSE
  )

  my_H2 <- H2(lettuce_asreml, "gen", c("Cullis", "Standard"))

  my_ci <- confint(my_H2)

  # Get bootstrap model
  boot_mod <- attr(my_ci, "boot_mod")
  boot_mod$t # Check bootstrap statistics

  # Parallel computing (On Windows)
  # Note that for asreml, `ncpus` can't be larger than the number of asreml
  # license available
  confint(my_H2, parallel = "snow", ncpus = 3)

  # Parallel computing (On non-Windows)
  confint(my_H2, parallel = "multicore", ncpus = 3)


## End(Not run)

---

Fixed-effects-only fitted values from an asreml model

Description

Returns the fitted values based on fixed effects only ($\hat{y} = X\hat{\beta}$), excluding all random effects.

Usage

get_fixed_fit_asreml(model, source = list())

Arguments

model	An object of class "asreml", fitted with model.frame = TRUE.
source	The known genomic relationship matrix (GRM) used in model fitted using asreml::vm(), provided as a named list. When not provided (an empty list by default), the GRM variable used for vm calling will be searched in the global environment.

Details

This function reconstructs the fixed-effect design matrix from the stored model frame and multiplies it by the estimated fixed coefficients. Sparse fixed terms (if any) are included.

Random effects (BLUPs) are not included.

Value

A numeric vector of length $N$, giving the fixed-effects-only fitted value for each observation.

---

Calculate broad-sense or narrow sense heritability from model object

Description

A case-specific wrapper for calculating broad / narrow sense heritability.

• The lowercase prefix h2_ refers to the wrapper or subfunctions e.g. h2_Oakey() for calculating narrow sense heritability

• The upper case prefix H2_ refers to the wrapper or subfunctions e.g. H2_Delta() for calculating broad sense heritability

Usage

h2(model,
   target,
   method = c("Cullis", "Oakey", "Piepho", "Delta", "Standard"),
   options = NULL,
   marginal = TRUE,
   stratification = NULL,
   source = list(),
   vc = NULL,
   ...)

H2(model,
   target,
   method = c("Cullis", "Oakey", "Piepho", "Delta", "Standard"),
   options = NULL,
   marginal = TRUE,
   stratification = NULL,
   source = list(),
   vc = NULL,
   ...
   )

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
method	Character vector of name of method to calculate heritability. See details.
options	NULL by default, for internal checking of model object before calculations
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
source	The known genomic relationship matrix (GRM) used in model fitted using asreml::vm(), provided as a named list. When not provided (an empty list by default), the GRM variable used for vm calling will be searched in the global environment. Ignored for broad-sense and lmerMod methods
vc	A list of precomputed variance components. Should be in the same structure as the output of var_comp()
...	Additional arguments that specify heritability calculation when interactions with genotype effects are modelled

Details

The following methods are currently implemented for narrow-sense heritability h2(method = "XX"):

• "Cullis":

  $H^2_{Cullis} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ..}}{2\sigma^2_g}$

• "Oakey":

  $H^2_{Oakey} = \frac{\sum_{i = n_z+1}^{n_g} \lambda_i}{\sum_{n_g}^{\lambda_i\neq 0}}$

• "Piepho":

  $H^2_{Piepho} = \frac{\sigma^2_g}{\sigma^2_g + \overline{PEV_{BLUE_g}} / 2}$

• "Delta":

  $H^2_{\Delta ij} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ij}}{\operatorname{Var}(g_i - g_j)}$

• "Standard":

  $H^2_{Standard} = \frac{\operatorname{Var}(g_i - g_j)}{\operatorname{Var}(y_i.. - y_j..)}$

The following methods are currently implemented for broad-sense heritability H2(method = "XX"):

• "Cullis":

  $H^2_{Cullis} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ..}}{2\sigma^2_g}$

• "Oakey":

  $H^2_{Oakey} = \frac{\sum_{i = n_z+1}^{n_g} \lambda_i}{\sum_{n_g}^{\lambda_i\neq 0}}$

• "Piepho":

  $H^2_{Piepho} = \frac{\sigma^2_g}{\sigma^2_g + \overline{PEV_{BLUE_g}} / 2}$

• "Delta":

  $H^2_{\Delta ij} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ij}}{2\sigma^2_g}$

• "Standard":

  $H^2_{Standard} = \frac{\sigma^2_g}{\sigma^2_g + \frac{1}{n_g}\sum_{n_g}^{i=1} \sigma^2_p / n_{gi}}$

For further details of a specific method - take a look at helpfile for each subfunctions ?H2_Cullis

Value

A named numeric vector, length matching number of methods supplied

References

• Cullis, B. R., Smith, A. B., & Coombes, N. E. (2006). On the design of early generation variety trials with correlated data. Journal of Agricultural, Biological, and Environmental Statistics, 11(4), 381–393. https://doi.org/10.1198/108571106X154443

• Oakey, H., Verbyla, A., Pitchford, W., Cullis, B., & Kuchel, H. (2006). Joint modeling of additive and non-additive genetic line effects in single field trials. Theoretical and Applied Genetics, 113(5), 809–819. https://doi.org/10.1007/s00122-006-0333-z

• Schmidt, P., Hartung, J., Rath, J., & Piepho, H.-P. (2019). Estimating Broad-Sense Heritability with Unbalanced Data from Agricultural Cultivar Trials. Crop Science, 59(2), 525–536. https://doi.org/10.2135/cropsci2018.06.0376

• Piepho, H.-P., & Möhring, J. (2007). Computing Heritability and Selection Response From Unbalanced Plant Breeding Trials. Genetics, 177(3), 1881–1888. https://doi.org/10.1534/genetics.107.074229

• Falconer, D. S., & Mackay, T. F. C. (1996). Introduction to quantitative genetics (4th ed.). Longman.

See Also

H2_Cullis(), H2_Oakey(), H2_Delta(), H2_Piepho(), H2_Standard(), h2_Oakey(), h2_Delta(), h2_Standard()

Examples

# lme4 model
lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
lettuce_lme4 <- lme4::lmer(y ~ rep + (1 | gen), data = lettuce_subset)
H2(lettuce_lme4, target = "gen", method = c("Standard", "Delta"))

# asreml model (Requires license)
## Not run: 
lettuce_asreml <- asreml::asreml(fixed = y ~ rep,
                                 random = ~ gen,
                                 data = lettuce_subset,
                                 trace = FALSE
                                 )

H2(lettuce_asreml, target = "gen", method = c("Standard", "Delta"))

## End(Not run)

---

Calculate Cullis' heritability from model object

Description

Compute "generalised heritability" for unbalanced experimental designs. See Cullis, Smith and Coombes (2006) for derivation.

Usage

H2_Cullis(model,
          target,
          options = NULL,
          marginal = TRUE,
          stratification = NULL,
          vc = NULL,
          ...)
h2_Cullis(model,
          target,
          options = NULL,
          marginal = TRUE,
          stratification = NULL,
          vc = NULL,
          ...)

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
options	NULL by default, for internal checking of model object before calculations
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
vc	A list of precomputed variance components. Should be in the same structure as the output of var_comp()
...	Additional arguments that specify heritability calculation when interactions with genotype effects are modelled

Details

The equation for Cullis heritability is as follow

$H^2_{Cullis} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ij}}{2\sigma^2_g}$

where:

• $PEV$ is the prediction error variance matrix of the pairwise differences among BLUPS

• $\sigma^2$ is the variance attributed to differences between genotype

Value

Numeric value

References

Cullis, B. R., Smith, A. B., & Coombes, N. E. (2006). On the design of early generation variety trials with correlated data. Journal of Agricultural, Biological, and Environmental Statistics, 11(4), 381–393. https://doi.org/10.1198/108571106X154443

Examples

# lme4 model
lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
lettuce_lme4 <- lme4::lmer(y ~ rep + (1 | gen), data = lettuce_subset)
H2_Cullis(lettuce_lme4, target = "gen")

# asreml model (Requires license)
## Not run: 
lettuce_asreml <- asreml::asreml(fixed = y ~ rep,
                                 random = ~ gen,
                                 data = lettuce_subset,
                                 trace = FALSE
                                 )

H2_Cullis(lettuce_asreml, target = "gen")

## End(Not run)

---

Calculate Cullis heritability using variance parameters

Description

Compute the Cullis heritability for genotype means using the average variance of pairwise differences of best linear unbiased predictors (BLUPs).

Usage

H2_Cullis_parameters(vd_BLUP_avg, vc_g)

Arguments

vd_BLUP_avg	Numeric. Average variance of pairwise differences among BLUPs
vc_g	Numeric. Genotype variance component

Details

The equation for Cullis heritability is as follow

$H^2_{Cullis} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ij}}{2\sigma^2_g}$

where:

• $PEV$ is the prediction error variance matrix of the pairwise differences among BLUPS

• $\sigma^2$ is the variance attributed to differences between genotype

Value

Numeric value

References

Cullis, B. R., Smith, A. B., & Coombes, N. E. (2006). On the design of early generation variety trials with correlated data. Journal of Agricultural, Biological, and Environmental Statistics, 11(4), 381–393. https://doi.org/10.1198/108571106X154443

Examples

H2_Cullis_parameters(vd_BLUP_avg = 0.25, vc_g = 0.8)

---

Calculate average heritability of differences between genotypes from model object

Description

Instead of computing heritability on a "entry-mean" basis, this method calculates heritability using "entry-differences". Entry here is referring to the genotype, line or variety of interest. See reference for origin and interpretation of h2/H2_Delta and it's variants

Usage

h2_Delta(model,
         target,
         type = c("BLUP", "BLUE"),
         options = NULL,
         marginal = TRUE,
         stratification = NULL,
         vc = NULL,
         ...)

H2_Delta(model,
         target,
         type = c("BLUP", "BLUE"),
         options = NULL,
         marginal = TRUE,
         stratification = NULL,
         vc = NULL,
         ...)

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
type	character, whether heritability is calculated using BLUEs or BLUPs
options	NULL by default, for internal checking of model object before calculations
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
vc	A list of precomputed variance components. Should be in the same structure as the output of var_comp()
...	Additional arguments that specify heritability calculation when interactions with genotype effects are modelled

Details

The broad-sense heritability of differences between genotypes is given by:

$H^2_{\Delta ..} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ..}}{2\sigma^2_g}$

where:

• $PEV^{BLUP}_{\overline\Delta ..}$ is the mean of the prediction error variance matrix for the pairwise differences among BLUPs (BLUEs if method = "BLUE") across all genotypes

• $\sigma^2$ is the variance attributed to differences between genotype

The narrow-sense heritability of differences between genotypes is given by:

$h^2_{\Delta ij} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ij}}{\operatorname{Var}(g_i - g_j)}$

where:

• $g_i$ is the random effect of the $i^{th}$ genotype

See reference page 995 - 997 for full derivation of this heritability measure and related variants

Value

Numeric

References

Schmidt, P., Hartung, J., Rath, J., & Piepho, H.-P. (2019). Estimating Broad-Sense Heritability with Unbalanced Data from Agricultural Cultivar Trials. Crop Science, 59(2), 525–536. https://doi.org/10.2135/cropsci2018.06.0376

See Also

h2_Delta_by_genotype(), H2_Delta_by_genotype(), h2_Delta_pairwise(), H2_Delta_pairwise()

Examples

# lme4 model
lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
lettuce_lme4 <- lme4::lmer(y ~ rep + (1 | gen), data = lettuce_subset)
H2_Delta(lettuce_lme4, target = "gen", type = "BLUP")

# asreml model (Requires license)
## Not run: 
lettuce_asreml <- asreml::asreml(fixed = y ~ rep,
                                 random = ~ gen,
                                 data = lettuce_subset,
                                 trace = FALSE
                                 )

H2_Delta(lettuce_asreml, target = "gen", type = "BLUP")

## End(Not run)

---

Calculate heritability of differences for a given genotype from model object

Description

Instead of computing heritability on a "entry-mean" basis, this method calculates heritability using "entry-differences". Entry here is referring to the genotype, line or variety of interest. See reference for origin and interpretation of h2/H2_Delta_by_genotype and it's variants

Usage

h2_Delta_by_genotype(model,
                     target,
                     type = c("BLUP", "BLUE"),
                     options = NULL,
                     marginal = TRUE,
                     stratification = NULL,
                     vc = NULL,
                     ...)
H2_Delta_by_genotype(model,
                     target,
                     type = c("BLUP", "BLUE"),
                     options = NULL,
                     marginal = TRUE,
                     stratification = NULL,
                     vc = NULL,
                     ...)

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
type	character, whether heritability is calculated using BLUEs or BLUPs
options	NULL by default, for internal checking of model object before calculations
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
vc	A list of precomputed variance components. Should be in the same structure as the output of var_comp()
...	Additional arguments that specify heritability calculation when interactions with genotype effects are modelled

Details

The broad-sense heritability of differences between genotypes is given by:

$H^2_{\Delta ..} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ..}}{2\sigma^2_g}$

where:

• $PEV^{BLUP}_{\overline\Delta ..}$ is the mean of the prediction error variance matrix for the pairwise differences among BLUPs (BLUEs if method = "BLUE") across all genotypes

• $\sigma^2$ is the variance attributed to differences between genotype

The narrow-sense heritability of differences between genotypes is given by:

$h^2_{\Delta ij} = 1 - \frac{PEV^{BLUP}_{\overline\Delta ij}}{\operatorname{Var}(g_i - g_j)}$

where:

• $g_i$ is the random effect of the $i^{th}$ genotype

See reference page 995 - 997 for full derivation of this heritability measure and related variants

Value

Numeric

Named list, with each element containing a named numeric vector

References

Schmidt, P., Hartung, J., Rath, J., & Piepho, H.-P. (2019). Estimating Broad-Sense Heritability with Unbalanced Data from Agricultural Cultivar Trials. Crop Science, 59(2), 525–536. https://doi.org/10.2135/cropsci2018.06.0376

See Also

h2_Delta(), H2_Delta(), h2_Delta_pairwise(), H2_Delta_pairwise()

Examples

# lme4 model
lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
lettuce_lme4 <- lme4::lmer(y ~ rep + (1 | gen), data = lettuce_subset)
H2_Delta_by_genotype(lettuce_lme4, target = "gen", type = "BLUP")

# asreml model (Requires license)
## Not run: 
lettuce_asreml <- asreml::asreml(fixed = y ~ rep,
                                 random = ~ gen,
                                 data = lettuce_subset,
                                 trace = FALSE
                                 )

H2_Delta_by_genotype(lettuce_asreml, target = "gen", type = "BLUP")

## End(Not run)

---

Calculate pairwise heritability of differences between genotypes from model object

Description

Instead of computing heritability on a "entry-mean" basis, this method calculates heritability using "entry-differences". Entry here is referring to the genotype, line or variety of interest. See reference for origin and interpretation of h2/H2_Delta_pairwise and it's variants

Usage

h2_Delta_pairwise(model,
                  target,
                  type = c("BLUP", "BLUE"),
                  options = NULL,
                  marginal = TRUE,
                  stratification = NULL,
                  vc = NULL,
                  ...)
H2_Delta_pairwise(model,
                  target,
                  type = c("BLUP", "BLUE"),
                  options = NULL,
                  marginal = TRUE,
                  stratification = NULL,
                  vc = NULL,
                  ...)

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
type	character, whether heritability is calculated using BLUEs or BLUPs
options	NULL by default, for internal checking of model object before calculations
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
vc	A list of precomputed variance components. Should be in the same structure as the output of var_comp()
...	Additional arguments that specify heritability calculation when interactions with genotype effects are modelled

Value

A dspMatrix

References

Schmidt, P., Hartung, J., Rath, J., & Piepho, H.-P. (2019). Estimating Broad-Sense Heritability with Unbalanced Data from Agricultural Cultivar Trials. Crop Science, 59(2), 525–536. https://doi.org/10.2135/cropsci2018.06.0376

See Also

h2_Delta_by_genotype(), H2_Delta_by_genotype(), h2_Delta(), H2_Delta()

Examples

# lme4 model
lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
lettuce_lme4 <- lme4::lmer(y ~ rep + (1 | gen), data = lettuce_subset)
H2_Delta_pairwise(lettuce_lme4, target = "gen", type = "BLUP")

# asreml model (Requires license)
## Not run: 
lettuce_asreml <- asreml::asreml(fixed = y ~ rep,
                                 random = ~ gen,
                                 data = lettuce_subset,
                                 trace = FALSE
                                 )

H2_Delta_pairwise(lettuce_asreml, target = "gen", type = "BLUP")

## End(Not run)

---

Calculate heritability of pairwise differences using variance parameters

Description

Compute broad-sense heritability of differences using the variance of differences between two BLUPs/BLUEs

Usage

H2_Delta_parameters(delta_g, delta_pev, type = c("BLUP", "BLUE"))

Arguments

delta_g	Numeric. Genotypic variance-covariance matrix.
delta_pev	Matrix. Variance of pairwise differences among BLUES or BLUPs
type	Character. Either BLUES or BLUPS used to compute the variance of pairwise differences.

Details

See H2_Delta() and reference for full derivation and equation for heritability Delta

Value

Matrix of pairwise heritability of differences among BLUES or BLUPs

References

Schmidt, P., Hartung, J., Rath, J., & Piepho, H.-P. (2019). Estimating Broad-Sense Heritability with Unbalanced Data from Agricultural Cultivar Trials. Crop Science, 59(2), 525–536. https://doi.org/10.2135/cropsci2018.06.0376

Examples

H2_Delta_parameters(delta_g = diag(0.15, 2, 2),
                    delta_pev = matrix(c(NA,0.2,0.2,NA),2,2),
                    type = "BLUP"
                    )

---

Calculate Oakey's heritability from model object

Description

Compute heritability for genotype means using the variance–covariance matrix of the genotype BLUPs as described by Oakey et al. (2006).

Usage

h2_Oakey(model,
            target,
            options = NULL,
            marginal = TRUE,
            stratification = NULL,
            vc = NULL,
            ...)
H2_Oakey(model,
            target,
            options = NULL,
            marginal = TRUE,
            stratification = NULL,
            vc = NULL,
            ...)

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
options	NULL by default, for internal checking of model object before calculations
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
vc	A list of precomputed variance components. Should be in the same structure as the output of var_comp()
...	Additional arguments that specify heritability calculation when interactions with genotype effects are modelled

Details

$h^2_{Oakey} = \frac{\sum_{i = n_z+1}^{n_g} \lambda_i}{\sum_{n_g}^{\lambda_i\neq 0}}$

where:

• $n_g$ is the number of genotypes

• $n_z$ is the number of zero eigenvalues

• $\lambda_i$ is the ith eigenvalue of the matrix $I_{m} - G^{-1}C^{gg}$

• $\sigma^2$ is the variance attributed to differences between genotype

See pages 813 and 818 of the reference for full derivation and explanation for Oakey's heritability

Value

Numeric

References

Oakey, H., Verbyla, A., Pitchford, W., Cullis, B., & Kuchel, H. (2006). Joint modeling of additive and non-additive genetic line effects in single field trials. Theoretical and Applied Genetics, 113(5), 809–819. https://doi.org/10.1007/s00122-006-0333-z

See Also

H2_Oakey(), h2_Oakey()

Examples

# lme4 model
lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
lettuce_lme4 <- lme4::lmer(y ~ rep + (1 | gen), data = lettuce_subset)
H2_Oakey(lettuce_lme4, target = "gen")

---

Calculate Oakey's heritability using variance parameters

Description

Rather than providing a model object, supply the necessary components to compute this heritability measure.

Usage

H2_Oakey_parameters(Gg_inv, C22_g)

Arguments

Gg_inv	The inverse of the genotypic variance-covariance matrix.
C22_g	Prediction error variance matrix associated with the genotype effects.

Value

Numeric value

Examples

Gg_inv = diag(1/0.15, 3, 3)
C22_g <- matrix(
  c(
    0.08, 0.01, 0.00,
    0.01, 0.07, 0.01,
    0.00, 0.01, 0.09
  ),
  nrow = 3, byrow = TRUE
)
H2_Oakey_parameters(Gg_inv, C22_g)

---

Calculate Piepho's heritability from model object Compute Piepho's heritability using variance differences between genotype BLUEs

Description

Calculate Piepho's heritability from model object Compute Piepho's heritability using variance differences between genotype BLUEs

Usage

H2_Piepho(model,
          target,
          options = NULL,
          marginal = TRUE,
          stratification = NULL,
          vc = NULL,
          ...)
h2_Piepho(model,
          target,
          options = NULL,
          marginal = TRUE,
          stratification = NULL,
          vc = NULL,
          ...)

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
options	NULL by default, for internal checking of model object before calculations
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
vc	A list of precomputed variance components. Should be in the same structure as the output of var_comp()
...	Additional arguments that specify heritability calculation when interactions with genotype effects are modelled

Details

The equation for Piepho's heritability is as follows:

$H^2_{Piepho} = \frac{\sigma^2_g}{\sigma^2_g + \overline{PEV_{BLUE_g}} / 2}$

where:

• $\overline{PEV_{BLUE_g}}$ is the prediction error variance matrix for genotype BLUEs

• $\sigma^2_g$ is the variance attributed to differences between genotype

See reference for full derivation and details.

Value

Numeric

References

Piepho, H.-P., & Möhring, J. (2007). Computing Heritability and Selection Response From Unbalanced Plant Breeding Trials. Genetics, 177(3), 1881–1888. https://doi.org/10.1534/genetics.107.074229

Examples

# lme4 model
lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
lettuce_lme4 <- lme4::lmer(y ~ rep + (1 | gen), data = lettuce_subset)
H2_Piepho(lettuce_lme4, target = "gen")

# asreml model (Requires license)
## Not run: 
lettuce_asreml <- asreml::asreml(fixed = y ~ rep,
                                 random = ~ gen,
                                 data = lettuce_subset,
                                 trace = FALSE
                                 )

H2_Piepho(lettuce_asreml, target = "gen")

## End(Not run)

---

Calculate Piepho's heritability using variance parameters

Description

Compute Piepho's heritability using the variance of differences between two BLUES.

Usage

H2_Piepho_parameters(vc_g, vd_BLUE_avg)

Arguments

vc_g	Numeric. Genotype variance component
vd_BLUE_avg	Numeric. Mean variance of pairwise differences among BLUES

Details

The equation for Piepho's heritability is as follows:

$H^2_{Piepho} = \frac{\sigma^2_g}{\sigma^2_g + \overline{PEV_{BLUE_g}} / 2}$

where:

• $\overline{PEV_{BLUE_g}}$ is the prediction error variance matrix for genotype BLUEs

• $\sigma^2_g$ is the variance attributed to differences between genotype

Value

Numeric value

References

Piepho, H.-P., & Möhring, J. (2007). Computing Heritability and Selection Response From Unbalanced Plant Breeding Trials. Genetics, 177(3), 1881–1888. https://doi.org/10.1534/genetics.107.074229

Examples

H2_Piepho_parameters(vc_g = 0.25, vd_BLUE_avg = 0.68)

---

Calculate standard heritability from model object

Description

Compute standard heritability using the classic ratio method of genotypic and phenotypic variance. See Falconer & Mackay (1996)

Usage

h2_Standard(model,
            target,
            options = NULL,
            marginal = TRUE,
            stratification = NULL,
            vc = NULL,
            ...)
H2_Standard(model,
            target,
            options = NULL,
            marginal = TRUE,
            stratification = NULL,
            vc = NULL,
            ...)

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
options	NULL by default, for internal checking of model object before calculations
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
vc	A list of precomputed variance components. Should be in the same structure as the output of var_comp()
...	Additional arguments that specify heritability calculation when interactions with genotype effects are modelled

Details

The equation used to calculate standard heritability (broad-sense) is:

$H^2_{Standard} = \frac{\sigma^2_g}{\sigma^2_g + \frac{1}{n_g}\sum_{n_g}^{i=1} \sigma^2_p / n_{gi}}$

where:

• $n_g$ is the number of genotypes

• $n_{gi}$ is the number of replicate for a given genotype i

• $\sigma_g$ is the variance attributed to genotype differences

• $\sigma_p$ is the variance attributed to phenotypic differences

The equation used to calculate standard heritability (narrow-sense) is:

$h^2_{Standard} = \frac{\operatorname{Var}(g_i - g_j)}{\operatorname{Var}(y_i.. - y_j..)}$

where:

• $g_i$ is the random effect of the $i^{th}$ genotype

• $y_i..$ is the sample average of the $i^{th}$ genotype

Value

Numeric value

References

Falconer, D. S., & Mackay, T. F. C. (1996). Introduction to quantitative genetics (4th ed.). Longman.

See Also

H2_Standard(), h2_Standard()

Examples

# lme4 model
lettuce_subset <- lettuce_phenotypes |> subset(loc == "L2")
lettuce_lme4 <- lme4::lmer(y ~ rep + (1 | gen), data = lettuce_subset)
H2_Standard(lettuce_lme4, target = "gen")

# asreml model (Requires license)
## Not run: 
lettuce_asreml <- asreml::asreml(fixed = y ~ rep,
                                 random = ~ gen,
                                 data = lettuce_subset,
                                 trace = FALSE
                                 )

H2_Standard(lettuce_asreml, target = "gen")

## End(Not run)

---

Calculate Standard heritability using variance parameters

Description

Compute Standard heritability for genotype means using the variance components of genotype and residuals.

Usage

H2_Standard_parameters(vc_g, vc_e, n_r = 1)

Arguments

vc_g	Numeric. Genotype variance component
vc_e	Numeric. Residuals variance component
n_r	A numeric vector of size n_g, the number of genotype replicates.

Details

The equation for Standard heritability is as follows:

$H^2_{Standard} = \frac{\sigma^2_g}{\sigma^2_g + \frac{1}{n_g}\sum_{n_g}^{i=1} \sigma^2_p / n_{gi}}$

where:

• $n_g$ is the number of genotypes

• $n_{gi}$ is the number of replicate for a given genotype i

• $\sigma_g$ is the variance attributed to genotype differences

• $\sigma_p$ is the variance attributed to phenotypic differences

Value

Numeric value

References

Falconer, D. S., & Mackay, T. F. C. (1996). Introduction to quantitative genetics (4th ed.). Longman.

Examples

H2_Standard_parameters(vc_g = 0.25, vc_e = 0.8)

---

Molecular marker data and genomic relatedness matrix of 89 lettuce varieties

Description

Molecular marker data and genomic relatedness matrix of 89 lettuce varieties

Usage

lettuce_markers

lettuce_GRM

Format

lettuce_markers

A data frame with 89 rows and 301 columns:

• gen genotype identifier

• 300 genetic markers scored as -1, 0, 1 (see Details)

lettuce_GRM

A matrix array with 89 rows and 89 columns where each row/column represents a genotype

Details

The varieties were genotyped with a total of 300 markers (i.e. 95 single nucleotide polymorphisms and 205 amplified fragment length polymorphism markers, see Hayes et al. (2014) for more details of marker matrix. The biallelic marker $M_iw$ for the ith genotype and the $w$th marker with alleles $A_1$ (i.e. the reference allele) and $A_2$ was coded as:

• 1 for $A_1$ $A_1$,

• -1 for $A_2$ $A_2$

• 0 for $A_1$ $A_2$ and $A_2$ $A_1$

Source

https://figshare.com/articles/dataset/Lettuce_trial_phenotypic_and_marker_data_/8299493

References

Hadasch, S., Simko, I., Hayes, R.J., Ogutu, J.O. and Piepho, H.-P. (2016), Comparing the Predictive Abilities of Phenotypic and Marker-Assisted Selection Methods in a Biparental Lettuce Population. The Plant Genome, 9: plantgenome2015.03.0014. doi:10.3835/plantgenome2015.03.0014

Hayes, R. J., Galeano, C. H., Luo, Y., Antonise, R., & Simko, I. (2014). Inheritance of Decay of Fresh-cut Lettuce in a Recombinant Inbred Line Population from ‘Salinas 88’ × ‘La Brillante’. Journal of the American Society for Horticultural Science, 139(4), 388–398. doi:10.21273/JASHS.139.4.388

---

Phenotypic data of 89 lettuce varieties

Description

89 lettuce varieties tested at three environments, each laid out as a randomized complete block design. The measured trait was resistance to downy mildew scored on a scale ranging from 0 to 5.

Usage

lettuce_phenotypes

Format

lettuce_phenotypes

A data frame with 703 rows and 4 columns:

• loc environment identifier

• gen genotype identifier

• rep replicate identifier

• y resistance to downy mildew scored on a scale ranging from 0 to 5

Source

https://figshare.com/articles/dataset/Lettuce_trial_phenotypic_and_marker_data_/8299493

References

Hadasch, S., Simko, I., Hayes, R.J., Ogutu, J.O. and Piepho, H.-P. (2016), Comparing the Predictive Abilities of Phenotypic and Marker-Assisted Selection Methods in a Biparental Lettuce Population. The Plant Genome, 9: plantgenome2015.03.0014. doi:10.3835/plantgenome2015.03.0014

Hayes, R. J., Galeano, C. H., Luo, Y., Antonise, R., & Simko, I. (2014). Inheritance of Decay of Fresh-cut Lettuce in a Recombinant Inbred Line Population from ‘Salinas 88’ × ‘La Brillante’. Journal of the American Society for Horticultural Science, 139(4), 388–398. doi:10.21273/JASHS.139.4.388

---

Molecular markers data and genomic relatedness matrix of Australian lizards

Description

Molecular markers data and genomic relatedness matrix of Australian lizards

Usage

lizard_markers

lizard_GRM

Format

lizard_markers

A data frame with 261 rows and 8438 columns:

• gen individual identifier, equivalent to liz_id in lizard_phenotypes

• 8437 genetic markers scored as 0, 2, 1 (see Details)

lizard_GRM

A matrix array with 261 rows and 261 columns where each row/column represents a genotype

Details

See ?snpReady::G.matrix for how GRM was computed. The biallelic marker $M_iw$ for the ith genotype and the $w$th marker with alleles $A_1$ (i.e. the reference allele) and $A_2$ was coded as:

• 0 for $A_1$ $A_1$,

• 1 for $A_1$ $A_2$ and $A_2$ $A_1$

• 2 for $A_2$ $A_2$

Source

https://osf.io/hjkxd/?view_only=12a6b6010567474fac9fecd54472aa3d

References

Kar, F., Nakagawa, S. and Noble, D.W.A. (2024) “Heritability and developmental plasticity of growth in an oviparous lizard,” Heredity, 132(2), pp. 67–76. Available at: https://doi.org/10.1038/s41437-023-00660-3.

---

Phenotypic data of Australian lizards

Description

Phenotypic data for Australian lizards (L. delicata). Lizard eggs were incubated at two different incubation treatment temperatures. Lizards were weighed to investigate differences in growth between treatments.

Usage

lizard_phenotypes

Format

lizard_phenotypes

A data frame with 3928 rows and 9 columns:

• liz_id individual identifier, equivalent to gen in lizard_markers 261 individuals

• treatment temperature (degrees celcius) at which lizard eggs were incubated

• dam_id dam identifier

• sire_id sire identifer

• mass mass of lizard in

• ln_mass natural log mass

• days_since_hatch days since hatching (age)

• z_days_since_hatch scaled and centered days_since_hatch see ?scale()

• z_days_since_hatch_i2 squared z_days_since_hatch see Kar et al 2024 to see details on their analysis

Source

https://osf.io/hjkxd/?view_only=12a6b6010567474fac9fecd54472aa3d

References

Kar, F., Nakagawa, S. and Noble, D.W.A. (2024) “Heritability and developmental plasticity of growth in an oviparous lizard,” Heredity, 132(2), pp. 67–76. Available at: https://doi.org/10.1038/s41437-023-00660-3.

---

Extract variance components

Description

This function provides the variance matrix quantities needed to evaluate heritability with respect to a target random-effect term in a fitted linear mixed model.

Usage

var_comp(
  model,
  target,
  calc_C22 = TRUE,
  calc_V = TRUE,
  calc_C11 = TRUE,
  marginal = TRUE,
  stratification = NULL,
  solver = c("direct", "LMM"),
  ...
)

Arguments

model	Model object of class lmerMod/merMod or asreml
target	The name of the random effect for which heritability is to be calculated.
calc_C22	Logical; whether to compute the prediction error variance (PEV) matrix for the transformed target effect.
calc_V	Logical; whether to retain the marginal variance matrix of the response and supporting quantities (V, G, Z, X, idx, and m) in the output.
calc_C11	Logical; whether to compute the variance matrix of the fixed-effect counterpart estimator for the transformed target effect.
marginal	Logical; if TRUE, construct marginal (strata-averaged) mappings so that each genotype receives a single averaged effect per term. If FALSE, mappings will only consider the main genotype effect and ignore the iteracting terms.
stratification	A one-row data frame defining the stratum in which genotype effects should be evaluated. The columns must correspond to model terms that interact with target.
solver	A string specifying the solver for the PEV matrix. Can be either "direct" (directly invert V) or "LMM" (Solve the LMM equation).
...	Additional arguments passed to downstream helper functions.

Value

A named list with the following elements:

n_g

Number of transformed genetic coefficients after applying the mapping matrix m.

gnames

Names of the transformed genetic coefficients.

G_g

Variance matrix of the transformed target genetic effect.

C22_g

Prediction error variance matrix of the transformed target effect, if calc_C22 = TRUE; otherwise NULL.

G_g_tilde

Variance matrix of the fixed-effect counterpart estimator for the transformed target effect, if calc_C11 = TRUE; otherwise NULL.

G_g_tilde_no_cov

Variance matrix of the fixed-effect counterpart estimator for the transformed target effect, without considering target covariance, if calc_C11 = TRUE; otherwise NULL.

C11_g

Estimation error variance matrix of the fixed-effect counterpart estimator for the transformed target effect, if calc_C11 = TRUE; otherwise NULL.

V

Marginal covariance matrix of the response, if calc_V = TRUE; otherwise NULL.

G

Variance matrix of all random effects, if calc_V = TRUE; otherwise NULL.

Z

Random-effect design matrix, if calc_V = TRUE; otherwise NULL.

X

Fixed-effect design matrix, if calc_V = TRUE; otherwise NULL.

idx

Indices of the random-effect coefficients associated with the target term, if calc_V = TRUE; otherwise NULL.

W

Linear mapping from the original target coefficients to the transformed target effect, if calc_V = TRUE; otherwise NULL.

marginal

Logical scalar indicating whether the returned quantities correspond to a marginal definition of the target effect.

stratification

The user-supplied stratification object, if any.

---