TSDFGS

Version 3.0.0 keeps every function of v2 and adds 15 criteria. See what changed.

TSDFGS helps you decide which individuals to phenotype, and how many, before you build a genomic prediction model. Give it genotypes (principal components or markers) and it searches for the training set that optimizes a criterion.

Find what you need

Criteria

optTrain(method = ) takes the name in the last column; criteria() returns this table in R. Each criterion has a page with its definition, the original paper, the authors’ repository, and a license review. “Test set” says whether the criterion uses the individuals to be predicted.

The r-score is the criterion of Ou & Liao (2019). The others come from the papers named on their pages. TSDFGS is released under GPL (>= 3) and implements every criterion from its published definition in C++ (RcppEigen).

What is tested. Only three criteria are tested carefully: the r-score, PEVmean, and CD, the criteria of v2.4.2. For all 12 routes of optTrain() (with or without sub-populations, with or without a test set), the training sets, scores, and score histories equal the output recorded from v2.4.2.

The other 15 criteria are provided as they are described in their papers, and the code runs without errors on all routes, but we have not checked them carefully. We compared several of them with other implementations (see the license review), and each has a small test against a direct formula. This is not a validation. Please evaluate them yourself on your own data before you rely on them, for example by scoring training sets you know with the matching *_score() function.

Installation

This repository is the home of the package. Every push to main is checked on Linux, macOS, and Windows (GitHub Actions), and the website and the Docker image are built from it.

# Current version of the main branch (needs a C++17 compiler)
# install.packages("remotes")
remotes::install_github("oumarkme/TSDFGS")

# A given release, for example v3.0.0
remotes::install_github("oumarkme/TSDFGS@v3.0.0")

# Source package of a release (the file also attached to each GitHub release)
install.packages("https://github.com/oumarkme/TSDFGS/releases/download/v3.0.0/TSDFGS_3.0.0.tar.gz", repos = NULL)

# From CRAN, once the version is accepted there
install.packages("TSDFGS")

Without installing anything, use the Docker image (R, compilers, and TSDFGS included):

docker run --rm -it -v "$PWD":/work ghcr.io/oumarkme/tsdfgs:latest R

The article Installation and environments has the details for each system. Old versions are on the releases page.

Version used in the manuscript

The manuscript (Ou & Liao, 2019) used TSDFGS 1.0, the first CRAN release (2019-03-07). The r-score and the search of this package are the method of that paper. To run version 1.0 itself, install it from the CRAN archive:

install.packages("https://cran.r-project.org/src/contrib/Archive/TSDFGS/TSDFGS_1.0.tar.gz", repos = NULL, type = "source")

Quick start

library(TSDFGS)
data(geno)                                   # 404 rice accessions, principal components
g <- as.matrix(geno)[, 1:15]

# 30 of the first 100 accessions to phenotype, to predict accessions 101-150
fit <- optTrain(g, cand = 1:100, n.train = 30, test = 101:150, seed = 1)
fit$OPTtrain                                 # rows to phenotype
r_score(g[fit$OPTtrain, ], g[101:150, ])     # criterion of the chosen set

# How many individuals are enough? (slow; use multi.threads = TRUE on Linux or macOS)
res <- SSDFGS(geno)
res$OC.fig

More in the Getting started guide.

Main functions

The packages STPGA (GPL-3) and TSODBG (GPL >= 3) implement several of the same criteria in R; we used them to check our results (see the license review).

What changed from v2 to v3

New in v3.0.0: 15 added criteria (see above), the criteria() function, and the lambda argument of optTrain().

Nothing you call has changed. All exported functions keep their names and arguments, and the method is the one published in 2019.

Speed on the rice principal components (one core, same seed and iteration count; median of one run per case):

Milliseconds per iteration of optTrain() (rice principal components, n.train = 50 to 100):

