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"
)

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

Extracting Results

Variance Components

var_comps <- model$varcomp
print(var_comps)

Heritability

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

Fixed-Effect Coefficients (model$BLUEs)

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

coef_table <- model_fixed$BLUEs
head(coef_table)

model$BLUEs is the fixed-effect solution table from the fitted model. For genotype-level adjusted means, use mandala_predict().

Genotype BLUEs (Genotype Fixed)

Use a model where genotype is fitted as a fixed effect.

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

blue_means <- mandala_predict(model_fixed, classify_term = "genotype")
head(blue_means)

Genotype BLUPs (Genotype Random)

Use a model where genotype is fitted as a random effect.

model_random <- mandala(
  fixed  = yield ~ 1,
  random = ~ genotype + block,
  data   = field_data
)

blups <- mandala_predict(model_random, 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, Gmat)
)
head(gp_fit$gebv)

# Cross-validation
cv <- mandala_gp_cv(
  fixed   = yield ~ 1,
  random  = ~ GM(genotype, Gmat),
  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(), mmes() lmer()
Variance components $varcomp summary()$varcomp VarCorr()
Genotype BLUEs/BLUPs model$BLUEs, mandala_predict() Beta, U, predict.mmes() fixef(), ranef()
Heritability h2_estimates() Manual Manual
GBLUP GM(), mandala_gp() vsr(Gu=) Not supported
FA models FA() Reduced-rank / FA-style structures via mmes() Not supported
AR1 spatial ar1(row) Row/column or custom covariance structures Not supported
P-spline spatial pspline2D() spl2Dc() via mmes() Not supported
Variograms mandala_variogram() Manual Not supported

Common Experimental Designs

The blocks below show the corresponding fixed and random specifications inside mandala().

1. RCBD

Effect Type
Genotype Fixed
Block Random 
# Mandala syntax
fixed  = yield ~ genotype
random = ~ block

2. Alpha-Lattice

Effect Type
Genotype Fixed
Rep Random
Incomplete Block(Rep) Random 
# Mandala syntax
fixed  = yield ~ genotype
random = ~ rep + rep:incomplete_block

3. Row-Column

Effect Type
Genotype Fixed
Row Random
Column Random 
# Mandala syntax
fixed  = yield ~ genotype
random = ~ row + col

4. Multi-Environment Trial

Effect Type
Genotype Fixed
Environment Fixed
G×E Fixed
Block(Env) Random 
# Mandala syntax
fixed  = yield ~ genotype + env + genotype:env
random = ~ env:block

5. FA G×E Model

Effect Type
Environment Fixed
Genotype Fixed
FA G×E Random (k factors) 
# Mandala syntax
fixed  = yield ~ env + genotype
random = ~ FA(genotype, env, k = 2) + by(env):ar1(row) + by(env):ar1(col)

6. GBLUP

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

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