Metadata-Version: 2.1
Name: defense-predictor-2
Version: 0.0.1
Summary: Python module for running Defense Predictor 2, a machine learning model to predict antiphage defense systems
License: MIT
Author: peterdeweirdt
Author-email: petedeweirdt@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: fair-esm (>=2.0.0,<3.0.0)
Requires-Dist: joblib (>=1.4.2,<2.0.0)
Requires-Dist: lightgbm (>=4.5.0,<5.0.0)
Requires-Dist: numpy (>=2.1.2,<3.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: scikit-learn (>=1.5.2,<2.0.0)
Requires-Dist: torch (>=2.5.1,<2.6.0)
Requires-Dist: tqdm (>=4.67.0,<5.0.0)
Description-Content-Type: text/markdown

# DefensePredictor2: A Machine Learning Model to Discover Novel Prokaryotic Immune Systems

Python package to run DefensePredictor2, a machine-learning model that leverages embeddings from a protein language model, [ESM2](https://github.com/facebookresearch/esm), to classify proteins as anti-phage defensive. 

This repo is for the second version of DefensePredictor, which was trained with larger ESM2 embeddings and an updated training set. This model has not been experimentally tested, so use with caution. 

For additional details, read the original DefensePredictor paper [here](https://www.science.org/doi/10.1126/science.adv7924).

### Installation

In a fresh [conda](https://anaconda.org/anaconda/conda) or other virutal environment, run:

```bash
pip install defense_predictor_2
defense_predictor_2_download
```

The first command downloads the python package from PyPI and the second downloads the model weights. Once model weights are downloaded you do not need to run this command again. 

### Requirements 

Requires `python >= 3.10`

### Usage

`defense_predictor_2` can be run as python code

```python
import defense_predictor_2 as dfp

ncbi_feature_table = 'GCF_003333385.1_ASM333338v1_feature_table.txt'
ncbi_cds_from_genomic = 'GCF_003333385.1_ASM333338v1_cds_from_genomic.fna'
ncbi_protein_fasta = 'GCF_003333385.1_ASM333338v1_protein.faa'
output_df, feature_matrix = dfp.defense_predictor(ft_file=ncbi_feature_table, fna_file=ncbi_cds_from_genomic, faa_file=ncbi_protein_fasta)
output_df.head()                                    
```

Or from the command line

```bash
defense_predictor_2 \
     --ncbi_feature_table GCF_003333385.1_ASM333338v1_feature_table.txt \
     --ncbi_cds_from_genomic GCF_003333385.1_ASM333338v1_cds_from_genomic.fna \ 
     --ncbi_protein_fasta GCF_003333385.1_ASM333338v1_protein.faa \
     --output GCF_003333385_defense_predictor_output.csv
```

Alternatively, `defense_predictor_2` can take a single [GFF3](https://useast.ensembl.org/info/website/upload/gff3.html?) file with embedded genomic FASTA:

```python
output_df, feature_matrix = dfp.defense_predictor(gff='annot_with_genomic_fasta.gff')
```

```bash
defense_predictor_2 \
     --gff annot_with_genomic_fasta.gff \
     --output defense_predictor_2_output.csv
```

When given a GFF, `defense_predictor_2` translates proteins from the embedded genomic sequence using the bacterial codon table (`transl_table=11`) and uses each CDS's `locus_tag` as its identifier.

<br>

`defense_predictor_2` outputs the predicted log-odds of defense for each input protein in the columns `mean_log_odds`. We reccomend using a stringent log-odds cutoff of `4` to call a protein predicted defensive.

To see an example you can run the `defense_predictor_2_example.ipynb` in colab: <a href="https://colab.research.google.com/github/PeterDeWeirdt/defense_predictor_2/blob/main/defense_predictor_2_example.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a> 

We reccomend running `defense_predictor_2` on a computer with a cuda-enabled GPU, to maximize computational efficiency. 

### Inputs

The NCBI input files can be downloaded from the [ftp webpage](https://ftp.ncbi.nlm.nih.gov/genomes/all/GCF/000/005/845/GCF_000005845.2_ASM584v2/) for any gemone of interest, which is linked on its [assembly page](https://www.ncbi.nlm.nih.gov/datasets/genome/GCF_000005845.2/).

For an unannotated nucleotide assembly, run NCBI's [Prokaryotic Genome Annotation Pipeline (PGAP)](https://github.com/ncbi/pgap) 
or [prokka](https://github.com/tseemann/prokka) and pass its `*.gff` output directly via `--gff`.

