Package {SelectionTools}

Maximum Allele Code Used by SelectionTools

Description

Internal constant giving the largest biological allele code supported by SelectionTools.

Usage

.GS_ALLELE_MAX

Format

An integer scalar with value 254.

Details

The value is used when validating allele codes in the R interface. The separate internal missing-value code is not a biological allele code. This constant is intended for internal use and should not be modified.

Value

An integer scalar with value 254, giving the largest biological allele code supported by the SelectionTools R interface. The separate missing-value code is not included in this maximum.

Maximum Number of ALT Alleles in STvcf Data

Description

Internal constant giving the maximum number of ALT alleles supported for one marker in an STvcf object.

Usage

.GS_STVCF_MAX_ALT

Format

An integer scalar with value 253.

Details

Together with the REF allele, at most 254 biological allele states are supported for one marker. Missing data use a separate internal state. This constant is intended for internal use and should not be modified.

Value

An integer scalar with value 253, giving the maximum number of ALT alleles supported for one marker in an STvcf object. Together with the REF allele this permits 254 biological allele states.

Technow Hybrid Phenotype Data

Description

Phenotypic data for a maize hybrid data set used for examples of genomic prediction in SelectionTools. The records identify dent and flint parents, their hybrid, and grain-yield performance.

Usage

data(DT_technow)

Format

A data frame containing the variables dent, flint, hy, and GY. The first two variables identify the parental lines, hy identifies the hybrid, and GY contains grain-yield phenotypes.

Source

Data supplied with SelectionTools for genomic prediction examples. Original data published in Technow et al. (2014): doi:10.1534/genetics.114.165860.

Technow Dent Marker Data

Description

Marker data for the dent parental lines corresponding to the hybrid phenotype data in DT_technow. The data are used to construct genomic relationship matrices and for genomic-prediction examples.

Usage

data(Md_technow)

Format

A marker-data matrix or data frame with dent parental lines in rows and markers in columns. Row names identify the parental lines and the entries contain marker genotypes.

Source

Data supplied with SelectionTools for genomic prediction examples. Original data published in Technow et al. (2014): doi:10.1534/genetics.114.165860.

Technow Flint Marker Data

Description

Marker data for the flint parental lines corresponding to the hybrid phenotype data in DT_technow. The data are used to construct genomic relationship matrices and for genomic-prediction examples.

Usage

data(Mf_technow)

Format

A marker matrix with flint parental lines in rows and markers in columns. Row names identify the parental lines and the entries contain marker genotypes.

Source

Data supplied with SelectionTools for genomic prediction examples. Original data published in Technow et al. (2014): doi:10.1534/genetics.114.165860.

append.population()

Description

Appends a copy of one population to another.

Usage

append.population(NameP1, NameP2)

Arguments

Details

The individuals of NameP2 are copied to the end of NameP1. Existing individuals in NameP1 are retained, and NameP2 is not modified.

The source population must exist and contain at least one individual. The source and destination population names must differ.

Value

Returns NameP1 and NameP2. Usually called for side effects.

See Also

population.append, which is called by this wrapper.

Examples

# Define the genome and linkage map
map <- data.frame(
   chrom = 1,
   pos = 0.5,
   name = "form",
   class = "trait1"
)
define.genome(map)

# Create two populations with different alleles
init.population("P1", homozygote(1, NoInd = 3))
init.population("P2", homozygote(2, NoInd = 2))

# Combine copies of both populations in a new population
append.population("Combined", "P1")
append.population("Combined", "P2")

# Combined contains three individuals with genotype 1/1
# and two individuals with genotype 2/2.
# The original populations P1 and P2 are retained.
evaluate.genotype("Combined", "form")
population.list()

Switch SelectionTools output to a quiet mode

Description

Switch SelectionTools output to a quiet mode.

Usage

be.quiet()

Value

Returns the same invisible implementation-level list as set.info.level(0); the main effect is switching package information output to quiet mode.

concat.population()

Description

Concatenates two populations and removes the second population.

Usage

concat.population(NameP1, NameP2)

Arguments

Details

The individuals of NameP2 are appended to NameP1. After successful concatenation, NameP2 is removed. Complete individual records are moved or copied as required so chromosome data and any valid per-individual derived information remain associated with the correct individuals.

Value

Returns the same invisible implementation-level list as population.concat(). The function is a compatibility wrapper and the meaningful result is the delegated population operation.

copy.population()

Description

Copies all or a contiguous part of a simulation population into a destination population.

Usage

copy.population(NameP1, NameP2, start=1, n=-1)

Arguments

Details

Copying starts at the one-based position start. A negative n requests the remaining individuals through the end of the source; a positive value requests that many individuals subject to the source bounds. The source population is not modified. Raw chromosome data are copied, and genotype or genetic-value data are copied only when the corresponding source category is complete for all active source individuals.

Value

Returns the same invisible implementation-level list as population.copy(). The function is a compatibility wrapper and the meaningful result is the delegated population operation.

cross()

Description

Generates a diploid progeny population by crossing individuals drawn from two parental populations.

Usage

cross(NamePg, NameP1, NameP2, NoPg = -1, self = 0, mode = 1,
      crossing.scheme = 0)

Arguments

Details

The simulation genome must be diploid. The progeny population must have a name different from both parental populations. Both parental population names may refer to the same population. Using the same population for both parents does not, by itself, ensure selfing. Existing contents under the progeny name are replaced when a new progeny population is constructed.

For positive NoPg, exactly that many progeny individuals are generated. The special value -1 uses the already allocated size of an existing progeny population; it is therefore meaningful only when such a destination population already exists with positive allocation.

The four crossing schemes control whether the parent chosen from each parental population is random or deterministic. Deterministic selection cycles through the active individuals of the corresponding parent population. For progeny number n (counted from 1), the one-based position of the deterministically selected parent in parental population P of size S_P is

i_P(n) = ((n-1) \bmod S_P) + 1.

Thus deterministic selection cycles through all active individuals and starts again with the first individual after the end of the parental population is reached. The rule is applied separately to each parental population, so the two populations may have different sizes. self controls selfing, and mode controls whether the mating logic applies self-incompatibility.

Each progeny receives newly simulated chromosome segments produced by meiosis. Cached marker genotypes and evaluated genetic values are not inherited as authoritative derived data; they can be generated from the new chromosomes when needed. If chromosome construction fails, the incomplete progeny population is removed rather than left partially generated.

Value

Invisibly returns a list containing the arguments passed to the compiled crossing routine. The function is primarily called for its side effect of creating the progeny population.

Note

Crossing scheme 0 selects both parents randomly; scheme 1 selects the first parent randomly and the second deterministically; scheme 2 does the reverse; scheme 3 selects both deterministically.

Examples

map <- data.frame(chrom = 1,
                  pos = 0.01,
                  name = "form")
define.genome(map)

init.population("P1", homozygote(1))
init.population("P2", homozygote(2))

# Example: Generate 100 F1 hybrids
cross("F1","P1", "P2", 100)
evaluate.genotype("P1","form")

# Example: Repeated selfing
cross("F2", "F1", "F1", 1000, self = 1)
cross("F3", "F2", "F2", 1000, self = 1)
cross("F4", "F3", "F3", 1000, self = 1)
evaluate.genotype("F4", "form")

Return or inspect parameters associated with a data object

Description

Return or inspect parameters associated with a data object.

Usage

data.params(dta)

Arguments

Value

A named list describing the supplied data object, with components:

define.effects()

Description

Defines effects that can be used for selection

Usage

define.effects(name, description)

Arguments

Details

The syntax for the description string is
Mean, Classname Allele [Allele] Distribution Parameter [,...]

For normal mean/variance, the first number is the mean and the second number is the variance of the normal distribution from which an effect is drawn independently for every matching locus. Thus normal 1/0.05 uses mean 1 and variance 0.05 (standard deviation \sqrt{0.05}). The variance must be nonnegative.

For uniform value, the supplied number is used as a fixed effect value at every matching locus; despite the historical keyword uniform, no random draw is made for this form.

If one allele is supplied, the specification defines an allele effect. If two alleles are supplied before the distribution keyword, the specification defines the effect of that allele combination and can be used for dominance effects. Several effect specifications can be included in one description, separated by commas.

Value

An integer status returned by the final unlink() call that removes the temporary effect-definition file. The meaningful result is the side effect of defining/loading the requested effects.

define.effects.df()

Description

Automatically generates effects for loci: effect is always 1 for allele 1.

Usage

define.effects.df ( LocNames )

Arguments

Details

Population specified via PopName is accessed in the background and must therefore be available in the backend.

Value

NULL. The function is called for its side effect of defining effect maps for the locus names in the supplied data frame; invalid pre-existing definitions return NULL invisibly.

Examples

map <- data.frame(chrom = 1:2,
    pos = c(0.01,0.02),
    name = c("form","color"))
define.genome(map)

define.effects.df(map$name)

Define a genome from a linkage map and optional chromosome lengths

Description

Defines a diploid simulation genome and linkage map from a data frame of locus positions. The number of chromosomes is inferred from the map. Chromosome lengths can be supplied explicitly or inferred from the locus positions.

Usage

define.genome(map, length.vec=NULL)

Arguments

Details

Dataframe provided to the map function must have three columns and an optional fourth column. First four columns are interpreted as: Chromosome, Position, Name, Class. Column names do not need to be specified.

Chromosome

Numeric chromosome identifier. Values must be whole numbers.

Position

Numeric position of the locus in Morgans, greater than or equal to zero. When chromosome lengths are supplied explicitly, locus positions must lie within the corresponding chromosomes.

Name

Character string identifying the locus. Locus names must be unique.

Class

Optional character class label. Classes can be used to define effects for groups of loci. If this column is omitted, class names are generated by prefixing each locus name with "Class". For example, locus "form" receives class "Classform".

Calling this function replaces the simulation genome and linkage map. Existing simulation populations and effect definitions are removed.

Value

NULL on successful completion. The function is called for setting genome parameters and defining the linkage map in the backend.

See Also

This function is a wrapper for the more explicit [set.genome.par] and [define.map] that behave slightly differently.

Examples

map <- data.frame(chrom = 1:2,
   pos = c(0.01,0.02),
   name = c("form","color"))
define.genome(map)

map <- data.frame(chrom = 1:2,
   pos = c(0.01,0.02),
   name = c("form","color"),
   class = paste0("trait",1:2))
define.genome(map)

map <- data.frame(chrom = 1:2,
   pos = c(0.01,0.02),
   name = c("form","color"),
   class = paste0("trait",1:2))
define.genome(map, length.vec=c(0.1,0.1))

define.map()

Description

Defines and installs a simulation linkage map from a compact textual map description.

Usage

define.map(description)

Arguments

Details

Genome parameters must be defined before calling this function, for example using set.genome.par. Each call replaces the currently defined linkage map.

[*Number] Locusname Classname Position

where *Number is optional. Locusname is the locus-name prefix, Classname is the locus class, and Position controls placement.

For a single explicitly positioned locus, Position is written as chromosome/position. The chromosome is one-based and the position must lie between 0 and the chromosome length defined for the simulation genome. The position is in the same unit as the simulation chromosome lengths (Morgan in the standard SelectionTools simulation setup). A multiplicity prefix is not allowed for explicitly positioned loci.

Generated positions can be specified as follows:

random

Generate Number loci at independently random positions over the complete genome. Chromosomes are sampled in proportion to their lengths, so these positions are genuinely random rather than equidistant.

terminal

Distribute Number loci equally among the chromosomes and place them equidistantly on each chromosome including the telomeres. Number must be a multiple of the number of chromosomes.

nonterminal

Distribute Number loci equally among the chromosomes and place them equidistantly in the chromosome interiors, excluding the telomeres. Number must be a multiple of the number of chromosomes.

For generated positions a running integer suffix is added to the supplied Locusname prefix to obtain unique locus names.

The description is first converted to a temporary map file by generate.map.file and is then loaded through the simulation linkage-map loader. The generated map is validated for chromosome bounds, position bounds, unique locus names, and complete specifications, and is ordered by chromosome and position before loading. The operation replaces the currently active simulation linkage map definition only after the description has been accepted by the map-generation/loading steps.

Value

Invisibly returns a list whose retval component indicates success or failure. The function is primarily called for its side effect of defining the simulation linkage map.

Examples

set.genome.par(no.chrom = 1,
               no.hom = 2,
               chrom.len = 0.05)

# Define a single locus
# Format: Name Class Chromosome/Position
define.map("form trait1 1/0")

# Replace the map with two loci supplied in one string
define.map("form trait1 1/0, color trait2 1/0.02")

# Define the same map using a character vector
define.map(c("form trait1 1/0",
             "color trait2 1/0.02"))

# Inspect the resulting map
linkage.map.get()

Issue information for a deprecated function or object name

Description

Issue information for a deprecated function or object name.

Usage

deprecated(NameOld, NameNew)

Arguments

Value

NULL. This helper has no result object.

dh()

Description

Generates a diploid population of doubled-haploid lines from a parental population.

Usage

dh(NamePg, NameP1, NoPg=-1)

Arguments

Details

For each progeny, a parental individual is chosen randomly from the active individuals of the parental population and a haploid meiotic product is generated. The selected haploid chromosome set is then doubled so that both homologues of each progeny carry the same recombined haplotype.

The simulation genome must be diploid. For positive NoPg, that many doubled-haploid progeny are generated. The special value -1 uses the allocation of an existing progeny population and therefore requires an existing destination with positive allocation.

The destination population is constructed from raw chromosome segments. Cached genotype and evaluation data can subsequently be recalculated. If meiosis or chromosome construction fails, the incomplete progeny population is removed.

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of creating doubled-haploid progeny.

divide.population()

Description

Splits individuals from one simulation population into a second population.

Usage

