User FAQ

TOPP

• How to disable the OpenMS update check.
  Starting with OpenMS 2.1 all TOPP tools will check for updated versions of the tools online and will print an information message if a newer version is available. This version check occurs only once per day and tool. Information on which tools are executed will be collected anonymously to identify which tools are no longer used and to optimally distribute development resources. If the feature causes problems or concerns, it can be disabled by setting the environment variable 'OPENMS_DISABLE_UPDATE_CHECK' to "ON".

• How can I change the temporary directory that OpenMS uses?
  By default OpenMS will use the system wide temporary directory (defined either by TMPDIR, TEMP or the TMP environmental variable, depending on your Operating System). You can override this by setting the environmental variable OPENMS_TMPDIR, or the temp_dir entry of OpenMS.ini (see the next question).

• Do I need an OpenMS.ini file, and where does OpenMS look for it?
  You do not need one. OpenMS.ini is optional and OpenMS never creates or changes it; without it, the built-in defaults are used. A file you write yourself only needs the entries you want to change:

  • temp_dir: the directory for temporary files. The environment variable OPENMS_TMPDIR takes precedence.
  • home_dir: the user data directory (shown as "Userdata path" by OpenMSInfo), for example the default output directory of TOPPAS. The environment variable OPENMS_HOME_PATH takes precedence.
  • id_db_dir: directories in which TOPP tools look for a protein database (FASTA file) that was given by a relative name and does not exist as given.

  Example:

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <PARAMETERS version="1.8.0">
    <ITEM name="temp_dir" value="/scratch/openms_tmp" type="string" />
    <ITEMLIST name="id_db_dir" type="string">
      <LISTITEM value="/data/fasta"/>
    </ITEMLIST>
  </PARAMETERS>

  On Linux, OpenMS reads $XDG_CONFIG_HOME/OpenMS/OpenMS.ini, or ~/.config/OpenMS/OpenMS.ini if XDG_CONFIG_HOME is not set. On macOS and Windows, it reads ~/.OpenMS/OpenMS.ini. Here ~ is your home directory, or the directory in OPENMS_HOME_PATH if that is set. If the file is empty or not valid XML, TOPP tools stop with an error that names it; fix or delete the file.

• Which environment variables does OpenMS read?
  None of them is needed for a normal installation.

  • OPENMS_DATA_PATH: the OpenMS shared-data directory (share/OpenMS), if OpenMS cannot find it by itself.
  • OPENMS_HOME_PATH: the directory used instead of your home directory, e.g. for OpenMS.ini (see above).
  • OPENMS_TMPDIR: the directory for temporary files (see above).
  • OPENMS_DISABLE_UPDATE_CHECK: set to "ON" to turn off the update check (see above).
  • OPENMS_BRUKER_SDK_PATH: the path of Bruker's SDK library (timsdata.dll or libtimsdata.so), to convert the ion mobility of Bruker .d input with Bruker's own code. It is not needed to read .d input.
  • OPENMS_THERMO_MANAGED_DIR: a folder with the managed assemblies of the Thermo reader, used instead of the copy in the shared-data directory. A folder without them is reported and ignored.
  • OPENMS_TOOL_REGISTRY_PATH: an additional directory with *.tsv files that register TOPP tools built outside OpenMS. OPENMS_TTD_INTERNAL_PATH, its name in earlier releases, is still read.
  • MSFRAGGER_PATH, NOVOR_PATH: the MSFragger and Novor executables, which OpenMS does not ship. MSFraggerAdapter and NovorAdapter use them when -executable is empty.

  For developers, OPENMS_DUMP_CORE makes an uncaught exception end the process with a core dump.

• Calling msConvert (of ProteoWizard) results in small mzML files with no peak data.
  The Thermo interface expects an English locale setting. Otherwise it will silently forget to return peak data. Set your locale to English and it should work.

• Some TOPP tools always crashes when executed. Other TOPP tools work properly.
  If a error message similar to

  OpenMS::File::find(...) of File.cpp error message: the file 'CHEMISTRY/unimod.xml' could not be found 

  is shown, you have probably moved your OpenMS installation manually?! Then the TOPP tools cannot find some required data files anymore, e.g. XML schema files or chemical isotope data.

  To fix, set the environment variable OPENMS_DATA_PATH to your <OpenMS>/share/OpenMS/ folder.

• A TOPP tool crashes when loading a certain input file. Other files work properly.
  If an XML input file is used, please check if the file is valid.

  For most XML data formats, this can be done using the FileInfo tool. Here is how to invoke it on the commandline:

  FileInfo -v -in <file>

  You can also check for corrupt data in peak files:

  FileInfo -c -in <file>

  You can, of course, also run it via your workflow system of choice.