Skip to content

Commit d98af08

Browse files
robinschmidrobinschmid
authored
Merge pull request #295 from SteffenHeu/preferences
add preferences documentation
2 parents edc99b7 + 0947241 commit d98af08

5 files changed

Lines changed: 222 additions & 3 deletions

File tree

‎docs/getting_started.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,8 @@ Before starting your first project, configure a few key settings:
7373

7474
![Settings](getting_started_set_parameters.png)
7575

76+
See [mzmine preferences](preferences.md) for the full list of global settings.
77+
7678
!!! warning "Project compatibility"
7779
mzmine 2 and mzmine 3 project files and batch files **cannot** be imported due to fundamental
7880
changes in data structure and parameter formats. Start a new project in mzmine 4.

‎docs/img/preferences/agilent-centroiding-options.jpg‎

30.7 KB
Loading

‎docs/performance.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,9 @@ Most processing steps in mzmine create new feature lists and have options to han
4343

4444
## Preferences
4545

46-
The preferences can be changed in mzmine's graphical user interface by accessing _File/Set
47-
preferences_ from the menu. The choices will be stored in a (hidden) _.mzmine3.conf_ file in the
48-
user's home directory (Windows: _C:\Users\USERNAME_) once mzmine is closed.
46+
The preferences can be changed in mzmine's graphical user interface by accessing _Project/Set
47+
preferences_ from the menu. The choices are stored in the user's mzmine configuration file
48+
(`.mzmine/.mzconfig`) once mzmine is closed. See [mzmine preferences](preferences.md) for the full list.
4949

5050
![Preferences](img/menu_pref.png){: style="width:200px"}
5151