divide.population(NameP1, NameP2, NoI=-1)

Arguments

Details

The first requested individuals are separated from NameP2 and placed in NameP1; the remaining individuals stay in NameP2. Complete individual structures are moved, so chromosome segments, information fields, genotype data, and evaluations that belong to an individual move together.

Value

Returns the same invisible implementation-level list as population.divide(). The function is a compatibility wrapper and the meaningful result is the delegated population operation.

Set effect weights for all effects

Description

Set effect weights for all effects.

Usage

effect.weight.set.all(weight)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of setting all effect weights.

Remove a stored effect map

Description

Remove a stored effect map.

Usage

effmap.remove(Name)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of removing the requested effect map.

Remove all stored effect maps

Description

Remove all stored effect maps.

Usage

effmap.remove.all()

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of removing all effect maps.

Evaluate all loci in a population

Description

Evaluate all loci in a population.

Usage

evaluate.all.loci(PopName,
                  loci = paste(as.vector(unlist(linkage.map.get()[,3])), collapse=" "))

Arguments

Value

The same data.frame structure as evaluate.locus(), evaluated for all loci in the current map: rows are loci and columns are homozygote, heterozygote, and missing.

evaluate.allele()

Description

Calculates allele counts at one or more loci in a simulation population.

Usage

evaluate.allele(PopName, Loci, missing=0)

Arguments

Details

The population and linkage map must already be defined. For multiple loci, each row represents an allele at one locus. The other locus columns contain zero placeholders.

Value

A data.frame containing locus columns and count. Returns NULL invisibly when no result is available.

See Also

evaluate.allele2 accepts a character vector of locus names and excludes missing allele copies without first removing loci lacking completely observed genotypes. evaluate.allele.freq also calculates relative frequencies.

Examples

map <- data.frame(
   chrom = 1:2,
   pos = c(0.01, 0.02),
   name = c("form", "color")
)
define.genome(map)
init.population("P1", homozygote(1, NoInd = 2))

evaluate.allele("P1", "form color")

Calculate or return allele frequencies for selected loci

Description

Calculate or return allele frequencies for selected loci.

Usage

evaluate.allele.freq(PopName, Loci, missing=0)

Arguments

Value

A data.frame containing the allele counts and relative frequencies.

See Also

For vector based input of loci, see evaluate.allele.freq2.

Examples

map <- data.frame(chrom = 1,
                  pos = 0.01,
                  name = "form")
define.genome(map)

init.population("P1", homozygote(1))
init.population("P2", homozygote(2))

# Example: Generate 100 F1 hybrids
cross("F1","P1", "P2", 100)
evaluate.genotype("P1","form")

# Example: Repeated selfing
cross("F2", "F1", "F1", 1000, self = 1)
cross("F3", "F2", "F2", 1000, self = 1)
cross("F4", "F3", "F3", 1000, self = 1)

evaluate.genotype("F4", "form")
evaluate.allele.freq("F4","form")

evaluate.allele.freq2()

Description

Calculates allele counts and relative frequencies at one or more loci in a simulation population.

Usage

evaluate.allele.freq2(PopName, Loci, missing=0)

Arguments

Details

The population and linkage map must already be defined. Each element of Loci is interpreted as one locus name. Space-separated names within a single string are not split.

For multiple loci, each row represents an allele at one locus; the other locus columns contain zero placeholders. Frequencies are calculated by dividing each count by the sum of all returned counts. They therefore sum to one across the complete table, not separately within each locus. To obtain frequencies within a locus, evaluate that locus separately.

Value

A data.frame containing locus columns, count, and freq.

See Also

evaluate.allele.freq, an alternative implementation that accepts space-separated locus names and differs in its handling of missing alleles.

Examples

map <- data.frame(
   chrom = 1:2,
   pos = c(0.01, 0.02),
   name = c("form", "color"),
   class = paste0("trait", 1:2)
)
define.genome(map)

init.population("P1", homozygote(1))
init.population("P2", homozygote(2))
cross("F1", "P1", "P2", 10)
cross("F2", "F1", "F1", 1000, self = 1)

# Allele frequencies at a single locus
evaluate.allele.freq2("F2", "form")

# Allele counts at both loci, with frequencies normalised
# across the complete table
evaluate.allele.freq2("F2", map$name)

# Evaluate each locus separately for within-locus frequencies
evaluate.allele.freq2("F2", "form")
evaluate.allele.freq2("F2", "color")

evaluate.allele2()

Description

Calculates allele counts at one or more loci in a simulation population.

Usage

evaluate.allele2(PopName, Loci, missing=0)

Arguments

Details

The population and linkage map must already be defined. For multiple loci, each row represents an allele at one locus. The other locus columns contain zero placeholders.

Value

A data.frame containing locus columns and count. Returns NULL invisibly when the request cannot be evaluated.

See Also

evaluate.allele accepts space-separated locus names. evaluate.allele.freq2 also calculates relative frequencies.

Examples

map <- data.frame(
   chrom = 1:2,
   pos = c(0.01, 0.02),
   name = c("form", "color")
)
define.genome(map)
init.population("P1", homozygote(1, NoInd = 2))

evaluate.allele2("P1", c("form", "color"))

evaluate.genome()

Description

Computes the frequency distribution of an allele across the whole genome.

Usage

evaluate.genome(PopName, allele, chromosome=NULL, begin=NULL, end=NULL,
                verbose=FALSE)

Arguments

Details

Analysis is done on the level of the chromosomes, independently of the loaded marker map.

Value

A data.frame with one row per individual. It always contains ratio, the evaluated allele proportion. With verbose = TRUE it additionally contains length, total, and noBlocks, as returned by the genome-evaluation routine.

Note

See the lib00.example1 for an application of the command.

evaluate.genotype()

Description

Calculates genotype frequencies

Usage

evaluate.genotype(PopName, Loci, alleles=0, mode=2, bg=0)

Arguments

Details

The population and linkage map must already be defined. Counts represent numbers of individuals, and frequencies are calculated relative to the total number of included individuals. Names must only consist of letters and numbers (no spaces, dots, etc.).

Value

A data.frame containing the genotype combinations and the count/frequency information returned by the compiled genotype evaluator. If a specific allele combination is requested the result can be reduced to the matching row. Returns NULL invisibly if no result is available.

Examples

# Simple functionalty:
map <- data.frame(chrom = 1,
                  pos = 0.0,
                  name = "form",
                  class = "trait1")
define.genome(map)

init.population("P1", homozygote(1))
init.population("P2", homozygote(2))

cross("F1","P1", "P2", 100)
cross("BC1","F1", "P2", 100)

evaluate.genotype("BC1","form")

# Complex functionality: Two linked loci
reset.all()

map <- data.frame(
  chrom = c(1, 1),
  pos = c(0.2, 0.8),
  name = c("A", "B")
)
define.genome(map, length.vec = 1)

# Individual 1 carries haplotypes 1-1 and 2-2.
# Individual 2 carries haplotypes 1-2 and 2-1.
pop <- data.frame(
  ind   = c(1, 1, 1, 1, 2, 2, 2, 2),
  chrom = c(1, 1, 1, 1, 1, 1, 1, 1),
  hom   = c(1, 1, 2, 2, 1, 1, 2, 2),
  pos = c(0.2, 0.8, 0.2, 0.8, 0.2, 0.8, 0.2, 0.8),  
  all   = c(1, 2, 1, 2, 1, 2, 2, 1)
)
init.population("PhaseExample", pop)

# Preserve phase: the two individuals form separate categories,
# each with count 1 and frequency 0.5.
evaluate.genotype("PhaseExample", c("A", "B"), mode = 0)

# Ignore phase: both individuals are heterozygous at both loci,
# giving one category with count 2 and frequency 1.
evaluate.genotype("PhaseExample", c("A", "B"), mode = 2)

# Loci can also be supplied as a space-separated string.
evaluate.genotype("PhaseExample", "A B", mode = 2)

# Retrieve one observed phased combination.
evaluate.genotype("PhaseExample", c("A", "B"),
                  alleles = c(1, 2, 1, 2), mode = 0)

Calculate haplotype information for a pair of loci

Description

Calculate haplotype information for a pair of loci.

Usage

evaluate.hap.calc(locusA, locusB)

Arguments

Value

A numeric vector of length five, in the order noTI, noI, nodH, dLocA, and dLocB, containing the values returned by the compiled pairwise haplotype calculation.

Calculate a haplotype statistic for a pair of loci

Description

Calculate a haplotype statistic for a pair of loci.

Usage

evaluate.hap.calc.d(locusA, locusB)

Arguments

Value

An invisible numeric vector of length three, in the order dd, dp, and rr, containing the values returned by the compiled haplotype-statistic calculation.

Release or reset temporary haplotype-evaluation state

Description

Release or reset temporary haplotype-evaluation state.

Usage

evaluate.hap.free()

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of releasing haplotype evaluation state.

Initialize haplotype evaluation for a population

Description

Initialize haplotype evaluation for a population.

Usage

evaluate.hap.init(PopName, doubleHetero=0, missing=0)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of initializing haplotype evaluation state.

Return genotype results from the current haplotype evaluation

Description

Return genotype results from the current haplotype evaluation.

Usage

evaluate.hap.return.genotype()

Value

A data.frame containing the genotype table from the current initialized haplotype evaluation.

Return the table produced by the current haplotype evaluation

Description

Return the table produced by the current haplotype evaluation.

Usage

evaluate.hap.return.table()

Value

A data.frame containing the table from the current initialized haplotype evaluation.

Evaluate haplotypes for selected loci in a population

Description

Evaluate haplotypes for selected loci in a population.

Usage

evaluate.haplotype(PopName, Loci, missing=0,
                   bg=plabsim$allele.missing.indicator)

Arguments

Value

A data.frame containing the haplotype-evaluation table returned for the requested population and loci.

Evaluate linkage disequilibrium for a population and genomic position

Description

Evaluate linkage disequilibrium for a population and genomic position.

Usage

evaluate.ld(PopName, allele, chrom, pos)

Arguments

Value

A one-column data.frame named length, containing the linkage-disequilibrium segment lengths returned for the requested population, allele and position.

Evaluate selected loci in a population

Description

Evaluate selected loci in a population.

Usage

evaluate.locus(PopName, eLoci)

Arguments

Value

A data.frame with one row for each requested locus and columns homozygote, heterozygote, and missing, containing the corresponding genotype counts.

Evaluate marker-assisted donor-parent information for populations

Description

Evaluate marker-assisted donor-parent information for populations.

Usage

evaluate.mdp(NamePg, NameP1, NameP2, effectfile=NULL)

Arguments

Value

When a specific effectfile is supplied, the result is the invisible implementation-level list returned by the compiled MDP evaluator. When effectfile = NULL, the function evaluates all active effects for side effects and returns NULL.

Evaluate genetic values for simulation populations

Description

Evaluates genetic values for all active individuals in one or more simulation populations using loaded effect definitions.

Usage

evaluate.population(PopNames, effName=NULL)

Arguments

Details

The population must have a complete genotype representation for all active individuals. Evaluation calculates the effect-specific genetic values for all loaded effects. Element 0 is first calculated as the weighted sum of these values. If effName is supplied, element 0 is then replaced by the genetic value of the named effect, preserving the existing selection behavior.

Evaluation is population-wide. Allocation failure clears the genetic-value category rather than leaving only some individuals evaluated.

Any stored phenotypic values for a population being re-evaluated are discarded before the new genetic values are calculated.

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of calculating/storing evaluation values for the requested populations.

See Also

genotype.population, phenotype.population, get.population.gvalue

gd.allele.frequencies()

Description

Calculates the allele frequencies of the populations in a data set consisting of codominant molecular marker data.

Usage

gd.allele.frequencies(dta)

Arguments

Value

A data.frame of allele frequencies, with marker/allele combinations in rows and populations in columns.

gd.allow.zero.frequencies()

Description

If for a marker no allele was observed, this is a missing value if codominant markers are used. However, for dominant markers where each band is regarded as a marker with only one allele, markers where no allele are observed are not missing data.

Usage

gd.allow.zero.frequencies(allow=0)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of setting whether zero allele frequencies are allowed in the genetic-diversity routines.

gd.correct.missing()

Description

The function gd.correct.missing corrects missing marker data points in a data set. Two rules are applied: (1) If at least one allele was observed at a marker, missing values for this marker at other alleles are changed to zeros. (2) If at a marker no allele was observed but for all alleles only zeros are in the data set, the zeros are changed to missing data.

Usage

gd.correct.missing(dta)

Arguments

Value

A data.frame containing the corrected data, with the same row and column structure as the supplied data object.

gd.data.parameters()

Description

Determines the structure of a data set containing molecular marker data.

Usage

gd.data.parameters(dta)

Arguments

Value

A named list describing the genetic-diversity data object, with components colhead, rowhead, no.mar, no.all, no.pop, no.ind, ind.list, mar.list, and pop.list. These contain parsed column and row headings, marker/allele/population counts, individual indices, marker names, and population names, respectively.

Gd distance similarity

Description

Calculate genetic distance or similarity measures, with optional bootstrap inputs.

Usage

gd.distance.similarity(dta, measure, par, boot=0, no.pop.u=0, pop.u=0,
                       no.ind.u=0, ind.u=0, no.mar.u=0, mar.u=0)

Arguments

Value

A data.frame with columns OTU1, OTU2, and Measure, containing pairwise population comparisons. When resampling-based uncertainty is requested an additional SDev column contains the corresponding standard deviations.

Molecular marker data for several dummy populations

Description

This dataset illustrates how missing values are handled in the calculation of allele freuquencies.

Usage

data(gd.dummy.populations)

gd.genetic.distance()

Description

Calculates pairwise genetic distances between all pairs of populations in the dataset.

Usage

