FScanpy 1.0.0__tar.gz → 1.0.1__tar.gz

{fscanpy-1.0.0 → fscanpy-1.0.1}/CHANGELOG.md

@@ -1,19 +1,19 @@
-# Changelog
-
-## 1.0.0
-
-### Fixed
-- Include pretrained model weights and example data in package distributions.
-- Locate bundled models without the deprecated `pkg_resources` API.
-- Load PyTorch checkpoints with `weights_only=True` and pin scikit-learn to 1.7.2 for the bundled short model.
-- Accept region DataFrames containing `Long_Sequence` or `399bp`.
-- Accept pathlib paths when saving prediction plots.
-- Export `fscanr` and `extract_prf_regions` from the public package API.
-- Repair notebook examples and document Jupyter installation.
-
-### Added
-- Package regression tests and a notebook validation runner.
-- PyPI project metadata, maintainer contact, MIT license file, and project links.
-
-### Changed
-- Align the package's reported version with distribution version 1.0.0.
+# Changelog
+
+## 1.0.0
+
+### Fixed
+- Include pretrained model weights and example data in package distributions.
+- Locate bundled models without the deprecated `pkg_resources` API.
+- Load PyTorch checkpoints with `weights_only=True` and pin scikit-learn to 1.7.2 for the bundled short model.
+- Accept region DataFrames containing `Long_Sequence` or `399bp`.
+- Accept pathlib paths when saving prediction plots.
+- Export `fscanr` and `extract_prf_regions` from the public package API.
+- Repair notebook examples and document Jupyter installation.
+
+### Added
+- Package regression tests and a notebook validation runner.
+- PyPI project metadata, maintainer contact, MIT license file, and project links.
+
+### Changed
+- Align the package's reported version with distribution version 1.0.0.

{fscanpy-1.0.0 → fscanpy-1.0.1}/FScanpy/__init__.py

@@ -1,15 +1,15 @@
-from .predictor import PRFPredictor
+from .predictor import PRFPredictor, plot_prediction_results, plot_prediction_regions
 from . import data
 from .utils import fscanr, extract_prf_regions
 import pandas as pd
 import numpy as np
 from typing import Union, List, Dict
 
-__version__ = '1.0.0'
-__author__ = 'Yang Yuhao'
-__email__ = 'ykongxiang@qq.com'
+__version__ = '1.0.1'
+__author__ = 'Yang Yuhao'
+__email__ = 'ykongxiang@qq.com'
 
