DefenseFinder is a program to systematically detect known anti-phage systems. DefenseFinder uses MacSyFinder.
If you are using DefenseFinder please cite
This repository contains DefenseFinder a tool allowing for a systematic search of anti-phage systems. The DefenseFinder models based on MacSyFinder architecture can be here.
The CRISPR-Cas models used in DefenseFinder come from the macsy models of CasFinder available here.
To make DefenseFinder results more intuitive, we created a Wiki of defense systems to gather information on all the defense systems. The defense wiki is available here.
This website gather information on all defense systems detected by DefenseFinder as well as precomputed results and predicted structure of defense systems.
DefenseFinder is available as a webservice.
DefenseFinder has one program dependency: the Hmmer program, version 3.1 or greater (http://hmmer.org/). The hmmsearch program should be installed (e.g., in the PATH) to use MacSyFinder. DefenseFinder also relies on Python library dependencies:
DefenseFinder is installable through pip. Before starting, if you can, it is recommended to install DefenseFinder in a virtualenv (such as condas).
conda create –name defensefinder
conda activate defensefinder
pip install mdmparis-defense-finderHowever, you can also install DefenseFinder using only pip.
pip install mdmparis-defense-finderAt this stage, if you have an issue, this could be due to a problem with your pip installer. Check the following webpage for details on how to solve it
After installing DefenseFinder, you need to retrieve the DefenseFinder models. To retrieve it run:
defense-finder updateWhen you have not used DefenseFinder in the last days, make sure you have the latest versions of the models. To verify and downloaded if necessary the latest models run:
defense-finder updateWhen the DefenseFinder models are updated you only have to update the models and not the tool. However, if you have an outdated version of the DefenseFinder tool, you can use the following line to get the most recent version
pip install -U mdmparis-defense-finder
defense-finder updateTo check the different DefenseFinder update options run
$ defense-finder update --help
Usage: defense-finder update [OPTIONS]
Fetches the latest defense finder models.
The models will be downloaded from mdmparis repositories and installed on
macsydata.
This will make them available to macsyfinder and ultimately to defense-
finder.
Models repository: https://github.com/mdmparis/defense-finder-models.
Options:
--models-dir TEXT Specify a directory containing your models.
--help Show this message and exit.If you want to run DefenseFinder on a small set of genomes (< 30 000 proteins). You can run the following command.
defense-finder run genome.faaThe input file, here “genome.faa” can be a protein fasta file or a nucleotide fasta file. In case of a protein file all proteins should in the order of their position in the genome. Indeed DefenseFinder takes into account the order of the proteins. DefenseFinder automatically detects whether the file is a nucleotide or a protein fasta file.
A run on a genome (few thousand proteins) should take less than two minutes on a standard laptop. If more, make sure everything is installed properly. In this configuration, all the replicon will be named UserReplicon. ATTENTION, If you want to run DefenseFinder on a larger set of genomes you need to format your dataset as described in "Larger dataset and Gembase Format".
DefenseFinder will generate three types of files (and an option to conserve MacSyFinder options). All the files are described below.
defense_finder_systems.tsv : In this file, each line corresponds to a system found in the given genomes. This is a summary of what was found and gives the following information
sys_id : Each system detected by DefenseFinder have a unique ID based on the replicon where it was found and the type of systemstype: Type of the anti-phage system found (such as RM, Cas...)subtype : Subtype of the anti-phage system found (such as RM_type_I, CAS_Class1-Subtype-I-E)sys_beg : Protein where the system begins (name found in the input file)sys_end : Protein where the system ends (name found in the input file)protein_in_syst : List of all protein(s) present in this system (name found in the input file)genes_count : Number of genes found in the systemname_of_profiles_in_sys: List of the protein profiles that hit the protein of the system (name from the HMM).defense_finder_genes.tsv : In this file, each line corresponds to a gene found in a system.
For each gene, there is several information such as the replicon, the position, the system..
All the information comes from MacSyFinder and follows MacSyFinder nomenclature (best_solution.tsv) and more can be found in the MacSyFinder Ma documentation.
defense_finder_hmmer.tsv : In this file, each line corresponds to an HMM hit. This file show all hit of HMM regardless if they are in a complete system or not. Those results have to be used cautiously for deep inspection. Indeed, biologically, it was shown that only a full system will be anti phage. This function can be used to found defense gene in small portion of genomes.
Beware, a single protein can have several hits. The output is a part of the result of HMMer results table.
hit_id : the protein name (name found in the input file)replicon : The name of the repliconposition_hit: The position in the input fileGene_name : the name of the HMMBy using the argument --preserve-raw , you will have all the results from MacSyFinder. Those results are explained here
When running DefenseFInder on several genomes, like MacSyFinder, we propose to adopt the following convention to fulfill the requirements for the “gembase dbtype”. The difference between any fasta file and the gembase format is the name of the protein (Protein name = the text after > in a fasta file). For both type, protein have to be ordered but in the first case the name of the protein do not matter (except no repetition). In the gembase format, protein name are composeded of two part: the replicon and the position. The replicon name is the same for all the protein that the user want to be analyse simultaneously (for example a complete genome, a plasmid...) The second component is the position. Those two component must be separated by "". It is possible to use "_" in the replicon name, only the last instance will be used as the separator between replicon name and position. With this format of file, MacSyFinder will be able to treat each replicon separately to assess macromolecular systems presence and reduce ressource use.
Example: esco_genomes.faa
> ESCO388_0001
XXXXXXX
> ESCO388_0002
XXXXXXX
…..
> ESCO388_3603
XXXXXXX
> ESCO389_0001
XXXXXXX
> ESCO389_0002
XXXXXXX
…..
> ESCO389_3555
XXXXXXXTo use DefenseFinder with gembase format file on larger dataset of genomes run
defense-finder run –dbtype gembase esco_genomes.faaTo check the different DefenseFinder options run
$ defense-finder run --help
Usage: defense-finder run [OPTIONS] FILE
Search for all known anti-phage defense systems in the target fasta file.
Options:
-o, --out-dir TEXT The target directory where to store the results.
Defaults to the current directory.
-w, --workers INTEGER The workers count. By default all cores will be used
(w=0).
-c, --coverage FLOAT Minimal percentage of coverage for each profiles. By
default set to 0.4
--db-type TEXT The macsyfinder --db-type option. Run macsyfinder
--help for more details. Possible values are
ordered_replicon, gembase, unordered, defaults to
ordered_replicon.
--preserve-raw Preserve raw MacsyFinder outputs alongside Defense
Finder results inside the output directory.
--models-dir TEXT Specify a directory containing your models.
--no-cut-ga Advanced! Run macsyfinder in no-cut-ga mode. The
validity of the genes and systems found is not
guaranteed!
--log-level TEXT set the logging level among DEBUG, [INFO], WARNING,
ERROR, CRITICAL
-h, --help Show this message and exit.To install defense-finder in development mode (so when you edit a file the changes are directly visible without reinstalling), one can do :
conda create -n defensefinder_dev
conda activate defensefinder_dev
pip install -e .
defense-finder updateTo test that changes in the code are not breaking the output, you can compare your results with the test dataset :
defense-finder run test/df_test_prot.faa
defense-finder run test/df_test_nt.fna
#
for i in systems genes hmmer; do
echo "Verifying $i results in : "
echo -n "Protein file :"
diff -q df_test_prot_defense_finder_$i.tsv test/expected_results/df_test_prot_defense_finder_$i.tsv && echo " > Tests OK" || echo " >> Test Failed <<"
echo -n "Nucleotide file :"
diff -q df_test_nt_defense_finder_$i.tsv test/expected_results/df_test_nt_defense_finder_$i.tsv && echo " > Tests OK" || echo " >> Test Failed <<"
echo
doneFor questions: you can contact aude.bernheim@pasteur.fr