Troubleshooting

A common issue that comes up when running spiec.easi is coming up with an empty network after running StARS.

For example:

library(SpiecEasi)
data(amgut1.filt)

pargs <- list(seed=10010)
se3 <- spiec.easi(amgut1.filt, method='mb', lambda.min.ratio=5e-1, nlambda=10, pulsar.params=pargs)

getOptInd(se3)
# [1] 1
sum(getRefit(se3))/2
# [1] 139

As the warning indicates, the network stability could not be determined from the lambda path. Looking at the stability along the lambda path, se$select$stars$summary, we can see that the maximum value of the StARS summary statistic never crosses the default threshold (0.05).

This problem we can fix by lowering lambda.min.ratio to explore denser networks:

se4 <- spiec.easi(amgut1.filt, method='mb', lambda.min.ratio=1e-1, nlambda=10, pulsar.params=pargs)

We have now fit a network, but since we have only a rough, discrete sampling of networks along the lambda path, we should check how far we are from the target stability threshold (0.05):

getStability(se4)
# [1] 0.0003237095
sum(getRefit(se4))/2
# [1] 158

To get closer to the mark, we should bump up nlambda to more finely sample of the lambda path, which gives a denser network:

se5 <- spiec.easi(amgut1.filt, method='mb', lambda.min.ratio=1e-1, nlambda=100, pulsar.params=pargs)

getStability(se5)
# [1] 0.0003237095
sum(getRefit(se5))/2
# [1] 210

Common issues and solutions

1. Empty networks

Problem: After running spiec.easi, you get an empty network (no edges).

Solutions: - Lower lambda.min.ratio to explore denser networks - Increase nlambda for finer sampling of the lambda path - Check if your data has sufficient signal-to-noise ratio - Try different methods (‘mb’ vs ‘glasso’)

2. Very dense networks

Problem: The inferred network has too many edges.

Solutions: - Increase lambda.min.ratio to explore sparser networks - Adjust the StARS threshold in pulsar.params - Use cross-validation instead of StARS

3. Computational issues

Problem: The analysis takes too long or runs out of memory.

Solutions: - Use parallel processing with ncores parameter (Unix-like systems only) - Use B-StARS method for large datasets - Reduce rep.num in pulsar.params - Use batch mode for HPC clusters

4. Windows parallel processing issues

Problem: Error “‘mc.cores’ > 1 is not supported on Windows”

Solutions: - Use ncores=1 for serial processing on Windows - Use snow cluster for parallel processing on Windows:

library(parallel)
cl <- makeCluster(4, type = "SOCK")
pargs.windows <- list(rep.num=50, seed=10010, cluster=cl)
se.windows <- spiec.easi(data, method='mb', pulsar.params=pargs.windows)
stopCluster(cl)

Use batch mode which works on all platforms
Consider using WSL (Windows Subsystem for Linux) for Unix-like environment

5. Convergence issues

Problem: The algorithm doesn’t converge or gives warnings.

Solutions: - Check data preprocessing and normalization - Ensure data doesn’t have constant columns - Try different starting values - Check for missing or infinite values

6. Memory issues

Problem: R runs out of memory during analysis.

Solutions: - Use sparse matrices where possible - Reduce dataset size by filtering rare taxa - Use batch processing for large datasets - Increase system memory if available

Platform-specific considerations

Windows users:

Default parallel processing (mc.cores > 1) is not supported
Use ncores=1 for serial processing
Use snow cluster for parallel processing
Consider batch mode for large datasets

Unix-like systems (Linux, macOS):

Full support for parallel processing with mc.cores
Can use ncores parameter directly
Both multicore and snow clusters available

Diagnostic functions

SpiecEasi provides several functions to help diagnose issues:

# Check stability along lambda path
getStability(se)

# Get optimal lambda index
getOptInd(se)

# Get summary statistics
se$select$stars$summary

# Check network density
sum(getRefit(se))/2

# Visualize stability curve
plot(se$select$stars$summary)

# Check platform information
.Platform$OS.type

Parameter tuning guidelines

For small datasets (< 100 samples, < 50 taxa):

lambda.min.ratio = 1e-2
nlambda = 20-50
rep.num = 20-50

For medium datasets (100-1000 samples, 50-200 taxa):

lambda.min.ratio = 1e-3
nlambda = 50-100
rep.num = 50-100
Use parallel processing (Unix-like systems only)

For large datasets (> 1000 samples, > 200 taxa):

lambda.min.ratio = 1e-4
nlambda = 100+
rep.num = 100+
Use B-StARS method
Consider batch processing

Windows-specific recommendations:

Use ncores=1 for serial processing
Use snow cluster for parallel processing
Consider batch mode for large datasets
Use B-StARS method to reduce computational time

Session info:

sessionInfo()
# R version 4.5.3 (2026-03-11)
# Platform: x86_64-pc-linux-gnu
# Running under: Ubuntu 24.04.4 LTS
# 
# Matrix products: default
# BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
# LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
# 
# locale:
#  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
# [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
# 
# time zone: Etc/UTC
# tzcode source: system (glibc)
# 
# attached base packages:
# [1] stats     graphics  grDevices utils     datasets  methods   base     
# 
# other attached packages:
# [1] igraph_2.2.2     Matrix_1.7-5     phyloseq_1.55.2  SpiecEasi_1.99.5
# [5] BiocStyle_2.39.0
# 
# loaded via a namespace (and not attached):
#  [1] gtable_0.3.6        shape_1.4.6.1       xfun_0.57          
#  [4] bslib_0.10.0        ggplot2_4.0.2       Biobase_2.71.0     
#  [7] lattice_0.22-9      vctrs_0.7.2         tools_4.5.3        
# [10] generics_0.1.4      biomformat_1.39.16  stats4_4.5.3       
# [13] parallel_4.5.3      cluster_2.1.8.2     pkgconfig_2.0.3    
# [16] huge_1.5.1          data.table_1.18.2.1 RColorBrewer_1.1-3 
# [19] S7_0.2.1            S4Vectors_0.49.1    lifecycle_1.0.5    
# [22] compiler_4.5.3      farver_2.1.2        stringr_1.6.0      
# [25] Biostrings_2.79.5   Seqinfo_1.1.0       codetools_0.2-20   
# [28] permute_0.9-10      htmltools_0.5.9     sys_3.4.3          
# [31] buildtools_1.0.0    sass_0.4.10         yaml_2.3.12        
# [34] glmnet_4.1-10       crayon_1.5.3        jquerylib_0.1.4    
# [37] MASS_7.3-65         cachem_1.1.0        vegan_2.7-3        
# [40] iterators_1.0.14    foreach_1.5.2       nlme_3.1-169       
# [43] digest_0.6.39       stringi_1.8.7       reshape2_1.4.5     
# [46] labeling_0.4.3      maketools_1.3.2     splines_4.5.3      
# [49] ade4_1.7-24         fastmap_1.2.0       grid_4.5.3         
# [52] cli_3.6.5           magrittr_2.0.5      survival_3.8-6     
# [55] ape_5.8-1           withr_3.0.2         scales_1.4.0       
# [58] rmarkdown_2.31      XVector_0.51.0      multtest_2.67.0    
# [61] pulsar_0.3.13       VGAM_1.1-14         evaluate_1.0.5     
# [64] knitr_1.51          IRanges_2.45.0      mgcv_1.9-4         
# [67] rlang_1.1.7         Rcpp_1.1.1          glue_1.8.0         
# [70] BiocManager_1.30.27 BiocGenerics_0.57.0 jsonlite_2.0.0     
# [73] R6_2.6.1            plyr_1.8.9

- Troubleshooting