Skip to content

Commit 66c49c1

Browse files
SteffenHeuSteffenHeu
authored
Merge pull request #297 from SteffenHeu/biotransformer
add biotransformer docs
2 parents aa1b200 + a9b28ad commit 66c49c1

2 files changed

Lines changed: 211 additions & 0 deletions

File tree

‎docs/module_docs/id_biotransformer/biotransformer.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# **BioTransformer 3.0**
2+
3+
## **Description**
4+
5+
:material-menu-open: **Feature list methods -> Annotation -> Search precursor mass -> BioTransformer 3.0**
6+
7+
or, for one annotated feature row:
8+
9+
:material-menu-open: right-click a row in the feature table and choose **Identification -> Compute transformation products (BioTransformer 3)**
10+
11+
The BioTransformer 3.0 module predicts possible transformation products for compounds that are
12+
already annotated with a structure. MZmine sends the educt SMILES string to an external
13+
BioTransformer 3 `.jar`, imports the generated CSV file, calculates product ions from the selected
14+
ion library, and adds matching products as compound annotations to feature list rows.
15+
16+
Use this module after a spectral library search or compound database search has produced
17+
annotations with SMILES structures. BioTransformer 3.0 does not identify unknown educts by itself:
18+
it starts from an existing annotation, predicts transformation products, and searches for those
19+
products in the same feature list.
20+
21+
!!! warning
22+
23+
BioTransformer 3.0 is not bundled with MZmine. Download the BioTransformer `.jar` from the
24+
[BioTransformer 3.0 jar downloads](https://bitbucket.org/wishartlab/biotransformer3.0jar/downloads/)
25+
or the [BioTransformer download page](https://biotransformer.ca/download), and keep the
26+
extracted BioTransformer files together in one folder. MZmine runs the selected jar via
27+
`java -jar`, so the `java` command must be available to MZmine.
28+
29+
!!! tip
30+
31+
Start with a restrictive m/z tolerance and, when retention time behavior is expected, enable
32+
the advanced RT tolerance filter. This keeps predicted products from being assigned to unrelated
33+
features with similar m/z values.
34+
35+
## **Recommended citations**
36+
37+
!!! info
38+
39+
When using MZmine for your work, please consider citing:<br>
40+
Schmid R., Heuckeroth S., Korf A., et al. Integrative analysis of multimodal mass spectrometry
41+
data in MZmine 3, Nature Biotechnology (2023), doi:10.1038/s41587-023-01690-2.
42+
43+
When using this module, please also cite the BioTransformer publication(s):<br>
44+
Djoumbou Feunang Y., Fiamoncini J., de la Fuente A.G., Manach C., Greiner R., Wishart D.S.
45+
BioTransformer: a comprehensive computational tool for small molecule metabolism prediction and
46+
metabolite identification. Journal of Cheminformatics 11, 2 (2019).
47+
doi:10.1186/s13321-018-0324-5.
48+
49+
Wishart D.S., Tian S., Allen D., Oler E., Peters H., Lui V.W., Gautam V.,
50+
Djoumbou Feunang Y., Greiner R., Metz T.O. BioTransformer 3.0 - A Web Server for Accurately
51+
Predicting Metabolic Transformation Products.
52+
53+
---
54+
55+
## **Parameters**
56+
57+
#### **Feature lists**
58+
59+
Feature list(s) to process. Each selected feature list is processed independently.
60+
61+
#### **BioTransformer .jar path**
62+
63+
Path to the BioTransformer 3 `.jar` file. Select the jar inside the folder that contains the
64+
unpacked BioTransformer download.
65+
66+
#### **Transformation type**
67+
68+
BioTransformer prediction mode. The available modes are:
69+
70+
- **EC-based (Enzyme Commission)**
71+
- **CYP450**
72+
- **Phase II**
73+
- **Gut microbial**
74+
- **All human**
75+
- **Super bio**
76+
- **Environmental microbial** (default)
77+
78+
#### **Iterations**
79+
80+
Number of BioTransformer prediction iterations. One iteration predicts direct products of the
81+
input compound. Higher values also predict products of previous products. Default: `1`.
82+
Allowed range: `1` to `10`.
83+
84+
#### **m/z tolerance**
85+
86+
Maximum m/z difference for matching predicted product ions to feature list rows. Default:
87+
`0.003 m/z` or `5 ppm`.
88+
89+
#### **Ion library**
90+
91+
Ion types used to calculate product m/z values from the predicted neutral products. The default is
92+
the MZmine main ion library for both positive and negative polarity.
93+
94+
#### **Filter parameters** _(Optional)_
95+
96+
Additional filters for choosing educt rows and product rows. Disabled by default.
97+
98+
- **Educt must have MS/MS**: only predicts transformations for rows with an MS/MS spectrum.
99+
- **Minimum Educt intensity**: only predicts transformations for rows whose best feature height is
100+
at least the selected intensity. The embedded default value is `1E4`, but the filter is disabled
101+
until selected.
102+
- **Product must have MS/MS**: only assigns predicted products to rows with an MS/MS spectrum.
103+
- **Minimum Product intensity**: only assigns predicted products to rows whose best feature height
104+
is at least the selected intensity. The embedded default value is `1E4`, but the filter is
105+
disabled until selected.
106+
107+
#### **SMILES source**
108+
109+
Annotation source used to obtain the educt SMILES in the full feature-list workflow.
110+
111+
- **Spectral library**: use the first spectral library match with structure information.
112+
- **Compound DB**: use the first compound database annotation with structure information.
113+
- **All** (default): prefer the first spectral library match; if none is available, use the first
114+
compound database annotation.
115+
116+
This parameter is not shown in the single-row context-menu workflow. The context action uses the
117+
first spectral library match with structure information, or the first compound database annotation
118+
with structure information if no spectral library match is available.
119+
120+
#### **Advanced parameters**
121+
122+
Extra matching and annotation-ranking options.
123+
124+
- **RT tolerance filter** _(Optional)_: only assigns predicted products within the selected
125+
retention-time tolerance around the educt row. Default embedded value: `0.15 min`.
126+
- **Filter by row correlation**: only assigns predicted products to rows that are correlated with
127+
the educt row. The feature list must have been grouped by correlation, for example with the
128+
correlation grouping module.
129+
- **Re-rank annotations**: controls whether compound annotations are re-ranked by highest score
130+
after BioTransformer matches are added. Enabled by default when advanced parameters are enabled.
131+
132+
---
133+
134+
## **Algorithm** {#algorithm}
135+
136+
### Selecting educts
137+
138+
In the full feature-list workflow, MZmine scans the selected feature list and looks for rows that
139+
pass the optional educt filters and contain a usable SMILES structure. The selected annotation is:
140+
141+
1. the first spectral library match, if the SMILES source allows spectral library annotations and
142+
the match has structure information,
143+
2. otherwise the first compound database annotation, if the SMILES source allows compound database
144+
annotations and the annotation has structure information.
145+
146+
Rows without a usable structure are skipped. Identical canonical SMILES strings are predicted only
147+
once per feature list.
148+
149+
In the single-row workflow, MZmine uses the selected row's first spectral library match with a
150+
structure, or the first compound database annotation with a structure if no spectral library match
151+
is available.
152+
153+
!!! warning
154+
155+
BioTransformer is not run for educt structures whose calculated monoisotopic mass is above
156+
`1000 Da`, because the BioTransformer command-line tool cannot process those compounds.
157+
158+
### Running BioTransformer
159+
160+
For each selected educt SMILES, MZmine creates a temporary CSV file and runs BioTransformer in
161+
prediction mode:
162+
163+
```text
164+
java -jar BioTransformer3.0.jar -k pred -b <transformation type> -s <iterations> -ismi <SMILES> -ocsv <temporary CSV>
165+
```
166+
167+
The BioTransformer result CSV is imported as compound database annotations. MZmine reads the
168+
product formula, SMILES, InChI, InChIKey, reaction, enzyme information, ALogP, and metabolite ID
169+
columns when present. Product names are prefixed with the educt compound name.
170+
171+
### Matching products to the feature list
172+
173+
Imported products are ionized with the selected ion library. Each generated product ion is compared
174+
against rows in the same feature list:
175+
176+
1. m/z must match within the configured m/z tolerance.
177+
2. If the RT tolerance filter is enabled, the product must also match within the RT window around
178+
the educt row.
179+
3. If the row correlation filter is enabled, the product row must be correlated with the educt row.
180+
4. If product filters are enabled, the product row must pass the selected MS/MS and intensity
181+
filters.
182+
183+
Matching product ions are added as compound annotations. The match score and deviation columns are
184+
calculated by the compound database annotation matcher.
185+
186+
### Output columns
187+
188+
BioTransformer matches are stored as compound annotations in the feature list. Depending on the
189+
available product data and enabled filters, annotations can include:
190+
191+
| Column | Description |
192+
| --- | --- |
193+
| Compound name | BioTransformer metabolite ID prefixed by the educt name |
194+
| Molecular formula | Product molecular formula |
195+
| SMILES | Product SMILES |
196+
| InChI / InChIKey | Product structure identifiers |
197+
| Reaction | BioTransformer reaction rule |
198+
| Enzyme(s) | Enzyme or biosystem information reported by BioTransformer |
199+
| ALogP | Predicted ALogP value reported by BioTransformer |
200+
| Ion type | Product ion type from the selected ion library |
201+
| Precursor m/z | Calculated product ion m/z |
202+
| Compound annotation score | Score from matching the predicted product ion to the row |
203+
| m/z ppm difference | Mass error in ppm |
204+
| m/z absolute difference | Absolute mass difference |
205+
| RT absolute difference | RT difference, if RT filtering was enabled |
206+
| RT relative error (%) | Relative RT error, if RT filtering was enabled |
207+
208+
---
209+
210+
{{ git_page_authors }}

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ nav:
126126
# - Spectral library creation: module_docs/id_spectral_library_creation/spectral_library_creation.md
127127
- Precursor mass search:
128128
- Local database search: module_docs/id_prec_local_cmpd_db/local-cmpd-db-search.md
129+
- BioTransformer: module_docs/id_biotransformer/biotransformer.md
129130
- Precursor search in local spectral MS/MS library: module_docs/id_prec_local_spectra_lib/local-spectra-lib-search.md
130131
- Manual compound annotation: module_docs/id_addmanualcomp/manual-annotation.md
131132
- Spectra search:

0 commit comments

Comments
 (0)