Quick tour of BLUPF90

Yutaka Masuda

August 2026

Back to index.html.

Trivial analyses for fixed models

This section describes the basic design and essential elements of BLUPF90 programs. We will explain how to prepare a data file and how to describe a parameter file using simple fixed-effect models. Most of the basic ideas will be introduced here, and you can extend them to more complicated models.

We use BLUPF90+ here. This software quickly solves mixed model equations and saves the solutions to a file. This program also solves the least squares equations (i.e., normal equations) for fixed effect models. The same parameter file is also used for variance component estimation and genomic prediction.

BLUPF90+ needs at least two files: a data file and a parameter file. The data file contains observations and related information (animal ID, age, sex, month, and so on). The parameter file defines the model, the name of the data file, genetic and non-genetic variance components, and, optionally, the names of the pedigree file and genetic-marker file. The files should be prepared by the user. We start here with a linear fixed model with one class variable; this is equivalent to one-way ANOVA (with unbalanced data).

One-way ANOVA model

Model

First, we describe the statistical model for the one-way ANOVA: \[ y_{ij} = A_{i} + e_{ij} \] where \(y_{ij}\) is an observation, \(A_{i}\) is a fixed effect, and \(e_{ij}\) is the residual effect. The corresponding matrix notation is \[ \mathbf{y} = \mathbf{Xb} + \mathbf{e} \] and the system of generalized least-squares equations is \[ \mathbf{X}'\mathbf{R}^{-1}\mathbf{X}\mathbf{\hat{b}} = \mathbf{X}'\mathbf{R}^{-1}\mathbf{y} \] where \(\mathbf{R} = \mathrm{var}(\mathbf{e}) = \mathrm{var}(\mathbf{y})\). We actually assume \(\mathbf{R} = \mathbf{I}\sigma_{e}^{2}\) with a residual variance \(\sigma_{e}^{2}\), so the above equations reduce to ordinary normal equations: \(\mathbf{X}'\mathbf{X}\mathbf{\hat{b}} = \mathbf{X}'\mathbf{y}\). The purpose of this example is to solve the equations with blupf90+. The program does not perform any hypothesis tests.

Data

In this analysis, we need at least two pieces of information: (1) observations and (2) a code to distinguish the levels of a class. The following table shows an actual data set with 10 observations.

Observation Group
3.0 A1
2.0 A1
4.0 A1
6.0 A2
3.0 A2
6.0 A2
6.0 A3
6.0 A3
8.0 A3
4.0 A3

The first column represents observations, and the second column contains the group code. You can put any positive or negative observations in the data file. You can use any numerical value for an observation except 0. By default, the program treats 0 as a missing code. If you want to use an arbitrary number, including 0, as a measurement, see the Remarks section below for how to handle this case correctly.

For BLUPF90 programs, the user should prepare the data set as a text file with columns separated by spaces and the same number of columns on every line. If you use other software, such as R or SAS, you should save the data as a text file. Almost any software can export data to a text file. Do not forget to replace symbolic missing codes (such as NA or .) with a numeric value that the BLUPF90 family treats as missing.

Here we can write down the data file. You can use any file name. We save the following 10 lines as the file data0.txt.

3.0   1
2.0   1
4.0   1
6.0   2
3.0   2
6.0   2
6.0   3
6.0   3
8.0   3
4.0   3

This file illustrates the rules for a data file used with the BLUPF90 family. The data are in a space-separated format with several columns, as supported by many statistical software packages. No headers are allowed. The file should contain numerical expressions only. We will explain the acceptable data format later.

Parameter file

A parameter file to run this analysis is something like:

DATAFILE
data0.txt
NUMBER_OF_TRAITS
1
NUMBER_OF_EFFECTS
1
OBSERVATION(S)
1
WEIGHT(S)

EFFECTS:
2 3 cross
RANDOM_RESIDUAL VALUES
1.0

The parameter file is described using pairs of keywords and values. For example, the first line, DATAFILE, is a keyword, and the next line, data0.txt, is the corresponding value. The value(s) should be placed on the line following the keyword. The keyword must start in the first position on a line (i.e., with no leading spaces). The value can have leading spaces at the beginning of a line. The above example is a minimal one. We need at least 7 keywords in every parameter file, even when some values are empty. The following is a detailed explanation of the above parameter file.

  1. DATAFILE = the name of the data file
    • → data0.txt in this case
  2. NUMBER_OF_TRAITS
    • → 1 for a single-trait model
  3. NUMBER_OF_EFFECTS = number of effects except residual
    • → 1 for the fixed effect (only 1 effect in this model except residual)
  4. OBSERVATION(S) = position of observation in the data file
    • → 1 for the 1st column
  5. WEIGHT(S) = position of weight in the data file 1
    • → There is no weight but empty line must be there.
  6. EFFECTS: = description of the model (2 3 cross; see below)
    • → 2 for the position of group code [2nd column in the data file]
    • → 3 for the maximum level [the column contains 1, 2, or 3; so the maximum is 3]
    • → cross for the cross-classified effect
  7. RANDOM_RESIDUAL VALUES = residual variance \(\sigma_e^2\)
    • → 1.0; this value does not affect the results in this case (see the normal equations).

