Package 'RuSirius'

Description

This function to set up the parameter for de novo structure annotation using the MSNovelist tool.

MSNovelist generates molecular structures de novo from MS/MS data - without relying on any database. This makes it particularly useful for analyzing poorly represented analyte classes and novel compounds, where traditional database searches may fall short. However, it is not intended to replace database searches altogether, as structural elucidation of small molecules from MS/MS data remains a challenging task, and identifying a structure without database candidates is even more difficult.

Usage

deNovoStructureParam(numberOfCandidateToPredict = 10)

Arguments

Value

An object of class deNovoStructureParam.

Note

For more information, see the Sirius documentation.

References

Stravs MA, Dührkop K, Böcker S, Zamboni N (2022). MSNovelist: de novo structure generation from mass spectra. Nature Methods, 19, 865-870. doi:10.1038/s41592-022-01486-3

Examples

# Example of setting up the parameters for de novo structure annotation
param <- deNovoStructureParam(numberOfCandidateToPredict = 10)

Description

This function configures the parameters for molecular formula annotation in Sirius. Molecular formula identification is done using isotope pattern analysis on the MS1 data as well as fragmentation tree computation on the MS2 data. The score of a molecular formula candidate is a combination of the isotope pattern score and the fragmentation tree score.

Usage

formulaIdParam(
  instrument = c("QTOF", "ORBITRAP", "FTICR"),
  numberOfCandidates = 10,
  numberOfCandidatesPerIonization = 1,
  massAccuracyMS2ppm = 10,
  isotopeMs2Settings = c("IGNORE", "FILTER", "SCORE"),
  filterByIsotopePattern = TRUE,
  enforceElGordoFormula = TRUE,
  performBottomUpSearch = TRUE,
  performDeNovoBelowMz = 400,
  formulaSearchDBs = character(0),
  applyFormulaConstraintsToDBAndBottomUpSearch = FALSE,
  enforcedFormulaConstraints = c("H", "C", "N", "O", "P"),
  fallbackFormulaConstraints = c("S"),
  detectableElements = c("B", "S", "Cl", "Se", "Br"),
  ilpTimeout = FALSE,
  numberOfSecondsPerDecomposition = 0,
  numberOfSecondsPerInstance = 0,
  useHeuristic = TRUE,
  useHeuristicAboveMz = 300,
  useOnlyHeuristicAboveMz = 650,
  injectSpecLibMatchFormulas = TRUE,
  minScoreToInjectSpecLibMatch = 0.7,
  minPeaksToInjectSpecLibMatch = 6,
  candidateFormulas = character(0)
)

Arguments

   - `"FILTER"`: Excludes formulas if the theoretical isotope pattern
     doesn't match.
   - `"SCORE"`: Uses isotope patterns for scoring, useful for clear
     MS/MS isotope patterns.
   - `"IGNORE"`: Ignores isotope patterns in MS/MS.

Value

An object of class formulaIdParam with the specified parameters.

General parameters

We advise to set up these following parameter to fit your specific study.

Advanced parameters

If you want to specify these parameters we advise you read the Sirius documentation to learn how to adapt them to your dataset and annotation needs.

Note

For more information, see the Sirius documentation.

References

Dührkop K, Fleischauer M, Ludwig M, et al. (2019). SIRIUS 4: a rapid tool for turning tandem mass spectra into metabolite structure information. Nature Methods, 16, 299-302. doi:10.1038/s41592-019-0344-8

Examples

# Example of creating a formulaIdParam object
param <- formulaIdParam(instrument = "QTOF",
                        numberOfCandidates = 5,
                        enforceElGordoFormula = TRUE)

# Restrict formula identification to a known molecular formula
param_known <- formulaIdParam(candidateFormulas = "C10H12N2O")

Description

Import Data into Sirius

Usage

import(
  sirius,
  spectra,
  ms_column_name = character(),
  adducts = character(),
  chunkSize = 500,
  deleteExistingFeatures = TRUE
)

Arguments

Value

A Sirius object with the imported features and updated feature map.

Description

This function creates an object of class predictParam that can be used to predict molecular fingerprints and compound identifications using CSI:FingerID and CANOPUS.

CSI:FIngerID identifies the structure of a molecule by predicting its molecular fingerprint and using this fingerprint to search in a molecular structure database.

