library(metan)
library(gtools)
library(dplyr)
data(data_g, package = "metan")
traits <- c("PH", "EH", "EP", "EL", "ED",
"CL", "CD", "CW", "KW", "NR", "NKR")
mod <- gamem(data_g, # Y ~ REP + (1 | GEN), by REML
gen = GEN,
rep = REP,
resp = all_of(traits),
verbose = FALSE)
blupg <- gmd(mod, "blupg", verbose = FALSE) # BLUP genetic means
blupg <- blupg[match(mixedsort(blupg$GEN), blupg$GEN), ]
idx <- mgidi(mod,
use_data = "blup", # or "pheno"
SI = 15, # selection intensity, %
mineval = 1, # Kaiser criterion
ideotype = rep("h", length(traits)),
weights = rep(1, length(traits)),
verbose = FALSE)
Computational Provenance & Reproducibility Record Multi-Trait Genotype-Ideotype Distance Index · 2.0.0 · DOI 10.5281/zenodo.22154874
This Computational Provenance Record documents the statistical computing environment, software dependencies, computational provenance, and bibliographic references associated with the RAISINS MGIDI Analysis module. It is intended to support computational reproducibility and software transparency. Detailed statistical methodology, mathematical derivations, and user guidance are provided separately in the official module documentation.
Any issues or updates required please comment here
Go to the App from here
1 Module Metadata
| Parameter | Specification |
|---|---|
| Module | Multi-Trait Genotype-Ideotype Distance Index (MGIDI) |
| Module Version | 2.0.0 |
| DOI | 10.5281/zenodo.22154874 |
| Document Type | Computational workflow |
| Statistical Engine | R |
| R Version | 4.5.2 |
| Reproducibility | Execution Environment: Posit Connect · GCR · renv-locked |
2 Statistical Dependency Manifest
| Package | Version | Repository | Core Statistical Functions |
|---|---|---|---|
| stats | 4.5.2 |
Base R | cor(), eigen(), varimax(), dist(), lm() |
| metan | 1.19.0 |
CRAN | gamem(), mgidi(), gmd() |
| lme4 | 2.0-1 |
CRAN | Mixed-model fitting engine underlying gamem() |
| lmerTest | 3.2-1 |
CRAN | lmer(), ranova() - called internally by gamem() for REML fitting and the likelihood-ratio test |
| gtools | 3.9.5 |
CRAN | mixedsort() - natural ordering of genotype labels in the reported genotype-means table |
3 Statistical Function Registry
| Analytical Role | Primary Function(s) |
|---|---|
| Per-trait mixed model | metan::gamem(gen, rep, resp) - fits Y ~ REP + (1 | GEN) by REML |
| Fixed-effect companion model | stats::lm(Y ~ REP + GEN), stored as model_lm; supplies the F-test and residual degrees of freedom |
| Significance of the genotype effect | lmerTest::ranova(reduce.terms = FALSE) - likelihood-ratio test on the random genotype term |
| Variance components & genetic parameters | gamem()$ESTIMATES - Gen_var, Res_var, Phen_var, H2, h2mg, Accuracy, CVg, CVr, CV ratio |
| Genotype predictions | gamem()$BLUPgen - BLUPg, Predicted, LL, UL, Rank |
| Multi-trait genotype means | metan::gmd(mod, "blupg") |
| Trait correlation matrix | stats::cor(use = "complete.obs") |
| Factor extraction | stats::eigen() on the trait correlation matrix; factors retained where eigenvalue ≥ mineval |
| Factor rotation | stats::varimax() on the initial loadings |
| Sampling adequacy | mgidi()$KMO, mgidi()$MSA - computed internally from the correlation and partial-correlation matrices |
| Communalities & uniqueness | mgidi()$FA$Communality, mgidi()$FA$Uniquenesses |
| Factor scores & ideotype scores | mgidi()$scores_gen, mgidi()$scores_ide |
| Multi-trait index | stats::dist() - Euclidean distance from each genotype’s factor scores to the ideotype, returned as mgidi()$MGIDI |
| Selected genotypes | mgidi()$sel_gen - the top SI% of genotypes by ascending MGIDI |
| Strengths and weaknesses | mgidi()$contri_fac - percentage contribution of each factor to a genotype’s distance |
| Selection differential & gain | mgidi()$sel_dif - Xo, Xs, SD, SDperc, h2, SG, SGperc, sense, goal |
4 Default Methods & Parameters
| Analysis | Step / Parameter | Default Method / Value |
|---|---|---|
| Input Validation |
Data layout | Long format, one row per genotype × replication. One genotype column (text labels), one replication column (numeric), and two or more numeric trait columns |
| Minimum traits | Two. A single trait is rejected with an explicit error - MGIDI factor-analyses the trait correlation matrix, which is undefined for one variable | |
| Missing values | Blank cells and wholly blank rows/columns are detected on upload and block the analysis until corrected. Within mgidi() the correlation matrix uses use = "complete.obs", so a genotype missing any selected trait contributes to none of the correlations |
|
| Per-Trait Mixed Model ( gamem()) |
Model | Y ~ REP + (1 | GEN) - randomised complete block with genotype random and replication fixed, fitted by REML through lmerTest::lmer(). One model is fitted per selected trait |
| Fixed-effect companion | Y ~ REP + GEN fitted by lm() and stored as model_lm. Its residual degrees of freedom are (g - 1)(r - 1), where g = genotypes and r = replications. This is the only closed-form df in the module; the REML denominator df reported for the fixed effect is Satterthwaite-approximated and has no closed form |
|
| Significance of genotype | ranova(reduce.terms = FALSE) - a likelihood-ratio test comparing the complete model against one with the genotype variance removed. Reported as LRT, Df and Pr(>Chisq); prob = 0.05 is the gamem() default and is not exposed to the user |
|
| Genetic parameters | Computed from the variance components as H2 = GV/FV, h2mg = GV/(GV + RV/r), Accuracy = sqrt(h2mg), CVg = sqrt(GV)/mean × 100, CVr = sqrt(RV)/mean × 100, CV ratio = CVg/CVr |
|
| Index Input Values |
Use Data | use_data = "blup" (default). The index is built from the BLUPs of the genotype effects, which are shrunk toward the overall mean in proportion to each trait's heritability, so low-heritability traits contribute less noise. The alternative "pheno" uses the arithmetic genotype means with no shrinkage. These are the only two options |
| Genotype means table | gmd(mod, "blupg"), reordered with gtools::mixedsort() so G2 precedes G10. This table is always BLUP-based regardless of the Use Data setting, which only governs what mgidi() itself consumes |
|
| Correlation matrix | cor(means, use = "complete.obs") - Pearson correlations among the genotype values, and the input to every subsequent step |
|
| Factor Analysis |
Factor retention | mineval = 1, hardcoded and not user-adjustable. Factors are retained where the eigenvalue of the correlation matrix is at least 1 (Kaiser criterion). The full eigenvalue table, variance explained and cumulative variance are reported for all components |
| Rotation | varimax() orthogonal rotation of the initial loadings. No alternative rotation is offered |
|
| Sampling adequacy | Overall KMO and per-variable MSA are computed from the squared off-diagonal correlations and partial correlations. They are reported for inspection only - the analysis is not blocked on a low value | |
| Ideotype & Selection |
Input Type | Direction (default; the toggle ships with value = FALSE). Each trait gets a direction selector defaulting to "h" = Higher is better; "l" = Lower is better. Switching the toggle to Numeric replaces the selectors with per-trait weights defaulting to 1, and every trait is then treated as "h" |
| Weights | In Direction mode all weights are fixed at 1. In Numeric mode a blank, non-numeric or non-positive entry falls back to 1 |
|
| Selection intensity | SI = 15 per cent, user-adjustable from 1 to 99 in steps of 1. A missing value falls back to 15. The number of genotypes retained is the top SI% by ascending MGIDI |
|
| Index construction | Traits are rescaled toward the ideotype ("h" → 100, "l" → 0), factor scores are formed from the rotated loadings, and MGIDI is the Euclidean dist() between each genotype's scores and the ideotype's. Lower MGIDI is better - it is a distance from the ideal, not a merit score |
|
| Selection Differential |
Quantities | Xo = mean of all genotypes, Xs = mean of the selected genotypes, SD = Xs - Xo, SDperc = SD/|Xo| × 100, SG = SD × h2, SGperc = SG/Xo × 100 |
| Desired direction | sense is "increase" for "h" traits and "decrease" for "l" traits. goal = 100 when the sign of SDperc matches sense, otherwise 0. A negative differential is therefore favourable for a trait being minimised |
|
| Reporting | Display precision | User-set, 1–4 decimal places (default 2). Display only; never affects computation |
| Plots | Four: the MGIDI rank/index plot (which also switches to a contribution radar), the trait correlation matrix, the selection differential, and the variance-components plot. All are drawn from the same fitted objects as the tables |
5 R Code for Key Analytical Steps
The code blocks below demonstrate the exact computation behind each reported result using the data_g dataset (13 maize hybrids, 3 replications, 17 traits) from the metan package. Eleven traits are analysed. The tables are given in the order the module reports them.
5.1 Mixed-Model Fitting and Index Computation
5.2 Factor Extraction, Rotation and Selection Response
tab_pca <- idx$PCA # Principal Component Analysis
colnames(tab_pca) <- c("PC", "Eigen Values",
"Variance(%)", "Cumulative Variance(%)")
fa_mean <- as.data.frame(matrix(NA_real_, 1, ncol(idx$FA)))
colnames(fa_mean) <- colnames(idx$FA)
fa_mean$VAR <- "Communality mean"
fa_mean$Communality <- idx$communalities_mean
tab_fa <- rbind(idx$FA, fa_mean) # Factor Analysis
tab_sel_dif <- idx$sel_dif # Selection Differential
tab_cor <- idx$cormat # Correlation Matrix
tab_gmd <- blupg # BLUP Genetic Mean (GMD)5.3 Genotype-Ideotype Distance and Selection
tab_sel_gen <- t(idx$sel_gen) # Selected Genotypes
tab_mgidi_index <- idx$MGIDI # MGIDI Index, ascending5.4 Variance Components and Genetic Parameters
trait <- "PH" # one trait at a time
tr <- mod[[trait]]
tab_fixed <- tr$fixed # Fixed effect ANOVA
tab_var <- tr$random # Variance Components
tab_lrt <- tr$LRT # Likelihood Ratio Test
tab_details <- tr$Details # Trait Details
tab_genetic <- tr$ESTIMATES # Genetic Parameters
tab_blup <- tr$BLUPgen %>% # BLUP Genotype Values
dplyr::mutate(Rank = as.integer(Rank))5.5 Derivation of the Rotated Loadings
means <- as.data.frame(blupg[, traits])
R <- cor(means, use = "complete.obs") # Pearson correlation matrix
E <- eigen(R)
nf <- sum(E$values >= 1) # factors retained, mineval = 1
initial_loadings <- E$vectors[, 1:nf] %*% diag(sqrt(E$values[1:nf]))
A <- varimax(initial_loadings)$loadings[] # reproduces idx$FA
communality <- rowSums(A^2) # h2
uniqueness <- 1 - communality # u25.6 Derivation of the Selection Differential
selected <- as.character(unlist(idx$sel_gen))
Xo <- colMeans(means, na.rm = TRUE) # all genotypes
Xs <- colMeans(means[as.character(blupg$GEN) %in% selected, ,
drop = FALSE], na.rm = TRUE) # selected only
SD <- Xs - Xo
SDperc <- SD / abs(Xo) * 100
SG <- idx$sel_dif$SD * idx$sel_dif$h2 # expected gain
SGperc <- SG / idx$sel_dif$Xo * 100Explore the entire MGIDI Analysis module in preview mode using our demo datasets. To submit suggestions or report a workflow issue, please use the discussion section below, or visit the official RAISINS website.
6 RAISINS Native Statistical Framework
RAISINS uses R for all its statistical computations. Every package used to generate major results is listed and demonstrated with examples, so results can be reproduced independently. These results are then organized and formatted on the RAISINS website along with visualisation to make them easier to use and interpret. RAISINS also has its own custom-built statistical tools for managing workflows, validating results, and generating reports. Details of these are not fully covered here, they’re shared with outside researchers only on request, and are subject to licensing terms.
7 Package References
R Core Team. (2025). R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. https://www.R-project.org/
Olivoto, T., & Lúcio, A. D. C. (2020). metan: An R package for multi-environment trial analysis. Methods in Ecology and Evolution, 11(6), 783-789. https://doi.org/10.1111/2041-210X.13384
Olivoto, T. (2025). metan: Multi Environment Trials Analysis (R package version 1.19.0). https://doi.org/10.32614/CRAN.package.metan
Olivoto, T., & Nardino, M. (2021). MGIDI: toward an effective multivariate selection in biological experiments. Bioinformatics, 37(10), 1383-1389. https://doi.org/10.1093/bioinformatics/btaa981
Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting Linear Mixed-Effects Models Using lme4. Journal of Statistical Software, 67(1), 1-48. https://doi.org/10.18637/jss.v067.i01
Kuznetsova, A., Brockhoff, P. B., & Christensen, R. H. B. (2017). lmerTest Package: Tests in Linear Mixed Effects Models. Journal of Statistical Software, 82(13), 1-26. https://doi.org/10.18637/jss.v082.i13
Kaiser, H. F. (1958). The varimax criterion for analytic rotation in factor analysis. Psychometrika, 23(3), 187-200. https://doi.org/10.1007/BF02289233
Kaiser, H. F. (1960). The application of electronic computers to factor analysis. Educational and Psychological Measurement, 20(1), 141-151. https://doi.org/10.1177/001316446002000116
Kaiser, H. F. (1974). An index of factorial simplicity. Psychometrika, 39(1), 31-36. https://doi.org/10.1007/BF02291575
Henderson, C. R. (1975). Best linear unbiased estimation and prediction under a selection model. Biometrics, 31(2), 423-447. https://doi.org/10.2307/2529430
Warnes, G. R., Bolker, B., & Lumley, T. (2023). gtools: Various R Programming Tools (R package version 3.9.5). https://doi.org/10.32614/CRAN.package.gtools
Allaire, J. J., Xie, Y., Dervieux, C., McPherson, J., Luraschi, J., Ushey, K., Atkins, A., Wickham, H., Cheng, J., Chang, W., & Iannone, R. (2026). rmarkdown: Dynamic Documents for R (R package version 2.30). https://github.com/rstudio/rmarkdown