-__all__ = ['PRFPredictor', 'predict_prf', 'plot_prf_prediction', 'fscanr', 'extract_prf_regions', 'data', '__version__', '__author__', '__email__']
+__all__ = ['PRFPredictor', 'predict_prf', 'plot_prf_prediction', 'plot_prediction_results', 'plot_prediction_regions', 'fscanr', 'extract_prf_regions', 'data', '__version__', '__author__', '__email__']
 
 def predict_prf(
     sequence: Union[str, List[str], None] = None,
@@ -21,35 +21,35 @@ def predict_prf(
 ) -> pd.DataFrame:
     """
     PRF site prediction function
-    
+
     Args:
         sequence: Single or multiple DNA sequences for sliding window prediction
         data: DataFrame data, must contain 'Long_Sequence' or '399bp' column for region prediction
-        window_size: Sliding window size (default: 3)
+        window_size: Scanning interval in nucleotides (default: 3)
         short_threshold: Short model (HistGB) probability threshold (default: 0.1)
         ensemble_weight: Weight of short model in ensemble (default: 0.4, long weight: 0.6)
         model_dir: Model directory path (optional)
-    
+
     Returns:
         pandas.DataFrame: Prediction results containing the following main fields:
             - Short_Probability: Short model prediction probability
-            - Long_Probability: Long model prediction probability  
+            - Long_Probability: Long model prediction probability
             - Ensemble_Probability: Ensemble prediction probability (main result)
             - Ensemble_Weights: Weight configuration information
-        
+
     Examples:
         # 1. Single sequence sliding window prediction
         >>> from FScanpy import predict_prf
         >>> sequence = "ATGCGTACGT..."
         >>> results = predict_prf(sequence=sequence)
-        
+
         # 2. Multiple sequences sliding window prediction
         >>> sequences = ["ATGCGTACGT...", "GCTATAGCAT..."]
         >>> results = predict_prf(sequence=sequences)
-        
+
         # 3. Custom ensemble weight ratio
         >>> results = predict_prf(sequence=sequence, ensemble_weight=0.3)  # 3:7 ratio
-        
+
         # 4. DataFrame region prediction
         >>> import pandas as pd
         >>> data = pd.DataFrame({
@@ -57,8 +57,6 @@ def predict_prf(
         ... })
         >>> results = predict_prf(data=data)
     """
-    predictor = PRFPredictor(model_dir=model_dir)
-    
     # Validate input parameters
     if sequence is None and data is None:
         raise ValueError("Must provide either sequence or data parameter")
@@ -66,7 +64,9 @@ def predict_prf(
         raise ValueError("Cannot provide both sequence and data parameters")
     if not (0.0 <= ensemble_weight <= 1.0):
         raise ValueError("ensemble_weight must be between 0.0 and 1.0")
-    
+
+    predictor = PRFPredictor(model_dir=model_dir)
+
     # Sliding window prediction mode
     if sequence is not None:
         if isinstance(sequence, str):
@@ -83,14 +83,16 @@ def predict_prf(
                     result['Sequence_ID'] = f'seq_{i}'
                     results.append(result)
                 except Exception as e:
-                    print(f"Warning: Sequence {i} prediction failed - {str(e)}")
+                    raise RuntimeError(f"Prediction failed for sequence {i}: {e}") from e
             return pd.concat(results, ignore_index=True) if results else pd.DataFrame()
-    
+        else:
+            raise ValueError("sequence must be a string or a list/tuple of strings")
+
     # Region prediction mode
     else:
         if not isinstance(data, pd.DataFrame):
             raise ValueError("data parameter must be pandas DataFrame type")
-        
+
         # Check column names (support both new and old naming conventions)
         seq_column = None
         if 'Long_Sequence' in data.columns:
@@ -99,35 +101,14 @@ def predict_prf(
             seq_column = '399bp'
         else:
             raise ValueError("DataFrame must contain 'Long_Sequence' or '399bp' column")
-        
-        # Call region prediction function
-        try:
-            results = predictor.predict_regions(
-                data[seq_column], short_threshold, ensemble_weight)
-                
-            # Add other columns from original data
-            for col in data.columns:
-                if col not in ['Long_Sequence', '399bp', 'Short_Sequence', '33bp']:
-                    results[col] = data[col].values
-                    
-            return results
-            
-        except Exception as e:
-            print(f"Warning: Region prediction failed - {str(e)}")
-            # Create empty results
-            long_weight = 1.0 - ensemble_weight
-            results = pd.DataFrame({
-                'Short_Probability': [0.0] * len(data),
-                'Long_Probability': [0.0] * len(data),
-                'Ensemble_Probability': [0.0] * len(data),
-                'Ensemble_Weights': [f'Short:{ensemble_weight:.1f}, Long:{long_weight:.1f}'] * len(data)
-            })
-            
-            # Add original data columns
-            for col in data.columns:
-                results[col] = data[col].values
-                
-            return results
+
+        results = predictor.predict_regions(data[seq_column], short_threshold, ensemble_weight)
+        # Preserve metadata without allowing stale scores to replace model output.
+        for column in data.columns:
+            if column not in results.columns and column not in ['Long_Sequence', '399bp', 'Short_Sequence', '33bp']:
+                results[column] = data[column].values
+        return results
+
 
 def plot_prf_prediction(
     sequence: str,
@@ -139,14 +120,18 @@ def plot_prf_prediction(
     save_path: str = None,
     figsize: tuple = (12, 8),
     dpi: int = 300,
-    model_dir: str = None
+    model_dir: str = None,
+    *,
+    reference_positions=None,
+    heatmap_ratios=(0.1, 0.1, 1),
+    candidate_threshold=0.8
 ) -> tuple:
     """
     Plot PRF prediction results for sequence frameshifting probability
-    
+
     Args:
         sequence: Input DNA sequence
-        window_size: Sliding window size (default: 3)
+        window_size: Scanning interval in nucleotides (default: 3)
         short_threshold: Short model (HistGB) filtering threshold (default: 0.65)
         long_threshold: Long model (BiLSTM-CNN) filtering threshold (default: 0.8)
         ensemble_weight: Weight of short model in ensemble (default: 0.4, long weight: 0.6)
@@ -154,34 +139,37 @@ def plot_prf_prediction(
         save_path: Save path (optional, saves plot if provided)
         figsize: Figure size (default: (12, 8))
         dpi: Figure resolution (default: 300)
+        reference_positions: Optional independently supplied 0-based reference coordinates
+        heatmap_ratios: Three panel heights; use (0.35, 0.35, 2.8) for thick heatmaps
+        candidate_threshold: Ensemble cutoff for predicted candidate marks (default: 0.8)
         model_dir: Model directory path (optional)
-    
+
     Returns:
         tuple: (pd.DataFrame, matplotlib.figure.Figure) prediction results and figure object
-        
+
     Examples:
         # 1. Simple plotting
         >>> from FScanpy import plot_prf_prediction
         >>> sequence = "ATGCGTACGT..."
         >>> results, fig = plot_prf_prediction(sequence)
         >>> plt.show()
-        
+
         # 2. Custom thresholds and ensemble weights
         >>> results, fig = plot_prf_prediction(
-        ...     sequence, 
-        ...     short_threshold=0.7, 
+        ...     sequence,
+        ...     short_threshold=0.7,
         ...     long_threshold=0.85,
         ...     ensemble_weight=0.3,  # 3:7 weight ratio
         ...     title="Custom Weight Prediction Results",
         ...     save_path="prediction_result.png"
         ... )
-        
+
         # 3. Equal weight combination
         >>> results, fig = plot_prf_prediction(
         ...     sequence,
         ...     ensemble_weight=0.5  # 5:5 equal weights
         ... )
-        
+
         # 4. Long model dominated
         >>> results, fig = plot_prf_prediction(
         ...     sequence,
@@ -190,9 +178,9 @@ def plot_prf_prediction(
     """
     if not (0.0 <= ensemble_weight <= 1.0):
         raise ValueError("ensemble_weight must be between 0.0 and 1.0")
-    
+
     predictor = PRFPredictor(model_dir=model_dir)
-    
+
     return predictor.plot_sequence_prediction(
         sequence=sequence,
         window_size=window_size,
@@ -202,5 +190,8 @@ def plot_prf_prediction(
         title=title,
         save_path=save_path,
         figsize=figsize,
-        dpi=dpi
+        dpi=dpi,
+        reference_positions=reference_positions,
+        heatmap_ratios=heatmap_ratios,
+        candidate_threshold=candidate_threshold
     )

fscanpy-1.0.1/FScanpy/features/cnn_input.py

@@ -0,0 +1,24 @@
+import numpy as np
+from typing import List, Union
+
+class CNNInputProcessor:
+    """CNN模型输入数据处理器"""
+    
+    def __init__(self, max_length: int = 399):
+        self.max_length = max_length
+        self.base_to_num = {'A': 0, 'T': 1, 'C': 2, 'G': 3, 'N': 4} 
+    
+    def trim_sequence(self, seq, target_length):
+        """Center-crop to exactly target_length, removing an odd extra base on the right."""
+        if len(seq) <= target_length:
+            return seq
+        start = (len(seq) - target_length) // 2
+        return seq[start:start + target_length]
+    
+    def prepare_sequence(self, sequence: str) -> np.ndarray:
+        """Encode an exactly sized input; U is treated as T and unknown bases as N."""
+        sequence = str(sequence).upper().replace('U', 'T')
+        sequence = self.trim_sequence(sequence, self.max_length)
+        encoded = [self.base_to_num.get(base, 4) for base in sequence]
+        encoded.extend([4] * (self.max_length - len(encoded)))
+        return np.array(encoded).reshape(1, self.max_length, 1)

fscanpy-1.0.1/FScanpy/features/sequence.py

@@ -0,0 +1,171 @@
+import numpy as np
+import pandas as pd
+import itertools
+from typing import List, Dict, Union
+
+class SequenceFeatureExtractor:
+    """DNA序列特征提取器"""
+    
+    def __init__(self, seq_length=33):
+        """初始化特征提取器"""
+        self.bases = ['A', 'T', 'G', 'C']
+        self.valid_bases = set('ATGCN')
+        self.seq_length = seq_length  # 添加序列长度配置
+        self.feature_names = self._get_feature_names()
+    
+    def _get_feature_names(self) -> List[str]:
+        """
+        返回特征名称列表，包含所有可能的碱基特征
+        
+        Returns:
+            features: 特征名称列表
+        """
+        features = []
+
+        # 基础特征 (包含N)
+        bases = ['A', 'T', 'G', 'C', 'N']
+        features.extend(bases)
+
+        # 3-mer特征
+        kmers_3 = [''.join(p) for p in itertools.product(bases, repeat=3)]  # 125个特征
+        features.extend(kmers_3)
+
+        # 密码子特征
+        codons = [''.join(p) for p in itertools.product(['A', 'T', 'G', 'C'], repeat=3)]  # 64个密码子
+        n_codons = self.seq_length // 3  # 计算序列中包含的完整密码子数量
+        for i in range(n_codons):
+            for codon in codons:
+                features.append(f'codon_pos_{i}_{codon}')
+
+        # GC含量特征
+        features.append('gc_content')
+
+        # 序列复杂度特征
+        features.append('sequence_complexity')
+
+        return features
+
+    def trim_sequence(self, seq, target_length):
+        """Center-crop to exactly target_length, removing an odd extra base on the right."""
+        if len(seq) <= target_length:
+            return seq
+        start = (len(seq) - target_length) // 2
+        return seq[start:start + target_length]
+    
+    def _preprocess_sequence(self, sequence):
+        """
+        将DNA序列转换为特征向量
+        
+        Args:
+            sequence: DNA序列
+            
+        Returns:
+            feature_vector: 特征向量
+        """
+        try:
+            feature_names = self.feature_names
+            
+            if pd.isna(sequence) or not isinstance(sequence, str):
+                sequence = str(sequence)
+            sequence = sequence.upper().replace('U', 'T')  # 统一为大写字母
+            sequence = ''.join(base if base in self.valid_bases else 'N' for base in sequence)
+
+            # 如果序列长度不等于目标长度，进行截取或填充
+            if len(sequence) > self.seq_length:
+                sequence = self.trim_sequence(sequence, self.seq_length)
+            else:
+                sequence = sequence[:self.seq_length].ljust(self.seq_length, 'N')
+
+            # 初始化特征字典
+            features = {
+                'A': 0,
+                'T': 0,
+                'G': 0,
+                'C': 0,
+                'N': 0
+            }
+            kmer_features = {}
+
+            # 碱基组成
+            for base in ['A', 'T', 'G', 'C', 'N']:
+                features[base] = sequence.count(base) / self.seq_length
+
+            # 3-mer特征
+            for kmer in [''.join(p) for p in itertools.product(['A', 'T', 'G', 'C', 'N'], repeat=3)]:
+                kmer_count = 0
+                for i in range(self.seq_length - 2):
+                    if sequence[i:i+3] == kmer:
+                        kmer_count += 1
+                kmer_features[kmer] = kmer_count / max(1, self.seq_length - 2)
+
+            # 密码子特征
+            codon_features = {}
+            codons = [''.join(p) for p in itertools.product(['A', 'T', 'G', 'C'], repeat=3)]  # 64个密码子
+            n_codons = self.seq_length // 3  # 计算序列中包含的完整密码子数量
+            for i in range(n_codons):
+                pos_start = i * 3
+                current_codon = sequence[pos_start:pos_start+3]
+                for codon in codons:
+                    codon_features[f'codon_pos_{i}_{codon}'] = 1 if current_codon == codon and 'N' not in current_codon else 0
+
+            # GC含量
+            valid_bases = [b for b in sequence if b != 'N']
+            gc_content = (valid_bases.count('G') + valid_bases.count('C')) / len(valid_bases) if valid_bases else 0
+
+            # 序列复杂度（Shannon熵）
+            from collections import Counter
+            valid_counts = Counter(valid_bases)
+            total_valid = sum(valid_counts.values())
+            entropy = 0
+            for cnt in valid_counts.values():
+                p = cnt / total_valid
+                entropy += -p * np.log2(p)
+            entropy /= np.log2(4)  # 归一化到0-1
+
+            # 合并所有特征
+            all_features = {**features, **kmer_features, **codon_features}
+            all_features['gc_content'] = gc_content
+            all_features['sequence_complexity'] = entropy
+
+            # 确保特征顺序一致
+            feature_vector = [all_features.get(f, 0.0) for f in feature_names]
+
+            return feature_vector
+        except Exception as e:
+            raise ValueError(f"特征提取失败: {str(e)}")
+    
+    def extract_features_batch(self, sequences: List[Union[str, float]]) -> np.ndarray:
+        """
+        批量提取特征
+        
+        Args:
+            sequences: DNA序列列表
+            
+        Returns:
+            np.ndarray: 特征矩阵
+        """
+        try:
+            return np.array([self.extract_features(seq) for seq in sequences])
+        except Exception as e:
+            raise ValueError(f"批量特征提取失败: {str(e)}")
+    
+    def predict_region_batch(self, data: pd.DataFrame, gb_threshold: float = 0.1) -> pd.DataFrame:
+        """Deprecated compatibility wrapper for the public region predictor.
+
+        Uses the central 33 bp of Long_Sequence/399bp through predict_prf;
+        feature extraction itself does not own classification models.
+        """
+        import warnings
+        from .. import predict_prf
+        warnings.warn('Use PRFPredictor.predict_regions() or predict_prf(data=...) instead',
+                      DeprecationWarning, stacklevel=2)
+        return predict_prf(data=data, short_threshold=gb_threshold)
+
+    def extract_features(self, sequence: str) -> list:
+        """Return the trained feature dimensions after trimming or N-padding the input.
+
+        This shares the preprocessing used by batch feature extraction, including
+        U-to-T normalization. Short inputs are right-padded to ``seq_length``.
+        Feature extraction errors are raised rather than replaced by zero vectors.
+        """
+        return self._preprocess_sequence(sequence)