Package: mdmparis-defense-finder
Documentation DefenseFinderDefenseFinder is a program to systematically detect known anti-phage systems. DefenseFinder uses MacSyFinder.If you are using DefenseFinder please cite"Systematic and quantitative view of the antiviral arsenal of prokaryotes"Nature Communication, 2022,Tesson F., Hervé A. , Mordret E., Touchon M., d’Humières C., Cury J., Bernheim A."MacSyFinder: A Program to Mine Genomes for Molecular Systems with an Application to CRISPR-Cas Systems." PloS one 2014Abby S., Néron B.,Ménager H., Touchon M. Rocha EPC.DefenseFinder ModelsThis repository contains DefenseFinder a tool allowing for a systematic search of anti-phage systems.
The DefenseFinder models based on MacSyFinder architecture can behereInstalling DefenseFinder command-line interfaceInstall dependencyDefenseFinder 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:macsyfindercolorlogpyyamlpackagingnetworkxThese dependencies will be automatically retrieved and installed when using pip for installation (see below).Install DefenseFinderDefenseFinder is installable through pip.
Before starting, if you can, it is recommended to install DefenseFinder in a virtualenv (such as condas).condacreate–namedefensefinder
condaactivatedefensefinder
pipinstallmdmparis-defense-finderHowever, you can also install DefenseFinder using only pip.pipinstallmdmparis-defense-finderAt this stage, if you have an issue, this could be due to a problem with your pip installer.
Check the followingwebpagefor details on how to solve itAfter installing DefenseFinder, you need to retrieve the DefenseFinder models.
To retrieve it run:defense-finderupdateUpdating DefenseFinderWhen 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-finderupdateWhen 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 versionpipinstall-Umdmparis-defense-finder
defense-finderupdatedefense-finder update optionsTo check the different DefenseFinder update options run$defense-finderupdate--help

Usage:defense-finderupdate[OPTIONS]Fetchesthelatestdefensefindermodels.Themodelswillbedownloadedfrommdmparisrepositoriesandinstalledonmacsydata.Thiswillmakethemavailabletomacsyfinderandultimatelytodefense-finder.Modelsrepository:https://github.com/mdmparis/defense-finder-models.

Options:--models-dirTEXTSpecifyadirectorycontainingyourmodels.--helpShowthismessageandexit.Running Defense FinderQuick runIf you want to run DefenseFinder on a small set of genomes (< 30 000 proteins).
You can run the following command.defense-finderrungenome.faaInput.The 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".OutputsDefenseFinder 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 informationsys_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 Madocumentation.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 explainedhereRunning DefenseFinder on several genomesWhen running DefenseFInder on several genomes, like MacSyFinder, we propose to adopt the following convention to fulfill the requirements for the “gembase db_type”.
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 rundefense-finderrun–dbtypegembaseesco_genomes.faadefense-finder run optionsTo check the different DefenseFinder options run$defense-finderrun--help

Usage:defense-finderrun[OPTIONS]FILESearchforallknownanti-phagedefensesystemsinthetargetfastafile.

Options:-o,--out-dirTEXTThetargetdirectorywheretostoretheresults.Defaultstothecurrentdirectory.-w,--workersINTEGERTheworkerscount.Bydefaultallcoreswillbeused(w=0).-c,--coverageFLOATMinimalpercentageofcoverageforeachprofiles.Bydefaultsetto0.4--db-typeTEXTThemacsyfinder--db-typeoption.Runmacsyfinder--helpformoredetails.Possiblevaluesareordered_replicon,gembase,unordered,defaultstoordered_replicon.--preserve-rawPreserverawMacsyFinderoutputsalongsideDefenseFinderresultsinsidetheoutputdirectory.--models-dirTEXTSpecifyadirectorycontainingyourmodels.--no-cut-gaAdvanced!Runmacsyfinderinno-cut-gamode.Thevalidityofthegenesandsystemsfoundisnotguaranteed!--log-levelTEXTsetthelogginglevelamongDEBUG,[INFO],WARNING,ERROR,CRITICAL-h,--helpShowthismessageandexit.DevelopmentTo install defense-finder in development mode (so when you edit a file the changes are directly visible without reinstalling), one can do :condacreate-ndefensefinder_dev
condaactivatedefensefinder_dev
pipinstall-e.
defense-finderupdateTo test that changes in the code are not breaking the output, you can compare your results with the test dataset :defense-finderruntest/df_test_prot.faa
defense-finderruntest/df_test_nt.fna#foriinsystemsgeneshmmer;doecho"Verifying$iresults in : "echo-n"Protein file :"diff-qdf_test_prot_defense_finder_$i.tsvtest/expected_results/df_test_prot_defense_finder_$i.tsv&&echo" > Tests OK"||echo" >> Test Failed <<"echo-n"Nucleotide file :"diff-qdf_test_nt_defense_finder_$i.tsvtest/expected_results/df_test_nt_defense_finder_$i.tsv&&echo" > Tests OK"||echo" >> Test Failed <<"echodoneFor questions: you can contactaude.bernheim@inserm.fr