tima

Lifecycle: experimental CRAN status R-CMD-check Codecov test coverage r-universe badge DOI Docker

The initial work is available at https://doi.org/10.3389/fpls.2019.01329, with many improvements made since then. The workflow is illustrated below.

Workflow

This repository contains everything needed to perform Taxonomically Informed Metabolite Annotation.

Requirements

Minimum Required Files

Here is what you minimally need:

  • Feature quantification table (.csv/.tsv) - Peak areas/heights across samples (example)
    • Must contain: feature ID, retention time, m/z, and sample intensity columns
    • Column names are customizable
  • MS/MS spectra file (.mgf) - Fragment spectra for each or some features (example)
  • Sample metadata (.csv/.tsv) - Links samples to organisms (example)
    • Optional if analyzing only a single organism

Optional Additions

  • Structure-organism pairs library - We provide LOTUS (>650k pairs) as default
  • External annotations - SIRIUS (v5/v6), GNPS-FBMN results
  • Custom spectral libraries - For in-house compound matching

Tip: All column names and file paths are customizable through the Shiny app interface or YAML/CLI parameters - no need to rename your files!

Installation

As the package is not (yet) available on CRAN, you will need to install with:

install.packages(
  "tima",
  repos = c(
    "https://taxonomicallyinformedannotation.r-universe.dev",
    "https://bioc.r-universe.dev",
    "https://cloud.r-project.org"
  )
)

Then, you should be able to install the rest with:

tima::install()

Normally, everything you need should then be installed (as tested in here). If for some reason, some packages were not installed, try to install them manually. To avoid such issues, we offer a containerized version (see Docker).

Once installed, you are ready to go through our documentation, with the major steps detailed.

In case you do not have your data ready, you can obtain some example data using:

tima::get_example_files()

Once you are done, you can open a small GUI to adapt your parameters and launch your job:

tima::run_app()

This command will open a small app in your default browser.

Docker

A container is also available, together with a small compose file. Main commands are below:

docker pull adafede/tima-r
# docker build . -t adafede/tima-r
docker run --user tima-user -v "$(pwd)/.tima/data:/home/tima-user/.tima/data" -p 3838:3838 adafede/tima-r Rscript -e "tima::run_app()"
# docker run --user tima-user -v "$(pwd)/.tima/data:/home/tima-user/.tima/data" adafede/tima-r Rscript -e "tima::tima_full()"

Main Citations

According to which steps you used, please give credit to the authors of the tools/resources used.

TIMA

General: https://doi.org/10.3389/fpls.2019.01329

⚠️ Do not forget to cite which version you used: https://doi.org/10.5281/zenodo.5797920

LOTUS

General: https://doi.org/10.7554/eLife.70780

⚠️ Do not forget to cite which version you used: https://doi.org/10.5281/zenodo.5794106

ISDB

General: https://doi.org/10.1021/acs.analchem.5b04804

⚠️ Do not forget to cite which version you used: https://doi.org/10.5281/zenodo.5607185

GNPS

General: https://doi.org/10.1038/nbt.3597

SIRIUS

General: https://doi.org/10.1038/s41592-019-0344-8

Others

Additional software credits