gd.genetic.distance(dta, measure="euc", par="dist", boot=0, no.pop.u=0,
                    pop.u=0, no.ind.u=0, ind.u=0, no.mar.u=0, mar.u=0)

Arguments

Value

A data.frame with columns OTU1, OTU2, and Measure, containing the requested pairwise genetic distances; an additional SDev column is included when resampling-based standard deviations are requested. Returns NULL invisibly on validation failure.

Note

1.) The Rogers distance and the Modified Rogers distance are standardized measures in the interval [0,1]. The standardization is achieved by the divisions by m and by 2 in the respective equations. This requests codominant markers! These measures can't be used with dominant markers. However the Euclidean distance is not standardized and can also be used with dominant marker data (such as the AFLP data in the dataset gd.maize.aflp).

2.) For homozygous genotypes Rogers' Distance (Rogers 1972) equals the Nei-Li Distance (Nei and Li 1979), which is the same as 1 minus the Dice coefficient (Dice 1945), further the Modified Rogers' Distance is the square root of the Rogers' Distance.

3.) For calculating pairwise genetic distances between individuals you can use populations consisting of one single individual each. The column names could be e.g., p1.1 p2.1 p3.1 p4.1

References

Dice, L.R. 1945. Measures of the amount of ecologic association between species. Ecology 26:197–302.

Nei, M. and W.H. Li. 1979. Mathematical Models for studying genetic variation in terms of restriction endonucleases. Proc. Natl. Acad. Sci. USA. 76:5268–5371.

Rogers, J.S. 1972. Measures of genetic similarity and genetic distance. VII. Univ. Tex. Publ. 7213:145–153.

Wright, S. 1978. Evolution and the Genetics of Populations. Volume 4: Variability Within and Among Natural Populations. University of Chicago Press, Chicago, Illinois.

gd.list.irregular()

Description

The function gd.list.irregular lists individuals for which at one marker more than two alleles were observed.

Usage

gd.list.irregular(dta1)

Arguments

Value

A data.frame with columns ind and marker, identifying individual/marker combinations for which more than two alleles were observed.

gd.list.missing()

Description

The function gd.list.missing lists the missing marker data points in a data set containing molecular marker data.

Usage

gd.list.missing(dta)

Arguments

Value

A data.frame with columns ind and marker, identifying individual/marker combinations with missing observations.

51 maize lines analyzed with 462 AFLP markers.

Description

This data set consists of AFLP data from 51 maize lines. 462 markers are used. This is dominant data. Each band is a marker, which has only one allele. For analyzing this type of dominant marker use gd.allow.zero.frequencies(1)

Usage

data(gd.maize.aflp)

Format

The first five rows and columns look like:

Each column contains the marker genotype of an individual. The identifier for an individual (the column name) contains the name of the population to which the individual belongs and the name of the individual, separated by a dot. For band there is a row in the dataset, the rowname contains the name of the marker and seperated by a dot a 1, indicating that each marker has only one allele.

The data matrix consists of zeros and ones, denoting whether a certain band was observed at an individual or not. Missing data are denoted with NA.

For AFLPs the primer combination and the band is separated by a +.

See Also

gd.genetic.distance, gd.similarity.coefficient, gd.maize.populations, gd.maize.lines, gd.salad.aflp

RFLP data from 50 maize lines

Description

This data set consists of the RFLP data from 50 maize lines.

Usage

data(gd.maize.lines)

Format

The format is described for the data set gd.maize.populations.

See Also

gd.genetic.distance, gd.similarity.coefficient, gd.maize.populations, gd.maize.aflp, gd.salad.aflp

SSR data from seven maize populations

Description

This data set consists of the SSR marker data of seven tropical maize populations. From each populations 48 individuals were samples analyzed with 85 polymorphic Single Sequence Repeat markers.

Usage

data(gd.maize.populations)

Format

The first five rows and columns look like:

Each column contains the marker genotype of an individual. The identifier for an individual (the column name) contains the name of the population to which the individual belongs and the name of the individual, separated by a dot. For each allel of a marker there is a row in the dataset, the rowname contains the name of the marker and the name of the allele seperated by a dot.

The data matrix consists of zeros and ones, denoting whether a certain allale was observed at an individual or not. Missing data are denoted with NA.

See Also

gd.genetic.distance, gd.similarity.coefficient, gd.maize.lines, gd.maize.aflp, gd.salad.aflp

Construct a matrix from genetic-distance results

Description

Construct a matrix from genetic-distance results.

Usage

gd.mk.matr(dta, distance)

Arguments

Value

A numeric matrix representation of the supplied pairwise distance results, with population labels taken from the data object.

gd.pcoa()

Description

Calculates a principal coordinate analysis for marker data. It is a wrapper for the cmdscale function.

Usage

gd.pcoa(dta, k=3)

Arguments

Value

A numeric matrix of principal-coordinate scores returned by cmdscale(), with rows corresponding to populations and columns to the first k principal coordinates.

Jasminas 44 salads analyzed with 108 AFLP markers.

Description

This data set consists of AFLP data from 44 salad lines. 108 markers are used. This is dominant data. Each band is a marker, which has only one allele. For analyzing this type of dominant marker use gd.allow.zero.frequencies(1)

Usage

data(gd.salad.aflp)

Format

The first five rows and columns look like:

Each column contains the marker genotype of an individual. The identifier for an individual (the column name) contains the name of the population to which the individual belongs and the name of the individual, separated by a dot. For band there is a row in the dataset, the rowname contains the name of the marker and seperated by a dot a 1, indicating that each marker has only one allele.

The data matrix consists of zeroes and ones, denoting whether a certain band was observed at an individual or not. Missing data are denoted with NA.

For AFLPs the primer combination and the band is separated by a +.

See Also

gd.genetic.distance, gd.similarity.coefficient, gd.maize.populations, gd.maize.lines, gd.maize.aflp

gd.similarity.coefficient()

Description

Calculates matching coefficients between individuals.

Usage

gd.similarity.coefficient(dta, measure="jac", par="dist", boot=0, no.pop.u=0,
                          pop.u=0, no.ind.u=0, ind.u=0, no.mar.u=0, mar.u=0,
                          resample.primers=FALSE)

Arguments

Value

A data.frame with columns OTU1, OTU2, and Measure, containing the requested pairwise similarity coefficients; an additional SDev column is included when resampling-based standard deviations are requested. Returns NULL invisibly on validation failure.

Note

Each population should consist of one indivdiual only.

Split or transform marker labels used by genetic-diversity routines

Description

Split or transform marker labels used by genetic-diversity routines.

Usage

gd.splitdot(m.a)

Arguments

Value

A character matrix with two columns and one row for each input string. The first column contains the part before the first dot (or underscore if no dot is present), and the second column contains the remaining part; if no separator is present the second field is empty.

Return status information concerning zero allele frequencies

Description

Return status information concerning zero allele frequencies.

Usage

gd.status.zero.frequencies()

Value

An integer scalar giving the current compiled status value for whether zero allele frequencies are allowed.

generate.effect.file()

Description

Generates a file with effect descriptions that can be used for selection. Effects can be loaded. Additive and dominance effects can be

Usage

generate.effect.file(fName, description)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of generating the effect file.

Note

See define.effects for the syntax of the descripton and for an example

generate.map.file()

Description

Generates a simulation linkage-map text file from a compact map description without itself installing the map.

Usage

generate.map.file(fName, description)

Arguments

Details

The description syntax is the same syntax consumed by define.map. The function validates the file name and description, normalizes a multi-element description to one comma-separated specification, and asks the simulation backend to write the map file.

The generated file can subsequently be loaded as a simulation linkage map. Generating the file does not by itself replace the currently loaded map.

Value

An invisible list whose retval component is the compiled map-generation status. Invalid map dimensions return list(retval = -2L) invisibly. The main effect is writing the generated map file.

generate.population()

Description

Generates one or more simulation populations from the marker-incidence matrix representation used by the genetic-distance routines.

Usage

generate.population(dta, backcross=FALSE)

Arguments

Details

The function interprets the row and column descriptors of dta to determine marker names, allele codes, population names, and individual membership. Allele coding must be numeric integer coding compatible with the simulation routines.

The R layer derives the population and marker dimensions and passes the matrix together with allele and missing-value information to the C population generator. The resulting objects are simulation populations represented by chromosome data, not SelectionTools marker-data sets.

The backcross flag selects the corresponding population-generation mode in the simulation backend. Existing genome and linkage-map definitions determine how generated marker information is represented in simulated chromosomes.

Value

An invisible implementation-level list returned by either the population-generation routine or the information routine used to report invalid allele encoding. The meaningful result is the side effect of generating the requested population when the input is valid.

genome.contribution()

Description

Calculates the distribution of one allele in populations.

Usage

genome.contribution(pops, allele, chromosome=NULL, begin=NULL, end=NULL)

Arguments

Details

Analysis is done on the level of the chromosomes, independently of the loaded marker map. Summarizes the results of evaluate.genome.

Value

A numeric matrix with one row per population and columns Obs, Mean, SDev, Min, Q10, Med, and Max, summarizing genome-contribution values.

Note

See the lib00.example1 for an application of the command.

Return the current genome parameters

Description

Returns the chromosome structure currently installed in the simulation backend.

Usage

genome.parameter.get()

Details

The result describes the simulation-wide genome parameters used to interpret chromosome segments and linkage-map positions. It includes the number of chromosomes, the number of homologues, and the chromosome-length vector.

Value

A named list with components no.chrom (number of chromosomes), no.hom (number of homologues), and chrom.len (chromosome-length vector).

Set genome parameters used by the simulation code

Description

Defines the chromosome structure used by the simulation backend.

Usage

genome.parameter.set(no.chrom, no.hom=2, chrom.len)

Arguments

Details

The genome definition is simulation-wide and determines the chromosome and homologue structure expected by population initialization, meiosis, crossing, single-seed descent, doubled-haploid production, and linkage-map operations.

chrom.len supplies one length per chromosome. Operations that model ordinary diploid marker data use two homologues. Changing genome parameters should therefore be coordinated with the loaded simulation linkage map and existing simulation populations.

Value

An invisible implementation-level list returned by the compiled state-setting or information routine. The function is primarily called for its side effect of resetting populations/map as needed and setting the genome parameters.

Extract or summarize genome segments for populations

Description

Extract or summarize genome segments for populations.

Usage

genome.segments(pops, allele, chromosome=NULL, begin=NULL, end=NULL)

Arguments

Value

A numeric matrix with one row per population and columns Obs, Mean, SDev, Min, Q10, Med, and Max, summarizing the number of genome segments.

genotype.population()

Description

Calculates marker genotypes for one or more simulation populations from their chromosome-segment representation and the currently loaded linkage map.

Usage

genotype.population(PopNames)

Arguments

Details

Simulation populations store chromosome segments as the primary genetic representation. This function projects those segments onto the loci of the currently loaded map and stores the two alleles for every active individual and mapped locus.

All active individuals of a population are treated as one genotype category: after a successful call every active individual has genotype data. If a population contains a mixture of genotyped and non-genotyped active individuals, the complete population is recalculated. Allocation failure clears the population genotype cache rather than leaving a partial mixture.

Population names may be supplied as a vector; the R wrapper combines multiple names into the space-separated form accepted by the C routine. Genotyping does not evaluate genetic values. Existing evaluations that depend on a genotype may need to be recalculated after changes to the underlying population or map.

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of generating/storing genotype information for the requested populations.

get.genome.par()

Description

Returns the current simulation genome parameters.

Usage

get.genome.par()

Details

The returned values describe the genome used by simulation populations: chromosome count, number of homologues, and chromosome lengths. These parameters are separate from a SelectionTools marker data set, although the marker-to-simulation bridge can derive and install compatible simulation genome parameters from a marker map.

Value

Returns the same named list as genome.parameter.get(), with components no.chrom, no.hom, and chrom.len.

get.map()

Description

Returns the currently loaded simulation linkage map.

Usage

get.map()

Details

The result describes the simulation map points in their active access order, including chromosome, map position, locus name, and class. Retrieving the map does not modify simulation populations or marker-data sets.

Value

Returns the same data.frame as linkage.map.get(), with columns chrom, pos, name, and class.

Return the current marker-assisted donor-parent information

Description

Return the current marker-assisted donor-parent information.

Usage

get.mdp()

Value

An integer scalar containing the current marker-assisted donor-parent (MDP) value returned by the compiled routine.

get.population()

Description

Returns the raw chromosome-segment representation of a simulation population as an R data frame.

Usage

get.population(PopName)

Arguments

Details

Each row identifies an individual, chromosome, homologue, segment start position, and allele. These rows are the primary simulation representation from which marker genotypes are derived when genotype.population is run.

The returned data frame can be used to inspect or serialize a population and is the representation accepted by init.population. Retrieving the population does not alter genotype or evaluation caches.

Value

A data.frame with columns ind, chrom, hom, pos, and all, representing the active population in the package population format.

Get genetic values from a simulation population

Description

Returns stored evaluated genetic values for the active individuals of a simulation population.

Usage

get.population.gvalue(name, EffName=NULL)

Arguments

Details

Genetic values are derived population data created by population evaluation or explicitly supplied through set.population.gvalue.

If EffName is omitted, element 0 of the genetic value array is returned. After ordinary population evaluation this is the weighted genetic selection index. If EffName is supplied, the corresponding effect-specific genetic value is returned.

Value

A one-column data.frame named gvalue, containing one genetic value per active individual in the requested population.

See Also

evaluate.population, set.population.gvalue, get.population.pvalue

Return stored information for individuals in a population

Description

Return stored information for individuals in a population.

Usage

get.population.info(PopName, ind)

Arguments

Value

Returns the same character value or NULL as population.info.get().

Get phenotypic values from a simulation population

Description

