Skip to contents

Add estimated breeding values to a tidybreed population

Source: R/add_ebv.R
add_ebv.Rd

Computes EBVs using one of two modes:

  • software = "blupf90" — runs the BLUPF90 suite (renumf90 + blupf90+). Both binaries must be on PATH. Writes all input/output files to a timestamped subfolder of run_dir for inspection and reproducibility.

  • parent_avg = TRUE — simple average of parent EBVs already stored in ind_ebv for the given model. Returns NA for any animal whose parents do not both have EBVs.

The first argument is a tidybreed_table (from get_table() and optionally dplyr::filter()). The filter controls which animals' phenotypic records are included in the evaluation; ancestors are traced back automatically for the pedigree via n_gen_pedigree.

Usage

add_ebv(
  tbl,
  trait_name,
  software = NULL,
  parent_avg = FALSE,
  model = "model_1",
  overwrite_trait = FALSE,
  delete_all = FALSE,
  n_gen_pedigree = 2L,
  chip_name = NULL,
  run_dir = ".",
  eval_id = NULL,
  estimate_var = FALSE,
  update_covars = FALSE,
  phenotype = NULL,
  ...
)

Arguments

tbl

A tidybreed_table from get_table() (optionally filtered). Must contain an id_ind column.

trait_name

Character vector of trait name(s) to evaluate.

software

Character or NULL (default). Set to "blupf90" to run the BLUPF90 suite (currently the only supported value). Exactly one of software = "blupf90" or parent_avg = TRUE must be supplied — leaving both at their defaults, or setting both, is an error.

parent_avg

Logical. If TRUE, compute EBVs as the average of parent EBVs from ind_ebv (for the given model). Cannot be combined with software; see software above. Default FALSE.

model

Character. Label stored in ind_ebv$model. Must be a valid SQL identifier. Default "model_1".

overwrite_trait

Logical. If TRUE, all existing ind_ebv rows for the traits being added are deleted before inserting; new rows receive eval_number = 1. Default FALSE.

delete_all

Logical. If TRUE, all rows in ind_ebv are deleted before inserting; new rows receive eval_number = 1. Takes precedence over overwrite_trait. Default FALSE.

n_gen_pedigree

Integer. Generations to trace back from the filtered candidates when building the pedigree file. Default 2. Used only in software = "blupf90" mode; ignored under parent_avg = TRUE.

chip_name

Character or NULL. Name of a SNP chip defined via define_chip() (e.g. "HD"). When provided, genotype file is written and single-step GBLUP (ssGBLUP) is requested via SNP_FILE in renum.par. Animals must have has_{chip_name} = TRUE in ind_meta (validated up front regardless of mode). Used only in software = "blupf90" mode; silently unused under parent_avg = TRUE.

run_dir

Character. Base directory for evaluation sub-folders. Default "." (working directory). Ignored when pop$run_dirs is non-empty (i.e. when open_pop() was called with a tools argument) — the managed output folder structure is used instead. Applies only in software = "blupf90" mode.

eval_id

Character or NULL. Sub-folder name suffix appended to "eval_". Auto-generated from model + timestamp when NULL. Ignored in managed output mode (see run_dir above); the run directory name generated by .create_run_dir() is used as the identifier. Applies only in software = "blupf90" mode.

estimate_var

Logical. If TRUE, request variance component estimation (OPTION method VCE) instead of BLUP-only. Default FALSE. Applies only in software = "blupf90" mode.

update_covars

Logical. If estimate_var = TRUE, attempt to write estimated variance components back to trait_var_comp. Default FALSE. Not yet implemented: the current writeback step (update_covars_from_blupf90()) is a stub that only prints a message pointing you to blupf90.out and define_effect_cov_matrix() for a manual update — no rows are written automatically yet. Applies only in software = "blupf90" mode.

phenotype

Optional tidybreed_table from get_table("ind_phenotype") |> filter(...). When supplied, only phenotype records matching the filter are included in the BLUPF90 data file. The pedigree is unaffected — all traced ancestors remain in the pedigree file regardless of this filter. Ignored (with a warning) in parent_avg mode. Applies only in software = "blupf90" mode.

...

Optional extra columns written to ind_ebv (scalars only; broadcast to all records). Supply per-record vectors with mutate_table() after the call.

Value

The modified tidybreed_pop (invisibly). EBVs are appended to ind_ebv with an auto-incrementing eval_number per trait. Use overwrite_trait = TRUE or delete_all = TRUE to clear previous records instead of accumulating them.

See also

get_table(), add_phenotype(), define_chip(), define_effect_cov_matrix()

Examples

if (FALSE) { # \dontrun{
# Parent average (parents must already have EBVs in ind_ebv for model
# "pa_v1" -- see the versioning example below for how eval_number accrues)

# Model / eval_number versioning: each call for the same `model` label
# appends a new eval_number rather than overwriting (ind_ebv's logical key
# is id_ind x trait_name x model x eval_number). Re-running as new data
# arrives builds up a history of evaluations you can compare over time;
# `overwrite_trait = TRUE` instead clears prior rows for the trait(s) and
# restarts eval_number at 1 for that model.
pop <- pop |>
  get_table("ind_meta") |>
  dplyr::filter(gen == 2L) |>
  add_ebv("ADG", parent_avg = TRUE, model = "pa_v1")   # eval_number = 1
pop <- pop |>
  get_table("ind_meta") |>
  dplyr::filter(gen == 3L) |>
  add_ebv("ADG", parent_avg = TRUE, model = "pa_v1")   # eval_number = 2
pop <- pop |>
  get_table("ind_meta") |>
  dplyr::filter(gen == 2L) |>
  add_ebv("ADG", parent_avg = TRUE, model = "pa_v1", overwrite_trait = TRUE) # back to 1

# BLUPF90 — renumf90 and blupf90+ must be on PATH
pop <- pop |>
  get_table("ind_meta") |>
  dplyr::filter(gen >= 3L) |>
  add_ebv(c("ADG", "BW"),
          software = "blupf90",
          model    = "blup_v1",
          run_dir  = "./eval_runs",
          n_gen_pedigree = 2)

# BLUPF90 with a phenotype filter (e.g. excluding a custom-added date
# column's future/incomplete records) -- `pheno_date` here is a user-added
# column (e.g. via add_phenotype(..., pheno_date = Sys.Date())), not a
# built-in ind_phenotype column
pop <- pop |>
  get_table("ind_meta") |>
  dplyr::filter(gen >= 3L) |>
  add_ebv(c("ADG", "BF"),
          software  = "blupf90",
          model     = "blup_v1",
          phenotype = pop |>
                        get_table("ind_phenotype") |>
                        dplyr::filter(pheno_date < Sys.Date()))
} # }