Export a pedigree to a breeding software format

Converts a tidyped pedigree into the tabular format expected by common animal/plant breeding software packages and either returns the result as a data.table or writes it to a plain-text file.

Usage

pedexport(
  ped,
  software = c("blupf90", "asreml", "echidna", "hiblup", "wombat", "mtdfreml", "dmu",
    "numeric", "sommer"),
  file = NULL,
  sep = " ",
  header = NULL,
  missing = NULL
)

Arguments

ped

A complete tidyped object (see tidyped). The pedigree must be structurally complete: every non-missing Sire and Dam identifier must be present in Ind.

software

Character scalar specifying the target format. One of:

"blupf90": Three integer columns (IndNum, SireNum, DamNum), no header, missing parents encoded as 0. Rows are sorted by IndNum so parent rows always precede offspring rows. Compatible with BLUPF90, REMLF90, GIBBSF90, and related programs.
"asreml": Three character columns (animal, sire, dam), with a one-line header by default, missing parents encoded as "0". Rows are sorted by generation (Gen) so founders appear first. Compatible with ASReml-R and ASReml-SA (character IDs require the !ALPHA qualifier; the header line requires the !SKIP 1 qualifier, placed immediately after the pedigree file name).
"echidna": Identical character layout and defaults to "asreml": columns animal, sire, and dam, a header by default, missing parents encoded as "0", and rows sorted by generation.
"hiblup": Three character columns (animal, sire, dam), no header by default, missing parents encoded as "0", and rows sorted by generation. Compatible with HIBLUP's --pedigree file.
"wombat": Integer layout identical to "blupf90" (IndNum, SireNum, DamNum), no header, missing parents encoded as 0. WOMBAT requires integer codes in the range 0 to 2147483647, with every offspring numerically larger than either parent and unknown parents coded 0 (WOMBAT manual section 6.3); the tidyped() integer index satisfies both ordering constraints by construction.
"mtdfreml": Identical integer layout to "blupf90". Compatible with MTDFREML and MTGSAM.
"dmu": Identical integer layout to "blupf90". Compatible with DMU.
"numeric": Integer layout with an optional header (IndNum SireNum DamNum). A portable, software-agnostic choice when the target program is not listed above.
"sommer": Three character columns (ID, Sire, Dam), missing parents coded as NA. Rows are sorted so parents precede offspring. Returned as a data.table ready to pair with a base R relationship matrix from pedmat(..., sparse = FALSE) for use in sommer::mmer(..., random = ~vsr(animal, Gu = A)).

file

Character scalar. Path to the output file. When NULL (default) the formatted data.table is returned invisibly and no file is written. File output is not supported for "sommer", which is intended for direct use as an R data.table.

sep

Character scalar. Field separator used when writing to file. Defaults to a single space (" "), which every file-based format accepts. BLUPF90 requires a space; WOMBAT, MTDFREML, DMU, and HIBLUP accept spaces or TABs; ASReml and Echidna accept spaces, TABs, or commas; and the generic "numeric" format accepts any single-byte, non-empty separator supported by fwrite. ASReml/Echidna comma-delimited output requires a .csv file extension or the !CSV qualifier.

header

Logical scalar or NULL. Whether to include a column header line. NULL (default) uses the software-specific default: TRUE for "asreml", "echidna", and "numeric", FALSE for "blupf90", "wombat", "mtdfreml", "dmu", and "hiblup". Ignored for "sommer". Note for ASReml and Echidna: a header line is read as data unless the !SKIP 1 qualifier is used in the command file (it must be placed immediately after the pedigree file name — trailing !SKIP after other qualifiers is silently ignored by ASReml-SA).

missing

Character or integer scalar. Symbol for missing parents. NULL (default) uses the software-specific default: 0L for numeric formats, "0" for "asreml", "echidna", and "hiblup". Numeric formats ("blupf90", "wombat", "mtdfreml", "dmu", "numeric") require a single integer value, and for "wombat" the value must be 0 (WOMBAT manual section 6.3); "asreml", "echidna", and "hiblup" accept a character value (numeric values are converted to character). Ignored for "sommer", which always codes missing parents as NA.

Value

A data.table in the target format, returned invisibly. Numeric formats carry an xref attribute mapping each numeric ID back to its original character ID (columns IndNum and Ind), and when file is given the mapping is also written to paste0(file, ".xref") without a header, mirroring RENUMF90's _XrefID file. For file-based formats, when file is not NULL, the table is also written to that path and a message reports the number of individuals written.

Details

Column semantics by format:

software	Col 1	Col 2	Col 3
blupf90 / wombat / mtdfreml / dmu / numeric	`IndNum` (integer)	`SireNum` (integer)	`DamNum` (integer)
asreml / echidna / hiblup	`animal` (character)	`sire` (character)	`dam` (character)
sommer	`ID` (character)	`Sire` (character)	`Dam` (character)

Software format requirements:

All file-based formats use unquoted, free-format plain text. The table below summarises what each program expects, and the defaults pedexport() uses to meet those expectations.

software	header	separator	missing	IDs	notes
blupf90	no	spaces only	`0`	integer	TAB separators rejected
wombat	no	space / TAB	`0`	integer	integer codes 0..2147483647; offspring code must exceed both parent codes (manual section 6.3)
hiblup	no	space / TAB	`"0"`	character	alphanumeric accepted; missing parents may also be `NA`
mtdfreml	no	space / TAB	`0`	integer
dmu	no	space / TAB	`0`	integer
asreml	yes	space / TAB / comma	`"0"`	char or integer	character IDs need `!ALPHA`; header needs `!SKIP 1`; comma needs `.csv` or `!CSV`
echidna	yes	space / TAB / comma	`"0"`	char or integer	same pedigree layout and defaults as ASReml
sommer	n/a	n/a	`NA`	character	returned as a data.table, not a file
numeric	optional	any	`0`	integer	generic software-agnostic layout

