Error handling (original) (raw)

• Errors in dream()
  • Gene-level errors
• Shared by multiple functions
  • Warnings
  • Errors
    * Errors: Problems removing samples with NA/NaN/Inf values
    * Errors with BiocParallel multithreading backend
• Session Info

Errors and warnings in variancePartition are mostly designed to let the user know that there is an isssue with the model. Note that some of these warnings and errors can be overridden by specifying hideErrorsInBackend=TRUE for dream() and showWarnings=FALSE for fitExtractVarPartModel() and fitVarPartModel().

Errors in dream()

The linear mixed model used by dream() can be a little fragile for small sample sizes and correlated covariates.

• Initial model failed: the fixed-effects model matrix is column rank deficient (rank(X) = 3 < 4 = p); the fixed effects will be jointly unidentifiable
  The design matrix has redundant variables, so the model is singular and coefficients can’t be estimated. Fix by dropping one or more variables. Use canCorPairs() to examine correlation betweeen variables.

Gene-level errors

The most common issue is when dream() analysis succeeds for most genes, but a handful of genes fail. These genes can fail if the iterative process of fitting the linear mixed model does not converge, or if the estimated covariance matrix that is supposed be positive definite has an eigen-value that is negative or too close to zero due to rounding errors in floating point arithmetic.

In these cases, dream() gives a warning that the model has failed for a subset of genes, and also provides the gene-level errors. All successful model fits are returned to be used for downstream analysis.

Here we demonstrate how dream() handles model fits:

library(variancePartition)
data(varPartData)

# Redundant formula
# This example is an extreme example of redundancy
# but more subtle cases often show up in real data
form <- ~ Tissue + (1 | Tissue)

fit <- dream(geneExpr[1:30, ], form, info)

## Warning in dream(geneExpr[1:30, ], form, info): Model failed for 29 responses.
##   See errors with attr(., 'errors')

# Extract gene-level errors
attr(fit, "errors")[1:2]

## gene1
## "Error in lmerTest:::as_lmerModLT(model, devfun, tol = tol): (converted from warning)
## Model may not have converged with 1 eigenvalue close to zero: -2.0e-09\n"

## gene2
## "Error: (converted from warning) Model failed to converge
##   with 1 negative eigenvalue: -1.5e-08\n"

Session Info

## R version 4.5.0 RC (2025-04-04 r88126)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.2 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.21-bioc/R/lib/libRblas.so 
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0  LAPACK version 3.12.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C               LC_TIME=en_GB             
##  [4] LC_COLLATE=C               LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                  LC_ADDRESS=C              
## [10] LC_TELEPHONE=C             LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: America/New_York
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] edgeR_4.6.0              pander_0.6.6             variancePartition_1.38.0
## [4] BiocParallel_1.42.0      limma_3.64.0             ggplot2_3.5.2           
## [7] knitr_1.50              
## 
## loaded via a namespace (and not attached):
##  [1] tidyselect_1.2.1    farver_2.1.2        dplyr_1.1.4         bitops_1.0-9       
##  [5] fastmap_1.2.0       digest_0.6.37       lifecycle_1.0.4     statmod_1.5.0      
##  [9] magrittr_2.0.3      compiler_4.5.0      rlang_1.1.6         sass_0.4.10        
## [13] tools_4.5.0         yaml_2.3.10         labeling_0.4.3      plyr_1.8.9         
## [17] KernSmooth_2.23-26  withr_3.0.2         purrr_1.0.4         numDeriv_2016.8-1.1
## [21] BiocGenerics_0.54.0 grid_4.5.0          aod_1.3.3           caTools_1.18.3     
## [25] colorspace_2.1-1    scales_1.3.0        gtools_3.9.5        iterators_1.0.14   
## [29] MASS_7.3-65         cli_3.6.4           mvtnorm_1.3-3       rmarkdown_2.29     
## [33] reformulas_0.4.0    generics_0.1.3      reshape2_1.4.4      minqa_1.2.8        
## [37] cachem_1.1.0        stringr_1.5.1       splines_4.5.0       parallel_4.5.0     
## [41] matrixStats_1.5.0   vctrs_0.6.5         boot_1.3-31         Matrix_1.7-3       
## [45] jsonlite_2.0.0      pbkrtest_0.5.3      locfit_1.5-9.12     jquerylib_0.1.4    
## [49] tidyr_1.3.1         snow_0.4-4          glue_1.8.0          nloptr_2.2.1       
## [53] codetools_0.2-20    stringi_1.8.7       gtable_0.3.6        EnvStats_3.0.0     
## [57] lme4_1.1-37         lmerTest_3.1-3      munsell_0.5.1       tibble_3.2.1       
## [61] remaCor_0.0.18      pillar_1.10.2       htmltools_0.5.8.1   gplots_3.2.0       
## [65] R6_2.6.1            Rdpack_2.6.4        evaluate_1.0.3      lattice_0.22-7     
## [69] Biobase_2.68.0      rbibutils_2.3       backports_1.5.0     RhpcBLASctl_0.23-42
## [73] broom_1.0.8         fANCOVA_0.6-1       corpcor_1.6.10      bslib_0.9.0        
## [77] Rcpp_1.0.14         nlme_3.1-168        xfun_0.52           pkgconfig_2.0.3