pygcap 1.2.6
Python package for probe-based gene cluster finding in large microbial genome database
Requires Python: >=3.6
Keywords: gene, cluster, genomics, bioinformatics

# pyGCAP: a (py)thon (G)ene (C)luster (A)nnotation & (P)rofiling

A Python Package for Probe-based Gene Cluster Finding in Large Microbial Genome Database

- [Introduction](#Introduction)
- [Pipeline-flow](#Pipeline-flow)
- [Pre-requirement](#Pre-requirement)
- [Usage](#Usage)
- [Output](#Output)

---

## Introduction

Bacterial gene clusters provide insights into metabolism and evolution, and facilitate biotechnological applications. We developed pyGCAP, a Python package for probe-based gene cluster discovery. This pipeline uses sequence search and analysis tools and public databases (e.g. BLAST, MMSeqs2, UniProt, and NCBI) to predict potential gene clusters by user-provided probe genes. We tested the pipeline with the division and cell wall (dcw) gene cluster, crucial for cell division and peptidoglycan biosynthesis.

To evaluate pyGCAP, we used 17 major dcw genes defined by Megrian et al. [1] as a probe set to search for gene clusters in 716 Lactobacillales genomes. The results were integrated to provide detailed information on gene content, gene order, and types of clusters. While PGCfinder examined the completeness of the gene clusters, it could also suggest novel taxa-specific accessory genes related to dcw clusters in Lactobacillales genomes. The package will be freely available on the Python Package Index, Bioconda, and GitHub.

[1] Megrian, D., et al. [Ancient origin and constrained evolution of the division and cell wall gene cluster in Bacteria](https://www.nature.com/articles/s41564-022-01257-y). Nat Microbiol 7, 2114–2127 (2022).

---

## Pipeline-flow

<p align="center">
  <img width="1000" alt="flowchart" src="https://github.com/user-attachments/assets/e957794d-091c-4931-a0c9-fd013f02d307">
</p>

---

## Pre-requirement

1. `Python` >= 3.6
2. `conda` environment

   - `blast` ([bioconda blast package](https://anaconda.org/bioconda/blast))

     ```
     conda install bioconda::blast
     conda install bioconda/label/cf201901::blast
     ```

   - `datasets` & `dataformat` from NCBI ([conda-forge ncbi-datasets-cli package](https://anaconda.org/conda-forge/ncbi-datasets-cli))

     ```
     conda install conda-forge::ncbi-datasets-cli
     ```

   - `MMseqs2` ([MMseqs2 github](https://github.com/soedinglab/MMseqs2))

     ```
     conda install -c conda-forge -c bioconda mmseqs2
     ```

   - If you want to make a new conda environment for pygcap, follow the instructions below:

     ```
     conda create -n pygcap
     conda activate pygcap
     pip install pygcap (or) conda install bioconda::pygcap
     conda install -c conda-forge ncbi-datasets-cli
     conda install -c conda-forge -c bioconda mmseqs2
     ```

---

## Usage

- pypi pygcap ([link](https://pypi.org/project/pygcap/)) / bioconda pygcap ([link](https://anaconda.org/bioconda/pygcap))

  ```python
  # pip install pygcap
  # conda install bioconda::pygcap
  pygcap [TAXON] [PROBE_FILE]
  ```

- input argument description

  ```python
  ### usage example
  pygcap Facklamia pygcap/data/probe_sample.tsv
  pygcap 66831 pygcap/data/probe_sample.tsv
  ```

  2.  `taxon` (both name and taxid are available)
  3.  path of `probe.tsv` ([sample file](https://github.com/jrim42/pyGCAP/blob/main/pygcap/data/probe_sample.tsv))

      - `Probe Name` (user defined)
      - `Prediction` (user defined)
      - `Accession` (UniProt entry)

- When the appropriate environment is set up, try running the following command from the root directory. If you have successfully met all the pre-requirements, it will execute correctly, and a directory named 'Facklamia' containing the test results will be created in the root directory.

  ```
  python3 test.py
  [or]
  pygcap Facklamia pygcap/data/probe_sample.tsv
  ```

### Options

1. `--working_dir` or `-w` (default: `.`): Specify the working directory path.

   ```
   pygcap [TAXON] [PROBE_FILE] —-working_dir or -w [PATH_OF_WORKING_DIRECTORY]
   ```

2. `--thread` or `-t` (default: `50`): Number of threads to use when running MMseqs2 and blastp. The number of threads can be adjusted automatically based on the CPU environment. It must be an integer greater than 0.

   ```
   pygcap [TAXON] [PROBE_FILE] —-thread or -t [NUMBER_OF_THREAD]
   ```

3. `--identity` of `-i` (default: `0.5`): The value of protein identity to be used in MMseqs2. It must be a value between 0 and 1.

   ```
   pygcap [TAXON] [PROBE_FILE] —-identity or -i [PROTEIN_IDENTITY]
   ```

4. `--max_target_seqs` of `-m` (default: `500`): The vaue of aligned sequences to retain in the overall BLASTP results. It must be an integergreater than 0.

   ```
   pygcap [TAXON] [PROBE_FILE] —-max_target_seqs or -m [MAX_TARGET]
   ```

5. `--skip` of `-s` (default: `none`): Specify steps to skip during the process. Multiple steps can be skipped by using this option multiple times. This option is useful when you want to add a new probe to the same TAXON as before or when you want to change the identity option for MMseqs2.

   ```
   pygcap [TAXON] [PROBE_FILE] —-skip or -s [ARG]
   ```

   - `all`: Skip all the processes listed below.
   - `ncbi`: Skip downloading genome data from NCBI.
   - `mmseqs2`: Skip running MMseqs2.
   - `parsing`: Skip parsing genome data.
   - `uniprot`: Skip downloading probe data from UniProt.
   - `blastdb`: Skip running makeblastdb.

---

## Output

- A directory with the following structure will be created in your `working directory` with the name of the `TAXON` provided as input.

  ```
  📦 [TAXON_NAME]
  ├─ data
  │  ├─ assembly_report.tsv
  │  ├─ metadata_target.tsv
  │  └─ ...
  ├─ input
  │  ├─ [GENUS_01]
  │  ├─ [GENUS_02]
  │  └─ ...
  ├─ output
  │  ├─ genus
  │  ├─ img
  │  └─ tsv
  └─ seqlib
     ├─ blast_output.tsv
     ├─ seqlib.tsv
     └─ ...
  ```

### Example

Profiling _dcw_ genes from pan-genomes of Lactobacillales (LAB)

- The following are some of the result data you can obtain through this pipeline:

  - `working_directory/TAXON/output/img`: A heatmap representing the dcw gene contents of Lactobacillales at the genus level.

    <p align="center">
      <img width="1000" alt="example1" src="https://github.com/user-attachments/assets/745e0d71-cf7c-4796-8601-5793dba42960">
    </p>

  - `working_directory/TAXON/output/geus`: A plot visualizing the dcw gene order of Lactobacillales grouped by genus.

    <p align="center">
      <img width="1000" alt="example2" src="https://github.com/user-attachments/assets/f9a3fd2f-b636-4171-a5cb-257062ebd1f0">
    </p>