The EFFECTS: block describes the model, and its format differs from that of other software. In this case, this block has only 1 line because the model has only 1 effect in addition to the residual. If you have more effects in the model, you can add a description for each effect.

Running a program

You can save the data file and parameter file in the same folder (directory) and run blupf90+. When the program is invoked, it prints a message on the screen and waits for key-in.

 name of parameter file?

When you supply the name of the parameter file param1.txt, the program reads the parameters, builds and solves the equations, and writes the solutions to a file.

What will happen if you give the wrong name of a parameter file or if your parameter file contains erroneous statements? In both cases, an error message is shown and the program stops. Possible results are:

Computations

After running the program, you can find a file named solutions. This is also a text file, and it contains the following lines.

trait/effect level  solution
    1   1         1      3.00000000
    1   1         2      5.00000000
    1   1         3      6.00000000

Ignoring the first line as a header, we have 3 lines with 4 columns, and the 4th column contains the solutions. The first solution (\(3.0\)) can be interpreted as the solution for trait 1, effect 1, and level (group) 1. The second (\(5.0\)) is for trait 1, effect 1, and level (group) 2. The third (\(6.0\)) is for trait 1, effect 1, and level (group) 3. In mathematical notation, \(\hat{A}_1 = 3.0\), \(\hat{A}_2 = 5.0\), and \(\hat{A}_3 = 6.0\). The solution is actually the within-class average because we employed a one-way model with an assumption of homogeneous residual variance.

Fixed effect model

We consider another fixed-effects model with more effects using the same data set. The model has 1 additional class effect and 1 regression coefficient: \[ y_{ijk} = A_i + S_j + \beta x_{ijk} + e_{ijk} \] where \(y_{ijk}\) is an observation, \(A_i\) is a fixed effect, \(S_j\) is another fixed effect, \(\beta\) is a regression coefficient, \(x_{ijk}\) is a covariate, and \(e_{ijk}\) is the residual effect. The matrix notation and covariance structure are the same as in the previous model. We will use the same data as before, but with some additional columns.

Observation Group1 Group2 \(x\)
3.0 A1 S1 1.0
2.0 A1 S2 1.0
4.0 A1 S1 2.0
6.0 A2 S2 2.0
3.0 A2 S1 1.0
6.0 A2 S2 2.0
6.0 A3 S1 2.0
6.0 A3 S2 1.0
8.0 A3 S1 1.0
4.0 A3 S2 2.0

The data file contains 4 columns in this case.

3.0  1  1  1.0
2.0  1  2  1.0
4.0  1  1  2.0
6.0  2  2  2.0
3.0  2  1  1.0
6.0  2  2  2.0
6.0  3  1  2.0
6.0  3  2  1.0
8.0  3  1  1.0
4.0  3  2  2.0

The parameter file is also similar to the previous one, but it needs additional entries for the two additional effects.

DATAFILE
data1.txt
NUMBER_OF_TRAITS
1
NUMBER_OF_EFFECTS
3
OBSERVATION(S)
1
WEIGHT(S)

EFFECTS:
2 3 cross
3 2 cross
4 1 cov
RANDOM_RESIDUAL VALUES
1.0

What is the difference? The only differences are in NUMBER_OF_EFFECTS and EFFECTS:. Because the model has 3 effects (2 class effects and 1 regression effect), we have changed the value of NUMBER_OF_EFFECTS, and EFFECTS: needs 3 lines. Note that the 3rd effect is a regression effect, and its description differs from those of the previous 2 cross-classified effects. The following is a detailed explanation.

The BLUPF90 programs refer to the first effect as effect 1, the second as effect 2, and so on. The order is preserved in the solutions file.

When you run the program with the parameter file, you can find the following results.

trait/effect level  solution
    1   1         1      0.22500000
    1   1         2      2.22500000
    1   1         3      3.22500000
    1   2         1      2.27500000
    1   2         2      1.77500000
    1   3         1      0.50000000

The program provides 6 estimates: the first 3 are for the first effect, the next 2 are for the second effect, and the last 1 is for the final effect. In mathematical notation, \(\hat{A}_1 = 0.225\), \(\hat{A}_2 = 2.225\), and \(\hat{A}_3 = 3.225\), \(\hat{S}_1 = 2.275\), \(\hat{S}_2 = 1.775\), and \(\hat{\beta} = 0.500\). This is a single-trait model, so the first column is always 1. The second column contains the effect number according to the order of the items in EFFECTS: in the parameter file.