Package Version Citation
archive 1.1.12 Hester and Csárdi (2025)
base 4.5.2 R Core Team (2025)
BiocManager 1.30.27 Morgan and Ramos (2025)
BiocParallel 1.44.0 Wang et al. (2025)
BiocVersion 3.22.0 Morgan (2025)
docopt 0.7.2 de Jonge (2025)
DT 0.34.0 Xie et al. (2025)
fs 1.6.6 Hester, Wickham, and Csárdi (2025)
gt 1.1.0 Iannone et al. (2025)
httr2 1.2.1 Wickham (2025)
igraph 2.2.1 Csárdi and Nepusz (2006); Antonov et al. (2023); Csárdi et al. (2025)
IRanges 2.44.0 Lawrence et al. (2013)
knitr 1.50 Xie (2014); Xie (2015); Xie (2025)
logger 0.4.1 Daróczi and Wickham (2025)
MetaboCoreUtils 1.18.0 Rainer et al. (2022a)
MsBackendMgf 1.18.0 Gatto, Rainer, and Gibb (2025)
MsBackendMsp 1.14.0 Rainer et al. (2022b)
MsCoreUtils 1.21.0 Rainer et al. (2022c)
msentropy 0.1.4 Li (2023)
reticulate 1.44.1 Ushey, Allaire, and Tang (2025)
rmarkdown 2.30 Xie, Allaire, and Grolemund (2018); Xie, Dervieux, and Riederer (2020); Allaire et al. (2025)
rotl 3.1.0 Michonneau, Brown, and Winter (2016); OpenTreeOfLife et al. (2019)
shiny 1.11.1 Chang et al. (2025)
shinybusy 0.3.3 Meyer and Perrier (2024)
shinyhelper 0.3.2 Mason-Thom (2019)
shinyjs 2.1.0 Attali (2021)
shinytest2 0.4.1 Schloerke (2025)
shinyvalidate 0.1.3 Sievert, Iannone, and Cheng (2023)
shinyWidgets 0.9.0 Perrier, Meyer, and Granjon (2025)
Spectra 1.19.11 Rainer et al. (2022d)
stringi 1.8.7 Gagolewski (2022)
targets 1.11.4 Landau (2021)
testthat 3.3.0 Wickham (2011)
tidyfst 1.8.2 Huang and Zhao (2020)
tidyselect 1.2.1 Henry and Wickham (2024)
tidytable 0.11.2 Fairbanks (2024)
tidyverse 2.0.0 Wickham et al. (2019)
tima 2.12.0 Rutz et al. (2019); Rutz and Allard (2025)
visNetwork 2.1.4 Almende B.V. and Contributors and Thieurmel (2025)
withr 3.0.2 Hester et al. (2024)
yaml 2.3.10 Garbett et al. (2024)

References