‎docs/preferences.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# mzmine preferences
2+
3+
:material-menu-open: **Project -> Set preferences**
4+
5+
The mzmine preferences control global behavior such as memory handling, number formats, chart
6+
appearance, and vendor data import defaults. They apply to newly opened dialogs, newly imported raw
7+
data files, and newly created plots or feature lists, depending on the setting.
8+
9+
Preferences are saved in the user configuration file (`.mzmine/.mzconfig` in the user's home
10+
directory). You can also save or load a configuration file from **Project -> Save configuration** or
11+
**Project -> Load configuration**. For command-line and batch processing, a specific `.mzconfig`
12+
file can be loaded with the `-p` / `-pref` option, while command-line options such as `--temp`,
13+
`--memory`, and thread settings can override the loaded preferences for that run.
14+
15+
!!! tip "First settings to check"
16+
17+
For most installations, first set the **Temporary file directory** to a fast local SSD and keep
18+
**Keep in memory** at **NONE** unless your system has enough RAM for the complete workflow.
19+
20+
## Preference groups
21+
22+
The dialog is organized into four groups:
23+
24+
| Group | What it controls |
25+
|----------------|----------------------------------------------------------------------------------------------------------------------|
26+
| General | Parallel tasks, memory mapping, temporary files, IMS storage strategy, and proxy settings |
27+
| Formats | Display formats for m/z, retention time, mobility, CCS, intensity, scores, ppm, percent values, and unit labels |
28+
| Visuals | Tab labels, chart colors, paint scales, chart theme defaults, application theme, image display, and precursor labels |
29+
| MS data import | Default vendor import and centroiding behavior for drag-and-drop import, the mzwizard, and raw data import dialogs |
30+
31+
## General
32+
33+
### Number of concurrently running tasks
34+
35+
Controls how many mzmine tasks may run in parallel. The default is automatic and uses the available
36+
processor count. Lower this value when you want to leave CPU resources for other applications or for
37+
other jobs on a shared workstation.
38+
39+
### Keep in memory
40+
41+
Controls which data objects stay in RAM instead of being memory mapped to temporary files. The
42+
default is **NONE**, which memory maps spectral data and feature data to the temporary directory.
43+
This is usually the best setting for large projects because it keeps RAM usage predictable.
44+
45+
Available options are:
46+
47+
| Option | Effect |
48+
|---------------------|-------------------------------------------------------------------------------------------------|
49+
| NONE | Memory map spectral data, mass lists, and feature data to temporary files. This is the default. |
50+
| ALL | Keep all supported data in RAM. Use only when memory is not a constraint. |
51+
| FEATURES | Keep feature data in RAM. |
52+
| MASS_LISTS | Keep centroid mass lists in RAM. |
53+
| RAW_SCANS | Keep raw spectral data in RAM. |
54+
| MASSES_AND_FEATURES | Keep centroid mass lists and feature data in RAM while memory mapping raw scans. |
55+
56+
The command-line `--memory` option overrides this preference for a command-line run.
57+
58+
### Optimize IMS processing
59+
60+
Controls how ion mobility feature data is stored. **Memory efficiency** is the default and stores
61+
references to individual mobilograms in temporary files. **Speed** keeps those references in RAM.
62+
Changes affect feature lists created after the preference is changed.
63+
64+
### Temporary file directory
65+
66+
mzmine uses temporary files for memory-mapped spectra, mass lists, and feature data. Choose a fast
67+
local SSD with enough free space. Avoid slow network drives and removable drives when possible.
68+
69+
Restart mzmine after changing this directory so all new project data uses the intended location. The
70+
command-line `--temp` option overrides this preference for a command-line run.
71+
72+
### Free memory in batch (experimental)
73+
74+
Runs garbage collection after each batch step. This can reclaim memory sooner, but may slightly
75+
reduce throughput. Keep it disabled unless a specific batch workflow benefits from it.
76+
77+
### Fast temp files cleanup
78+
79+
Deletes temporary files as soon as mzmine no longer needs them. This is enabled by default.
80+
81+
### Proxy
82+
83+
Configures proxy settings for internet access, including downloads, online services, and other
84+
network calls from mzmine.
85+
86+
## Formats
87+
88+
The format preferences control how values are displayed in the graphical interface. They do not
89+
change raw data, feature detection, or calculations.
90+
91+
| Preference | Default display pattern | Used for |
92+
|-----------------------------|------------------------:|----------------------------------------------------|
93+
| m/z value format | `0.0000` | m/z values |
94+
| Retention time value format | `0.00` | Retention times |
95+
| Mobility value format | `0.000` | Ion mobility values |
96+
| CCS value format | `0.0` | Collision cross section values |
97+
| Intensity format | `0.0E0` | Intensities |
98+
| PPM format | `0.0` | ppm mass errors |
99+
| Score format | `0.000` | Scores such as correlations or cosine similarities |
100+
| Percent format | `0.0%` | Percent values |
101+
| Unit format | DIVIDE | How units are written in labels |
102+
103+
## Visuals
104+
105+
### Show tab sub titles
106+
107+
Shows the related raw data file or feature list name in tab headers. This is enabled by default.
108+
109+
### Default color palette and default paint scale
110+
111+
Set the default colors used for charts and the default paint scale used for heat maps and image-like
112+
views.
113+
114+
### Chart parameters
115+
116+
Defines chart-wide defaults such as fonts, background color, axis style, and item label styling.
117+
118+
### Theme style and theme colors
119+
120+
The application theme is assembled from a structural **Theme style** and a **Theme colors** palette.
121+
The default style is **Classic (JabRef)** and the default colors are **Light**. Dark themes are
122+
available, and mzmine can offer to adjust chart colors when switching between light and dark themes
123+
if the existing chart colors would be hard to read.
124+
125+
### Presentation mode
126+
127+
Increases the main interface font size for presentations or high-DPI display situations. Chart fonts
128+
are still controlled by **Chart parameters**.
129+
130+
### Show precursor windows
131+
132+
Shows precursor isolation windows instead of only the precursor m/z where mzmine has the isolation
133+
window information.
134+
135+
### Image paint scale transformation and image normalization
136+
137+
Control newly generated MS imaging plots. Image normalization defaults to **No normalization**;
138+
**Average TIC normalization** normalizes displayed image traces to the average total ion current.
139+
The paint scale transformation defaults to a linear scale.
140+
141+
## MS data import
142+
143+
These preferences are copied into vendor import parameters used by drag-and-drop import, the
144+
mzwizard, and import dialogs. Some dialogs expose the same options for a single import; changing a
145+
single import dialog does not permanently change the global preferences.
146+
147+
### Apply vendor centroiding (recommended)
148+
149+
Enabled by default. When enabled, mzmine asks supported vendor readers or converters to centroid raw
150+
data during import. Vendor-specific centroiding usually gives better results than applying a generic
151+
centroiding method later. When disabled, supported vendor data is imported as profile data where the
152+
reader can provide it.
153+
154+
### Waters MassLynx data import
155+
156+
Controls how Waters MassLynx files are imported. The default is **Native (mzmine as vendor
157+
centroiding, recommended)**. **MSConvert** can convert to mzML first and allows converted files to
158+
be
159+
kept for faster re-import, but it does not centroid IMS data during conversion. **Native (Waters
160+
vendor centroiding)** uses Waters centroiding, which can be slow for IMS data.
161+
162+
### Agilent .d data import
163+
164+
Controls whether Agilent `.d` data files are imported through the native AgilentReader or through
165+
MSConvert. The default is **Native (AgilentReader, auto-centroid IMS)** with **Prefer stored
166+
centroids** as the centroid source.
167+
168+
| Option | Use when |
169+
|-------------------------------------------|-------------------------------------------------------------------------------------------------------------|
170+
| Native (AgilentReader) | Native Agilent import on Windows, mobility scans are imported as profile. |
171+
| Native (AgilentReader, auto-centroid IMS) | Same as Native Agilent, but uses mzmine algorithms to automatically centroid mobility scans. (if requested) |
172+
| MSConvert | You want Agilent `.d` files converted to mzML first. This path is Windows-only. |
173+
174+
When [Apply vendor centroiding](#apply-vendor-centroiding-recommended) is enabled, the embedded
175+
centroid source decides how the native
176+
AgilentReader obtains centroid spectra:
177+
178+
| Centroid source | Effect |
179+
|-------------------------|------------------------------------------------------------------------------------------------------------------------------|
180+
| Prefer stored centroids | Uses vendor-stored centroids when present; recentroids the profile only when stored centroids are unavailable. |
181+
| Prefer recentroided | Reads the profile data and recomputes centroids; falls back to stored centroids when no profile representation is available. |
182+
183+
![Agilent profile, recentroided, and stored centroid comparison](img/preferences/agilent-centroiding-options.jpg)
184+
185+
In the comparison above, black shows the profile spectrum with dots indicating the mzmine-computed
186+
centroids. Yellow shows centroids recomputed from
187+
the profile (**prefer recentroided**), and blue shows the **stored** vendor centroids. Stored
188+
centroids and recentroided peaks can
189+
differ in m/z position and intensity, so choose one strategy and keep it consistent across a study.
190+
191+
### Apply lockmass on import (Waters)
192+
193+
Enabled by default for native Waters import. The default lock masses are 556.276575 for positive
194+
mode and 554.262022 for negative mode.
195+
196+
### MSConvert path
197+
198+
Sets the MSConvert executable location used for automatic conversion of supported vendor formats to
199+
mzML during import.
200+
201+
### Keep files converted by MSConvert
202+
203+
Stores mzML files generated by MSConvert. This can make repeated imports faster, but requires more
204+
disk space.
205+
206+
### Thermo raw file parser location
207+
208+
Optionally overrides mzmine's internal Thermo raw file parser location. On macOS, an external parser
209+
and Mono may be required.
210+
211+
### Remove calibrant signals (Thermo)
212+
213+
Enabled by default. Removes internal Thermo Orbitrap calibration signals from MS1 and MS2 spectra
214+
during import. For MS3 and higher, use the **Scan signal removal** module.
215+
216+
{{ git_page_authors }}

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ nav:
1919
- Processing wizard: wizard.md
2020
- Data conversion: data_conversion.md
2121
- Sample metadata: module_docs/project_metadata/project_metadata.md
22+
- Preferences: preferences.md
2223
- Performance & Benchmarking:
2324
- Performance options: performance.md
2425
- Benchmarking: performance/benchmarking.md

0 commit comments

Comments
 (0)