Author : Thomas Lacroix

This script analyses co-localized groups of signature proteins (Relaxase, Coupling Protein, VirB4, Integrase) and find mobile element structures based on their ICE / IME conjugation modules (see paper Ambroset et al. 2016). It tries to resolve nested structures (guest/host structures) and signature proteins that could be attributed to multiple structures. More details on how the algorithm works is available under ./documentation. By default the algorithm gives priority to grouping SP of the same ICE family or IME family and forbids grouping SP belonging to different ICE superfamily.


** Test your installation
The directory ./tests/ contains ICEs / IMEs structures adapted from manually curated biological examples. They have been integrated over time to test the algorithm on a variety of complex cases. To ensure your local version of the software performs correctly, you can run the tests like so :
./runTests.sh


** Arguments for the script
   -i or --input : path to the .csv input file containing the sequence of signature proteins (SP) generated by the upstream part of the pipeline (icescreen_detection_SP)
   -c or --config : path to the config file that contains the default parameters for the script (./icescreen.conf)
   -o or --output : path to the detailed tsv output file about the ICE / IME structures
   -l or --log : path to the log file (details of the steps of the program)
   -m or --modified_input : path to the output csv file similar to the input file with extra columns added
   -verbose' : Turn on verbose mode ; default=False

Example running the script on a test file :
python3 src/icescreen_OO.py -c ./icescreen.conf -i tests/test_files/test1_NC_004668.1_detected_SP.csv -o results/test1_NC_004668.1_results_EM.tsv -m results/test1_NC_004668.1_detected_SP_withICEIMEIds.csv -l results/test1_NC_004668.1_results_EM.log
See more examples in the file ./runTests.sh.



 ** Output files
There are 3 main output files :

 - (1) _withICEIMEIds.csv (option -m) file similar to the input file with extra columns added :
    - The column "ICE / IME Number" is used to assign an identifier to signature proteins (SP) attributed to an ICE / IME structure with confidence. In other words, all the different SP with a similar ICE / IME structure number belong to the same ICE / IME structure according to the software. The ICE / IME identifiers are numbers assigned incrementally along the sequence of SP.
    - The column "ICE / IME Number (to review)" is used in a similar fashion but for SP that could be attributed to multiple ICE / IME structures or to a single ICE / IME structures with low confidence.
    - The column "Segment Number" reflects the segment number which contains the SP. One of the first step of the algorithm is to segment the sequence of SP in order to further work with shorter sub-sequences to assign SP to the structures (see maxNumberCDSForSplitSPsByColocalizion in the section parameters).
    - The column "Comment regarding ICE IME structure" specifies information on the SP regarding special decisions made by the algorithm. For example : The SP NP_XXXXXX is not a VirB4, constitutes a conjugaison module by itself, and no integrase has been attributed to the element 3, please manually check.

 - (2) detailed tsv output file about the ICE / IME structures (option -o). Each line of this file is a ICE / IME structure annotated by the algorithm. Its information is similar to the output file _withICEIMEIds.csv (option -m) but centered around a list of ICE / IME structures instead of a list of SP. It is comprised of the following columns : "ICE IME Number", "segment number", "integrase upstream", "integrase downstream", "relaxase", "coupling protein", "VirB4", "list ordered SPs", "ICEline format", "ICE SuperFamily From Blast Of SP Conj Module", "ICE Family From Blast Of SP Conj Module", "IME Family From Blast Of SP Conj Module", "family SP conj module HMM", "category of conj module", "category of integrase", "host ICE / IME", "guest ICE / IME", "other ICE / IME colocalized", "SPs conj module to manually review", "Integrase to manually review", "comment"

 - (3) a summary file containing different statistics (same file name as option -o but .summary instead of .tsv). This file summarizes the main parameters and statistics regarding ICE / IME structures and SP. Example of statistics includes "Total number of segments", "Number of segments with one element", "Number of segments with several elements", "Number of segments with nested elements", "Number of segments with no element", "Number of complete ICE (4 types of SP)", etc.



 ** The file icescreen.conf holds the following configuration parameters :

 - maxNumberCDSForSplitSPsByColocalizion : maximum number of CDS in the genome between two signature proteins for them to potentially belong to the same ICE or IME. Default : 100

 - maxNumberCDSForFilterIMESize = 10 : maximum number of CDS in the genome between two signature proteins for them to potentially belong to the same IME. Default : 10

 - groupListSPintoICEsIMEsUsingFamilyInfo : This parameter is used to group signature proteins of the conjugation module (relaxase, coupling, virB4) that potentially belong to the same ICE or IME. Default : LOOSE
       - "LOOSE" : in order for a SP of the conjugation module to extend a given ICE structure, its ICE super-family (information from Blast matches) needs to match the one of the SP in the given ICE structure. Empty ICE super-family (no data) is considered compatible to any ICE super-family. If a SP has multiple ICE super-family, a match of at least one ICE super-family is required, then the multiple ICE super-family of the SP will be registered for the ICE structure.
       - "STRICT" : in order for a SP of the conjugation module to extend a given ICE structure, its ICE super-family (information from Blast matches) needs to match the one of the SP in the given ICE structure. Empty family (no data on family) is considered a super-family of its own and can not be associated with non-empty super-families. Multiple families can only be associated with identical multiple families.
        - "NO" means that the SP of the conjugation module can be be affiliated with any SP regardless of ICE super-family or family

 - useFamilyInfoToTryToResolveSPModuleConjConflict : sometimes a given signature protein of the conjugation module (relaxase, coupling, virB4) could be attributed to two different ICEs or IMEs. "YES" means that the algorithm will give priority to one of the ICE or IME structure based on ICE or IME family information if available. "NO" means that no such test is performed and that this signature protein of the conjugaison module is flagged as being potentially part of two different ICE or IME. Default : YES

 - useDistanceCDSInfoToTryToResolveSPModuleConjConflict : sometimes a given signature protein of the conjugation module (relaxase, coupling, virB4) could be attributed to two different ICE or IME. "YES" means that the algorithm will give priority to one of the ICE or IME structure based on CDS distances, in other words the SP will be attributed to the closer structure if possible. "NO" means that no such test is performed and that this signature protein is flagged as being potentially part of two different ICE or IME. Default : YES
