Frequently Asked Questions


Q: MS Amanda does not work on Unix. What could be the problem?

To run MSAmanda one needs to install the Mono frameweork. Visit for proper installation instructions.

Q: MS-GF+ (or any Java based engine) fails. What could be the problem?

To run Java based engines like MS-GF+ or MSFragger, Java Runtime Environment needs to be installed. Visit for download and installation.

Q: Downloading http files is not working on OSX. Why?

Make sure that certificates are properly installed. Go to Applications/Python 3.6 and double-click Install Certificates.command. The latest version of Python3.6 for Mac should come with the right certifications for secure connections anyways.

Q: I have problems installing pyahocorasick on Windows! What can I do?

Generally, Python 3.6 should be used when working with Windows. Here are some general remarks for a flawless installation under Windows.

When using Windows 7, additionally install: Microsoft Visual C++ Build Tools,

When using Windows 10, consider additionally installing MS Build Tools 2015


Q: Found mismatch between json parameter ….

Found mismatch between json parameter csv_filter_rules:
[['PEP', 'lte', 0.01], ['Is decoy', 'equals', 'false']] and
controller params csv_filter_rules:
[('PEP', 'lte', 0.01), ('Is decoy', 'equals', 'false')].
Consider re-run with force=True or delete old u.jsons.

During JSON dump Python tuples are converted into list like objects, thus this might be a reason. Just change your parameter to lists instead of tuples :)

Q: How do I add an engine that is not installed via

Download the engine from the respective developers homepage (links are given in the wrapper documentation of the respective engine). Create a folder in the corresponding Ursgal resoucres (name of the folder = name of the engine in Ursgal, for more information see Create/Implement your own UNode: 1.Integration into Resources) and unpack/save all required files, especially the executable, there. Remember to run:

user@localhost:~/ursgal$ python3.4 install

to include Ursgal (and the changes you have made to the resources) into Python site-packages.

Q: The example script fails. What am I doing wrong?

Check the printouts: at which step is it failing? If the download of the example BSA1.mzML was not successful, and you’re using OSX, see Q: Downloading http files is not working on OSX. Why?. If MS-GF+ fails and you are not sure if you have installed Java Runtime Environment, see Q: MS-GF+ (or any Java based engine) fails. What could be the problem?. If this doesn’t help, shoot us a message or open an issue on GitHub (please include your printouts).

Q: A validation engine (Percolator, qvality, …) fails. What’s going on?

There are two common problems causing your workflow to fail at the point of validating results: 1. Your database doesn’t contain decoys (check out or decoys are not recognized (check if the uparam ‘decoy_tag’ is correct for your database). 2. Your list of results is too small for proper statistics (the error message is something like “Too good seperation between targets and decoys”). In this case, you need to improve your search parameters (e.g. mass tolerances), database size (e.g. whole proteome instead of a single protein) or MS measurements (i.e. your raw data).

Q: An engine fails with a certain combination of parameter values. Why is that not checked beforehand?

In general, we don’t check if a vertain combination of parameter values is allowed or makes sense, since this would be quite some work for all the different engines and use cases. Please check the documentation of the respective engines to avoid these issues.

  • MS-GF+ does not allow to specify a maximum number of missed cleavages wgen using unspecific cleavage -> use params[‘max_missed_cleavages’] = -1


Q: How do I create/add a new engine?

See Create/Implement your own UNode.

Q: How do I keep Ursgal up-to-date?

Ursgal is still in development and changes, extensions, etc. are pushed to GitHub. Therefore, the easiest way (if you have cloned Ursgal from GitHub) is:

user@localhost:~/ursgal$ git pull

If you have not cloned Ursgal but used the ZIP file you can replace the folder with the newly downloaded and extracted version.

In both cases you might need to run the setup again to update the python site-packages:

user@localhost:~/ursgal$ python3 install