FScanpy 1.0.0__py3-none-any.whl

FScanpy/utils.py

@@ -0,0 +1,203 @@
+import numpy as np
+import pandas as pd
+from typing import Tuple, Optional
+from Bio import SeqIO
+from Bio.Seq import Seq
+
+def fscanr(blastx_output: pd.DataFrame, 
+           mismatch_cutoff: float = 10,
+           evalue_cutoff: float = 1e-5,
+           frameDist_cutoff: float = 10) -> pd.DataFrame:
+    """
+    identify PRF sites from BLASTX output
+    
+    Args:
+        blastx_output: BLASTX output DataFrame
+        mismatch_cutoff: mismatch threshold
+        evalue_cutoff: E-value threshold 
+        frameDist_cutoff: frame distance threshold
+        
+    Returns:
+        pd.DataFrame: DataFrame containing PRF site information
+    """
+    blastx = blastx_output.copy()
+    
+    blastx.columns = ["qseqid", "sseqid", "pident", "length", "mismatch", 
+                     "gapopen", "qstart", "qend", "sstart", "send", 
+                     "evalue", "bitscore", "qframe", "sframe"]
+    
+    blastx = blastx[
+        (blastx['evalue'] <= evalue_cutoff) & 
+        (blastx['mismatch'] <= mismatch_cutoff)
+    ].dropna()
+
+    freq = blastx['qseqid'].value_counts()
+    multi_hits = freq[freq > 1].index
+    blastx = blastx[blastx['qseqid'].isin(multi_hits)]
+    
+    blastx = blastx.sort_values(['qseqid', 'sseqid', 'qstart'])
+    
+    prf_list = []
+    for i in range(1, len(blastx)):
+        curr = blastx.iloc[i]
+        prev = blastx.iloc[i-1]
+        
+        if (curr['qseqid'] == prev['qseqid'] and 
+            curr['sseqid'] == prev['sseqid'] and
+            curr['qframe'] != prev['qframe'] and 
+            curr['qframe'] * prev['qframe'] > 0):
+            
+            if curr['qframe'] > 0 and prev['qframe'] > 0:
+                frame_start = prev['qend'] 
+                frame_end = curr['qstart']
+                pep_start = prev['send']
+                pep_end = curr['sstart']
+                strand = "+"
+            elif curr['qframe'] < 0 and prev['qframe'] < 0:
+                frame_start = prev['qstart']
+                frame_end = curr['qend'] 
+                pep_start = curr['send']
+                pep_end = prev['sstart']
+                strand = "-"
+            else:
+                continue
+                
+            q_dist = frame_end - frame_start - 1
+            s_dist = pep_end - pep_start
+            fs_type = q_dist + (1 - s_dist) * 3
+            
+            if (abs(q_dist) <= frameDist_cutoff and 
+                abs(s_dist) <= frameDist_cutoff // 3 and
+                -3 < fs_type < 3):
+                
+                prf_list.append({
+                    'DNA_seqid': curr['qseqid'],
+                    'FS_start': frame_start,
+                    'FS_end': frame_end,
+                    'Pep_seqid': curr['sseqid'],
+                    'Pep_FS_start': prev['send'] + 1,
+                    'Pep_FS_end': curr['sstart'],
+                    'FS_type': fs_type,
+                    'Strand': strand
+                })
+    
+    if not prf_list:
+        print("No PRF events detected!")
+        return pd.DataFrame()
+        
+    prf = pd.DataFrame(prf_list)
+    
+    for col in ['DNA_seqid', 'Pep_seqid']:
+        for pos in ['FS_start', 'FS_end']:
+            loci = prf[col] + '_' + prf[pos].astype(str)
+            prf = prf[~loci.duplicated()]
+            
+    return prf
+
+def extract_prf_regions(mrna_file: str, prf_data: pd.DataFrame) -> pd.DataFrame:
+    """
+    从mRNA序列中提取PRF位点周围的序列
+    
+    Args:
+        mrna_file: mRNA序列文件路径 (FASTA格式)
+        prf_data: FScanR输出的PRF位点数据
+        
+    Returns:
+        pd.DataFrame: 包含399bp序列的DataFrame
+    """
+    mrna_dict = {rec.id: str(rec.seq) 
+                 for rec in SeqIO.parse(mrna_file, "fasta")}
+    
+    results = []
+    for _, row in prf_data.iterrows():
+        seq_id = row['DNA_seqid']
+        if seq_id not in mrna_dict:
+            print(f"警告: {seq_id} 未在mRNA文件中找到")
+            continue
+            
+        sequence = mrna_dict[seq_id]
+        strand = row['Strand']
+        fs_start = int(row['FS_start'])
+        
+        try:
+            if strand == '-':
+                sequence = str(Seq(sequence).reverse_complement())
+            
+            # 只提取399bp序列，33bp由predictor内部截取
+            full_seq = extract_window_sequences(sequence, fs_start)[1]
+            
+            results.append({
+                'DNA_seqid': seq_id,
+                'FS_start': fs_start,
+                'FS_end': int(row['FS_end']),
+                'Strand': strand,
+                '399bp': full_seq,
+                'FS_type': row['FS_type']
+            })
+            
+        except Exception as e:
+            print(f"处理 {seq_id} 时出错: {str(e)}")
+            continue
+            
+    return pd.DataFrame(results)
+
+def extract_window_sequences(seq: str, position: int) -> Tuple[Optional[str], Optional[str]]:
+    """
+    从指定位置提取分析窗口序列
+    
+    Args:
+        seq: 输入DNA序列
+        position: 当前分析位置 (FS_start)
+    
+    Returns:
+        Tuple[str, str]: (33bp序列, 399bp序列) - 已调整为与训练模型匹配的长度
+    """
+    # 确保位置在密码子边界上（整数倍的3）
+    frame_position = position - (position % 3)
+
+    # 计算33bp窗口的起止位置 (GB模型)
+    half_size_small = 33 // 2
+    start_small = frame_position - half_size_small
+    end_small = frame_position + half_size_small + (33 % 2)  # 添加余数以处理奇数长度
+    
+    # 计算399bp窗口的起止位置 (CNN模型)
+    half_size_large = 399 // 2
+    start_large = frame_position - half_size_large
+    end_large = frame_position + half_size_large + (399 % 2)  # 添加余数以处理奇数长度
+
+    # 提取序列并填充
+    seq_small = _extract_and_pad(seq, start_small, end_small, 33)
+    seq_large = _extract_and_pad(seq, start_large, end_large, 399)
+    
+    return seq_small, seq_large
+
+def _extract_and_pad(seq: str, start: int, end: int, target_length: int) -> str:
+    """提取序列并用N填充"""
+    if start < 0:
+        prefix = 'N' * abs(start)
+        extracted = prefix + seq[:end]
+    elif end > len(seq):
+        suffix = 'N' * (end - len(seq))
+        extracted = seq[start:] + suffix
+    else:
+        extracted = seq[start:end]
+    
+    # 确保序列长度正确
+    if len(extracted) < target_length:
+        # 从中心填充
+        pad_left = (target_length - len(extracted)) // 2
+        pad_right = target_length - len(extracted) - pad_left
+        extracted = 'N' * pad_left + extracted + 'N' * pad_right
+    elif len(extracted) > target_length:
+        # 从序列两端等量截取
+        excess = len(extracted) - target_length
+        trim_each_side = excess // 2
+        extracted = extracted[trim_each_side:len(extracted)-trim_each_side]
+    
+    return extracted
+
+def prepare_cnn_input(sequence: str) -> np.ndarray:
+    """prepare CNN model input"""
+    base_to_num = {'A': 1, 'T': 2, 'G': 3, 'C': 4, 'N': 0}
+    seq_numeric = [base_to_num.get(base, 0) for base in sequence.upper()]
+    return np.array(seq_numeric).reshape(1, len(sequence), 1) 