Row order:

All numeric formats sort by IndNum ascending, which guarantees that parent rows appear before offspring rows (parents always receive a smaller integer index after tidyped() topological sorting). The "asreml", "echidna", "hiblup" and "sommer" formats sort by Gen ascending for the same reason.

Optional tidyped() columns:

tidyped(..., addnum = FALSE) omits IndNum/SireNum/ DamNum and tidyped(..., addgen = FALSE) omits Gen. When these columns are absent, pedexport() reconstructs them from Ind/Sire/Dam. Because tidyped() always topologically sorts rows, parents still precede offspring in the output.

Identifiers in written files:

Output is deliberately unquoted because the supported breeding programs read pedigree files as free-format text. Therefore, identifiers and character missing-parent symbols must not contain whitespace. They also must not contain the selected non-whitespace separator. Numeric formats apply the same restriction to original identifiers written to the companion .xref file.

Sommer compatibility:

The Gu argument of sommer::vsr() requires a base R matrix. Because pedmat() defaults to sparse = TRUE and returns a Matrix object for method = "A", use pedmat(ped, method = "A", sparse = FALSE) or explicitly convert the result with as.matrix(). The matrix row and column names match the ID column returned by pedexport(..., software = "sommer").

Relationship to tidyped():

pedexport() is a post-processing step that re-encodes an already validated pedigree. Pass the output of tidyped directly to avoid redundant validation.

Examples

library(visPedigree)

tp <- tidyped(small_ped)

# Return a data.table (no file written)
out_blupf90 <- pedexport(tp, software = "blupf90")
head(out_blupf90)
#>    IndNum SireNum DamNum
#>     <int>   <int>  <int>
#> 1:      1       0      0
#> 2:      2       0      0
#> 3:      3       0      0
#> 4:      4       0      0
#> 5:      5       0      0
#> 6:      6       0      0

# ASReml format with character IDs and header
out_asreml <- pedexport(tp, software = "asreml")
head(out_asreml)
#>    animal   sire    dam
#>    <char> <char> <char>
#> 1:      A      0      0
#> 2:      B      0      0
#> 3:      F      0      0
#> 4:      I      0      0
#> 5:     J1      0      0
#> 6:     J2      0      0

# Echidna uses the same pedigree layout as ASReml
out_echidna <- pedexport(tp, software = "echidna")
identical(out_echidna, out_asreml)
#> [1] TRUE

# HIBLUP: character IDs, no header by default
out_hiblup <- pedexport(tp, software = "hiblup")
head(out_hiblup)
#>    animal   sire    dam
#>    <char> <char> <char>
#> 1:      A      0      0
#> 2:      B      0      0
#> 3:      F      0      0
#> 4:      I      0      0
#> 5:     J1      0      0
#> 6:     J2      0      0

# WOMBAT requires integer codes (manual section 6.3): same integer
# layout as BLUPF90, with the xref mapping back to original IDs
out_wombat <- pedexport(tp, software = "wombat")
head(out_wombat)
#>    IndNum SireNum DamNum
#>     <int>   <int>  <int>
#> 1:      1       0      0
#> 2:      2       0      0
#> 3:      3       0      0
#> 4:      4       0      0
#> 5:      5       0      0
#> 6:      6       0      0
head(attr(out_wombat, "xref"))
#>    IndNum    Ind
#>     <int> <char>
#> 1:      1      A
#> 2:      2      B
#> 3:      3      F
#> 4:      4      I
#> 5:      5     J1
#> 6:      6     J2

# Numeric formats carry the ID mapping back to character IDs
out_dmu <- pedexport(tp, software = "dmu")
head(attr(out_dmu, "xref"))
#>    IndNum    Ind
#>     <int> <char>
#> 1:      1      A
#> 2:      2      B
#> 3:      3      F
#> 4:      4      I
#> 5:      5     J1
#> 6:      6     J2

# sommer: character pedigree + visPedigree's own relationship matrix.
# pedmat() rownames match pedexport(..., software = "sommer")$ID, so the
# dense matrix is ready for sommer::mmer(..., Gu = A).
out_sommer <- pedexport(tp, software = "sommer")
head(out_sommer)
#>        ID   Sire    Dam
#>    <char> <char> <char>
#> 1:      A   <NA>   <NA>
#> 2:      B   <NA>   <NA>
#> 3:      F   <NA>   <NA>
#> 4:      I   <NA>   <NA>
#> 5:     J1   <NA>   <NA>
#> 6:     J2   <NA>   <NA>
A <- pedmat(tp, method = "A", sparse = FALSE)
identical(rownames(A), out_sommer$ID)
#> [1] TRUE

# \donttest{
# Write to a file (numeric formats also write <file>.xref)
tmp <- tempfile(fileext = ".txt")
pedexport(tp, software = "blupf90", file = tmp)
#> Written ID mapping to: /tmp/Rtmpir4iWc/file27ad7b0e837a.txt.xref
#> Written 28 individuals to: /tmp/Rtmpir4iWc/file27ad7b0e837a.txt
readLines(tmp, n = 5)
#> [1] "1 0 0" "2 0 0" "3 0 0" "4 0 0" "5 0 0"
readLines(paste0(tmp, ".xref"), n = 5)
#> [1] "1 A"  "2 B"  "3 F"  "4 I"  "5 J1"
# }