Speed with 50 cores. We ran 200 independent r-score searches (untargeted, 100 of 404 rice accessions, 50 principal components) on 50 cores, with TSDFGS 1.0, 2.4.2, and 3.0.0. Versions 1.0 and 2.4.2 have no multithreading, so they ran as 50 forked processes (parallel::mclapply). Each violin shows the time of the 200 searches; the white dot is the median. The median search took 5.07 s with version 1.0, 5.01 s with 2.4.2, and 0.29 s with 3.0.0 (17.6 times faster than 1.0). The whole job took 29.1 s, 29.5 s, and 1.9 s with the same forking, and 1.5 s with the OpenMP threads of 3.0.0 (19.6 times faster than 1.0). The spread within a violin comes from the stopping rule, which ends each search after a different number of iterations.

Parallel simulation. SSDFGS(), FGCM(), and nt2r() run their independent searches with OpenMP when you set multi.threads = TRUE or threads = n. On a Linux server limited to 50 threads (100 searches, 404 rice accessions, 50 PCs, wall time):

OpenMP is about as fast as mclapply. What it adds: the same values for any number of threads (tested), no forked copies of the data, and Windows support. At 50 threads 100 searches are too few to keep every thread busy. optTrain(threads = ) lets one search use several threads: the matrix products inside one search (only with several hundred columns) and, for the targeted r-score and PEV search, the 30 candidate sets of each generation.

The full list is in NEWS.md, the article Moving from v2 to v3 has the details.

Kept on purpose. The r-score code multiplies the test set by 1 - 1/n0 where a centering matrix may be intended. It stays as published, so that results do not change.

Example dataset

Zhao et al. (2011) published the rice genome data used as an example. The raw dataset is on the Rice Diversity website. The pre-arranged data are in this repository and load with data(geno) and data(subpop), or:

download.file("https://github.com/oumarkme/TSDFGS/raw/main/data/geno.rda", "geno.rda")
load("geno.rda")

Reproducible environment

We tested v3 with R 4.4.3, Rcpp 1.1.2, RcppEigen 0.3.4.0.2, and GCC 16.2.0. All versions are pinned in environment.yml, and the Docker image contains them. Use either of two ways to get the same software:

# Docker image with R and TSDFGS installed (built and tested by GitHub Actions)
docker run --rm -it -v "$PWD":/work ghcr.io/oumarkme/tsdfgs:3.0.0 R

# conda / mamba environment with the pinned versions; then install TSDFGS from a clone
git clone https://github.com/oumarkme/TSDFGS.git && cd TSDFGS
mamba env create -f environment.yml
mamba activate TSDFGS
R CMD INSTALL .

Use a release tag such as 3.0.0 in your analyses, because latest follows the main branch. The article Installation and environments also covers a small conda environment, Apptainer, and building the image yourself.

Development

Build and test with the same software versions in an Apptainer image:

env/build_sif.sh <work_dir>         # writes env/TSDFGS.sif (git-ignored)
apptainer exec --bind $PWD:/work --pwd /work env/TSDFGS.sif Rscript -e 'devtools::test()'

Authors

• Jen-Hsiang Ou, Ph.D.
  • Author, maintainer
  • E-mail: oumark.me@outlook.com
  • Department of Medical Genetics, National Taiwan University Hospital, Taipei, Taiwan
• Po-Ya Wu, Ph.D.
  • Author
  • E-mail: Po-Ya.Wu@hhu.de
  • Institute for Quantitative Genetics and Genomics of Plants, Heinrich Heine University, Düsseldorf, Germany
• Chen-Tuo Liao, Ph.D.
  • Author, thesis advisor
  • E-mail: ctliao@ntu.edu.tw
  • Department of Agronomy, National Taiwan University, Taipei, Taiwan

Citation

Ou, J.-H., & Liao, C.-T. (2019). Training set determination for genomic selection. Theoretical and Applied Genetics, 132, 2781-2792. https://doi.org/10.1007/s00122-019-03387-0