Returns stored phenotypic values for the active individuals of a simulation population.

Usage

get.population.pvalue(name, EffName=NULL)

Arguments

Details

Phenotypic values must previously have been generated with phenotype.population. If EffName is omitted, element 0 of the phenotypic value array is returned. This is the weighted phenotypic selection index. If EffName is supplied, the corresponding effect-specific phenotypic value is returned.

Value

A one-column data.frame named pvalue, containing one phenotypic value per active individual in the requested population.

See Also

phenotype.population, get.population.gvalue

get.population.size()

Description

Returns the active size and allocated capacity of a simulation population.

Usage

get.population.size(PopName)

Arguments

Details

The active size is the number of individuals currently belonging to a population. The allocated capacity is internal storage available to the population and can differ from the active size after resizing or other population operations.

Several population names can be supplied in one character string, separated by blanks. In that case, NoInds and NoIndsAlloc are summed over all specified populations.

Value

Returns the same one-row data.frame as population.size.get(), with columns NoInds and NoIndsAlloc. For several population names these columns contain the corresponding sums. Returns NULL if a requested population is unavailable.

get.score()

Description

The function get.score() returns a field with the calculated genotypic index for every individual of the population pop. If an effect is specified then the value of this effect is returned.

Usage

get.score(pop, effectfile=NULL)

Arguments

Value

A one-column data.frame named gvalue, containing the genetic values obtained after genotyping and evaluating the requested population.

Build the genomic-selection variance or covariance matrix for a data set

Description

Build the genomic-selection variance or covariance matrix for a data set.

Usage