fscanpy-1.0.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: FScanpy
+Version: 1.0.0
+Summary: Machine learning-based prediction of programmed ribosomal frameshifting sites
+Author-email: Yang Yuhao <ykongxiang@qq.com>
+Maintainer-email: Yang Yuhao <ykongxiang@qq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ykongxiang/FScanpy-package
+Project-URL: Documentation, https://github.com/ykongxiang/FScanpy-package/blob/master/tutorial/tutorial.md
+Project-URL: Repository, https://github.com/ykongxiang/FScanpy-package
+Project-URL: Issues, https://github.com/ykongxiang/FScanpy-package/issues
+Project-URL: Changelog, https://github.com/ykongxiang/FScanpy-package/blob/master/CHANGELOG.md
+Project-URL: Publication, https://doi.org/10.24272/j.issn.2095-8137.2025.648
+Keywords: bioinformatics,ribosomal-frameshifting,PRF,machine-learning,FScanR
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.3
+Requires-Dist: pandas>=2.3
+Requires-Dist: scikit-learn==1.7.2
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: joblib>=1.5
+Requires-Dist: biopython>=1.85
+Requires-Dist: torch>=2.5
+Requires-Dist: openpyxl
+Dynamic: license-file
+
+# FScanpy
+## A Machine Learning-Based Framework for Programmed Ribosomal Frameshifting Prediction
+
+[![中文](https://img.shields.io/badge/Language-中文-red.svg)](https://github.com/ykongxiang/FScanpy-package/blob/master/README_zh.md)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/ykongxiang/FScanpy-package/blob/master/LICENSE)
+
+FScanpy is a comprehensive Python package designed for the prediction of [Programmed Ribosomal Frameshifting (PRF)](https://en.wikipedia.org/wiki/Ribosomal_frameshift) sites in nucleotide sequences. By integrating advanced machine learning approaches (HistGradientBoosting and BiLSTM-CNN) with the established [FScanR](https://github.com/seanchen607/FScanR.git) framework, FScanpy provides robust and accurate PRF site predictions.
+
+![FScanpy Architecture](https://raw.githubusercontent.com/ykongxiang/FScanpy-package/master/tutorial/image/structure.jpg)
+
+## 🔧 Installation
+
+### Prerequisites
+- Python ≥ 3.11
+- All dependencies are automatically installed
+
+### Install via pip (Recommended)
+```bash
+pip install FScanpy
+```
+
+### Install from Source
+```bash
+git clone https://github.com/ykongxiang/FScanpy-package.git
+cd FScanpy-package
+pip install -e .
+```
+
+### Jupyter Notebook
+
+From the cloned package directory, install into the Python environment you will use for Jupyter:
+
+```bash
+python -m pip install . notebook ipykernel
+python -m ipykernel install --sys-prefix --name fscanpy --display-name "Python (FScanpy)"
+python -m notebook
+```
+
+Open `FScanpy_Demo.ipynb` or `tutorial/predict_sample.ipynb`, select **Python (FScanpy)**, then restart the kernel and run all cells. The API overview in the demo is explanatory Markdown; the runnable examples use the bundled data. If installing into an already open notebook, use `%pip install /path/to/FScanpy-package` and restart the kernel.
+
+## 🚀 Quick Start
+
+### Basic Usage
+```python
+from FScanpy import predict_prf
+
+# Simple sequence prediction
+sequence = "ATGCGTACGTTAGC"*100 # Your DNA sequence
+results = predict_prf(sequence=sequence)
+
+# View top predictions
+print(results[['Position', 'Ensemble_Probability', 'Short_Probability', 'Long_Probability']].head(10))
+```
+
+### Visualization
+```python
+from FScanpy import plot_prf_prediction
+
+# Generate prediction plot
+results, fig = plot_prf_prediction(
+    sequence=sequence,
+    short_threshold=0.65,    # HistGB threshold
+    long_threshold=0.8,      # BiLSTM-CNN threshold
+    ensemble_weight=0.4,     # 40% Short, 60% Long
+    title="PRF Prediction Results"
+)
+```
+
+### Advanced Usage
+```python
+from FScanpy import PRFPredictor
+import pandas as pd
+
+# Create predictor instance
+predictor = PRFPredictor()
+
+# Batch prediction on pre-extracted regions
+data = pd.DataFrame({
+    'Long_Sequence': ['ATG' * 133, 'GCT' * 133]  # 399bp sequences
+})
+results = predictor.predict_regions(data, ensemble_weight=0.4)
+
+# Sequence-level prediction with custom parameters
+results = predictor.predict_sequence(
+    sequence=sequence,
+    window_size=1,           # Step size for sliding window
+    ensemble_weight=0.3,     # Model weighting
+    short_threshold=0.5      # Filtering threshold
+)
+```
+
+## 🎛️ Ensemble Weight Configuration
+
+The `ensemble_weight` parameter controls the weight ratio between HistGB and BiLSTM-CNN models:
+
+| ensemble_weight | HistGB Model | BiLSTM-CNN Model | Characteristics | Best For |
+|----------------|-------------|------------------|-----------------|----------|
+| **0.2-0.3** | 20-30% | 70-80% | **High specificity**, reduces false positives | Precise validation, clinical applications |
+| **0.4** | 40% | 60% | **Optimal balance**, highest AUC | Standard analysis (recommended) |
+| **0.6-0.8** | 60-80% | 20-40% | **High sensitivity**, captures more sites | High-throughput screening, exploratory research |
+
+
+### Weight Selection Examples
+```python
+# High specificity configuration (favoring HistGB)
+precise_results = predict_prf(sequence, ensemble_weight=0.25)
+
+# Optimal balance configuration (4:6 ratio)
+balanced_results = predict_prf(sequence, ensemble_weight=0.4)
+
+# High sensitivity configuration (favoring BiLSTM-CNN)
+sensitive_results = predict_prf(sequence, ensemble_weight=0.7)
+```
+
+## 📊 Core Functions
+
+### Main Prediction Interface
+```python
+predict_prf(
+    sequence=None,           # Single/multiple sequences or None
+    data=None,              # DataFrame with 399bp sequences or None
+    window_size=3,          # Sliding window step size
+    short_threshold=0.1,    # Short model filtering threshold
+    ensemble_weight=0.4,    # Short model weight (0.0-1.0)
+    model_dir=None         # Custom model directory
+)
+```
+
+### Visualization Function
+```python
+plot_prf_prediction(
+    sequence,               # Input DNA sequence
+    window_size=3,          # Scanning step size
+    short_threshold=0.65,   # Short model threshold for plotting
+    long_threshold=0.8,     # Long model threshold for plotting
+    ensemble_weight=0.4,    # Model weighting
+    title=None,            # Plot title
+    save_path=None,        # Save file path
+    figsize=(12,8),        # Figure size
+    dpi=300               # Resolution for saved plots
+)
+```
+
+### PRFPredictor Class Methods
+```python
+predictor = PRFPredictor()
+
+# Sequence prediction (sliding window)
+predictor.predict_sequence(sequence, ensemble_weight=0.4)
+
+# Region prediction (batch processing)
+predictor.predict_regions(dataframe, ensemble_weight=0.4)
+
+# Feature extraction
+predictor.extract_features(sequences)
+
+# Model information
+predictor.get_model_info()
+```
+
+## 📈 Output Fields
+
+### Prediction Results
+- **`Position`**: Position in the original sequence
+- **`Ensemble_Probability`**: Final ensemble prediction (main result)
+- **`Short_Probability`**: HistGradientBoosting prediction (0-1)
+- **`Long_Probability`**: BiLSTM-CNN prediction (0-1)
+- **`Ensemble_Weights`**: Model weight configuration used
+
+### Sequence Information
+- **`Short_Sequence`**: 33bp sequence for Short model
+- **`Long_Sequence`**: 399bp sequence for Long model  
+- **`Codon`**: 3bp codon at the prediction position
+- **`Sequence_ID`**: Identifier for multi-sequence inputs
+
+## 🔬 Integration with FScanR
+
+FScanpy works seamlessly with the FScanR pipeline for comprehensive PRF analysis:
+
+```python
+from FScanpy import fscanr, extract_prf_regions, predict_prf
+
+# Step 1: BLASTX analysis with FScanR
+blastx_results = fscanr(
+    blastx_data,
+    mismatch_cutoff=10,
+    evalue_cutoff=1e-5,
+    frameDist_cutoff=10
+)
+
+# Step 2: Extract PRF candidate regions
+prf_regions = extract_prf_regions(original_sequence, blastx_results)
+
+# Step 3: Predict with FScanpy
+final_predictions = predict_prf(data=prf_regions, ensemble_weight=0.4)
+```
+
+## 📚 Documentation
+
+- **[Complete Tutorial](https://github.com/ykongxiang/FScanpy-package/blob/master/tutorial/tutorial.md)**: Comprehensive usage guide with examples
+- **[Demo Notebook](https://github.com/ykongxiang/FScanpy-package/blob/master/FScanpy_Demo.ipynb)**: Practical usage of each function in the library and demonstration of analysis workflow results
+- **[Predict Sample Interpretation](https://github.com/ykongxiang/FScanpy-package/blob/master/tutorial/predict_sample.ipynb)**: Detailed interpretation of FScanpy's plotting results and signal analysis
+
+## 📝 Citation
+
+If you use FScanpy in your research, please cite:
+
+```bibtex
+@article{yang2026deciphering,
+
+  author    = {Yang, Yu-Hao and Yang, Juan and Liu, Zi-Jia and Li, Yuan and Song, Weibo and Stover, Naomi and Chen, Xiao},
+
+  title     = {Deciphering ribosomal frameshifting determinants across species with a semi-supervised hybrid learning framework},
+
+  journal   = {Zoological Research},
+
+  doi       = {10.24272/j.issn.2095-8137.2025.648},
+
+  url       = {https://doi.org/10.24272/j.issn.2095-8137.2025.648}
+
+}
+```
+
+
+**FScanpy** - Advancing programmed ribosomal frameshifting research through machine learning 🧬
+
+## Maintainer and License
+
+Primary maintainer: **Yang Yuhao** ([ykongxiang@qq.com](mailto:ykongxiang@qq.com)).
+
+FScanpy is distributed under the [MIT License](https://github.com/ykongxiang/FScanpy-package/blob/master/LICENSE). See the [changelog](https://github.com/ykongxiang/FScanpy-package/blob/master/CHANGELOG.md) for version 1.0.0 changes.

fscanpy-1.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+FScanpy/__init__.py,sha256=mXZ6goG_0fW4Sbfx_D73KsnEdAWe1lbdl_nq-3SVpTI,8241
+FScanpy/predictor.py,sha256=KucUuuUW5TvPL34iPf-plfFiAIy9wcWp0Sk6HCwtZqc,28270
+FScanpy/utils.py,sha256=fidcKoTWNovG91jX8_cWrpgPyoVy3gwSKU6JrP3oFGU,7268
+FScanpy/data/__init__.py,sha256=In_VmR8joAx1cgiw4nwLjxLa-_4Yz6N3W71hei2FVbk,4046
+FScanpy/data/test_data/blastx_example.xlsx,sha256=pA5rfQzIAHq2P6EsxekDswmgbobkM0ofVzr7AEkW6Cs,98992
+FScanpy/data/test_data/full_seq.xlsx,sha256=6iiQPjdlFeTRR2pP1k5-fC8Y_HbznoTOKs32NeKjXg8,12835
+FScanpy/data/test_data/mrna_example.fasta,sha256=KA8WgICvYoGGyf9d2LvP6troa86gmC__sgAluNGg8ZQ,2992403
+FScanpy/data/test_data/region_example.csv,sha256=jZm-wu1JHStRdxFhKiLEkkAykbTeFJglfPfbgdZ0cBE,1514
+FScanpy/features/__init__.py,sha256=lTr7l2vWZWSgzrK0s0dIQ4OPyfXX54rKbGR3xmCPHy0,152
+FScanpy/features/cnn_input.py,sha256=0GL4InzOUmmQ_CwrgfZ_GxsvtoeQdhZBedEr7gsQWUo,2855
+FScanpy/features/sequence.py,sha256=2GtLLiHMZ1yW_KHv9Kk13fVNpzBcO6p8dTN_JYVO7oA,10939
+FScanpy/pretrained/long.pth,sha256=Egf6tqgMn4-Iezv_IGLZ6yDfljh9cCBxQoaPvmXE_Uo,39531146
+FScanpy/pretrained/short.pkl,sha256=AGVwsi6lIdbDBrXMkQ7QZ-n0Zt55HLWB3AOKclHAiZY,283657
+fscanpy-1.0.0.dist-info/licenses/LICENSE,sha256=Q2KsPV2-icUm7EvGt_GUkE5OmSgcnyktBPIFk-8LPQY,1092
+fscanpy-1.0.0.dist-info/METADATA,sha256=981uXrQpb-quEN3-JB60O72aW91ZTMqCtt4Wuj6E6lA,9912
+fscanpy-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fscanpy-1.0.0.dist-info/top_level.txt,sha256=5qIFIGC8pZHgM5MEkYh2EtQpBU0wUhRzbVktnX7hNjY,8
+fscanpy-1.0.0.dist-info/RECORD,,

fscanpy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fscanpy-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yang Yuhao and FScanpy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fscanpy-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+FScanpy