Quick Reference

Common tasks at a glance

A concise reference for common tasks when analyzing field trial data with the mandala package.

Basic Model Syntax

Simple RCBD

model <- mandala(
  fixed  = yield ~ genotype,
  random = ~ block,
  data   = field_data
)

Alpha-Lattice Design

model <- mandala(
  fixed  = yield ~ genotype,
  random = ~ rep + rep:incomplete_block,
  data   = field_data
)

Multi-Environment Trial

model <- mandala(
  fixed  = yield ~ genotype + env + genotype:env,
  random = ~ env:block,
  data   = field_data
)

Spatial Model (AR1)

model <- mandala(
  fixed  = yield ~ genotype,
  random = ~ block + ar1(row) + ar1(col),
  data   = field_data
)

Spatial Model (P-spline)

model <- mandala(
  fixed  = yield ~ genotype,
  random = ~ pspline2D(row.num, col.num,
                       nseg = c(10, 10),
                       degree = c(3, 3),
                       pord = c(2, 2)),
  data   = field_data
)

Factor-Analytic G×E

model <- mandala(
  fixed  = yield ~ env + genotype,
  random = ~ FA(genotype, env, k = 2) + by(env):ar1(row) + by(env):ar1(col),
  data   = met_data
)

Genomic Prediction (GBLUP)

# Prepare GRM
grm_prep <- mandala_grm_prep(
  GRM       = "path/to/grm.csv",
  data      = pheno_data,
  gen_col   = "genotype",
  GRM_label = "GRM"
)

# Fit model
model <- mandala(
  fixed       = yield ~ env,
  random      = ~ GM(genotype, GRM) + GM(genotype, GRM):env,
  matrix_list = grm_prep,
  data        = pheno_data
)

Extracting Results

Variance Components

var_comps <- summary(model)$varcomp
print(var_comps)

Heritability

h2 <- h2_estimates(
  random_mod = model_random,
  fixed_mod  = model_fixed,
  genotype   = "genotype"
)

BLUEs (Fixed Effects)

blues <- model$BLUEs
head(blues)

BLUPs (Random Effects)

blups <- mandala_predict(model, classify_term = "genotype")
head(blups)

Genomic Predictions

# High-level GP wrapper
gp_fit <- mandala_gp(
  GRM     = "path/to/grm.csv",
  data    = pheno_data,
  gen_col = "genotype",
  fixed   = yield ~ 1,
  random  = ~ GM(genotype, GRM)
)
head(gp_fit$gebv)

# Cross-validation
cv <- mandala_gp_cv(
  fixed   = yield ~ 1,
  random  = ~ GM(genotype, GRM),
  gen_col = "genotype",
  data    = pheno_data,
  GRM     = "path/to/grm.csv",
  k_folds = 5,
  n_reps  = 3
)
mean(cv$by_fold$pred_ability)

FA Model Results

# Visualization
fa_biplot(model)
fa_biplot(model, type = "which_won_where")
fa_heatmap(model)

# Environment correlations
fa_env_vcov(model)
fa_env_cor(model)

# Reliability
fa_reliability(model)
fa_reliability_by_env(model)
fa_reliability_by_geno(model)

# Scores and loadings
fa_geno_scores(model)
fa_env_loadings(model)

# Specific variance
fa_psi(model)

Spatial Diagnostics

# Variograms
mandala_variogram(model, data, plot_type = "3d")
mandala_variogram(model, data, plot_type = "2d")
mandala_variogram(model, data, plot_type = "dynamic")  # Interactive

# Spatial plots
plot_mandala_spatial(model, data, response = "yield",
                     geno = "genotype", row = "row", col = "col")

Model Diagnostics

mandala_diagnostic_plots(model, response = "yield")

Package Comparison

Mandala vs Sommer vs lme4

Task Mandala Sommer lme4
Model fit mandala() mmer() lmer()
Variance components $varcomp summary()$varcomp VarCorr()
BLUPs mandala_predict() randef() ranef()
Heritability h2_estimates() Manual Manual
GBLUP GM(), mandala_gp() vsr(Gu=) Not supported
FA models FA() dsr() Not supported
AR1 spatial ar1(row) Custom cov Not supported
P-spline spatial pspline2D() Not supported Not supported
Variograms mandala_variogram() Not supported Not supported

Common Experimental Designs

1. RCBD

Effect Type
Genotype Fixed
Block Random 
yield ~ genotype + (1|block)

2. Alpha-Lattice

Effect Type
Genotype Fixed
Rep Random
Incomplete Block(Rep) Random 
yield ~ genotype + (1|rep) + (1|rep:incomplete_block)

3. Row-Column

Effect Type
Genotype Fixed
Row Random
Column Random 
yield ~ genotype + (1|row) + (1|col)

4. Multi-Environment Trial

Effect Type
Genotype Fixed
Environment Fixed
G×E Fixed
Block(Env) Random 
yield ~ genotype + env + genotype:env + (1|env:block)

5. FA G×E Model

Effect Type
Environment Fixed
Genotype Fixed
FA G×E Random (k factors) 
# Mandala syntax
random = ~ FA(genotype, env, k = 2)

6. GBLUP

Effect Type
Intercept Fixed
Genotype (GRM) Random 
# Mandala syntax
random = ~ GM(genotype, GRM)

Heritability Formulas

Plot Basis

\[h^2 = \frac{\sigma^2_g}{\sigma^2_g + \sigma^2_e}\]

Entry-Mean Basis (Single Environment)

\[h^2 = \frac{\sigma^2_g}{\sigma^2_g + \sigma^2_e/r}\]

Where r = number of replications

Across Multiple Environments

\[h^2 = \frac{\sigma^2_g}{\sigma^2_g + \sigma^2_{g \times e}/e + \sigma^2_e/(e \times r)}\]

Where e = environments, r = reps per environment

Data Preparation Checklist

Model Checking

Check Convergence

summary(model)
# Look for warnings

Examine Residuals

plot(fitted(model), residuals(model))
abline(h = 0, col = "red")

Check Normality

qqnorm(residuals(model))
qqline(residuals(model))

Common Issues

Issue Solution
Model doesn’t converge Check for missing data, verify design
Negative variance estimates Simplify model, check data structure
Very low heritability Check data quality, model specification

Visualization Templates

Genotype Performance

library(ggplot2)

blues %>%
  ggplot(aes(x = reorder(genotype, estimate), y = estimate)) +
  geom_point(size = 3) +
  geom_errorbar(aes(ymin = lower_ci, ymax = upper_ci), width = 0.2) +
  coord_flip() +
  theme_minimal() +
  labs(x = "Genotype", y = "Estimated Yield")

G×E Interaction

gxe_data %>%
  ggplot(aes(x = environment, y = mean_yield, 
             group = genotype, color = genotype)) +
  geom_line() +
  geom_point(size = 2) +
  theme_minimal()

Field Heatmap

field_data %>%
  ggplot(aes(x = col, y = row, fill = yield)) +
  geom_tile() +
  scale_fill_viridis_c() +
  theme_minimal()

Resources

Key References

  • Piepho et al. (2003) - BLUP in plant breeding
  • Gilmour et al. (1997) - Spatial analysis
  • Smith et al. (2005) - Variety trials
  • Rodríguez-Álvarez et al. (2018) - SpATS spatial analysis
  • VanRaden (2008) - Genomic relationship matrices