Full Design

As its name suggests, the full design is the most comprehensive design of all. The full design encompasses all possible founder combinations (funnels), and thus it is always a balanced design (see Mod - balanced for more information on balanced design). In our simulation, the directions of crosses have no meaning and so 1 x 2 is equivalent to 2 x 1. But, if both directions are required, please refer to Mod - reps.

To obtain all possible founder combinations (funnels), we simply need to determine all permutations of \(n\) founders in the RILs, and that is \(n!\). Since we regard the reciprocal directions of crosses as equivalent, each permutation is equivalent to \(2^{n-1}-1\) other permutations. Therefore, we can eliminate those redundant permutations, which leads us to \(n!/2^{n-1}\) for a full design. For example, \(n=4\) would have \(3\) funnels and \(n=8\) would have \(315\) funnels. Unfortunately, it is impossible in practice to have a full design for \(n=16\) or larger as \(n=16\) would have \(638,512,875\) funnels.

A full design is only available for n=4 and n=8. To explicitly specify for a full design, we also need to specify the m and balanced arguments as shown in the table below. Details on m can be found in the Partial section and details on balanced can be found in the Mod - balanced section.

Partial Design

Unlike the full design, the partial design has a lot more choices to offer. A partial design is simply a subset of a full design, in which the subset can be either balanced or unbalanced. The subset is specified by the argument m in magic.eval, and the meaning of m depends on balanced=T or balanced=F.

In the case of balanced=T, m is the number of partial balanced funnel sets. Each funnel set has \(n-1\) funnels. As a corollary, a full design is made of \(n!/(2^{n-1}*(n-1))\) unique partial balanced funnel sets. In n=8, there are a total of \(45\) partial balanced funnel sets. Within a partial balanced funnel set, the founders meet once at two-way crosses, twice at four-way crosses, four times at eight-way crosses, and so on. For example, the following is a partial balanced funnel set for n=8.

Funnel 1: ((1 x 2) x (3 x 8)) x ((4 x 6) x (5 x 7))
Funnel 2: ((1 x 3) x (4 x 7)) x ((2 x 8) x (5 x 6))
Funnel 3: ((1 x 4) x (2 x 6)) x ((3 x 7) x (5 x 8))
Funnel 4: ((1 x 5) x (4 x 8)) x ((2 x 7) x (3 x 6))
Funnel 5: ((1 x 6) x (3 x 5)) x ((2 x 4) x (7 x 8))
Funnel 6: ((1 x 7) x (2 x 5)) x ((3 x 4) x (6 x 8))
Funnel 7: ((1 x 8) x (6 x 7)) x ((2 x 3) x (4 x 5))

In the case of balanced=F, m is the number of funnels. Since we do not need to keep the design balanced in this setting, we are not restricted by the need to have \(n-1\) funnels.

Note that n=4 has only one partial balanced set and that is the same as its full design. Although n=4 can have two partial unbalanced funnels, it has little purpose. To keep things simple, partial design for n=4 is not provided.

The arguments required for a partial design are shown in the table below.

Basic Design

The basic design is equivalent to a partial unbalanced design with m=1 funnel. For example, with 8 founders, the basic design is simply ((1 x 2) x (3 x 4)) x ((5 x 6) x (7 x 8)). Since there is one funnel, high replications of the crosses are usually needed to get the haplotype variations and increase the number of RILs. There is also an option to add an extra generation of crossing among the n-way crosses to further increase haplotype variation. These additional settings are described further in the Examples.

This design is available for n = 4, 8, 16, 32, 64, 128, and it can be used by setting m=0 for any n.

NP2 Design

The Non-Power of 2 (NP2) design is similar to the partial design except that it is meant for n that is not a power of 2. The crossing scheme for an NP2 design is based on a n=2^ceiling(log(n,2)) partial design. For example, ((1 x 2) x (1 x 3)) x ((3 x 5) x (4 x 6)) is a funnel for n=6 and it has same number of crosses as n=8 except that founder 1 and 3 are duplicated to fill in the empty slots.

The NP2 design is available as either balanced or unbalanced, where m is the number of funnel sets if balanced=T and m is the number of funnels if balanced=F. Strictly speaking, the balanced NP2 design should only be considered as semi-balanced, as we are only keeping the number of founders in a set balanced but not the crosses. Due to the nature of NP2 design, it requires more than just \(n-1\) funnels to keep the crosses balanced. For example, n=6 requires 3 and 15 funnels to be semi-balanced and fully balanced respectively.

In addition to partial design, full NP2 design is also available for n = 3, 5, 6, 7 by setting balanced=T and m = 1, 48, 285, 135 respectively.

The arguments required for an NP2 design is shown in the table below. Note that the number of funnel (nf) is just provided as a reference and not to be used as an input argument.

Pedigree