Note that this system of equations is not full rank, so the estimates are one of infinitely many possible solutions. The BLUPF90 family does not support arbitrary constraints for solving the equations. Although the estimates may differ from those obtained with other software, the contrasts for any estimable function will be consistent.

Options to control the program

The behavior of BLUPF90 programs (such as blupf90+) can be changed with options. Each program may or may not accept particular options. An option should be written in a parameter file as an additional line at the bottom of the file. If you have multiple options, you can add as many option lines as needed. There are many options, and the official manual explains them.

Here we show a typical option line for BLUPF90+ as a demonstration. We use an option that changes the method of solving the mixed model equations from the default PCG (preconditioned conjugate gradient) to the direct method using the FSPAK subroutine.

OPTION solv_method FSPAK

The option line starts with the uppercase keyword OPTION, followed by an option name and additional information, if needed. In the above case, the option name is solv_method, and the additional information is FSPAK. Be careful when writing an option because the BLUPF90 family distinguishes uppercase and lowercase letters in the option line and will fail if the name or information is incorrect.

The modified parameter file with this option looks as follows.

DATAFILE
data1.txt
NUMBER_OF_TRAITS
1
NUMBER_OF_EFFECTS
3
OBSERVATION(S)
1
WEIGHT(S)

EFFECTS:
2 3 cross
3 2 cross
4 1 cov
RANDOM_RESIDUAL VALUES
1.0
OPTION solv_method FSPAK

Again, this option is effective only for BLUPF90+. With this parameter file, blupf90+ runs successfully but prints different messages on the screen. The solutions are also different from the previous ones because the equations do not have unique solutions.

trait/effect level  solution
    1   1         1      2.50000000
    1   1         2      4.50000000
    1   1         3      5.50000000
    1   2         1      0.00000000
    1   2         2     -0.50000000
    1   3         1      0.50000000

You can still see the consistency of a linear combination of the solutions. For example, \(\hat{A}_1 + \hat{S}_1 + \hat{\beta} = 3.0\) in both cases.

Comment lines in parameter file

A parameter file can contain comments, which are ignored by typical BLUPF90 programs. A comment is a brief note for keeping additional information in a parameter file. A comment starts with the character #, and the program ignores all characters from # to the end of the line. The following example works like the previous parameter file.

#
# This is an example parameter file for a fixed effect model.
# Solving method: FSPAK
#
DATAFILE
data1.txt # write the name of data file here
NUMBER_OF_TRAITS
1 # single trait model
NUMBER_OF_EFFECTS
3 # A, S, b
OBSERVATION(S)
1
WEIGHT(S)

EFFECTS:   # y = A + S + b*x + e
2 3 cross  # effect A
3 2 cross  # effect S
4 1 cov    # regression
RANDOM_RESIDUAL VALUES # any values okay
1.0
# added options
OPTION solv_method FSPAK

This example shows how comments are ignored. You can write comments almost anywhere in a parameter file. There is one exception: comments should not be placed on lines containing variance components. If a comment is placed on the same line as a variance component, the program stops with an error. Also, comments are allowed in the parameter file but not in the data file.

Because comment lines are useful, we will use them in parameter files in later chapters.

Remarks

In real-life applications, your data file may contain alphabetic characters or symbols (alphanumeric values). Even when a class variable is an integer, it may not start at 1 or may end at a very large value (such as 2087654512). Before the analysis, you should edit the files to conform to the program’s requirements. RENUMF90 is a data preparation tool that replaces alphabetic characters or large numbers with sequential numbers starting from 1. Except in limited situations (e.g., simulated data or data renumbered by other means), you should usually use RENUMF90 to prepare and check the files.

By default, an observation (a trait) with value 0 (or a similar numerical expression, such as 0.0) is recognized as a missing observation. Similarly, an effect level read as 0 is treated as missing information. This means that the effect is ignored for that particular record. For a single-trait model, a missing observation has little meaning, except in rare circumstances such as cross-validation or automatic repeated analysis (i.e., dozens of univariate analyses from the same, already recorded file). A missing effect is also an unusual assumption. Therefore, you should avoid using 0 in the data. If your observation has a real value of 0, you can make the program treat it as a regular observation by adding an OPTION statement as follows:

OPTION missing -999

The missing option changes the missing value recognized in BLUPF90+ from 0 to -999. The value is treated as an integer; real values will not be accepted.

How do we include interactions among effects, as commonly found in a 2-way ANOVA (\(y = A + B + A \times B + e\))? To do this, we should prepare all the effects \(A\), \(B\), and \(A \times B\) in the data file. BLUPF90 does not generate \(A \times B\) from the effects \(A\) and \(B\). Also, BLUPF90 does not support automatic generation of nested effects. All interactions or nested effects should be prepared as class effects in the data file. The RENUMF90 program, a data preparation tool, can help generate such effects. One exception is regression nested in a class variable, which is supported by the BLUPF90 programs; we will mention this model in the context of random regression.

Summary

Back to index.html.