CANOPUS (Dührkop et al.) predicts the presense/absense of more than 2500 compound classes. CANOPUS predicts these classes based solely on MS/MS data and without requiring database information. This means it can identify a class even if no molecular structure of that class exists in the molecular structure database.

Usage

predictParam(useScoreThreshold = TRUE, alwaysPredictHighRefMatches = FALSE)

Arguments

Value

An object of class predictParam with the specified parameters.

Note

For more information, see the Sirius documentation.

References

Dührkop K, Shen H, Meusel M, et al. (2015). Searching molecular structure databases with tandem mass spectra using CSI:FingerID. Proceedings of the National Academy of Sciences, 112, 12580-12585. doi:10.1073/pnas.1509788112

Dührkop K, Nothias L-F, Fleischauer M, et al. (2021). Systematic classification of unknown metabolites using high-resolution fragmentation mass spectra. Nature Biotechnology, 39, 462-471. doi:10.1038/s41587-020-0740-8

Examples

# Example of setting up the parameters for the prediction of molecular
# fingerprints and compound class
param <- predictParam()

Description

Functions to retrieve results from the Sirius project, allowing customization of the result type, feature selection, and return format.

Get best match results for a Sirius project. Choose which type of results to fetch with the result.type parameter. "structure" and "deNovo" will both also give information on the formula.

Usage

## S4 method for signature 'Sirius'
summary(
  object,
  result.type = c("formulaId", "structure", "deNovo", "spectralDbMatch"),
  ...
)

results(
  sirius,
  features = character(),
  result.type = c("formulaId", "structureDb", "compoundClass", "deNovo",
    "spectralDbMatch", "fragTree"),
  return.type = c("list", "data.frame"),
  topFormula = 5,
  topStructure = 5,
  topSpectralMatches = 5
)

Arguments

Value

A data.frame or list of results, depending on return.type.

A data.frame with the summary of the results. Important column is the ApproximateConfidence column, which gives a score of how possible all the identifications for this feature are. The exactConfidence column is a score of how possible the top identification is.

Description

This function configures the job submission to Sirius. It creates an object of class config that can be used to submit a job Sirius, it can also be saved and reused later on through the saveJobConfig()function. For example on how to use, see the vignette.

Depending on what task you want to perform, you can specify the following parameters:

• spectraMatchingParam: Allows to perform matching betweeen spectra input to spectral libraries.

• formulaIdParam: Allows to generate molecular formula candidates for each features.

• zodiacParam: Allows to perform re-ranking of formula candidates using Zodiac. It is advised to only perform it if De Novo structure annotation is run later.

• predictParam: Allows to perform molecular fingeprint prediction using CSI:FingerID and compound classification using CANOPUS.

• structureDbSearchParam: Allows to perform structure annotation based on the fingerprint identifications.

• deNovoStructureParam: Allows to perform de novo structure generation using the MSNovelist tool.

Usage

run(
  sirius,
  compoundsIds = character(),
  alignedFeaturesIds = featuresId(sirius),
  fallbackAdducts = c("[M + H]+", "[M - H]-", "[M + Na]+", "[M + K]+"),
  enforceAdducts = character(),
  detectableAdducts = c("[M + H3N + H]+", "[M - H4O2 + H]+", "[M - H2O - H]-",
    "[M - H3N - H]-", "[M + Cl]-", "[2M + K]+", "[M + K]+", "[2M + Cl]-",
    "[M + C2H4O2 - H]-", "[M + H]+", "[2M + H]+", "[M - CH3 - H]-", "[M - H]-",
    "[M + Na]+", "[M - H2O + H]+"),
  spectraSearchParams = NA,
  formulaIdParams = NA,
  zodiacParams = NA,
  predictParams = NA,
  structureDbSearchParams = NA,
  msNovelistParams = NA,
  recompute = FALSE,
  configFile = character(),
  wait = TRUE
)

