FDSTools User Guide

Please note: the FDSTools User Guide is still a work in progress. For now, you will find a brief introduction and installation instructions on this page. The complete guide will be available here soon.

Index

  1. Introduction: What is FDSTools?
  2. Installing FDSTools
  3. Updating FDSTools

1. Introduction: What is FDSTools?

FDSTools is a package of analysis tools for Massively Parallel Sequencing (MPS, also known as Next Generation Sequencing or NGS) data from targeted (amplicon-based) essays, focused on forensic DNA markers. It includes tools for characterisation and filtering of PCR stutter artefacts and other systemic noise, and for automatic detection of the alleles in a sample.

The package was created by Jerry Hoogenboom in 2016 as the product of his MSc Bioinformatics thesis project, at the LUMC (Leiden, the Netherlands). Development is continued at the NFI (The Hague, the Netherlands).

FDSTools is a collection of many command-line tools which can either be used separately or by using one of the built-in pipeline options. Results are visualised in the form of web pages (HTML files) in which various analysis settings can still be tweaked. In this User Guide, you will get to know the most important tools and visualisations and the pipeline options. A complete description of all tools and options can be found on the Tools page, or through the built-in help (command: fdstools --help).

2. Installing FDSTools

FDSTools is written in Python, so you need to have Python installed on your system first. Starting with FDSTools 2.0, Python 3.5 or higher is required. Please refer to Updating FDSTools below if you are updating from FDSTools v1.x, which ran on Python 2.7. Get Python from Python.org if you are on Windows or MacOS; then, make sure to select the Add Python to PATH option. Most Linux systems come with Python3 preinstalled, or offer a python3 package which can be installed using the system's package management tools.

Note: If you have installed both Python 2.7 and Python 3 at the same time, you may need to use python3 and pip3 in the commands mentioned below, to make sure Python 3 is used. You can see which version is used by running python --version.

There are two ways to install FDSTools: you can use the Python package installer programme pip (recommended), or install FDSTools manually.

Installing FDSTools through pip

The easiest way to install FDSTools is by using the command pip install fdstools. This will automatically download and install FDSTools on your system. This command uses the pip programme, which is bundled with the Python installer for Windows and MacOS. On Linux, you can install pip using the system's package management tools (e.g., on Ubuntu, apt install python-pip).

Installing FDSTools manually

If you can't (or don't want to) use pip, it is also possible to install FDSTools manually. The latest stable version can be downloaded from the Python Package Index (PyPI). Unzip the package you downloaded from that site, and then run python setup.py install to set it up. As this will overwrite any previously-installed version of FDSTools, you can update FDSTools in the same way in the future.

3. Updating FDSTools

Updating FDSTools (as well as any other Python package) to the latest version is very easy with pip. Just run the command pip install --upgrade fdstools and you're done. The only exception is upgrading from v1.x to v2.x.

Upgrading from FDSTools 1.x to FDSTools 2.x

Please follow the steps below to upgrade from FDSTools 1.x to FDSTools 2.x. The upgrade will involve a switch from Python 2.7 to Python 3.5 or newer. In addition, some minor changes have been made to FDSTools file formats.

  1. If you wish to keep using output files obtained from FDSTools v1.x, bear in mind that reading v1.x allele names using v2.x is not supported, may fail without warning and produce incorrect results! Therefore, the first step is to make sure any output files you wish to keep using will contain only raw sequences. You can achieve this by running fdstools seqconvert --library your_library.ini raw old_file.txt new_file.txt on the files that contain allele names. Note that noise profile files (obtained from e.g., bgestimate) contain two columns ('allele' and 'sequence') that may need conversion to raw sequences. You can use the following pipeline for this:

    fdstools seqconvert --library your_library.ini raw old_file.txt - | fdstools seqconvert --library your_library.ini --allele-column allele raw - new_file.txt

  2. Install Python 3 and pip3 if not already installed. You can uninstall Python 2.7 if nothing else on your system depends on it anymore.
  3. Install the latest version of FDSTools (see Installing FDSTools above). Note that if you have installed Python 2.7 and Python 3 side-by-side, you need to make sure you're installing using pip3.
  4. In your FDSTools library files, make sure no more than one sequence is specified for any marker in the [prefix] and [suffix] sections.
  5. If you used the [aliases] section in your FDSTools library files, you may need to make further edits to the library file because aliases are no longer supported. More specifically, if you used any alias names in the [flanks], [prefix] or [suffix] section, these will be treated as independent loci in FDSTools 2.x. You can remove the [aliases] section completely; FDSTools will not use it anymore.
  6. Update your scripts! Many changes have been made to various tools. Read the Changelog for a complete list.