Instead of using designs from magicdesign, we also provide an option for users to input a complete pedigree of their design of choice. Theoretically, this option should work with any design as long as it can represented in a pedigree. The pedigree must be supplied as either a data.frame or matrix with four columns: individual ID, parent 1 ID, parent 2 ID, and generation number. The founders must be included in the pedigree, in which their individual IDs must be continuous from 1 to n founders, parent IDs as 0 or blank, and generation number as 0. All crosses going from the founders to final RILs including any selfing must be documented in the pedigree, and so the generation number must also be continuous (0 to final generations). The names of the individual IDs do not need to conform to any format as long as they are all unique, and the parent IDs must be present in the individual IDs from previous generations except for the founder parent IDs.

To use this option, the only input argument that is required is the ped argument in magic.eval.

Mod - reps

reps is an important argument in magic.eval as it determines the number of replicates (seeds) to keep from each biological cross. If reps is not supplied, magic.eval will automatically assume no replications at any generation. reps has to be provided as a vector of length \(log_2n\), with each element of the vector represent the number of replicates to keep at 2-way, 4-way, …, n-way crosses. For example, if n=8, reps=c(1,1,2) means that 2 replicates per 8-way cross are kept. In the same example, reps=c(2,1,1) is meaningless if the founders are inbred because the replicates of each 2-way cross are the same.

Here are three pedigrees showing the effects of different reps in a single funnel for n=8.

In addition, if there is a need to include both directions of crosses (i.e. 1 x 2 and 2 x 1), elements of reps can be supplied as even number. For example, reps=c(2,2,2) would ensure both cross directions are included in each crossing generation. As mentioned previously, the directions of crosses do not matter in our simulation and the only consequence is that the RIL population size increases.

Mod - self

self is another important argument in magic.eval as it determines the number of selfing generations after every cross. If self is not supplied, magic.eval will assume no selfing at all. Similar to reps, self is a vector of length \(log_2n\). In the common practice, self is only used in the single-seed descent (SSD) process after n-way crosses have been done. Using n=8 as an example again, self=c(0,0,3) represents no selfing after two-way crosses, no selfing after four-way crosses, and three generations of selfing after eight-way crosses.

Below are three pedigrees with different self for n=8.

Mod - inbred

The default in magic.eval is inbred=T since we assume that the founders are inbred. Although the use of non-inbred founders in MAGIC population has not been very common, we do provide an option for non-inbred founders by setting inbred=F.
The major consequence in inbred=F is how the 2-way crosses are handled. If the founders are inbred, then the 2-way crosses between the same founder pairs are all equivalent and so only one is needed for the subsequent 4-way crosses. But, if the founders are not inbred, then the 2-way crosses between the same founder pairs are no longer the same and so each unique individual (seed) is needed for the subsequent 4-way crosses. For example, we have two 4-way crosses here: (1 x 2) x (3 x 4) and (1 x 2) x (5 x 8). If the founders are inbred, we can just use the same (1 x 2) plant for both 4-way crosses. But if the founders are non-inbred, then we need to use two different (1 x 2) plants for each of the 4-way crosses because the (1 x 2) plants are all segregating differently.

Another consequence of inbred=F is how the founder alleles are tracked during simulation. With inbred founders, we have only n founder alleles but with non-inbred founders, we maintain 2*n founder alleles with two distinct alleles for each founder.

Just a note for caution, inbred=F has not been tested extensively so there may still be bugs in the codes. Please let us know if there is any issue with this setting.

Mod - balanced

The balanced argument in magic.eval is a logical indicator of whether to use a balanced or unbalanced MAGIC design. A balanced design is defined as a design where all the funnels have equal representation of founders and founder crosses. An example of how a balanced design should look is shown in Partial Design. A full design is always balanced, partial and NP2 designs can be either balanced or unbalanced, and a basic design is always unbalanced. Below is a figure and table to illustrate why a basic design is always unbalanced.

Mod - minimize

minimize is an argument for minimizing number of crosses and plants. By default, we set minimize=F. This is easier to describe through examples, so we will take two funnels as an example here: ((1 x 2) x (3 x 4)) x ((5 x 6) x (7 x 8)) and ((1 x 2) x (3 x 4)) x ((5 x 7) x (6 x 8)). Under the default setting, we require two different ((1 x 2) x (3 x 4)) individuals for the eight-way crosses to maximize haplotype diversity. If minimize=T, then the same ((1 x 2) x (3 x 4)) individual would be used to make the eight-way crosses.

Generally, there is little incentive to use minimize=T, but it is provided as an option in case there is a need for it.

Mod - n.try

n.try is an argument in magic.eval that is only used for finding partial balanced design. By default, n.try is set to 1000 and that should suffice unless there is a rare issue in finding partial balanced design.

Mod - addx

addx is an argument in magic.eval that adds an extra crossing generation after the final n-way crosses. addx is NULL by default, and it is available as either 1 or 2. For addx=1, this only works with a basic design as it splits the n-way crosses into two pools and make all possible crosses between these two pools like the approach of Stadlmeier et al. 2018. Since this requires two pools of n-way crosses, the reps must be provided such that even number of n-way crosses are produced. For addx=2, this works with any design although it is only recommended for basic or small partial design as this option makes all possible crosses among the n-way individuals (random mating). For k available n-way individuals, this would lead to \(k!/(2!*(k-2)!)\) extra crosses.

