Metadata-Version: 2.4
Name: gloome
Version: 2.0.5
Summary: GLOOME: Gain Loss Mapping Engine
Author-email: Rodion Polonskyi <rodion@tauex.tau.ac.il>
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: biopython>=1.85
Requires-Dist: d3blocks>=1.4.11
Requires-Dist: matplotlib>=3.7
Requires-Dist: networkx>=3.0
Requires-Dist: numpy<2.0,>=1.20
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: seaborn>=0.13.2

# 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

```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:

```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:

```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](https://www.tau.ac.il/~talp/publications/GLOOME.pdf)] [[abs](https://academic.oup.com/bioinformatics/article/26/22/2914/228050)]

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

```bibtex
@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.
