library(RSirius)
library(RuSirius)
#> Warning: package 'generics' was built under R version 4.6.1
library(MsDataHub)
library(Spectra)Introduction
Note: this vignette is pre-computed. See the session info for information on packages used and the date the vignette was rendered. The vignette requires a running Sirius instance. To reproduce this analysis, you will need Sirius 6.5 installed and running.
Sirius can search against custom databases in addition to the built-in databases (BIO, PubChem, etc.). This is useful when you have:
- A list of suspect compounds specific to your study
- A custom spectral library (e.g., from MassBank)
- Target compounds you want to prioritize in the search
This vignette demonstrates how to create and use custom databases, and shows the impact on structure identification results.
Managing Databases
Listing Available Databases
srs <- Sirius(port = 9999)
# List all searchable databases
dbs <- listDbs(srs)
dbs[, c("databaseId", "displayName")]
#> databaseId displayName
#> 1 ALL All included DBs
#> 2 BIO Bio Database
#> 3 PUBCHEM PubChem
#> 4 MESH MeSH
#> 5 HMDB HMDB
#> 6 KNAPSACK KNApSAcK
#> 7 CHEBI CHEBI
#> 8 PUBMED PubMed
#> 9 KEGG KEGG
#> 10 HSDB HSDB
#> 11 MACONDA Maconda
#> 12 METACYC Biocyc
#> 13 GNPS GNPS
#> 14 TRAIN Training Set
#> 15 YMDB YMDB
#> 16 PLANTCYC Plantcyc
#> 17 NORMAN NORMAN
#> 18 SUPERNATURAL SuperNatural
#> 19 COCONUT COCONUT
#> 20 BloodExposome Blood Exposome
#> 21 TeroMol TeroMOL
#> 22 PUBCHEMANNOTATIONBIO PubChem: bio and metabolites
#> 23 PUBCHEMANNOTATIONDRUG PubChem: drug
#> 24 PUBCHEMANNOTATIONSAFETYANDTOXIC PubChem: safety and toxic
#> 25 PUBCHEMANNOTATIONFOOD PubChem: food
#> 26 LOTUS LOTUS
#> 27 FooDB FooDB
#> 28 MiMeDB MiMeDB
#> 29 LIPIDMAPS LipidMaps
#> 30 LIPID Lipid
#> 31 DSSTox DSSToxDatabase Information
# Get details about a specific database
infoDb(srs, databaseId = "BIO")
#> $databaseId
#> [1] "BIO"
#>
#> $customDb
#> [1] FALSE
#>
#> $searchable
#> [1] TRUE
#>
#> $updateNeeded
#> [1] FALSE
#>
#> $displayName
#> [1] "Bio Database"
#>
#> $matchRtOfReferenceSpectra
#> [1] FALSECreating a Custom Database
Custom databases can be created from files containing compound
information. Supported formats include .tsv,
.csv, or .mgf files with structure
information.
From a Compound List (TSV/CSV)
The file should contain columns for compound name, SMILES (or InChI), and optionally the molecular formula.
From a Spectral Library (MGF)
Spectral libraries in MGF format can also be imported. Here we download the MassBank EU library from GNPS:
# Download the MassBank EU spectral library (MGF)
mgf_file <- file.path(getwd(), "MASSBANKEU.mgf")
download.file("https://external.gnps2.org/gnpslibrary/MASSBANKEU.mgf",
destfile = mgf_file, mode = "wb")
createDb(srs,
databaseId = "massbank_custom",
files = mgf_file,
location = getwd())
#> $databaseId
#> [1] "massbank_custom"
#>
#> $customDb
#> [1] TRUE
#>
#> $searchable
#> [1] TRUE
#>
#> $dbVersion
#> [1] 3
#>
#> $updateNeeded
#> [1] FALSE
#>
#> $numberOfStructures
#> [1] 652
#>
#> $numberOfFormulas
#> [1] 581
#>
#> $numberOfReferenceSpectra
#> [1] 1304
#>
#> $displayName
#> [1] "massbank_custom"
#>
#> $location
#> [1] "C:\\Users\\phili\\AppData\\Local\\Temp\\claude\\E--GitHub-RuSirius\\1afa4ba5-deea-4f05-82c3-5cfe3d2bdc91\\scratchpad\\vig_run\\massbank_custom.siriusdb"
#>
#> $matchRtOfReferenceSpectra
#> [1] FALSEComparing Results: Default vs Custom Database
Let’s demonstrate how using a custom database affects structure identification.
Setup: Import Sample Data
# Load example data
dda_file <- MsDataHub::PestMix1_DDA.mzML()
sp <- Spectra(dda_file)
#> Warning in fun(libname, pkgname): mzR has been built against a different Rcpp version (1.1.1.9)
#> than is installed on your system (1.1.1.1.1). This might lead to errors
#> when loading mzR. If you encounter such issues, please send a report,
#> including the output of sessionInfo() to the Bioc support forum at
#> https://support.bioconductor.org/. For details see also
#> https://github.com/sneumann/mzR/wiki/mzR-Rcpp-compiler-linker-issue.
sp <- setBackend(sp, MsBackendMemory())
sp <- filterEmptySpectra(sp)
# Group spectra
idxs <- fragmentGroupIndex(sp)
sp$Msn_idx <- idxs
# Create project and import
srs <- Sirius(projectId = "db_comparison", path = getwd(), port = 9999)
sp_subset <- sp[sp$Msn_idx %in% c(421, 707)]
srs <- import(srs, spectra = sp_subset, ms_column_name = "Msn_idx")Run with Default Database (BIO)
# Run structure search with BIO database only
run(srs,
formulaIdParams = formulaIdParam(numberOfCandidates = 5),
predictParams = predictParam(),
structureDbSearchParams = structureDbSearchParam(
structureSearchDbs = c("BIO")
),
recompute = TRUE,
wait = TRUE)
#> [1] "17"
# Get results
results_bio <- summary(srs, result.type = "structure")
results_bio[, c("alignedFeatureId", "molecularFormula",
"structureName", "confidenceExactMatch")]
#> alignedFeatureId molecularFormula
#> 1 898508999391855671 C9H16N2O4
#> 2 898508999412827192 C15H20F6N2O5
#> structureName
#> 1 Malonic acid, oxo-, diethyl ester, dimethylhydrazone
#> 2 tert-butyl-(3R)-3-{[5-(2,2,2-trifluoro-1-hydroxy-1-trifluoromethyl-ethyl)-4,5-dihydro-isoxazole-3-carbonyl]-amino}-butanoate
#> confidenceExactMatch
#> 1 0.05037627
#> 2 0.06367074Run with Custom Database Added
# Now include custom database in search
run(srs,
formulaIdParams = formulaIdParam(numberOfCandidates = 5),
predictParams = predictParam(),
structureDbSearchParams = structureDbSearchParam(
structureSearchDbs = c("BIO", "massbank_custom")
),
recompute = TRUE,
wait = TRUE)
#> [1] "18"
# Get results with custom DB
results_custom <- summary(srs, result.type = "structure")
results_custom[, c("alignedFeatureId", "molecularFormula",
"structureName", "confidenceExactMatch")]
#> alignedFeatureId molecularFormula
#> 1 898508999391855671 C9H16N2O4
#> 2 898508999412827192 C15H20F6N2O5
#> structureName
#> 1 Malonic acid, oxo-, diethyl ester, dimethylhydrazone
#> 2 tert-butyl-(3R)-3-{[5-(2,2,2-trifluoro-1-hydroxy-1-trifluoromethyl-ethyl)-4,5-dihydro-isoxazole-3-carbonyl]-amino}-butanoate
#> confidenceExactMatch
#> 1 0.05037627
#> 2 0.06367074Compare Results
# Compare confidence scores
comparison <- merge(
results_bio[, c("alignedFeatureId", "confidenceExactMatch")],
results_custom[, c("alignedFeatureId", "confidenceExactMatch")],
by = "alignedFeatureId",
suffixes = c("_bio", "_custom")
)
comparison
#> alignedFeatureId confidenceExactMatch_bio confidenceExactMatch_custom
#> 1 898508999391855671 0.05037627 0.05037627
#> 2 898508999412827192 0.06367074 0.06367074Including relevant custom databases can improve identification confidence when your compounds are well-represented in the custom database.
Removing a Database
By default removeDb() only removes the database from
Sirius and keeps its file; use delete = TRUE to also delete
the file:
# Remove a custom database when no longer needed
removeDb(srs, databaseId = "massbank_custom", delete = TRUE)
#> [1] TRUE
# Verify removal
listDbs(srs)
#> databaseId customDb searchable updateNeeded
#> 1 ALL FALSE FALSE FALSE
#> 2 BIO FALSE TRUE FALSE
#> 3 PUBCHEM FALSE TRUE FALSE
#> 4 MESH FALSE TRUE FALSE
#> 5 HMDB FALSE TRUE FALSE
#> 6 KNAPSACK FALSE TRUE FALSE
#> 7 CHEBI FALSE TRUE FALSE
#> 8 PUBMED FALSE TRUE FALSE
#> 9 KEGG FALSE TRUE FALSE
#> 10 HSDB FALSE TRUE FALSE
#> 11 MACONDA FALSE TRUE FALSE
#> 12 METACYC FALSE TRUE FALSE
#> 13 GNPS FALSE TRUE FALSE
#> 14 TRAIN FALSE FALSE FALSE
#> 15 YMDB FALSE TRUE FALSE
#> 16 PLANTCYC FALSE TRUE FALSE
#> 17 NORMAN FALSE TRUE FALSE
#> 18 SUPERNATURAL FALSE TRUE FALSE
#> 19 COCONUT FALSE TRUE FALSE
#> 20 BloodExposome FALSE TRUE FALSE
#> 21 TeroMol FALSE TRUE FALSE
#> 22 PUBCHEMANNOTATIONBIO FALSE TRUE FALSE
#> 23 PUBCHEMANNOTATIONDRUG FALSE TRUE FALSE
#> 24 PUBCHEMANNOTATIONSAFETYANDTOXIC FALSE TRUE FALSE
#> 25 PUBCHEMANNOTATIONFOOD FALSE TRUE FALSE
#> 26 LOTUS FALSE TRUE FALSE
#> 27 FooDB FALSE TRUE FALSE
#> 28 MiMeDB FALSE TRUE FALSE
#> 29 LIPIDMAPS FALSE TRUE FALSE
#> 30 LIPID FALSE FALSE FALSE
#> 31 DSSTox FALSE TRUE FALSE
#> displayName matchRtOfReferenceSpectra
#> 1 All included DBs FALSE
#> 2 Bio Database FALSE
#> 3 PubChem FALSE
#> 4 MeSH FALSE
#> 5 HMDB FALSE
#> 6 KNApSAcK FALSE
#> 7 CHEBI FALSE
#> 8 PubMed FALSE
#> 9 KEGG FALSE
#> 10 HSDB FALSE
#> 11 Maconda FALSE
#> 12 Biocyc FALSE
#> 13 GNPS FALSE
#> 14 Training Set FALSE
#> 15 YMDB FALSE
#> 16 Plantcyc FALSE
#> 17 NORMAN FALSE
#> 18 SuperNatural FALSE
#> 19 COCONUT FALSE
#> 20 Blood Exposome FALSE
#> 21 TeroMOL FALSE
#> 22 PubChem: bio and metabolites FALSE
#> 23 PubChem: drug FALSE
#> 24 PubChem: safety and toxic FALSE
#> 25 PubChem: food FALSE
#> 26 LOTUS FALSE
#> 27 FooDB FALSE
#> 28 MiMeDB FALSE
#> 29 LipidMaps FALSE
#> 30 Lipid FALSE
#> 31 DSSTox FALSEBest Practices
Targeted databases: Create focused databases with compounds relevant to your study rather than very large generic databases.
Quality over quantity: Ensure your custom database has accurate structure information (SMILES/InChI).
Combine strategically: Use custom databases alongside BIO for best coverage - BIO for general metabolites, custom for your specific targets.
Spectral libraries: When available, spectral libraries (MGF) provide additional matching power through spectral similarity.
Clean Up
shutdown(srs)
#> There does not seem to be any process or process_id to shut down...Session information
The R code was run on:
date()
#> [1] "Thu Oct 15 11:54:24 2026"Information on the R session:
sessionInfo()
#> R version 4.6.0 (2026-04-24 ucrt)
#> Platform: x86_64-w64-mingw32/x64
#> Running under: Windows 11 x64 (build 26300)
#>
#> Matrix products: default
#> LAPACK version 3.12.1
#>
#> locale:
#> [1] LC_COLLATE=English_United Kingdom.utf8
#> [2] LC_CTYPE=English_United Kingdom.utf8
#> [3] LC_MONETARY=English_United Kingdom.utf8
#> [4] LC_NUMERIC=C
#> [5] LC_TIME=English_United Kingdom.utf8
#>
#> time zone: Europe/Paris
#> tzcode source: internal
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] MsDataHub_1.12.0 RuSirius_1.0.6 Spectra_1.22.2
#> [4] BiocParallel_1.46.0 S4Vectors_0.50.1 BiocGenerics_0.58.1
#> [7] generics_0.1.4 ProtGenerics_1.44.0 RSirius_6.5.4
#>
#> loaded via a namespace (and not attached):
#> [1] DBI_1.3.0 bitops_1.0-9
#> [3] MetaboAnnotation_1.16.0 gridExtra_2.3.1
#> [5] httr2_1.2.3 rlang_1.2.0
#> [7] magrittr_2.0.5 clue_0.3-68
#> [9] otel_0.2.0 matrixStats_1.5.0
#> [11] compiler_4.6.0 RSQLite_3.53.3
#> [13] png_0.1-9 vctrs_0.7.3
#> [15] reshape2_1.4.5 stringr_1.6.0
#> [17] pkgconfig_2.0.3 MetaboCoreUtils_1.20.1
#> [19] crayon_1.5.3 fastmap_1.2.0
#> [21] dbplyr_2.6.0 XVector_0.52.0
#> [23] purrr_1.2.2 bit_4.6.0
#> [25] xfun_0.59 MultiAssayExperiment_1.38.0
#> [27] cachem_1.1.0 ChemmineR_3.64.0
#> [29] jsonlite_2.0.0 blob_1.3.0
#> [31] DelayedArray_0.38.2 parallel_4.6.0
#> [33] cluster_2.1.8.2 R6_2.6.1
#> [35] stringi_1.8.7 RColorBrewer_1.1-3
#> [37] GenomicRanges_1.64.0 Rcpp_1.1.1-1.1
#> [39] Seqinfo_1.2.0 SummarizedExperiment_1.42.0
#> [41] knitr_1.51 snow_0.4-4
#> [43] base64enc_0.1-6 IRanges_2.46.0
#> [45] Matrix_1.7-5 igraph_2.3.3
#> [47] tidyselect_1.2.1 abind_1.4-8
#> [49] yaml_2.3.12 codetools_0.2-20
#> [51] curl_7.1.0 lattice_0.22-9
#> [53] tibble_3.3.1 plyr_1.8.9
#> [55] withr_3.0.3 Biobase_2.72.0
#> [57] KEGGREST_1.52.2 S7_0.2.2
#> [59] evaluate_1.0.5 BiocFileCache_3.2.0
#> [61] xml2_1.6.0 ExperimentHub_3.2.0
#> [63] Biostrings_2.80.1 pillar_1.11.1
#> [65] BiocManager_1.30.27 filelock_1.0.3
#> [67] MatrixGenerics_1.24.0 DT_0.34.0
#> [69] ncdf4_1.24 RCurl_1.98-1.19
#> [71] BiocVersion_3.23.1 ggplot2_4.0.3
#> [73] scales_1.4.0 glue_1.8.1
#> [75] lazyeval_0.2.3 tools_4.6.0
#> [77] AnnotationHub_4.2.1 data.table_1.18.4
#> [79] mzR_2.46.0 QFeatures_1.22.0
#> [81] fs_2.1.0 grid_4.6.0
#> [83] tidyr_1.3.2 MsCoreUtils_1.24.0
#> [85] AnnotationDbi_1.74.0 cli_3.6.6
#> [87] rappdirs_0.3.4 rsvg_2.7.0
#> [89] S4Arrays_1.12.0 dplyr_1.2.1
#> [91] AnnotationFilter_1.36.0 gtable_0.3.6
#> [93] digest_0.6.39 SparseArray_1.12.2
#> [95] rjson_0.2.23 htmlwidgets_1.6.4
#> [97] farver_2.1.2 memoise_2.0.1
#> [99] htmltools_0.5.9 lifecycle_1.0.5
#> [101] httr_1.4.8 CompoundDb_1.16.0
#> [103] bit64_4.8.2 MASS_7.3-65