Mod - repx

repx is an argument in magic.eval that follows if addx is set to either 1 or 2. Like its counterpart reps, repx is simply an integer indicating how many replicates (seeds) per extra cross to keep.

Mod - selfx

selfx is an argument in magic.eval that follows if addx is set to either 1 or 2. Like its counterpart self, selfx is simply an integer indicating how many selfing generations to include after the extra cross.

Mod - marker.dist

marker.dist, as its name suggests, determines the marker distance in the simulated population. By default, this is set to 0.01 Morgan (1 centiMorgan).

Mod - chr.len

chr.len is an important argument as it provides the number of chromosomes and genetic lengths of each chromosome to the simulation. So, chr.len should be supplied as a vector of genetic lengths in the unit of Morgans. For example, chr.len=c(2.45, 2.89, 1.53) would mean that this simulated species has three chromosomes of 2.45, 2.89 and 1.53 Morgans respectively.

Mod - n.sim

n.sim determines the number of simulations to run. It is best to start off with n.sim=1, which is also the default, to ensure that the design is working fine before committing into a longer run time with higher n.sim. Once everything is working fine, users may choose n.sim=100 or some other values. The design (crossing scheme) is generated once regardless of n.sim, while the population is simulated over n.sim times.

Mod - hap.int

hap.int refers to haplotype interval, which is the interval in Morgans to look for recombinant haplotypes generated from the MAGIC design. By default, hap.int is set to 0.05 Morgan and that tells magic.eval to compute the count of all possible recombinant haplotypes among the founder pairs within that said interval.

Mod - n.hap

n.hap indicates the number of haploid marker data to extract from the MAGIC RILs for results. By default, n.hap is set to 1. If the RILs fully inbred, then there is no difference between n.hap=1 and n.hap=2. That said, n.hap=1 should be sufficient as long as there are a few generations of single-seed descent (SSD).

Mod - keep

keep decides if the simulated marker data is exported or not. By default, this is not kept because the data can be large and rarely useful. If keep=T, magic.eval will add the marker data from all simulations into the function output. If users choose to use this option, please keep n.sim=1 or small to prevent unnecessary slow down in processing.

Plot - Pedigree

The magic.ped2plot function has one required argument ped, as well as four optional arguments, basic, show.partial, w2h.ratio and force.option. The ped argument can take pedigree generated from magic.eval, which is the first element in the list of outputs from magic.eval. Similarly, the ped argument can also take any custom pedigree, as long as it conforms to the same standard as the pedigree required for ped input in magic.eval (see Pedigree).

As the name suggests, the optional argument basic should be set to TRUE only for pedigree created from basic design. show.partial=T should only be used for pedigree created from either full or partial balanced designs, as it displays the pedigree for only a single partial balanced funnel set. This is just a nicer way to show the subset of a complicated pedigree. w2h.ratio is 2 by default, and it is simply the width-to-height ratio of the pedigree plot. force.option is FALSE by default, and if it set to TRUE, it will create a simpler and less decorated pedigree plot.

Plot - Interval

The magic.plot function has six arguments, input, display, fpair, chr.names, annotate and design.names. The input argument is a list of one or more outputs from magic.eval. The display argument is a character string of either "interval" or "whole". The fpair argument is a matrix of two columns and is only required when display="interval" as it specifies which recombinant haplotypes to display. For example, with n=8, setting fpair=cbind(c(1,1,3,5), c(2,4,6,4)) would show only “1-2”, “1-4”, “3-6” and “5-4” recombinant haplotypes in the output. The chr.names argument is a vector of chromosome names, for example, chr.names=c("1A","1B","1D"). The annotate argument is a logical indicator of whether to annotate Plot C when display="whole".

For display="interval", a plot with 3 panels (labelled as A, B, C) will be created.

1. Plot A shows the proportions of total recombinant haplotypes within the specified hap.int.
2. Plot B shows the counts of unique recombinant haplotypes within hap.int. Note that this maxes out at \(n^2-n\).
3. Plot C shows the proportions of each recombinant haplotype within hap.int.

High mean and low variance are better for all of these plots, and “evenness” across each recombinant haplotype in Plot C is also important.

Plot - Whole

For display="whole", a plot with 3 panels (labeled as A, B, C) will be created.

1. Plot A shows the mean proportions of each founder genome.
2. Plot B shows the mean counts of unique founder genome in each chromosome.
3. Plot C shows the LOESS regression of the mean counts of non-recombinant segments of various lengths in each chromosome.

For Plot A, “evenness” across all founders is better. For Plot B, higher counts (right-biased) is better. For Plot C, higher counts of short segments (left-biased) is better.

Summary Tables

The magic.summary function presents a summary information for all the designs compared, as well as the same comparisons as magic.plot. The latter output is provided as an alternative to magic.plot and can be specified by setting complete=TRUE. In the case with many designs being compared, the designs shown in plots can be challenging to distinguish especially for users with color-blindness.

The only required argument for magic.summary is input, which is a list of one or more outputs from magic.eval.