config(
  compoundsIds = character(),
  alignedFeaturesIds = character(),
  fallbackAdducts = c("[M + H]+", "[M - H]-", "[M + Na]+", "[M + K]+"),
  enforceAdducts = character(),
  detectableAdducts = c("[M + H3N + H]+", "[M - H4O2 + H]+", "[M - H2O - H]-",
    "[M - H3N - H]-", "[M + Cl]-", "[2M + K]+", "[M + K]+", "[2M + Cl]-",
    "[M + C2H4O2 - H]-", "[M + H]+", "[2M + H]+", "[M - CH3 - H]-", "[M - H]-",
    "[M + Na]+", "[M - H2O + H]+"),
  formulaIdParams = formulaIdParam(),
  zodiacParams = NA,
  predictParams = NA,
  structureDbSearchParams = NA,
  msNovelistParams = NA,
  spectraSearchParams = NA,
  recompute = FALSE
)

Arguments

Value

The job ID of the submitted job, it can be inputted in the jobInfo() function to retrieve the job information. To retrieve results see results documentation.

Only formula identification

If you only want to perform formula identification, you can by only inputing the formulaIdParam object. In combination, you can also input the spectraMatchingParam object to perform spectral matching and subsequently compare the results.

Known molecular formula

If you already know the molecular formula for a compound, you can restrict SIRIUS to only consider that formula using the candidateFormulas parameter of formulaIdParam. This skips the de novo formula generation and instead computes the fragmentation tree for the specified formula(s) directly. Use the enforceAdducts parameter of run() to also fix the adduct type.

Structure annotation

To performe structure annotation, you need input the formulaIdParam object, as well as the predictParam object to perform molecular fingerprint prediction and compound classification. These results will then subsequently be used to perform structure annotation using the structureDbSearchParam object.

De Novo structure annotation

To perform de novo structure annotation, you need to input the formulaIdParam object, it is also advised in this case to perform re-ranking using the zodiacParam object. The molecular fingerprint prediction and compound classification can be performed using the predictParam object. The deNovoStructureParam object is then used to perform the de novo structure annotation.

Description

Creates a Sirius instance and checks that connection to the server is valid. returns the Api and SDK within its slots. Main object that the user will interact with to connect to the Sirius server and perform operations.

Creates a Sirius object and checks that the connection to the Sirius server is valid. If the Sirius server is not running, the function will attempt to start it using the provided path to the executable. If the connection is not valid, the function will attempt to log in using the provided credentials. If the connection is still not valid, the function will stop with an error message.

Usage

Sirius(
  username = character(),
  password = character(),
  projectId = character(),
  path = character(),
  port = integer(),
  path_to_sirius = character(),
  verbose = FALSE
)

## S4 method for signature 'Sirius'
show(object)

Arguments

Value

Sirius object with the Sirius api connected.

Slots

api

ANY, the api object to use for the connection

sdk

ANY, the sdk object to use for the connection

projectId

character, the project id to use for the connection

featureMap

data.frame, the feature map to use for the connection

Author(s)

Philippine Louail (+people that worked on the API)

Description

This set of functions provides tools for managing databases in Sirius. These include listing available databases, retrieving database information, deleting databases, and creating new databases from files.

List the databases that are searchable by Sirius for spectral matching.

Retrieve detailed information about a specific database.

Delete a database from Sirius.

Create a new database in Sirius from specified files.

Usage

listDbs(sirius)

infoDb(sirius, databaseId = character())

removeDb(sirius, databaseId = character())

createDb(
  sirius,
  databaseId = character(),
  files = character(),
  location = getwd()
)

Arguments

Value

A data.frame containing details of searchable databases.

A list containing details of the specified database.

A logical(1) indicating whether the database was successfully removed.

A list containing details of the created database.

Description

This function is to set up the parameter for matching to spectra databases. This needs to be run first. Spectral library matching is performed using the cosine score with squared peak intensities, ignoring the precursor peak.

Note that spectral library matches are added as annotations to CSI:FingerID results and do not influence the ranking of structure candidates.

Usage

spectraMatchingParam(
  spectraSearchDBs = c("BIO", "massbank"),
  peakDeviationPpm = 10,
  precursorDeviationPpm = 10,
  scoring = c("MODIFIED_COSINE", "INTENSITY", "GAUSSIAN")
)

Arguments

Value

An object of class spectraMatchingParam

Note

For more information, see the Sirius documentation.

Examples

# Example of setting up the parameters for spectra matching
param <- spectraMatchingParam(spectraSearchDBs = c("BIO", "massbank"),
                              peakDeviationPpm = 10,
                              precursorDeviationPpm = 10,
                              scoring = "MODIFIED_COSINE")

