- Jupyter Notebook 99.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| Figure_1 | ||
| Figure_2 | ||
| Figure_3 | ||
| Figure_4 | ||
| Figure_5 | ||
| PCN_Prediction_Models | ||
| Preprocessing | ||
| Supplementary_figures | ||
| environment.yml | ||
| LICENSE | ||
| README.md | ||
| requirements.txt | ||
Plasmid Copy Number Analysis: Integrating Theory and Machine Learning
This repository contains the code and data for the manuscript "Integrating theory and machine learning to reveal determinants of plasmid copy number".
📁 Repository Contents
This repository contains all code and outputs for manuscript figures and analyses:
- Figure_1/ - Code and outputs for Figure 1
- Figure_2/ - Code and outputs for Figure 2
- Figure_3/ - Code and outputs for Figure 3
- Figure_4/ - Code and outputs for Figure 4
- Figure_5/ - Code and outputs for Figure 5
- Supplementary_figures/ - Code and outputs for supplementary figures
- PCN_Prediction_Models/ - Pre-trained Random Forest models
- Preprocessing/ - Data preprocessing scripts and reference files
🔧 Installation
System Requirements
- Python 3.8 or higher
Option 1: Using Conda (Recommended)
conda env create -f environment.yml
conda activate pcn_prediction
Option 2: Using pip
pip install -r requirements.txt
Note: Bioinformatics tools (Prodigal, HMMER) are auto-installed with conda. For pip users, install separately:
# Ubuntu/Debian
sudo apt-get install prodigal hmmer
# macOS
brew install prodigal hmmer
🤖 Using Pre-trained Models for PCN Prediction
Step 1: Feature Engineering on Your Plasmid Sequences
To use our models, you must first extract the required features from your plasmid sequences:
A. Gene Prediction with Prodigal
prodigal -i your_plasmid.fasta -o genes.gbk -a proteins.faa -p meta
See detailed workflow: Figure_2A/Sequence_Annotation_and_Feature_Extraction/Prodigal.ipynb
B. Protein Domain Annotation with HMMER
hmmscan --domtblout domains.out Pfam-A.hmm proteins.faa
See detailed workflow: Figure_2A/Sequence_Annotation_and_Feature_Extraction/Hmmscan.ipynb
C. Calculate K-mer Frequencies
Extract k-mer frequencies for k=1, 2, and 3 from your plasmid sequences.
D. Genomic Length Features
- Plasmid_Length (in base pairs)
- Total_Chromosome_Length (in base pairs) - if available
Step 2: Arrange Features in Required Order
CRITICAL: Features must be arranged in the exact order specified in the reference file.
Reference file: Preprocessing/feature_order_reference.xlsx
import pandas as pd
# Load reference column order
reference = pd.read_excel('Preprocessing/feature_order_reference.xlsx')
required_columns = reference.columns.tolist()
# Arrange your data to match
your_data = your_data[required_columns]
Step 3: Choose the Appropriate Model
We provide two models depending on your data:
Model 1: With Host Context (Chromosome Length Available)
Use when: You have complete genome assemblies with chromosome information
Model: PCN_Prediction_Models/rf_model_final.pkl
Features required: K-mers + Domains + Plasmid_Length + Total_Chromosome_Length
import joblib
import pandas as pd
# Load model
model = joblib.load('PCN_Prediction_Models/rf_model_final.pkl')
# Load and arrange your data (must include chromosome length)
data = pd.read_excel('Preprocessing/feature_order_reference.xlsx')
your_data = your_data[data.columns]
# Predict
predictions = model.predict(your_data)
Model 2: Metagenomic / No Host Context (Chromosome Length Unavailable)
Use when: Working with metagenomic data or when chromosome information is not available
Model: PCN_Prediction_Models/rf_model_final_excluding_chromosome.pkl
Features required: K-mers + Domains + Plasmid_Length (NO chromosome length)
import joblib
import pandas as pd
# Load model
model = joblib.load('PCN_Prediction_Models/rf_model_final_excluding_chromosome.pkl')
# Load and arrange your data (exclude chromosome length)
# Use corresponding reference file without chromosome column
your_data = your_data[required_columns] # Without Total_Chromosome_Length
# Predict
predictions = model.predict(your_data)
Step 4: Interpret Predictions
Important: Model output is in log1p(PCN) scale.
To convert to actual copy number:
import numpy as np
# Predictions are in log1p scale
log1p_pcn = model.predict(your_data)
# Convert back to actual copy number
actual_pcn = np.expm1(log1p_pcn) # expm1(x) = exp(x) - 1
# Save results
results = pd.DataFrame({
'Plasmid_ID': your_data.index,
'Log1p_PCN': log1p_pcn,
'Predicted_Copy_Number': actual_pcn
})
results.to_csv('pcn_predictions.csv', index=False)
📊 Complete Example
See complete worked example with clinical isolate data:
- Data:
4A/Figure_4_data.zip(contains all required features) - Notebook:
4A/Clinical_isolates-PCN_predictions.ipynb
📖 Methodology
Data Source
Genome assemblies downloaded using NCBI dataset tools. Accession numbers in Preprocessing/Accessions.txt.
Plasmids filtered to match dataset from:
Reference:
Maddamsetti, R. et al. Scaling laws of bacterial and archaeal plasmids. Nature Communications 16, 6023 (2025).
Feature Engineering Pipeline
- Gene Prediction: Prodigal (
Figure_2A/Sequence_Annotation_and_Feature_Extraction/Prodigal.ipynb) - Protein Domains: HMMER/Pfam database (
Figure_2A/Sequence_Annotation_and_Feature_Extraction/Hmmscan.ipynb) - K-mer Calculation: k=1, 2, 3
- Length Features: Plasmid and chromosome lengths
Model Training
Random Forest Regressor trained on 11,000+ plasmids.
Training code: Figure_2C/Final_model_code.ipynb
📦 Required Software & Packages
Python Packages
See requirements.txt for complete list:
- pandas, numpy, scikit-learn, scipy
- matplotlib, seaborn, joblib
- biopython, ipykernel
Bioinformatics Tools
- Prodigal - Gene prediction
- HMMER - Protein domain annotation (requires Pfam database)
🗂️ Repository Structure
Plasmid_copy_number_Prediction/
│
├── README.md # This file
├── LICENSE # MIT License
├── requirements.txt # Python dependencies (pip)
├── environment.yml # Conda environment
│
├── Preprocessing/
│ ├── Accessions.txt # NCBI accession numbers
│ ├── plasmids_extraction.py # Plasmid extraction
│ └── feature_order_reference.xlsx # Required feature order
│
├── PCN_Prediction_Models/
│ ├── rf_model_final.pkl # Model 1: With chromosome
│ └── rf_model_final_excluding_chromosome.pkl # Model 2: Without chromosome
│
├── Figure_2A/Sequence_Annotation_and_Feature_Extraction/
│ ├── Prodigal.ipynb # Gene prediction workflow
│ └── Hmmscan.ipynb # Domain annotation workflow
│
├── Figure_2C/
│ └── Final_model_code.ipynb # Model training code
│
├── 4A/
│ ├── Clinical_isolates_example_data.csv # Example data
│ └── Clinical_isolates-PCN_predictions.ipynb # Usage example
│
├── Figure_1/ # Figure 1 codes, input files and outputs
├── Figure_2/ # Figure 2 codes, input files and outputs
├── Figure_3/ # Figure 3 codes, input files and outputs
├── Figure_4/ # Figure 4 codes, input files and outputs
├── Figure_5/ # Figure 5 codes, input files and outputs
└── Supplementary_figures/ # Supplementary figures codes and files