Allaire, JJ, Yihui Xie, Christophe Dervieux, Jonathan McPherson, Javier Luraschi, Kevin Ushey, Aron Atkins, et al. 2025. rmarkdown: Dynamic Documents for r. https://github.com/rstudio/rmarkdown.
Almende B.V. and Contributors, and Benoit Thieurmel. 2025. visNetwork: Network Visualization Using “vis.js” Library. https://doi.org/10.32614/CRAN.package.visNetwork.
Antonov, Michael, Gábor Csárdi, Szabolcs Horvát, Kirill Müller, Tamás Nepusz, Daniel Noom, Maëlle Salmon, Vincent Traag, Brooke Foucault Welles, and Fabio Zanini. 2023. “Igraph Enables Fast and Robust Network Analysis Across Programming Languages.” arXiv Preprint arXiv:2311.10260. https://doi.org/10.48550/arXiv.2311.10260.
Attali, Dean. 2021. shinyjs: Easily Improve the User Experience of Your Shiny Apps in Seconds. https://doi.org/10.32614/CRAN.package.shinyjs.
Chang, Winston, Joe Cheng, JJ Allaire, Carson Sievert, Barret Schloerke, Yihui Xie, Jeff Allen, Jonathan McPherson, Alan Dipert, and Barbara Borges. 2025. shiny: Web Application Framework for r. https://doi.org/10.32614/CRAN.package.shiny.
Csárdi, Gábor, and Tamás Nepusz. 2006. “The Igraph Software Package for Complex Network Research.” InterJournal Complex Systems: 1695. https://igraph.org.
Csárdi, Gábor, Tamás Nepusz, Vincent Traag, Szabolcs Horvát, Fabio Zanini, Daniel Noom, Kirill Müller, David Schoch, and Maëlle Salmon. 2025. igraph: Network Analysis and Visualization in r. https://doi.org/10.5281/zenodo.7682609.
Daróczi, Gergely, and Hadley Wickham. 2025. logger: A Lightweight, Modern and Flexible Logging Utility. https://doi.org/10.32614/CRAN.package.logger.
de Jonge, Edwin. 2025. docopt: Command-Line Interface Specification Language. https://doi.org/10.32614/CRAN.package.docopt.
Fairbanks, Mark. 2024. tidytable: Tidy Interface to “data.table”. https://doi.org/10.32614/CRAN.package.tidytable.
Gagolewski, Marek. 2022. “stringi: Fast and Portable Character String Processing in R.” Journal of Statistical Software 103 (2): 1–59. https://doi.org/10.18637/jss.v103.i02.
Garbett, Shawn P, Jeremy Stephens, Kirill Simonov, Yihui Xie, Zhuoer Dong, Hadley Wickham, Jeffrey Horner, et al. 2024. yaml: Methods to Convert r Data to YAML and Back. https://doi.org/10.32614/CRAN.package.yaml.
Gatto, Laurent, Johannes Rainer, and Sebastian Gibb. 2025. MsBackendMgf: Mass Spectrometry Data Backend for Mascot Generic Format (Mgf) Files. https://doi.org/10.18129/B9.bioc.MsBackendMgf.
Henry, Lionel, and Hadley Wickham. 2024. tidyselect: Select from a Set of Strings. https://doi.org/10.32614/CRAN.package.tidyselect.
Hester, Jim, and Gábor Csárdi. 2025. archive: Multi-Format Archive and Compression Support. https://doi.org/10.32614/CRAN.package.archive.
Hester, Jim, Lionel Henry, Kirill Müller, Kevin Ushey, Hadley Wickham, and Winston Chang. 2024. withr: Run Code “With” Temporarily Modified Global State. https://doi.org/10.32614/CRAN.package.withr.
Hester, Jim, Hadley Wickham, and Gábor Csárdi. 2025. fs: Cross-Platform File System Operations Based on “libuv”. https://doi.org/10.32614/CRAN.package.fs.
Huang, Tian-Yuan, and Bin Zhao. 2020. “tidyfst: Tidy Verbs for Fast Data Manipulation.” Journal of Open Source Software 5 (52): 2388. https://doi.org/10.21105/joss.02388.
Iannone, Richard, Joe Cheng, Barret Schloerke, Ellis Hughes, Alexandra Lauer, JooYoung Seo, Ken Brevoort, and Olivier Roy. 2025. gt: Easily Create Presentation-Ready Display Tables. https://doi.org/10.32614/CRAN.package.gt.
Landau, William Michael. 2021. “The Targets r Package: A Dynamic Make-Like Function-Oriented Pipeline Toolkit for Reproducibility and High-Performance Computing.” Journal of Open Source Software 6 (57): 2959. https://doi.org/10.21105/joss.02959.
Lawrence, Michael, Wolfgang Huber, Hervé Pagès, Patrick Aboyoun, Marc Carlson, Robert Gentleman, Martin Morgan, and Vincent Carey. 2013. “Software for Computing and Annotating Genomic Ranges.” PLoS Computational Biology 9. https://doi.org/10.1371/journal.pcbi.1003118.
Li, Yuanyue. 2023. msentropy: Spectral Entropy for Mass Spectrometry Data. https://doi.org/10.32614/CRAN.package.msentropy.
Mason-Thom, Chris. 2019. shinyhelper: Easily Add Markdown Help Files to “shiny” App Elements. https://doi.org/10.32614/CRAN.package.shinyhelper.
Meyer, Fanny, and Victor Perrier. 2024. shinybusy: Busy Indicators and Notifications for “Shiny” Applications. https://doi.org/10.32614/CRAN.package.shinybusy.
Michonneau, Francois, Joseph W. Brown, and David J. Winter. 2016. “rotl: An r Package to Interact with the Open Tree of Life Data.” Methods in Ecology and Evolution 7 (12): 1476–81. https://doi.org/10.1111/2041-210X.12593.
Morgan, Martin. 2025. BiocVersion: Set the Appropriate Version of Bioconductor Packages. https://doi.org/10.18129/B9.bioc.BiocVersion.
Morgan, Martin, and Marcel Ramos. 2025. BiocManager: Access the Bioconductor Project Package Repository. https://doi.org/10.32614/CRAN.package.BiocManager.
OpenTreeOfLife, Benjamin Redelings, Luna Luisa Sanchez Reyes, Karen A. Cranston, Jim Allman, Mark T. Holder, and Emily Jane McTavish. 2019. “Open Tree of Life Synthetic Tree.” Zenodo. https://doi.org/10.5281/zenodo.3937741.
Perrier, Victor, Fanny Meyer, and David Granjon. 2025. shinyWidgets: Custom Inputs Widgets for Shiny. https://doi.org/10.32614/CRAN.package.shinyWidgets.
R Core Team. 2025. R: A Language and Environment for Statistical Computing. Vienna, Austria: R Foundation for Statistical Computing. https://www.R-project.org/.
Rainer, Johannes, Andrea Vicini, Liesa Salzer, Jan Stanstrup, Josep M. Badia, Steffen Neumann, Michael A. Stravs, et al. 2022a. “A Modular and Expandable Ecosystem for Metabolomics Data Annotation in r.” Metabolites 12: 173. https://doi.org/10.3390/metabo12020173.
———, et al. 2022b. “A Modular and Expandable Ecosystem for Metabolomics Data Annotation in r.” Metabolites 12: 173. https://doi.org/10.3390/metabo12020173.
———, et al. 2022c. “A Modular and Expandable Ecosystem for Metabolomics Data Annotation in r.” Metabolites 12: 173. https://doi.org/10.3390/metabo12020173.
———, et al. 2022d. “A Modular and Expandable Ecosystem for Metabolomics Data Annotation in r.” Metabolites 12: 173. https://doi.org/10.3390/metabo12020173.
Rutz, Adriano, and Pierre-Marie Allard. 2025. tima: Taxonomically Informed Metabolite Annotation. https://doi.org/10.5281/zenodo.5797920.
Rutz, Adriano, Miwa Dounoue-Kubo, Simon Ollivier, Jonathan Bisson, Mohsen Bagheri, Tongchai Saesong, Samad Nejad Ebrahimi, Kornkanok Ingkaninan, Jean-Luc Wolfender, and Pierre-Marie Allard. 2019. “Taxonomically Informed Scoring Enhances Confidence in Natural Products Annotation.” Frontiers in Plant Science 10. https://doi.org/10.3389/FPLS.2019.01329.
Schloerke, Barret. 2025. Shinytest2: Testing for Shiny Applications. https://doi.org/10.32614/CRAN.package.shinytest2.
Sievert, Carson, Richard Iannone, and Joe Cheng. 2023. shinyvalidate: Input Validation for Shiny Apps. https://doi.org/10.32614/CRAN.package.shinyvalidate.
Ushey, Kevin, JJ Allaire, and Yuan Tang. 2025. reticulate: Interface to “Python”. https://doi.org/10.32614/CRAN.package.reticulate.
Wang, Jiefei, Martin Morgan, Valerie Obenchain, Michel Lang, Ryan Thompson, and Nitesh Turaga. 2025. BiocParallel: Bioconductor Facilities for Parallel Evaluation. https://doi.org/10.18129/B9.bioc.BiocParallel.
Wickham, Hadley. 2011. “testthat: Get Started with Testing.” The R Journal 3: 5–10. https://journal.r-project.org/articles/RJ-2011-002/.
———. 2025. Httr2: Perform HTTP Requests and Process the Responses. https://doi.org/10.32614/CRAN.package.httr2.
Wickham, Hadley, Mara Averick, Jennifer Bryan, Winston Chang, Lucy D’Agostino McGowan, Romain François, Garrett Grolemund, et al. 2019. “Welcome to the tidyverse.” Journal of Open Source Software 4 (43): 1686. https://doi.org/10.21105/joss.01686.
Xie, Yihui. 2014. “knitr: A Comprehensive Tool for Reproducible Research in R.” In Implementing Reproducible Computational Research, edited by Victoria Stodden, Friedrich Leisch, and Roger D. Peng. Chapman; Hall/CRC.
———. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. https://yihui.org/knitr/.
———. 2025. knitr: A General-Purpose Package for Dynamic Report Generation in R. https://yihui.org/knitr/.
Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.
Xie, Yihui, Joe Cheng, Xianying Tan, and Garrick Aden-Buie. 2025. DT: A Wrapper of the JavaScript Library “DataTables”. https://doi.org/10.32614/CRAN.package.DT.
Xie, Yihui, Christophe Dervieux, and Emily Riederer. 2020. R Markdown Cookbook. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown-cookbook.