Description

This function creates an object of class structureDbSearchParam that can be used to configure the structure database search in Sirius. The object can be passed to the runSirius function to perform the structure database search.

By default, SIRIUS searches for molecular structures in a biomolecule structure database. It can also search in the (extremely large) PubChem database or in custom “suspect databases” provided by the user.

Usage

structureDbSearchParam(
  structureSearchDbs = c("BIO", "massbank"),
  tagStructuresWithLipidClass = TRUE,
  expansiveSearchConfidenceMode = c("APPROXIMATE", "EXACT", "OFF")
)

Arguments

Value

An object of class structureDbSearchParam.

Note

For more information, see the Sirius documentation.

References

Dührkop K, Shen H, Meusel M, et al. (2015). Searching molecular structure databases with tandem mass spectra using CSI:FingerID. Proceedings of the National Academy of Sciences, 112, 12580-12585. doi:10.1073/pnas.1509788112

Examples

# Example of setting up the parameters for structure database search
param <- structureDbSearchParam(
                 structureSearchDbs = c("BIO", "massbank"),
                 tagStructuresWithLipidClass = TRUE,
                 expansiveSearchConfidenceMode = "APPROXIMATE")

Description

returns TRUE if the connection to the Sirius is valid, FALSE otherwise.

Usage

logIn(sirius, username, password)

checkConnection(sirius)

shutdown(sirius, closeProject = TRUE)

openGUI(sirius)

closeGUI(sirius, closeProject = FALSE)

projectInfo(sirius, infoType = c("compatibilityInfo", "sizeInformation"))

listOpenProjects(sirius)

openProject(sirius, projectId, path = character())

featuresId(sirius, type = c("sirius", "xcms"))

featuresInfo(sirius)

deleteFeatures(sirius, featureId = featuresId(sirius))

mapFeatures(sirius)

saveConfig(sirius, config, name)

jobInfo(sirius, jobId = character())

deleteJob(sirius, jobId = character(), all = FALSE)

Arguments

Value

A message whether the user is successfully logged in or not.

logical, TRUE if the connection is valid, FALSE otherwise.

Invisible NULL. Messages indicate shutdown status.

Invisible TRUE if successful.

Invisible TRUE if successful.

a list with the information requested.

a character vector with the open projects.

a Sirius object with the project opened.

a character vector with the features ID (empty if no features).

a data.frame with the features information.

A Sirius object with the features removed.

a data.frame with the features mapping.

nothing, will save the configuration locally.

a character vector with the job information.

nothing, will delete the job from Sirius.

Description

This function configures the parameters for the re-ranking of the previously computed molecular formula annotation in Sirius. This step is quite computationally and memory demanding, it is advised to perform it only if de novo structure annotation is used later on

ZODIAC uses the top X molecular formula candidates for each molecule from SIRIUS to build a similarity network, and uses Bayesian statistics to re-rank those candidates.

Usage

zodiacParam(
  consideredCandidatesAt300Mz = 10,
  consideredCandidatesAt800Mz = 50,
  runInTwoSteps = TRUE,
  edgeFilterThreshold = TRUE,
  thresholdFilter = 0.95,
  minLocalCandidates = 1,
  minLocalConnections = 10,
  gibbsSamplerParameters = TRUE,
  iterations = 20000,
  burnInPeriod = 2000,
  numberOfMarkovChains = 10
)

Arguments

Value

An object of class zodiacParam.

Note

For more information, see the Sirius documentation.

References

Ludwig M, Nothias L-F, Dührkop K, et al. (2020). Database-independent molecular formula annotation using Gibbs sampling through ZODIAC. Nature Machine Intelligence, 2, 629-641. doi:10.1038/s42256-020-00234-6

Examples

# Example of setting up the parameter for Zodiac re-ranking
param <- zodiacParam(consideredCandidatesAt300Mz = 10,
                     consideredCandidatesAt800Mz = 50,
                     runInTwoSteps = TRUE,
                     edgeFilterThreshold = TRUE,
                     thresholdFilter = 0.95,
                     minLocalCandidates = 1,
                     minLocalConnections = 10,
                     gibbsSamplerParameters = TRUE,
                     iterations = 20000,
                     burnInPeriod = 2000,
                     numberOfMarkovChains = 10)