gs.build.V(out.filename = "V.matrix", auxfiles = FALSE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the generated variance/covariance matrix V when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

gs.build.Z()

Description

The function gs.build.Z builds the design (Z) matrix out of the marker data for genomic selection.

Usage

gs.build.Z(out.filename = "Z.matrix", auxfiles = FALSE, data.set = "default")

Arguments

Details

By default, genotypes are coded as 0, 1, or 2, representing the number of copies of the effect allele. When effect alleles have not already been defined, the larger observed allele code at each marker is used as the effect allele. For biallelic STvcf data with both REF and ALT observed, this corresponds to 0 for REF/REF, 1 for REF/ALT, and 2 for ALT/ALT. Missing genotypes receive the same value as heterozygotes (1 by default), so these cannot be distinguished in the resulting matrix.

Value

Invisibly returns a matrix containing the generated marker/design matrix Z when auxfiles = TRUE and generation succeeds; otherwise NULL.

Build estimation and validation subsets from a base data set

Description

Build estimation and validation subsets from a base data set.

Usage

gs.build.esvs(es.size, base.set = "default", estimation.set = "none",
              validation.set = "none", es_m = NULL, es_p = NULL,
              vs_m = NULL, vs_p = NULL, auxfiles = FALSE)

Arguments

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of constructing the estimation and validation subsets. Validation failures may return NULL.

Build training and prediction subsets from a base data set

Description

Build training and prediction subsets from a base data set.

Usage

gs.build.tsps(ts.size, base.set = "default", training.set = "none",
              prediction.set = "none", es_m = NULL, es_p = NULL,
              vs_m = NULL, vs_p = NULL, auxfiles = FALSE)

Arguments

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of constructing the training and prediction subsets. Validation failures may return NULL.

Check whether p-values are available for a genomic-selection data set

Description

Check whether p-values are available for a genomic-selection data set.

Usage

gs.check.pvals(data.set ="default")

Arguments

Value

A logical scalar indicating whether p-values are available for the requested genomic-selection data set.

gs.compare.effects()

Description

Creates a scatter plot of effects of two different models to visualize differences in estimated effects.

Usage

gs.compare.effects(data.set.a, data.set.b, label.a = data.set.a,
                   label.b = data.set.b)

Arguments

Value

No useful return value; the function is called for its side effect of comparing and plotting marker-effect results. Validation failures return NULL invisibly.

Evaluate Crosses by Expected Superior Progeny Value

Description

Calculates the expected superior progeny value for every evaluated cross by combining its expected mean and segregation variance.

Usage

gs.cross.eval.es(data.set = "default", alpha = 0.1, N = 0, G = 0)

Arguments

Details

The expected superior progeny criterion combines the expected cross mean with the amount of segregation expected among the progeny. For a selected fraction \alpha, the criterion described by Zhong and Jannink (2007) is

\mathrm{es} = \mu + i(\alpha)\,\sigma_g

where \mu is the expected cross mean and \sigma_g is the square root of the segregation variance. The standardized selection differential is

i(\alpha) = \frac{g_{0,1}\left[G^{-1}_{0,1}(1-\alpha)\right]}{\alpha}

where g_{0,1} is the probability density function of the standard normal distribution and G^{-1}_{0,1} is the inverse of its cumulative distribution function.

For a small finite progeny population, when both N and G are nonzero, the function sets \alpha=N/G and applies the correction of Burrows (1972):

\mathrm{es} = \mu + i(N,G)\,\sigma_g

with

i(N,G) = i(\alpha) - \frac{G-N}{2N(G+1)i(\alpha)}

The calculated value is stored as the cross criterion es. Results for all evaluated crosses can subsequently be obtained with gs.cross.info.

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of evaluating all crosses by expected superior progeny value. Validation failures may return NULL.

References

Zhong S, Jannink JL (2007) Using quantitative trait loci results to discriminate among crosses on the basis of their progeny mean and variance. Genetics 177:567–576.

Burrows RM (1972) Expected selection differentials for directional selection. Biometrics 28:1091–1100.

See Also

gs.cross.eval.mu, gs.cross.eval.va, gs.cross.info

Evaluate Crosses by Genetic Distance

Description

Calculates a genetic distance for every possible pair of individuals in a SelectionTools data set and stores it as a cross-evaluation criterion.

Usage

gs.cross.eval.gd(dist = "rd", data.set = "default")

Arguments

Details

Genetic distance can be evaluated independently of estimated marker effects. The result is stored as the cross criterion gd and can subsequently be obtained together with the other cross criteria using gs.cross.info.

The definitions and formulas for Euclidean distance, Rogers distance, and Modified Rogers distance are documented in st.genetic.distances. The properties of these and related similarity and dissimilarity coefficients in plant breeding are discussed by Reif et al. (2005).

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of evaluating all crosses by genetic distance. Validation failures may return NULL.

References

Reif JC, Melchinger AE, Frisch M (2005) Genetical and mathematical properties of similarity and dissimilarity coefficients applied in plant breeding and seed bank management. Crop Science 45:1–7.

See Also

st.genetic.distances, gs.cross.eval.mu, gs.cross.info

Evaluate crosses using genetic-distance function

Description

Evaluate crosses using genetic-distance function.

Usage

gs.cross.eval.gd.fct(dist = "rd", split = 1, data.set = "default")

Arguments

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of evaluating factorial crosses by genetic distance. Validation failures may return NULL.

Evaluate Crosses by Maximum Marker-Effect Value

Description

Calculates the maximum marker-effect based performance that can be assembled from the parental alleles for every possible pair of parents in a SelectionTools data set.

Usage

gs.cross.eval.ma(data.set = "default")

Arguments

Details

Using the notation of gs.cross.eval.mu, the maximum value for a line derived from a cross is

\mathrm{ma} = \beta_0 + \sum_m \max(\beta_{mi},\beta_{mj})

where \beta_0 is the intercept and \beta_{mi} and \beta_{mj} are the marker-effect contributions of the alleles carried by P1 and P2 at marker m.

The calculated value is stored as the cross criterion ma. It is a marker-effect based upper limit obtained by combining, marker by marker, the larger of the two parental contributions. Results for all evaluated crosses can subsequently be obtained with gs.cross.info.

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of evaluating all crosses by the maximum marker-effect value. Validation failures may return NULL.

See Also

gs.cross.eval.mu, gs.cross.eval.mi, gs.cross.info

Evaluate Crosses by Minimum Marker-Effect Value

Description

Calculates the minimum marker-effect based performance that can be assembled from the parental alleles for every possible pair of parents in a SelectionTools data set.

Usage

gs.cross.eval.mi(data.set = "default")

Arguments

Details

Using the notation of gs.cross.eval.mu, the minimum value for a line derived from a cross is

\mathrm{mi} = \beta_0 + \sum_m \min(\beta_{mi},\beta_{mj})

where \beta_0 is the intercept and \beta_{mi} and \beta_{mj} are the marker-effect contributions of the alleles carried by P1 and P2 at marker m.

The calculated value is stored as the cross criterion mi. It is a marker-effect based lower limit obtained by combining, marker by marker, the smaller of the two parental contributions. Results for all evaluated crosses can subsequently be obtained with gs.cross.info.

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of evaluating all crosses by the minimum marker-effect value. Validation failures may return NULL.

See Also

gs.cross.eval.mu, gs.cross.eval.ma, gs.cross.info

Evaluate Crosses by Expected Progeny Mean

Description

Calculates the expected mean performance of the progeny for every possible pair of parents in a SelectionTools data set from previously estimated marker effects.

Usage

gs.cross.eval.mu(data.set = "default")

Arguments

Details

For a cross between parents P1 and P2, the expected progeny mean is calculated as

\mu = \beta_0 + \sum_m (\beta_{mi} + \beta_{mj})/2

where \beta_0 is the intercept, \beta_{mi} is the effect of allele i carried by P1 at marker m, and \beta_{mj} is the effect of allele j carried by P2 at marker m.

The calculated value is stored as the cross criterion mu. Results for all evaluated crosses can subsequently be obtained with gs.cross.info.

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of evaluating all crosses by expected progeny mean. Validation failures may return NULL.

See Also

gs.cross.eval.mi, gs.cross.eval.ma, gs.cross.eval.va, gs.cross.eval.es, gs.cross.info

Evaluate Crosses by Segregation Variance

Description

Calculates the expected segregation variance for every possible pair of parents in a SelectionTools data set from previously estimated marker effects.

Usage

gs.cross.eval.va(data.set = "default", pop.type = "unlinked", t = 0,
                 map.function = "Haldane")

Arguments

Details

The function estimates the segregation variance \sigma_g^2 of each cross from the marker effects. The segregation variance describes how strongly progeny from a cross are expected to differ genetically.

For pop.type = "DH" or "SSD", linkage and recombination are taken into account using the genetic map; this is the cross-variance calculation described by Osthushenrich et al. (2017). With pop.type = "unlinked", the calculation treats the loci as unlinked. The current implementation also accepts "CRS" as a linked population type.

The calculated variance is stored as the cross criterion va. Its square root, \sigma_g, is used by gs.cross.eval.es when the expected superior progeny criterion is calculated. Results for all evaluated crosses can subsequently be obtained with gs.cross.info.

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of evaluating all crosses by segregation variance. Validation failures may return NULL.

References

Osthushenrich T, Frisch M, Herzog E (2017) Genomic selection of crossing partners on basis of the expected mean and variance of their derived lines. PLoS ONE 12(12):e0188839.

See Also

gs.cross.eval.mu, gs.cross.eval.es, gs.cross.info

Return or write information for evaluated crosses

Description

Return or write information for evaluated crosses.

Usage

gs.cross.info(bestn = 0, sortby = "index", out.filename = "cross.info",
              data.set = "default")

Arguments

Value

Invisibly returns a data.frame containing the evaluated-cross information when the compiled operation succeeds; otherwise NULL. Columns P1Name and P2Name are character strings, so numeric-looking individual identifiers are retained unchanged.

Return or write genetic-distance information for crosses

Description

Return or write genetic-distance information for crosses.

Usage

gs.cross.info.gd(out.filename ="cross.info.gd", data.set ="default")

Arguments

Value

Invisibly returns a data.frame containing the genetic-distance cross information read from the generated result when the compiled operation succeeds; otherwise NULL.

gs.cross.validation()

Description

Splits a given data set into estimation and prediction set. Estimates marker effects with the specified model using the estimation set and predicts direct genomic values (DGV) for the built prediction set.

Usage

gs.cross.validation(estimation.method, n.ts, n.runs, hsq = 0.8, alpha = 1,
                    maxiter = 100, precision = 0.0001,
                    out.filename.r = "crosval", out.filename.u = "effects",
                    auxfiles = TRUE, data.set = "default")

Arguments

Value

Invisibly returns a list when auxfiles = TRUE and cross-validation succeeds. Component cor is a numeric matrix of cross-validation correlations and component eff is a numeric matrix of estimated effects. Otherwise NULL.

Estimate marker effects using the LSQ method

Description

Estimate marker effects using the LSQ method.

Usage

gs.esteff.lsq(out.filename = "eff.lsq", auxfiles = TRUE, data.set ="default")

Arguments

Value

Invisibly returns a numeric matrix containing the least-squares marker-effect estimates when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate marker effects using the RMLA method

Description

Estimate marker effects using the RMLA method.

Usage

gs.esteff.rmla(alpha = 1, maxiter = 1000, precision = 0.0001, hsq = 0.9,
               out.filename = "eff.rmla", auxfiles = TRUE,
               data.set ="default")

Arguments

Value

Invisibly returns a numeric matrix containing the RMLA marker-effect estimates when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

gs.esteff.rmlc()

Description

Estimates marker effects using BLUP with constant variances for each marker.

Usage

gs.esteff.rmlc(maxiter = 1000, precision = 0.0001, hsq = 0.9,
               out.filename = "eff.rmlc", auxfiles = FALSE,
               data.set ="default")

Arguments

Details

The restricted maximum likelihood (REML) method is used to estimate variance components. In a next step, lambda is calculated using the formula:

\lambda=\frac{\sigma_e^2}{\frac{\sigma_g^2}{m}}

where \sigma_e^2 is the residual error variance, \sigma_g^2 is the genetic variance and m is the number of markers.

Value

Invisibly returns a numeric matrix containing the RMLC marker-effect estimates when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate marker effects using the RMLR method

Description

Estimate marker effects using the RMLR method.

Usage

gs.esteff.rmlr(maxiter = 1000, precision = 0.001, hsq = 0.9,
               out.filename = "eff.rmlr", auxfiles = TRUE,
               data.set ="default")

Arguments

Value

Invisibly returns a numeric matrix containing the RMLR marker-effect estimates when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

gs.esteff.rmlv()

Description

Estimates marker effects using BLUP with variable variances for the markers.

Usage

gs.esteff.rmlv(maxiter = 1000, precision = 0.001, hsq = 0.9,
               out.filename = "eff.rmlv", auxfiles = FALSE,
               data.set ="default")

Arguments

Details

The restricted maximum likelihood (REML) method is used to estimate variance components.

Value

Invisibly returns a numeric matrix containing the RMLV marker-effect estimates when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate Marker Effects by Ridge Regression

Description

Estimates genome-wide marker effects by ridge-regression methods, including RR-BLUP.

Usage

gs.esteff.rr(method = "BLUP", maxiter = 1000, precision = 0.0001, hsq = 0.80,
             alpha = 1, out.filename = "eff.rr", auxfiles = FALSE,
             data.set = "default")

Arguments

Details

With method="BLUP", SelectionTools fits the standard ridge-regression BLUP model. The implementation derives starting genetic and residual variance components from the observed performance variance and hsq. If maxiter>0, these starting values are refined by the mixed-model engine until the requested precision is reached or maxiter iterations have been performed.

Setting maxiter=0 omits this variance-component iteration. In that case the hsq-derived variance components are retained directly. This provides the computationally faster fixed-heritability form used in the SelectionTools simulation vignette.

After effect estimation, the marker effects are stored in data.set and can be used for genomic prediction, cross evaluation, or transferred to the simulation backend. The model fit for the training population can be inspected with gs.plot.model.fit.

Value

Invisibly returns a numeric matrix containing the estimated marker effects from ridge regression when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL. The estimated effects are also stored in data.set.

References

Whittaker JC, Thompson R, Denham MC (2000) Marker-assisted selection using ridge regression. Genetics Research 75:249–252.

Meuwissen THE, Hayes BJ, Goddard ME (2001) Prediction of total genetic value using genome-wide dense marker maps. Genetics 157:1819–1829.

Habier D, Fernando RL, Dekkers JCM (2007) The impact of genetic relationship information on genome-assisted breeding values. Genetics 177:2389–2397.

Hofheinz N, Frisch M (2014) Heteroscedastic ridge regression approaches for genome-wide prediction with a focus on computational efficiency and accurate effect estimation. G3 4:539–546.

See Also

gs.plot.model.fit, gs.predict.genotypes, gs.return.effects

Estimate genomic values for an estimation or prediction data set

Description

Estimate genomic values for an estimation or prediction data set.

Usage

gs.estimate.gv(estimation.set ="default", prediction.set ="default",
               out.filename = "breeding.values", auxfiles = TRUE)

Arguments

Value

Invisibly returns a data.frame with genomic-value results when auxfiles = TRUE and estimation succeeds. It contains individual identifiers and predicted genomic values, and also observed phenotypes when those are present in the generated result. Otherwise NULL.

Return the genomic-selection variance or covariance matrix for a data set

Description

Return the genomic-selection variance or covariance matrix for a data set.

Usage

gs.get.V(data.set = "default")

Arguments

Value

Invisibly returns the current numeric variance/covariance matrix V; returns NULL if it cannot be obtained from the current data set.

Return the genomic-selection marker or design matrix for a data set

Description

Return the genomic-selection marker or design matrix for a data set.

Usage

gs.get.Z(data.set = "default")

Arguments

Value

Invisibly returns the current numeric marker/design matrix Z; returns NULL if it cannot be obtained from the current data set.

Return the genomic-selection information matrix for a data set

Description

Return the genomic-selection information matrix for a data set.

Usage

gs.get.im(data.set = "default")

Arguments

Value

An invisible named integer vector with components i, the number of individuals, and m, the number of markers in the requested data set.

Return the genomic-selection information level for a data set

Description

Return the genomic-selection information level for a data set.

Usage

gs.get.info.level(data.set ="default")

Arguments

Value

An integer scalar giving the current genomic-selection information level for the requested data set.

Return the genomic-selection response vector for a data set

Description

Return the genomic-selection response vector for a data set.

Usage

gs.get.y(data.set = "default")

Arguments

Value

Invisibly returns the current numeric response vector y; returns NULL if it cannot be obtained from the current data set.

Print or handle a genomic-selection information message

Description

Print or handle a genomic-selection information message.

Usage

gs.info(lev, msg)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of issuing the requested genomic-selection information message.

Estimate or set genomic-selection lambda values using the aov method

Description

Estimate or set genomic-selection lambda values using the aov method.

Usage

gs.lambda.aov(hsq, alpha = 1, out.filename = "lambda", auxfiles = TRUE,
              data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the ANOVA method when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the const method

Description

Estimate or set genomic-selection lambda values using the const method.

Usage

gs.lambda.const(lambda, out.filename = "lambda", auxfiles = FALSE,
                data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the constant-lambda calculation when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the emstep method

Description

Estimate or set genomic-selection lambda values using the emstep method.

Usage

gs.lambda.emstep(constvar = FALSE, out.filename = "lambda", auxfiles = TRUE,
                 data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the EM-step method when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the hsq method

Description

Estimate or set genomic-selection lambda values using the hsq method.

Usage

gs.lambda.hsq(hsq, out.filename = "lambda", auxfiles = TRUE,
              data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results calculated from heritability when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the reg method

Description

Estimate or set genomic-selection lambda values using the reg method.

Usage

gs.lambda.reg(hsq, out.filename = "lambda", auxfiles = TRUE,
              data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the regression method when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the rmla method

Description

Estimate or set genomic-selection lambda values using the rmla method.

Usage

gs.lambda.rmla(alpha = 1, maxiter = 1000, precision = 0.0001, hsq = 0.9,
               out.filename = "lambda", auxfiles = TRUE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the RMLA method when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the rmla.02 method

Description

Estimate or set genomic-selection lambda values using the rmla.02 method.

Usage

gs.lambda.rmla.02(alpha = 1, maxiter = 1000, precision = 0.001, hsq = 0.9,
                  out.filename = "lambda", auxfiles = TRUE,
                  data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the RMLA.02 method when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the rmlc method

Description

Estimate or set genomic-selection lambda values using the rmlc method.

Usage

gs.lambda.rmlc(maxiter = 1000, precision = 0.0001, hsq = 0.9,
               out.filename = "lambda", auxfiles = TRUE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the RMLC method when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the rmlr method

Description

Estimate or set genomic-selection lambda values using the rmlr method.

Usage

gs.lambda.rmlr(maxiter = 1000, precision = 0.001, hsq = 0.9,
               out.filename = "lambda", auxfiles = TRUE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the RMLR method when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the rmlv method

Description

Estimate or set genomic-selection lambda values using the rmlv method.

Usage

gs.lambda.rmlv(maxiter = 1000, precision = 0.001, out.filename = "lambda",
               auxfiles = TRUE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from the RMLV method when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate or set genomic-selection lambda values using the rrblup method

Description

Estimate or set genomic-selection lambda values using the rrblup method.

Usage

gs.lambda.rrblup(maxiter = 1000, precision = 1e-4, hsq = 0.8,
                 out.filename = "lambda", auxfiles = TRUE,
                 data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda results from RR-BLUP when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Gs mme coeff

Description

Build or return the coefficient matrix for genomic-selection mixed-model equations.

Usage

gs.mme.coeff(out.filename = "mme.coeff", auxfiles = FALSE,
             data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the mixed-model coefficient matrix when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Gs mme invcoeff

Description

Build or return the inverse coefficient matrix for genomic-selection mixed-model equations.

Usage

gs.mme.invcoeff(out.filename = "inv.mme", auxfiles = TRUE)

Arguments

Value

Invisibly returns a numeric matrix containing the inverse mixed-model coefficient matrix when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Gs mme restcoeff

Description

Build or return the restricted coefficient matrix for genomic-selection mixed-model equations.

Usage

gs.mme.restcoeff(out.filename = "mme.coeff", auxfiles = FALSE)

Arguments

Value

Invisibly returns a numeric matrix containing the restricted mixed-model coefficient matrix when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Gs mme restrhs

Description

Build or return the restricted right-hand side for genomic-selection mixed-model equations.

Usage

gs.mme.restrhs(out.filename = "mme.rhs", auxfiles = FALSE)

Arguments

Value

Invisibly returns a numeric matrix containing the restricted mixed-model right-hand side when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Build or return the right-hand side for genomic-selection mixed-model equations

Description

Build or return the right-hand side for genomic-selection mixed-model equations.

Usage

gs.mme.rhs(out.filename = "mme.rhs", auxfiles = FALSE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the mixed-model right-hand side when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Gs mme solve

Description

Build or return the mixed-model equation solution for genomic-selection mixed-model equations.

Usage

gs.mme.solve(out.filename = "mme.solution", auxfiles = FALSE,
             data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the mixed-model equation solution when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Build or solve transformed mixed-model equations (coeff)

Description

Build or solve transformed mixed-model equations (coeff).

Usage

gs.mmet.coeff(out.filename = "mme.coeff", auxfiles = FALSE,
              data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the transformed mixed-model coefficient matrix when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Build or solve transformed mixed-model equations (coeff.3)

Description

Build or solve transformed mixed-model equations (coeff.3).

Usage

gs.mmet.coeff.3(out.filename = "mme.coeff", auxfiles = FALSE,
                data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the alternative transformed mixed-model coefficient matrix when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Build or solve transformed mixed-model equations (rhs)

Description

Build or solve transformed mixed-model equations (rhs).

Usage

gs.mmet.rhs(out.filename = "mme.rhs", auxfiles = FALSE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the transformed mixed-model right-hand side when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Build or solve transformed mixed-model equations (solve)

Description

Build or solve transformed mixed-model equations (solve).

Usage

gs.mmet.solve(out.filename = "mme.solution", auxfiles = FALSE,
              data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the transformed mixed-model solution when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Set or process all marker effects using the negative-effect convention

Description

Set or process all marker effects using the negative-effect convention.

Usage

gs.neg.effall(data.set ="default")

Arguments

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of processing marker effects using the negative-effect convention. Validation failures may return NULL.

gs.plot.effects()

Description

Plotting function for the estimated marker effects.

Usage

gs.plot.effects(data.set = "default", absolute = TRUE, alpha = 0.05,
                p.adjust.method = "none", pvals = NULL, xlim = NULL,
                ylim = NULL, plt = TRUE, col.sp = "blue", pch.sp = 19,
                col.sn = "blue", pch.sn = 19, col.ns = "blue", pch.ns = 1,
                ...)

Arguments

Value

Invisibly returns the data.frame used for plotting, with columns chrom, pos, name, cpos, and effect, and a pvalue column when p-values are available. Returns NULL if the required effect or map data are unavailable.

Plot the Fit of a Genomic Prediction Model

Description

Plots observed performance values against genomic predictions for the individuals used to fit the marker model.

Usage

gs.plot.model.fit(training.set ="default", title = "")

Arguments

Details

The function calls gs.predict.genotypes with training.set used as both training and prediction set. The plotted y values are the observed performance values stored in that data set, whereas yhat are the direct genomic predictions obtained from the estimated marker effects. In the simulation workflow, these yhat values represent estimated genotypic values of the training population.

The plot includes the identity line, horizontal and vertical lines through the respective means, and reports both the Pearson correlation r and the Spearman rank correlation rho between y and yhat. Marker effects must have been estimated before this function is called, and performance data must be available in training.set.

Value

No useful return value is intended. The function is called for its side effect of plotting model-fit information; invalid input returns NULL invisibly.

See Also

gs.esteff.rr, gs.predict.genotypes, gs.plot.validation

gs.plot.validation()

Description

Creates a graphical output wit two plots. The left plot shows the model fit as produced with the function gs.plot.model.fit. The right plot shows a scatter plot of the predicted DGV and the real phenotypes for a set of individuals that was not used for estimation of marker effects.

Usage

gs.plot.validation(training.set, prediction.set, title="")

Arguments

Details

Within this function, the function gs.estimate.gv is called twice. For the model fit, the estimation set is both used as estimation and prediction set in gs.estimate.gv. To validate the model, the function gs.estimate.gv is called again with the validation set used as prediction set.
The validation set is a set of individuals that was not used for building the model, but having phenotypes to be correlated to the predicted DGVs.

Value

No useful return value is intended. The function is called for its side effect of plotting validation information; invalid input returns NULL invisibly.

Set or process all marker effects using the positive-effect convention

Description

Set or process all marker effects using the positive-effect convention.

Usage

gs.pos.effall(data.set ="default")

Arguments

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of processing marker effects using the positive-effect convention. Validation failures may return NULL.

gs.predict.genotypes()

Description

Predicts direct genomic values (DGV) for a given set of individuals in the prediction set. Works only after the marker effects were estimated.

Usage

gs.predict.genotypes(training.set ="default", prediction.set ="default",
                     out.filename = "breeding.values", auxfiles = TRUE)

Arguments

Value

Invisibly returns a data.frame with prediction results when auxfiles = TRUE and prediction succeeds. It contains individual identifiers and predicted genomic values, and also observed phenotypes when those are present in the generated result. Otherwise NULL.

Reset genomic-selection data and settings

Description

Reset genomic-selection data and settings.

Usage

gs.reset()

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of resetting the genomic-selection state.

Restrict marker data using the package genomic-selection interface

Description

Restrict marker data using the package genomic-selection interface.

Usage

gs.restrict.marker.data.01(outfile, traitfile = NULL, NoAll.MAX = 999,
                           MaMis.MAX = 1, ExHet.MIN = 0, InMis.MAX = 1,
                           data.set = "default")

Arguments

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of restricting the genomic-selection marker data. Validation failures may return NULL.

gs.return.effects()

Description

Returns the marker effects currently stored in a SelectionTools data set. The underlying routine writes the effects to an intermediate file; the R wrapper reads that file into R and deletes it before returning.

Usage

gs.return.effects(out.filename ="effects", data.set ="default")

Arguments

Value

A data.frame containing the marker-effect table. If the underlying routine reports an error, NULL is returned invisibly. The intermediate file used to transfer the table is deleted after reading.

Note

This function provides access to effects stored by genomic-effect estimation functions such as gs.esteff.rr(), gs.esteff.rmlc(), and gs.esteff.rmlv(). Their auxfiles argument defaults to FALSE; gs.return.effects() can be used to retrieve the stored effects independently of that output option.

Return marker p-values for a genomic-selection data set

Description

Return marker p-values for a genomic-selection data set.

Usage

gs.return.pvals(out.filename ="effects", data.set ="default")

Arguments

Value

A data.frame containing the marker p-value table. If the underlying routine reports an error, NULL is returned invisibly. The intermediate file used to transfer the table is deleted after reading.

Set all info levels used by the genomic-selection routines

Description

Set all info levels used by the genomic-selection routines.

Usage

gs.set.all.info.levels(level)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of setting all genomic-selection information levels.

Set allele codes used by the genomic-selection routines

Description

Set allele codes used by the genomic-selection routines.

Usage

gs.set.allele.codes(aa = 0, aA = 1, AA = 2, an = 0.5, nn = 1, nA = 1.5,
                    data.set ="default")

Arguments

Value

NULL, returned invisibly. The function is called for its side effect of setting the allele codes used by the genomic-selection routines.

Set effects used by the genomic-selection routines

Description

Set effects used by the genomic-selection routines.

Usage

gs.set.effects(eff, filename ="seteffects", data.set ="default")

Arguments

Value

On a successful run, an invisible implementation-level list returned by the final timing/information helper; the meaningful result is the side effect of setting marker effects in the genomic-selection data set. Validation failures may return NULL.

Set info level used by the genomic-selection routines

Description

Set info level used by the genomic-selection routines.

Usage

gs.set.info.level(level, data.set ="default")

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of setting the genomic-selection information level for the data set.

Set lambda used by the genomic-selection routines

Description

Set lambda used by the genomic-selection routines.

Usage

gs.set.lambda(lambda, out.filename = "lambda", auxfiles = FALSE,
              data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the lambda values produced while setting lambda when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Set num threads used by the genomic-selection routines

Description

Set num threads used by the genomic-selection routines.

Usage

gs.set.num.threads(active)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of setting the number of genomic-selection computational threads.

Set performance data used by the genomic-selection routines

Description

Set performance data used by the genomic-selection routines.

Usage

gs.set.performance.data(y, data.set = "default")

Arguments

Value

An invisible integer scalar containing the status value returned by the compiled performance-data setter.

Perform single-marker analysis for a genomic-selection data set

Description

Perform single-marker analysis for a genomic-selection data set.

Usage

gs.single.marker.aov(alpha = 1, out.filename = "sm.reg", auxfiles = TRUE,
                     data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the single-marker ANOVA results when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Perform single-marker analysis for a genomic-selection data set

Description

Perform single-marker analysis for a genomic-selection data set.

Usage

gs.single.marker.reg(out.filename = "sm.reg", auxfiles = TRUE,
                     data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the single-marker regression results when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Start or stop the genomic-selection timing helper

Description

Start or stop the genomic-selection timing helper.

Usage

gs.start.timer(depth=1)

Arguments

Value

An invisible implementation-level list returned by the SelectionTools timing helper. The function is called for the side effect of starting timing.

Start or stop the genomic-selection timing helper

Description

Start or stop the genomic-selection timing helper.

Usage

gs.stop.timer(depth=1, info.level=0)

Arguments

Value

An invisible implementation-level list returned by the SelectionTools information helper after reporting elapsed time. The function is called for the timing/reporting side effect.

Test marker or model parameters used by genomic-selection routines

Description

Test marker or model parameters used by genomic-selection routines.

Usage

gs.test.mp(n = 0)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of running the compiled marker/model-parameter test.

Test estimated marker effects using the indicated method

Description

Test estimated marker effects using the indicated method.

Usage

gs.testeff.lsq(nperm = 0, out.filename = "test.lsq", auxfiles = TRUE,
               data.set ="default")

Arguments

Value

Invisibly returns a numeric matrix containing the LSQ effect-test results when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Test estimated marker effects using the indicated method

Description

Test estimated marker effects using the indicated method.

Usage

gs.testeff.rmlc(nperm = 1000, maxiter = 1000, precision = 0.001, hsq = 0.9,
                out.filename = "test.rmlc", auxfiles = TRUE,
                data.set ="default")

Arguments

Value

Invisibly returns a data.frame containing the RMLC effect-test results when auxfiles = TRUE and the test succeeds; otherwise NULL.

Test estimated marker effects using the indicated method

Description

Test estimated marker effects using the indicated method.

Usage

gs.testeff.rmlv(nperm = 1000, maxiter = 1000, precision = 0.001, hsq = 0.9,
                out.filename = "test.rmlv", auxfiles = TRUE,
                data.set ="default")

Arguments

Value

Invisibly returns a numeric matrix containing the RMLV effect-test results when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Estimate variance components for ridge-regression BLUP

Description

Estimate variance components for ridge-regression BLUP.

Usage

gs.vc.rrblup(maxiter = 1000, precision = 1e-4, hsq = 0.8,
             out.filename = "lambda", auxfiles = TRUE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the variance-component results from RR-BLUP when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Calculate weights or statistics used by the genomic-selection ANOVA method

Description

Calculate weights or statistics used by the genomic-selection ANOVA method.

Usage

gs.w.aov(alpha = 1, out.filename = "W", auxfiles = TRUE, data.set = "default")

Arguments

Value

Invisibly returns a numeric matrix containing the ANOVA weights/statistics when auxfiles = TRUE and the compiled calculation succeeds; otherwise NULL.

Write Marker Effects for the Simulation Backend

Description

Writes estimated marker effects in the effect-file format used by the simulation backend.

Usage

gs.write.pseff(e, beta0 = NA, file)

Arguments

Details

The genomic-selection and simulation parts of SelectionTools use different origins for additive marker coding.

With the default allele codes used by the genomic-selection routines, gs.set.allele.codes() assigns the additive dosage codes 0, 1, and 2 to the genotypes with zero, one, and two copies of the effect allele, respectively. For marker j with estimated effect u_j, the marker contribution is therefore 0, u_j, or 2u_j.

The simulation effect-file representation stores an additive effect per allele. The effect allele is written with effect +u_j/2 and the complementary allele with effect -u_j/2. The corresponding diploid marker contributions are therefore -u_j, 0, and +u_j. This is equivalent to changing the marker dosage from z_{ij} to

z^*_{ij}=z_{ij}-1.

On the genomic-selection scale,

\hat{g}_i=\hat{\mu}_{012}+\sum_{j=1}^{m}z_{ij}\hat{u}_j.

Using z_{ij}=z^*_{ij}+1 gives

\hat{g}_i= \left(\hat{\mu}_{012}+\sum_{j=1}^{m}\hat{u}_j\right) +\sum_{j=1}^{m}z^*_{ij}\hat{u}_j.

Consequently, the first line written to the effect file is

\hat{\mu}_{\mathrm{sim}}= \hat{\mu}_{012}+\sum_{j=1}^{m}\hat{u}_j.

If beta0 is supplied, it replaces \hat{\mu}_{012} before this coding correction is applied.

This is the coding-shift correction described by Stranden and Christensen (2011), Equation (2). The shift is distinct from allele-frequency centering. For coding z^c_{ij}=z_{ij}-2p_j, the corresponding mean shift is 2\sum_j p_j u_j; the simulation effect-file coding instead uses z^*_{ij}=z_{ij}-1.

The exact equivalence described above applies to the default allele codes. gs.set.allele.codes() permits power users to define other codes; an arbitrary custom coding is not in general represented by the fixed -u_j/2, +u_j/2 simulation allele effects.

Value

NULL, returned invisibly by the file-writing operation. The function is called for its side effect of writing marker effects for the simulation backend.

References

Stranden I, Christensen OF (2011) Allele coding in genomic evaluation. Genetics Selection Evolution 43:25. See Equation (2).

See Also

gs.return.effects, gs.set.allele.codes, st.set.sim.ef, load.effmap

homozygote()

Description

Produces a dataframe of a population whith NoInd individuals which carry at all loci the same allele (allele). This dataframe can be used to initialise a population.

Usage

homozygote(allele, NoInd = 1)

Arguments

Value

A data.frame with columns ind, chrom, hom, pos, and all, representing the requested homozygous genome.

Note

See init.population for an example

Construct or evaluate introgression-line libraries

Description

Construct or evaluate introgression-line libraries.

Usage

il.eval.library(rp.allele = 1, dp.allele = 2, chrom = 0, lower = 0, upper = 0,
                data.set = "default")

Arguments

Value

A named numeric vector summarizing the evaluated introgression-line library. It contains cov, dep, seglib, dpg, ndps, and ldps; when target regions are supplied it additionally contains tr.dpg, nt.rpg, nt.ndps, and nt.ldps. Returns NULL on validation failure.

Construct or evaluate introgression-line libraries

Description

Construct or evaluate introgression-line libraries.

Usage

il.eval.lines(allele = 1, chrom = 0, lower = 0, upper = 0, exclude = 0,
              data.set = "default")

Arguments

Value

A data.frame with one row per evaluated line and columns name, nseg, lseg, abs, tot, and rel, summarizing introgressed segments and their lengths/proportions. Returns NULL on validation failure.

Construct or evaluate introgression-line libraries

Description

Construct or evaluate introgression-line libraries.

Usage

il.ideal.library(n.c = 5, l.c = 100, s.l = 20, data.set = "default")

Arguments

Value

An integer cleanup status returned by the final unlink() call after construction of the ideal introgression-line library. The main result is the population/library created by the function.

Construct or evaluate introgression-line libraries

Description

Construct or evaluate introgression-line libraries.

Usage

il.overlapping.library(n.c = 5, l.c = 100, s.l = 20, data.set = "default")

Arguments

Value

An integer cleanup status returned by the final unlink() call after construction of the overlapping introgression-line library. The main result is the population/library created by the function.

Print or handle an information message

Description

Print or handle an information message.

Usage

info(lev, msg)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of issuing the requested information message.

Emit information-level-controlled status output

Description

Emit a status message when the requested information level is enabled. The message is signaled with message() and can therefore also be suppressed with suppressMessages().

Usage

info.cat(lev, msg)

Arguments

Value

NULL. The function is called for its side effect of conditionally signaling a status message according to the current information level.

init.population()

Description

Creates a simulation population from the internal chromosome-segment data frame representation.

Usage

init.population(name, data, delete=TRUE)

Arguments

Details

The input data frame must have exactly five columns named or interpretable as individual number, chromosome number, homologue number, position, and allele. Each row describes the start of a chromosome segment carrying the specified allele. The data must be ordered consistently with the simulation representation.

The number of input rows must be positive. Chromosome and homologue identifiers must be compatible with the currently defined simulation genome. The routine constructs the raw chromosome representation; marker genotypes and evaluated genetic values are derived data and are not implied merely by initialization.

When delete=TRUE, an existing population of the same name is removed before initialization. If creation fails while chromosome segments are being inserted, the incomplete new population is removed rather than retained.

Uses the currently defined genome and linkage map. Both must be defined before calling this function.

Value

The function initialises the named simulation population from the supplied data in the backend. Returns list of name, total number of alleles and input data columns. The function is primarily called for its side effect of creating the simulation population.

Examples

# Define a population explicitly
set.genome.par(no.chrom = 1, no.hom = 2, chrom.len = 1)
define.map("form trait1 1/0.5")

# Individual 1: genotype 1/1
# Individual 2: genotype 1/2
pop <- data.frame(
   ind   = c(1, 1, 2, 2),
   chrom = c(1, 1, 1, 1),
   hom   = c(1, 2, 1, 2),
   pos   = c(0, 0, 0, 0),
   all   = c(1, 1, 1, 2)
)

init.population("P1", pop)
evaluate.genotype("P1", "form")

# Define a genome from a data frame and create homozygous individuals
reset.all()

map <- data.frame(
   chrom = 1,
   pos = 0.5,
   name = "form"
)
define.genome(map)

# Two individuals, both homozygous for allele 1
init.population("P2", homozygote(1, NoInd = 2))
evaluate.genotype("P2", "form")

Linkage Map for Marker-Assisted Backcrossing Examples

Description

A linkage-map data set used in the marker-assisted backcrossing examples based on Frisch et al. (1999). This version represents the map with approximately 80 marker loci used for background selection.

Usage

data(lib00.map1)

Format

An R data object containing linkage-map records in the format used by SelectionTools linkage-map input routines.

Source

Data used for the examples based on Frisch et al. (1999), Crop Science 39:1295–1301.

Reduced Linkage Map for Marker-Assisted Backcrossing Examples

Description

A reduced linkage-map data set used in the marker-assisted backcrossing examples based on Frisch et al. (1999). This version represents the reduced map with approximately 40 marker loci used to compare marker density for background selection.

Usage

data(lib00.map1a)

Format

An R data object containing linkage-map records in the format used by SelectionTools linkage-map input routines.

Source

Data used for the examples based on Frisch et al. (1999), Crop Science 39:1295–1301.

Linkage Map for Three-Stage Marker-Assisted Backcrossing

Description

A linkage-map data set used in the three-stage marker-assisted backcrossing examples based on Frisch et al. (1999). The example uses target, flanking and background-marker information for selection.

Usage

data(lib00.map2)

Format

An R data object containing linkage-map records in the format used by SelectionTools linkage-map input routines.

Source

Data used for the examples based on Frisch et al. (1999), Crop Science 39:1295–1301.

Calculate or summarize linkage drag

Description

Calculate or summarize linkage drag.

Usage

linkage.drag(pops, allele, chrom, pos)

Arguments

Value

A numeric matrix with one row per population and columns Obs, Mean, SDev, Min, Q10, Med, and Max, summarizing linkage-drag segment lengths.

Get a linkage map used by the simulation routines

Description

Returns the currently active simulation linkage map.

Usage

linkage.map.get()

Details

The result contains the map points used by the simulation backend, including chromosome, position, locus name, and class, in the current simulation map order.

Value

A data.frame with columns chrom, pos, name, and class, describing the active simulation linkage map.

Load a linkage map used by the simulation routines

Description

Loads and prepares the linkage map used by the simulation backend.

Usage

linkage.map.load(file, disperse=TRUE, file.disperse=NA, disperse.factor=100)

Arguments

Details

The simulation map supplies chromosome, position, locus-name, and class information used by population genotyping and recombination. The loader prepares map points in a valid access order and can disperse coincident positions when requested. The active simulation map is a simulation-wide object and is separate from a SelectionTools marker data set.

Value

An invisible list with a retval status component. Invalid input returns list(retval = -2L) invisibly; otherwise the list is returned by the compiled map loader. The main effect is loading the linkage map.

Save a linkage map used by the simulation routines

Description

Writes a simulation linkage map to a text file.

Usage

linkage.map.save(file, dta.map=linkage.map.get())

Arguments

Details

By default the currently active simulation linkage map is obtained and written. A supplied dta.map can instead be written. Saving does not alter the active map or any simulation population.

Value

NULL, returned invisibly by write.table(). The function is called for its side effect of writing the linkage map.

list.effects()

Description

Rerturns all defined effects and their weights.

Usage

list.effects()

Value

A data.frame with columns effect and weight, listing the currently defined effects and their weights.

Note

See define.effects for for an example

list.populations

Description

Returns the names and active sizes of the currently registered simulation populations.

Usage

list.populations()

Details

The result reflects the simulation population registry and is independent of SelectionTools marker-data-set names.

Value

Returns the same data.frame as population.list(), with columns PopName and count.

load.effmap()

Description

Loads an effect file

Usage

load.effmap(name, file = NA)

Arguments

Details

Effect files are text files can be generated either by hand with an editor or with the command generate.effect.file().

An effect file consists of a value, which is assigned to each individual of a population (the population mean) and a list of effects which are added to the population mean if the certain allelic combinations occur in an individual. The order of the effects is arbitrary, but the population mean must occur first in the map file.
Mean;

Structure of an effect file:
Locus Allele [Locus Allele ...] Effect;
[,...]

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of loading the requested effect map.

Note

See define.effects for for an example

Load an internal effect map

Description

Load an internal effect map.

Usage

load.internal.effmap(name, spec, weight)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of loading the requested internal effect map.

load.linkage.map()

Description

Loads the simulation linkage map from a text file.

Usage

load.linkage.map(file, disperse=TRUE, file.disperse=NA, disperse.factor=100)

Arguments

Details

The simulation linkage map is distinct from the marker-data map managed by st.read.map. It defines the loci available to simulation-population genotyping, recombination, and evaluation.

A map file contains one locus definition per record with four fields:

Chromosome

Chromosome number.

Position

Distance from the chromosome telomere in Morgan.

Locusname

Name of the locus.

Classname

Class to which the locus belongs.

The record grammar is therefore Chromosome Position Locusname Classname. Any number of locus records can be supplied.

The input file does not need to be pre-sorted. The current loader parses and validates all records and prepares the loci in chromosome/position order. Coincident map positions can be dispersed according to disperse, file.disperse, and disperse.factor. Only one simulation linkage map is active at a time.

The function linkage.map.load provides the same linkage-map loading operation.

Value

Returns the same invisible status list as linkage.map.load(), including its retval component.

mab.Examples

Description

Examples for the optimize-mab routines

Value

No return value. This is a documentation page describing examples for the marker-assisted backcrossing routines.

See Also

mab.simulate, mab.compare, mab.load.data, mab.tabulate, mab.Input.files

Structure of input files for the optimize-mab routines.

Description

Structure of the files describing linkage maps and crossing parents. Files must be placed in the directory st.input.dir.

Details

A linkage-map file contains chromosome number, position in cM, and marker name. The old package documentation gave, for example:

1       0      umc94
1       0002   bnl805
1       0067   umc76
1       0070   umc137
2       0      bnl845
2       0012   umc53

For a homozygous crossing parent, the first line is the genotype name and each following line contains a marker name and one allele, for example:

dh.2010.12345
s1e2855 ade
s1e3177 cyt
s1e2083 ade
s1e4552 gua

For a heterozygous crossing parent, the first line is again the genotype name and each following line contains a marker name and two alleles, for example:

bc1i3
umc94   1  8
bnl805  1  8
umc76   8  8
umc137  8  8

Value

No return value. This is a documentation page describing the input-file formats used by the marker-assisted backcrossing routines.

See Also

mab.simulate, mab.Examples

Run and Compare a Series of Marker-Assisted Backcrossing Simulations

Description

Runs up to nine marker-assisted backcrossing simulation scenarios by calling mab.simulate() for each active scenario. Scenario A provides the base settings; scenarios B through I can override individual settings.

Usage

mab.compare(
    a.simulation.name,
    a.simulation.run,
    a.repetitions = 1000,
    a.recurrent.parent = "H",
    a.donor.parent = "H",
    a.linkage.map,
    a.target.loci = NULL,
    a.flanking.loci = NULL,
    a.recipient.loci = NULL,
    a.gen.type = NULL,
    a.population.size = NULL,
    a.sel.strategy = NULL,
    a.no.selected = NULL,
    a.no.preselected = NULL,
    a.reg.chr = NULL,
    a.reg.begin = NULL,
    a.reg.end = NULL,
    a.missing.allele = "9",
    a.success.factor = 1,
    b.simulation.name = NULL,
    c.simulation.name = NULL,
    d.simulation.name = NULL,
    b.simulation.run = NULL,
    c.simulation.run = NULL,
    d.simulation.run = NULL,
    b.repetitions = NULL,
    c.repetitions = NULL,
    d.repetitions = NULL,
    b.recurrent.parent = NULL,
    c.recurrent.parent = NULL,
    d.recurrent.parent = NULL,
    b.donor.parent = NULL,
    c.donor.parent = NULL,
    d.donor.parent = NULL,
    b.linkage.map = NULL,
    c.linkage.map = NULL,
    d.linkage.map = NULL,
    b.target.loci = NULL,
    c.target.loci = NULL,
    d.target.loci = NULL,
    b.flanking.loci = NULL,
    c.flanking.loci = NULL,
    d.flanking.loci = NULL,
    b.recipient.loci = NULL,
    c.recipient.loci = NULL,
    d.recipient.loci = NULL,
    b.gen.type = NULL,
    c.gen.type = NULL,
    d.gen.type = NULL,
    b.population.size = NULL,
    c.population.size = NULL,
    d.population.size = NULL,
    b.sel.strategy = NULL,
    c.sel.strategy = NULL,
    d.sel.strategy = NULL,
    b.no.selected = NULL,
    c.no.selected = NULL,
    d.no.selected = NULL,
    b.no.preselected = NULL,
    c.no.preselected = NULL,
    d.no.preselected = NULL,
    b.reg.chr = NULL,
    c.reg.chr = NULL,
    d.reg.chr = NULL,
    b.reg.begin = NULL,
    c.reg.begin = NULL,
    d.reg.begin = NULL,
    b.reg.end = NULL,
    c.reg.end = NULL,
    d.reg.end = NULL,
    b.missing.allele = NULL,
    c.missing.allele = NULL,
    d.missing.allele = NULL,
    b.success.factor = NULL,
    c.success.factor = NULL,
    d.success.factor = NULL,
    e.simulation.name = NULL,
    f.simulation.name = NULL,
    g.simulation.name = NULL,
    e.simulation.run = NULL,
    f.simulation.run = NULL,
    g.simulation.run = NULL,
    e.repetitions = NULL,
    f.repetitions = NULL,
    g.repetitions = NULL,
    e.recurrent.parent = NULL,
    f.recurrent.parent = NULL,
    g.recurrent.parent = NULL,
    e.donor.parent = NULL,
    f.donor.parent = NULL,
    g.donor.parent = NULL,
    e.linkage.map = NULL,
    f.linkage.map = NULL,
    g.linkage.map = NULL,
    e.target.loci = NULL,
    f.target.loci = NULL,
    g.target.loci = NULL,
    e.flanking.loci = NULL,
    f.flanking.loci = NULL,
    g.flanking.loci = NULL,
    e.recipient.loci = NULL,
    f.recipient.loci = NULL,
    g.recipient.loci = NULL,
    e.gen.type = NULL,
    f.gen.type = NULL,
    g.gen.type = NULL,
    e.population.size = NULL,
    f.population.size = NULL,
    g.population.size = NULL,
    e.sel.strategy = NULL,
    f.sel.strategy = NULL,
    g.sel.strategy = NULL,
    e.no.selected = NULL,
    f.no.selected = NULL,
    g.no.selected = NULL,
    e.no.preselected = NULL,
    f.no.preselected = NULL,
    g.no.preselected = NULL,
    e.reg.chr = NULL,
    f.reg.chr = NULL,
    g.reg.chr = NULL,
    e.reg.begin = NULL,
    f.reg.begin = NULL,
    g.reg.begin = NULL,
    e.reg.end = NULL,
    f.reg.end = NULL,
    g.reg.end = NULL,
    e.missing.allele = NULL,
    f.missing.allele = NULL,
    g.missing.allele = NULL,
    e.success.factor = NULL,
    f.success.factor = NULL,
    g.success.factor = NULL,
    h.simulation.name = NULL,
    i.simulation.name = NULL,
    h.simulation.run = NULL,
    i.simulation.run = NULL,
    h.repetitions = NULL,
    i.repetitions = NULL,
    h.recurrent.parent = NULL,
    i.recurrent.parent = NULL,
    h.donor.parent = NULL,
    i.donor.parent = NULL,
    h.linkage.map = NULL,
    i.linkage.map = NULL,
    h.target.loci = NULL,
    i.target.loci = NULL,
    h.flanking.loci = NULL,
    i.flanking.loci = NULL,
    h.recipient.loci = NULL,
    i.recipient.loci = NULL,
    h.gen.type = NULL,
    i.gen.type = NULL,
    h.population.size = NULL,
    i.population.size = NULL,
    h.sel.strategy = NULL,
    i.sel.strategy = NULL,
    h.no.selected = NULL,
    i.no.selected = NULL,
    h.no.preselected = NULL,
    i.no.preselected = NULL,
    h.reg.chr = NULL,
    i.reg.chr = NULL,
    h.reg.begin = NULL,
    i.reg.begin = NULL,
    h.reg.end = NULL,
    i.reg.end = NULL,
    h.missing.allele = NULL,
    i.missing.allele = NULL,
    h.success.factor = NULL,
    i.success.factor = NULL,
    result.files
)

Arguments

Details

The scenario prefixes a. through i. identify up to nine simulation definitions. Scenario A is always defined by a.simulation.name. A scenario B through I is run only when its simulation.name argument is non-NULL.

For every setting other than simulation.name, an active scenario B through I inherits the corresponding scenario-A value when its own argument is NULL; a non-NULL scenario-specific value overrides the scenario-A value. The resulting settings are passed directly to mab.simulate(). See mab.simulate() for the detailed meaning of the generation and selection settings and for the structure of the simulation results. The file name for every active scenario is taken from result.files; no result-file name is generated automatically.

Value

NULL, returned invisibly as the value of the final for loop. The function is called for its side effect of running the active simulation scenarios; each call to mab.simulate() saves its result in the corresponding explicitly supplied file from result.files.

See Also

mab.simulate, mab.load.data, mab.tabulate, mab.Input.files, mab.Examples

Helper used by the marker-assisted backcross simulation routines

Description

Resolves MAB file names against a configured directory while preserving explicit absolute paths.

Usage

mab.df(d, f)

Arguments

Value

A character scalar. If f is absolute it is returned unchanged. If f is relative and d is non-empty, the two are combined with file.path(); otherwise f is returned unchanged.

Loads the data of a simulation

Description

Loads a simulation result from the explicitly supplied result.file for further analysis or printing. Relative file names are resolved against st.data.dir; absolute paths are used directly.

Usage

mab.load.data(simulation.name, simulation.run, result.file)

Arguments

Value

The object outp loaded from the requested simulation result file. For files created by mab.simulate(), this is a named list containing the simulation parameters and, depending on the requested analyses, the following summaries:

TargetAlleles

Target-allele summary for selected plants over generations.

RPG.gw

Recurrent-parent genome content over the whole genome.

RPG.reg1, RPG.reg2, ...

Recurrent-parent genome content for separately defined chromosome regions.

DonorSegments.gw

Donor chromosome segments in selected individuals, counted per homologue.

DonorSegments.reg1, DonorSegments.reg2, ...

Donor chromosome segments in separately defined chromosome regions.

LinkageDrag1, LinkageDrag2, ...

Donor chromosome segment attached to each target locus; target loci are evaluated separately and linkage drag is averaged over the two homologues.

SM

Number of marker data points attributed to single-marker assays.

HT

Number of marker data points attributed to high-throughput assays.

See mab.simulate for the selection-strategy rules used to count SM and HT marker data points.

See Also

mab.simulate, mab.tabulate, mab.Examples

Helper used by the marker-assisted backcross simulation routines

Description

Writes one marker-data file for each individual in a population. Output file names use the explicitly supplied file.prefix.

Usage

mab.save.inds(pop, pname, file.prefix)

Arguments

Value

NULL. The function is called for its side effect of writing one marker-data file for each individual in the supplied population.

Simulates a marker-assisted backcrossing program

Description

Simulates one marker-assisted backcrossing program. The simulation result is stored in the explicitly supplied result.file. A relative file name is resolved against st.data.dir; an absolute path is used as supplied.

Usage

mab.simulate(simulation.name, simulation.run, repetitions = 1000,
             recurrent.parent = "H", donor.parent = "H", linkage.map,
             target.loci = NULL, flanking.loci = NULL, recipient.loci = NULL,
             gen.type = NULL, population.size = NULL, sel.strategy = NULL,
             no.selected = NULL, no.preselected = NULL, reg.chr = NULL,
             reg.begin = NULL, reg.end = NULL, missing.allele = "9",
             result.file, success.factor = 1, recode.infiles = FALSE,
             recode.file = NULL)

Arguments

Value

On successful completion, invisibly returns a named list containing both the simulation definition and the simulation summaries. The parameter part includes simulation.name, simulation.run, repetitions, recurrent.parent, donor.parent, linkage.map, target.loci, flanking.loci, recipient.loci, gen.type, population.size, sel.strategy, no.selected, no.preselected, reg.chr, reg.begin, reg.end, and success.factor.

Depending on the requested analyses, the result part can contain:

TargetAlleles

Summary of the frequency of target alleles in the selected plants over the generations of the backcrossing program.

RPG.gw

Summary of recurrent-parent genome content of the selected plants over the whole genome.

RPG.reg1, RPG.reg2, ...

Recurrent-parent genome content in chromosome regions defined by reg.chr, reg.begin, and reg.end; the suffix identifies the region.

DonorSegments.gw

Number of donor chromosome segments in the selected individuals over the whole genome. Segments are counted per homologue, so the two homologues of each chromosome in a diploid individual are counted separately.

DonorSegments.reg1, DonorSegments.reg2, ...

Number of donor chromosome segments within separately evaluated chromosome regions.

LinkageDrag1, LinkageDrag2, ...

Length of the donor chromosome segment attached to each target locus. Target loci are evaluated separately and linkage drag is averaged over the two homologues.

SM

Summary of the number of marker data points attributed to single-marker assays. In the implemented accounting these arise from selection steps using flanking-marker assays.

HT

Summary of the number of marker data points attributed to high-throughput assays, including genome-wide background selection and selection for a low number of donor segments as specified by the selection strategy.

Validation failures return NULL invisibly. The same list is saved in the explicitly supplied result.file.

See Also

mab.compare, mab.load.data, mab.tabulate, mab.Input.files, mab.Examples

Tabulate the results of a series of simulations

Description

Tabulates results from a series of simulations. The files to load are supplied explicitly in result.files.

Usage

mab.tabulate(simulation.names.runs, par.summary = TRUE, ext.summary = FALSE,
             RPG.gw.mean = FALSE, TargetAlleles = FALSE, RPG.gw.Q10 = FALSE,
             RPG.reg.Q10 = FALSE, RPG.reg.mean = FALSE, DonorSegments.gw = FALSE,
             DonorSegments.reg = FALSE, LinkageDrag = FALSE, MarkerAnalyses = FALSE,
             digits = 1, percent = TRUE, result.files)

Arguments

Value

A named list of the summary matrices requested by the logical arguments. Possible components include par.summary, ext.summary, TargetAlleles.mean, RPG.gw.mean, RPG.gw.Q10, numbered regional RPG.reg*.mean and RPG.reg*.Q10 matrices, DonorSegments.gw.mean, numbered DonorSegments.reg*.mean matrices, numbered LinkageDrag*.mean matrices, SM.mean, and HT.mean. If incompatible scenario definitions are detected, NULL is returned invisibly.

See Also

mab.simulate, mab.load.data, mab.compare, mab.Examples

Input Files for Marker-Assisted Backcrossing Examples

Description

A collection of linkage maps and parental marker-genotype files used by the marker-assisted backcrossing examples. The files are stored as an R data object so that they can be loaded with data() and written to a temporary directory when the file-based mab.* interface is used.

Usage

data(masbc.input)

Format

A named list of 16 character vectors. Each list element contains the exact text lines of one input file. The element names are the file names: ex-mab1.map, ex-mab2.map, ex-mab3.map, ex-mab4.map, ex-mabi1.mda through ex-mabi8.mda, ex-mabp1.mda, ex-mabp1_m.mda, ex-mabp2.mda, and ex-mabp2_m.mda.

Details

The *.map elements contain linkage-map input files. The *.mda elements contain marker genotypes for donor, recurrent-parent, or individual backcross plants. Keeping the files as character vectors preserves the original input-file representation while making the complete example data available through the standard R data() mechanism.

The marker-assisted backcrossing functions still use file names. Therefore, a vignette or analysis can load masbc.input, write the required list elements to tempdir(), and set st.input.dir to that temporary directory.

Source

Input files used by the marker-assisted backcrossing examples supplied with SelectionTools.

See Also

mab.simulate, mab.compare, mab.load.data, mab.tabulate, mab.Input.files

Examples

data("masbc.input")

mab.input.dir <- file.path(tempdir(), "masbc-input")
dir.create(mab.input.dir, showWarnings = FALSE)

invisible(Map(
    function(x, file) writeLines(x, file.path(mab.input.dir, file)),
    masbc.input,
    names(masbc.input)
))

list.files(mab.input.dir)
unlink(mab.input.dir, recursive = TRUE)

Optimize a population using the package selection routines

Description

Optimize a population using the package selection routines.

Usage

optimize.population(PopNames)

Arguments

Value

Returns the same invisible implementation-level list as population.optimize(). The function is a compatibility wrapper and the meaningful result is the delegated population operation.

Create a linkage map for phenotype or simulation use

Description

Create a linkage map for phenotype or simulation use.

Usage

ph.linkage.map.create(map, disperse=FALSE, file.disperse=NA,
                      disperse.factor=100)

Arguments

Value

When disperse = TRUE, returns the modified map object after positions have been dispersed. With the default disperse = FALSE, returns NULL; in both cases the main side effect is installing the map through the compiled map-definition routine.

Generate phenotypic values for a simulation population

Description

Generates phenotypic values for all loaded effects and all active individuals of a simulation population.

Usage

phenotype.population(PopName, hsq)

Arguments

Details

Phenotypic values are generated for all loaded effects in one operation. Partial phenotypic evaluation is not supported. The length of hsq must therefore equal the number of loaded effects.

The function first genotypes and evaluates the population. For effect i, let V_{G,i} be the sample variance of the effect-specific genetic values and let h_i^2 be the supplied heritability. The residual variance is

V_{E,i} = V_{G,i}/h_i^2 - V_{G,i}.

For every individual an independent normal residual with variance V_{E,i} is added to the effect-specific genetic value.

The phenotypic value array is parallel to the genetic value array. Elements 1 through the number of effects contain the effect-specific phenotypic values. Element 0 contains the weighted phenotypic selection index, calculated with the current effect weights in the same way as the genetic selection index.

Phenotypic values are population-wide derived data. Re-evaluating genetic values, explicitly setting genetic values, removing an evaluation, removing cached genotypes, changing the effect configuration or effect weights, or removing the linkage map invalidates stored phenotypic values.

Value

On successful phenotype generation, an invisible implementation-level list returned by the compiled routine; its retval component is the status code. Validation failures return NULL invisibly.

See Also

evaluate.population, get.population.pvalue, population.sort, select.n.best, select.all.best

Perform the SelectionTools operation "plabsim"

Description

Perform the SelectionTools operation "plabsim".

Format

A list containing PLABSIM run-time state and parameters.

Value

A list containing the current PLABSIM run-time state and parameters.

Perform the SelectionTools operation "plabsim R date"

Description

Perform the SelectionTools operation "plabsim R date".

Format

A character string containing the PLABSIM R-code date.

Value

A character scalar containing the PLABSIM R-code date.

Perform the SelectionTools operation "plabsim R version"

Description

Perform the SelectionTools operation "plabsim R version".

Format

A character string containing the PLABSIM R-code version.

Value

A character scalar containing the PLABSIM R-code version.

Initialize the PLABSIM simulation state

Description

Initialize the PLABSIM simulation state.

Usage

plabsim.init()

Value

Returns the same invisible implementation-level list as rng.init(); the main effect is initializing the simulation random-number generator state.

Perform the SelectionTools operation "plabsim version"

Description

Perform the SelectionTools operation "plabsim version".

Usage

plabsim.version()

Value

Returns the same invisible implementation-level list as write.version.2(); the main effect is reporting package version information.

Create or process a plant object in the simulation framework

Description

Create or process a plant object in the simulation framework.

Usage

plant(genotype, NoInd=1)

Arguments

Value

A data.frame with columns ind, chrom, hom, pos, and all, representing the requested genome from the supplied homologue genotypes.

Append a copy of a simulation population

Description

Appends a copy of a source population to the end of a destination population.

Usage

population.append(NameP1, NameP2)

Arguments

Details

Raw chromosome data are copied for every appended individual. If the destination is initially empty, complete genotype, genetic-value, and phenotypic-value categories are copied when present in the source. For a nonempty destination, a derived category is retained only when it is complete in both populations. Otherwise that category is cleared in the result.

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of appending a copy of one simulation population to another.

Concatenate Simulation Populations

Description

Moves all individuals of one population into another simulation population.

Usage

population.concat(NameP1, NameP2)

Arguments

Details

Individuals already present in NameP1 retain their order and remain at the beginning of the receiving population. The active individuals from NameP2 are appended after them. Code that depends on population order can therefore, for example, concatenate a selected fraction first and the remaining individuals second and subsequently identify the two groups by position.

Individuals are transferred as complete individual structures and NameP2 is removed. As in the existing implementation, cached genotype and genetic evaluation data are discarded before concatenation. Phenotypic values are also discarded because they depend on the genetic evaluation.

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of concatenating simulation populations.

See Also

population.append, population.copy, population.divide

Copy a simulation population

Description

Copies all or a contiguous subset of a source population into a destination population.

Usage

population.copy(NameP1, NameP2, start=1, n=-1)

Arguments

Details

The source population is not modified. Raw chromosome data are copied. Complete cached genotype, genetic-value, and phenotypic-value categories are deep-copied when present in the source. Derived categories are maintained as all-or-none population data; allocation failure cannot leave only a subset of active destination individuals with a category.

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of copying a simulation population.

Divide a simulation population

Description

Moves the first requested individuals of a source population into a new population.

Usage

population.divide(NameP1, NameP2, NoI=-1)

Arguments

Details

The operation moves complete individual structures. Therefore chromosome data, information fields, genotype data, genetic values, and phenotypic values remain attached to the same individuals. No value category is recalculated merely because the population is divided.

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of dividing a simulation population.

Check whether a simulation population exists

Description

Checks whether the requested population name occurs in the current simulation population list.

Usage

population.exist(PopName)

Arguments

Value

An invisible logical scalar indicating whether PopName occurs in the current population list.

Individual remove a population or population data

Description

Individual remove a population or population data.

Usage

population.individual.remove(PopName, IndPos)

Arguments

Value

For a valid individual position, the invisible implementation-level list returned by the final population operation used to remove the individual. If the position is outside the population, NULL. The main effect is modification of the population.

Return stored information for an individual

Description

Returns the character information stored for an individual in a simulation population.

Usage

population.info.get(PopName, ind)

Arguments

Value

A character value containing the stored information for the requested individual when the individual index is valid; otherwise NULL.

Set stored information for an individual

Description

Sets the character information stored for an individual in a simulation population.

Usage

population.info.set(PopName, ind, info)

Arguments

Value

For a valid individual index, an invisible implementation-level list returned by the compiled setter. For an invalid index, NULL. The main effect is updating the stored individual information.

List a population or population data

Description

Lists the currently registered simulation populations and their active sizes.

Usage

population.list()

Details

The returned population registry is independent of SelectionTools marker-data-set names. The count associated with each name is the active number of individuals, not necessarily the allocated storage capacity.

Value

A data.frame with columns PopName and count, giving each current population name and its number of individuals.

Matrix load a population or population data

Description

Matrix load a population or population data.

Usage

population.matrix.load(file, backcross=FALSE, keep.IndID=TRUE)

Arguments

Value

NULL. The function is called for its side effect of loading matrix-format population data and, when requested, restoring individual identifiers.

Matrix save a population or population data

Description

Matrix save a population or population data.

Usage

population.matrix.save(file, PopNames, missing.rm=TRUE, keep.IndID=TRUE)

Arguments

Value

NULL, returned invisibly by the file-writing operation. The function is called for its side effect of writing matrix-format population data.

Swap the names of two simulation populations

Description

Swaps the registered names of two simulation populations.

Usage

population.name.swap(NameP1, NameP2)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of swapping simulation-population names.

Optimize storage for simulation populations

Description

Calls the compiled population-optimization routine for the requested simulation populations.

Usage

population.optimize(PopNames)

Arguments

Value

An invisible list returned by the underlying .C routine. The list is an implementation-level result containing the arguments returned by the compiled routine; the function is primarily called for its side effect of optimizing the requested simulation populations.

Load a population from PLABSIM-style data

Description

Loads a simulation population from the PLABSIM-style file representation and restores stored individual information.

Usage

population.plabsim.load(file, PopName=NA)

Arguments