GLOOME: Gain Loss Mapping Engine

A high-performance bioinformatics tool for analyzing gene gain and loss events, and pattern co-evolution during evolution.

GLOOME provides evolutionary analysis of presence and absence profiles (phyletic patterns). These patterns are assumed to result from gain and loss dynamics along a phylogenetic tree. Examples of characters represented by phyletic patterns include:

• Restriction sites
• Gene families
• Introns
• Indels

The primary purpose of GLOOME is to accurately infer branch-specific and site-specific gain and loss events, as well as to analyze the co-evolution of presence-absence patterns (CoPAP). This inference is based on a stochastic mapping approach, using evolutionary models that accurately reflect the underlying biological processes.

Features

• Support for various evolutionary models
• Gain and loss inference using stochastic mapping or maximum parsimony
• CoPAP (Co-evolution of presence-absence patterns) analysis to study correlated character evolution
• High-performance computing powered by optimized NumPy vectorization for ultra-fast phylogenetic calculations
• Estimation of gain/loss rates per character
• Advanced optimization options for evolutionary parameters
• Comprehensive likelihood, parsimony, and correlation-based output

Project structure

gloome
├── gloome
│   ├── services
│   │   ├── __init__.py
│   │   └── service_functions.py
│   ├── tree
│   │   ├── __init__.py
│   │   ├── node.py
│   │   ├── npencoder.py
│   │   └── tree.py
│   ├── __init__.py
│   ├── __main__.py
│   ├── config.py
│   ├── consts.py
│   └── utils.py
├── pyproject.toml
└── README.md

This manual provides comprehensive documentation on input formats, command-line usage, interpretation of results, and troubleshooting.

Program Execution

To get the project working, you need to run the command gloome or python3 -m gloome or python -m gloome in the terminal with the following parameters:

Required parameters:

    --msa_file <type=str>
        Specify the msa filepath. Input must be a 0/1 binary matrix 
        ('1' for presence, '0' for absence, and '?' for missing data).

    --tree_file <type=str>
        Specify the newick filepath.

Optional parameters:

    --out_dir <type=str>
        Specify the outdir path.

    --process_id <type=str>
        Specify a process ID, otherwise it will be generated automatically.

    --mode <type=str>
        Specify execution mode. Possible options: 
        ('draw_tree', 'compute_likelihood_of_tree', 'create_all_file_types', 'execute_all_actions'). 
        Default is 'execute_all_actions'.

    --with_internal_nodes <type=int> 
        Specify the tree has internal nodes. Default is 1.

    --categories_quantity <type=int>
        Specify categories quantity. Default is 4.

    --alpha <type=float>
        Specify alpha. Default is 0.5.

    --pi_1 <type=float> 
        Specify pi_1. Default is 0.5.

    --coefficient_bl <type=float> 
        Specify coefficient_bl. Default is 1.0.
        
    --probability_lg <type=float> 
        Specify probability_lg. Default is 0.9.
    
    --number_lg <type=float> 
        Specify number_lg. Default is 5.
    
    --number_datasets <type=float> 
        Specify number_datasets. Default is 100.
    
    --is_do_not_use_copap <type=int> 
        Specify whether to skip CoPAP analysis. Default is 0.

    --is_optimize_pi <type=int> 
        Specify is_optimize_pi. Default is 1.

    --is_optimize_pi_average <type=int> 
        Specify is_optimize_pi_average. Default is 0.

    --is_optimize_alpha <type=int> 
        Specify is_optimize_alpha. Default is 1.

    --is_optimize_bl <type=int> 
        Specify is_optimize_bl. Default is 1.

    --file_interactive_tree_html <type=int> 
        Specify file_interactive_tree_html. Default is 0.

    --file_newick_tree_png <type=int> 
        Specify file_newick_tree_png. Default is 0.

    --file_table_of_coevolution_tsv <type=int> 
        Specify file_table_of_coevolution_tsv. Default is 1.

    --file_simulated_datasets_fastas <type=int> 
        Specify file_simulated_datasets_fastas. Default is 1.

    --file_barplot_of_correlation_svg <type=int> 
        Specify file_barplot_of_correlation_svg. Default is 1.

    --file_plot_distribution_of_correlation_svg <type=int> 
        Specify file_plot_distribution_of_correlation_svg. Default is 1.

    --file_plot_correlation_by_rate_bin_svg <type=int> 
        Specify file_plot_correlation_by_rate_bin_svg. Default is 1.

    --file_table_of_posterior_rates_tsv <type=int> 
        Specify file_table_of_posterior_rates_tsv. Default is 1.

    --file_table_of_pearson_correlation_tsv <type=int> 
        Specify file_table_of_pearson_correlation_tsv. Default is 1.

    --file_table_of_nodes_tsv <type=int> 
        Specify file_table_of_nodes_tsv. Default is 1.

    --file_branch_position_probabilities_tsv <type=int>  
        Specify file_branch_position_probabilities_tsv. Default is 1.

    --file_table_of_branches_tsv <type=int> 
        Specify file_table_of_branches_tsv. Default is 1.

    --file_log_likelihood_tsv <type=int> 
        Specify file_log_likelihood_tsv. Default is 1.

    --file_table_of_attributes_tsv <type=int> 
        Specify file_table_of_attributes_tsv. Default is 1.

    --file_table_of_parsimony_and_homoplasy_scores_tsv <type=int> 
        Specify file_table_of_parsimony_and_homoplasy_scores_tsv. Default is 1.

    --file_phylogenetic_tree_nwk <type=int> 
        Specify file_phylogenetic_tree_nwk. Default is 1.

    --rooting_method <type=str> 
        Specify tree rooting method. Possible options: ('mad', 'mvr', 'midpoint', 'outgroup').
        mad - Minimal Ancestor Deviation
        mvr - Minimum Variance Rooting
        midpoint - Midpoint Rooting
        outgroup - Outgroup Rooting
        Default is 'midpoint'.
    
    --leaf <type=str> 
        Specify leaf for outgroup rooting. Default is ''.

Citing

If you use GLOOME for your research, please make sure to cite the following publication:

Cohen, O., Ashkenazy, H., Belinky, F., Huchon, D., and Pupko, T. 2010. GLOOME: gain loss mapping engine. Bioinformatics 26(22):2914-2915. [pdf] [abs]

BibTeX

Proper citation helps support the development and maintenance of this tool.

@article{cohen2010gloome,
  author = {Cohen, Ofir and Ashkenazy, Haim and Belinky, Frida and Huchon, Doroth{\'e}e and Pupko, Tal},
  title = {GLOOME: gain loss mapping engine},
  journal = {Bioinformatics},
  volume = {26},
  number = {22},
  pages = {2914--2915},
  year = {2010},
  publisher = {Oxford University Press}
}

Contact

For questions, issues, or contributions, please open an issue on the repository or contact the maintainer directly.