@bgicli/bgicli 2.1.1 → 2.2.0

package/data/workflows/pcr-primer-design/scripts/calculate_tm.py

@@ -0,0 +1,306 @@
+"""
+Calculate melting temperatures using multiple methods.
+
+This module provides functions for calculating primer Tm using various
+algorithms and salt correction methods.
+"""
+
+import primer3
+from Bio.SeqUtils import MeltingTemp as mt
+from Bio.Seq import Seq
+from typing import Dict
+
+
+def calculate_tm_comprehensive(
+    primer_sequence: str,
+    method: str = "nearest_neighbor",
+    salt_conc: float = 50.0,
+    dna_conc: float = 200.0,
+    mg_conc: float = 0.0,
+    dntp_conc: float = 0.0
+) -> Dict:
+    """
+    Calculate melting temperature using multiple methods.
+
+    Parameters
+    ----------
+    primer_sequence : str
+        Primer sequence
+    method : str
+        Tm calculation method:
+        - "nearest_neighbor" (most accurate, default)
+        - "salt_adjusted" (salt-adjusted formula)
+        - "gc_content" (simple GC% method)
+        - "all" (calculate using all methods)
+    salt_conc : float
+        Monovalent cation (Na+, K+) concentration in mM. Default: 50.0
+    dna_conc : float
+        DNA/primer concentration in nM. Default: 200.0
+    mg_conc : float
+        Mg2+ concentration in mM. Default: 0.0
+    dntp_conc : float
+        dNTP concentration in mM. Default: 0.0
+
+    Returns
+    -------
+    dict
+        Dictionary with Tm values from different methods
+
+    Example
+    -------
+    >>> tm_results = calculate_tm_comprehensive(
+    ...     "ATGCGTACGATCGATCG",
+    ...     method="all",
+    ...     salt_conc=50.0
+    ... )
+    >>> print(f"Nearest-Neighbor Tm: {tm_results['tm_nn']:.1f}°C")
+    """
+
+    # Validate input
+    primer_sequence = primer_sequence.upper().strip()
+
+    if not all(base in 'ATCGN' for base in primer_sequence):
+        raise ValueError("Primer must contain only A, T, C, G, or N")
+
+    if len(primer_sequence) < 10:
+        raise ValueError("Primer too short for accurate Tm calculation (minimum 10 bp)")
+
+    results = {
+        'primer_sequence': primer_sequence,
+        'primer_length': len(primer_sequence),
+    }
+
+    # Method 1: Nearest-Neighbor (most accurate)
+    if method in ["nearest_neighbor", "all"]:
+        # Using primer3
+        tm_nn_primer3 = primer3.calcTm(
+            primer_sequence,
+            mv_conc=salt_conc,
+            dv_conc=mg_conc,
+            dntp_conc=dntp_conc,
+            dna_conc=dna_conc
+        )
+        results['tm_nn'] = round(tm_nn_primer3, 2)
+        results['method_nn'] = "Primer3 (SantaLucia 1998)"
+
+        # Also calculate using Biopython for comparison
+        try:
+            tm_nn_biopython = mt.Tm_NN(
+                Seq(primer_sequence),
+                Na=salt_conc,
+                Mg=mg_conc,
+                dNTPs=dntp_conc,
+                saltcorr=7  # Owczarzy et al. 2008
+            )
+            results['tm_nn_biopython'] = round(tm_nn_biopython, 2)
+        except:
+            pass
+
+    # Method 2: Salt-adjusted formula
+    if method in ["salt_adjusted", "all"]:
+        # Wallace rule with salt adjustment
+        # Tm = 2(A+T) + 4(G+C) - 16.6*log10[Na+] + 0.41(%GC)
+        gc_count = primer_sequence.count('G') + primer_sequence.count('C')
+        at_count = primer_sequence.count('A') + primer_sequence.count('T')
+        gc_percent = (gc_count / len(primer_sequence)) * 100
+
+        import math
+        tm_basic = 2 * at_count + 4 * gc_count
+        salt_correction = 16.6 * math.log10(salt_conc / 1000.0)  # Convert mM to M
+        gc_correction = 0.41 * gc_percent
+
+        tm_salt_adjusted = tm_basic - salt_correction + gc_correction
+        results['tm_salt_adjusted'] = round(tm_salt_adjusted, 2)
+        results['method_salt'] = "Wallace with salt correction"
+
+    # Method 3: Simple GC content
+    if method in ["gc_content", "all"]:
+        gc_count = primer_sequence.count('G') + primer_sequence.count('C')
+        at_count = primer_sequence.count('A') + primer_sequence.count('T')
+
+        # Basic Wallace rule: Tm = 2(A+T) + 4(G+C)
+        tm_gc = 2 * at_count + 4 * gc_count
+        results['tm_gc'] = round(tm_gc, 2)
+        results['method_gc'] = "Wallace rule (GC content)"
+
+    # Method 4: %GC-based formula (for primers >13 bp)
+    if method in ["all"] and len(primer_sequence) > 13:
+        gc_count = primer_sequence.count('G') + primer_sequence.count('C')
+        gc_percent = (gc_count / len(primer_sequence)) * 100
+
+        # Tm = 64.9 + 41*(G+C-16.4)/(A+T+G+C)
+        tm_percent = 64.9 + 41 * (gc_percent - 16.4) / 100
+        results['tm_percent'] = round(tm_percent, 2)
+        results['method_percent'] = "%GC formula"
+
+    # Add parameters used
+    results['parameters'] = {
+        'salt_conc_mM': salt_conc,
+        'dna_conc_nM': dna_conc,
+        'mg_conc_mM': mg_conc,
+        'dntp_conc_mM': dntp_conc,
+    }
+
+    # Add recommendation
+    if method == "all":
+        results['recommended_tm'] = results.get('tm_nn', results.get('tm_salt_adjusted'))
+        results['recommendation'] = "Use nearest-neighbor (tm_nn) for most accurate results"
+
+    return results
+
+
+def calculate_tm_range(
+    primer_list: list,
+    method: str = "nearest_neighbor",
+    **kwargs
+) -> Dict:
+    """
+    Calculate Tm for multiple primers and return range.
+
+    Parameters
+    ----------
+    primer_list : list of str
+        List of primer sequences
+    method : str
+        Tm calculation method
+    **kwargs
+        Additional parameters for calculate_tm_comprehensive
+
+    Returns
+    -------
+    dict
+        Dictionary with Tm values and statistics
+
+    Example
+    -------
+    >>> primers = ["ATGCGTACG...", "CGTAGCTA...", "GCTATCGA..."]
+    >>> tm_range = calculate_tm_range(primers)
+    >>> print(f"Tm range: {tm_range['tm_min']}°C - {tm_range['tm_max']}°C")
+    """
+
+    tm_values = []
+    primer_tms = []
+
+    for primer in primer_list:
+        tm_result = calculate_tm_comprehensive(primer, method=method, **kwargs)
+        tm_key = 'tm_nn' if method == "nearest_neighbor" else f'tm_{method}'
+        tm = tm_result.get(tm_key)
+
+        if tm is not None:
+            tm_values.append(tm)
+            primer_tms.append({
+                'sequence': primer,
+                'tm': tm,
+            })
+
+    if not tm_values:
+        raise ValueError("Could not calculate Tm for any primers")
+
+    tm_min = min(tm_values)
+    tm_max = max(tm_values)
+    tm_mean = sum(tm_values) / len(tm_values)
+    tm_range = tm_max - tm_min
+
+    return {
+        'num_primers': len(primer_list),
+        'primer_tms': primer_tms,
+        'tm_min': round(tm_min, 2),
+        'tm_max': round(tm_max, 2),
+        'tm_mean': round(tm_mean, 2),
+        'tm_range': round(tm_range, 2),
+        'tm_compatible': tm_range <= 5.0,  # All primers within 5°C
+        'method': method,
+    }
+
+
+def optimize_tm(
+    primer_sequence: str,
+    target_tm: float,
+    tolerance: float = 2.0,
+    max_length_change: int = 3
+) -> Dict:
+    """
+    Suggest primer modifications to achieve target Tm.
+
+    Parameters
+    ----------
+    primer_sequence : str
+        Original primer sequence
+    target_tm : float
+        Desired melting temperature
+    tolerance : float
+        Acceptable Tm deviation from target. Default: 2.0°C
+    max_length_change : int
+        Maximum bases to add/remove. Default: 3
+
+    Returns
+    -------
+    dict
+        Suggestions for achieving target Tm
+
+    Example
+    -------
+    >>> suggestions = optimize_tm("ATGCGTACGATCG", target_tm=60.0)
+    >>> for s in suggestions['modifications']:
+    ...     print(f"{s['action']}: New Tm = {s['new_tm']}°C")
+    """
+
+    # Calculate current Tm
+    current_result = calculate_tm_comprehensive(primer_sequence)
+    current_tm = current_result['tm_nn']
+
+    modifications = []
+
+    # If already within tolerance, no changes needed
+    if abs(current_tm - target_tm) <= tolerance:
+        return {
+            'current_tm': current_tm,
+            'target_tm': target_tm,
+            'needs_optimization': False,
+            'message': f"Primer Tm ({current_tm:.1f}°C) is within tolerance of target ({target_tm:.1f}°C)",
+        }
+
+    # Try shortening (if Tm too high)
+    if current_tm > target_tm:
+        for i in range(1, max_length_change + 1):
+            # Try removing from 5' end
+            shortened_5 = primer_sequence[i:]
+            if len(shortened_5) >= 15:  # Keep minimum length
+                tm_5 = calculate_tm_comprehensive(shortened_5)['tm_nn']
+                modifications.append({
+                    'action': f"Remove {i} bp from 5' end",
+                    'new_sequence': shortened_5,
+                    'new_tm': tm_5,
+                    'tm_difference': abs(tm_5 - target_tm),
+                })
+
+            # Try removing from 3' end
+            shortened_3 = primer_sequence[:-i]
+            if len(shortened_3) >= 15:
+                tm_3 = calculate_tm_comprehensive(shortened_3)['tm_nn']
+                modifications.append({
+                    'action': f"Remove {i} bp from 3' end",
+                    'new_sequence': shortened_3,
+                    'new_tm': tm_3,
+                    'tm_difference': abs(tm_3 - target_tm),
+                })
+
+    # Try lengthening (if Tm too low)
+    else:
+        modifications.append({
+            'action': f"Increase primer length by {max_length_change} bp",
+            'new_sequence': None,
+            'recommendation': "Extend primer into flanking sequence to increase Tm",
+        })
+
+    # Sort by closest to target Tm
+    modifications.sort(key=lambda x: x.get('tm_difference', float('inf')))
+
+    return {
+        'current_tm': current_tm,
+        'target_tm': target_tm,
+        'needs_optimization': True,
+        'tm_difference': abs(current_tm - target_tm),
+        'modifications': modifications[:5],  # Top 5 suggestions
+        'recommendation': "Try the suggested modifications to achieve target Tm",
+    }

package/data/workflows/pcr-primer-design/scripts/check_dimers.py

@@ -0,0 +1,298 @@
+"""
+Check for primer dimers and cross-dimers.
+
+This module analyzes primer-primer interactions to identify potential
+dimer formation that can reduce PCR efficiency.
+"""
+
+import primer3
+from typing import List, Dict
+
+
+def analyze_dimers(
+    primer_list: List[str],
+    temperature: float = 60.0,
+    dg_threshold: float = -5.0,
+    mv_conc: float = 50.0,
+    dv_conc: float = 0.0,
+    dntp_conc: float = 0.8,
+    dna_conc: float = 50.0
+) -> Dict:
+    """
+    Analyze primer dimers and cross-dimers for a set of primers.
+
+    Parameters
+    ----------
+    primer_list : list of str
+        List of primer sequences to analyze
+    temperature : float
+        PCR annealing temperature in °C. Default: 60.0
+    dg_threshold : float
+        ΔG threshold in kcal/mol for flagging dimers. Default: -5.0
+        Dimers with ΔG < threshold are likely to form
+    mv_conc : float
+        Monovalent cation concentration in mM. Default: 50.0
+    dv_conc : float
+        Divalent cation concentration in mM. Default: 0.0
+    dntp_conc : float
+        dNTP concentration in mM. Default: 0.8
+    dna_conc : float
+        DNA concentration in nM. Default: 50.0
+
+    Returns
+    -------
+    dict
+        Dictionary containing:
+        - 'interactions': list of all primer-primer interactions
+        - 'problematic_dimers': list of dimers below threshold
+        - 'has_issues': bool indicating if any dimers exceed threshold
+
+    Example
+    -------
+    >>> primers = ["ATGCGTACGATCGATCG", "CGTAGCTAGCTAGCTAG"]
+    >>> analysis = analyze_dimers(primers, temperature=60.0)
+    >>> if analysis['has_issues']:
+    ...     print("⚠ Primer dimers detected!")
+    """
+
+    # Validate inputs
+    primer_list = [p.upper().strip() for p in primer_list]
+
+    if len(primer_list) < 2:
+        raise ValueError("Need at least 2 primers to check for dimers")
+
+    for primer in primer_list:
+        if not all(base in 'ATCGN' for base in primer):
+            raise ValueError(f"Invalid primer sequence: {primer}")
+
+    interactions = []
+    problematic_dimers = []
+
+    # Check all pairwise interactions
+    for i, primer1 in enumerate(primer_list):
+        for j, primer2 in enumerate(primer_list):
+            if i <= j:  # Check each pair once, including self-dimers
+                # Determine interaction type
+                if i == j:
+                    interaction_type = "self-dimer"
+                    primer1_name = f"Primer_{i+1}"
+                    primer2_name = f"Primer_{i+1}"
+                else:
+                    interaction_type = "cross-dimer"
+                    primer1_name = f"Primer_{i+1}"
+                    primer2_name = f"Primer_{j+1}"
+
+                # Calculate homodimer (self-dimer) or heterodimer (cross-dimer)
+                if i == j:
+                    result = primer3.calcHomodimer(
+                        primer1,
+                        mv_conc=mv_conc,
+                        dv_conc=dv_conc,
+                        dntp_conc=dntp_conc,
+                        dna_conc=dna_conc,
+                        temp_c=temperature,
+                        output_structure=True
+                    )
+                else:
+                    result = primer3.calcHeterodimer(
+                        primer1,
+                        primer2,
+                        mv_conc=mv_conc,
+                        dv_conc=dv_conc,
+                        dntp_conc=dntp_conc,
+                        dna_conc=dna_conc,
+                        temp_c=temperature,
+                        output_structure=True
+                    )
+
+                # Extract results
+                dg = result.dg / 1000.0  # Convert cal/mol to kcal/mol
+                tm = result.tm
+                structure = result.ascii_structure if hasattr(result, 'ascii_structure') else "N/A"
+
+                interaction = {
+                    'type': interaction_type,
+                    'primer1': primer1_name,
+                    'primer2': primer2_name,
+                    'primer1_seq': primer1,
+                    'primer2_seq': primer2,
+                    'dg': round(dg, 2),
+                    'tm': round(tm, 2) if tm is not None else None,
+                    'structure': structure,
+                    'problematic': dg < dg_threshold,
+                }
+
+                interactions.append(interaction)
+
+                if dg < dg_threshold:
+                    problematic_dimers.append(interaction)
+
+    # Compile results
+    results = {
+        'interactions': interactions,
+        'problematic_dimers': problematic_dimers,
+        'has_issues': len(problematic_dimers) > 0,
+        'num_primers': len(primer_list),
+        'num_interactions': len(interactions),
+        'num_problematic': len(problematic_dimers),
+        'parameters': {
+            'temperature': temperature,
+            'dg_threshold': dg_threshold,
+            'mv_conc': mv_conc,
+            'dv_conc': dv_conc,
+            'dntp_conc': dntp_conc,
+            'dna_conc': dna_conc,
+        }
+    }
+
+    return results
+
+
+def check_3prime_complementarity(
+    primer1: str,
+    primer2: str,
+    window_size: int = 5
+) -> Dict:
+    """
+    Check for 3' end complementarity between two primers.
+
+    3' complementarity is critical as it can lead to primer extension
+    and dimer formation during PCR.
+
+    Parameters
+    ----------
+    primer1 : str
+        First primer sequence
+    primer2 : str
+        Second primer sequence
+    window_size : int
+        Number of bases at 3' end to check. Default: 5
+
+    Returns
+    -------
+    dict
+        Dictionary with 3' complementarity analysis
+
+    Example
+    -------
+    >>> result = check_3prime_complementarity("ATGCGTACGATCG", "CGATCGTACGCAT")
+    >>> print(f"3' complementarity: {result['complementary_bases']} bp")
+    """
+
+    from Bio.Seq import Seq
+
+    primer1 = primer1.upper()
+    primer2 = primer2.upper()
+
+    # Get 3' ends
+    primer1_3prime = primer1[-window_size:]
+    primer2_3prime = primer2[-window_size:]
+
+    # Get reverse complement of primer2's 3' end
+    primer2_3prime_rc = str(Seq(primer2_3prime).reverse_complement())
+
+    # Count complementary bases at 3' end
+    complementary_bases = 0
+    for i in range(min(len(primer1_3prime), len(primer2_3prime_rc))):
+        if primer1_3prime[-(i+1)] == primer2_3prime_rc[i]:
+            complementary_bases += 1
+        else:
+            break
+
+    is_problematic = complementary_bases >= 3
+
+    return {
+        'primer1_3prime': primer1_3prime,
+        'primer2_3prime': primer2_3prime,
+        'complementary_bases': complementary_bases,
+        'is_problematic': is_problematic,
+        'warning': f"High 3' complementarity ({complementary_bases} bp)" if is_problematic else None,
+    }
+
+
+def analyze_multiplex_compatibility(
+    primer_pairs: List[Dict],
+    temperature: float = 60.0,
+    dg_threshold: float = -5.0
+) -> Dict:
+    """
+    Analyze compatibility of multiple primer pairs for multiplex PCR.
+
+    Parameters
+    ----------
+    primer_pairs : list of dict
+        List of primer pair dictionaries, each with 'forward_seq' and 'reverse_seq'
+    temperature : float
+        PCR annealing temperature
+    dg_threshold : float
+        ΔG threshold for dimer flagging
+
+    Returns
+    -------
+    dict
+        Multiplex compatibility analysis
+
+    Example
+    -------
+    >>> pairs = [
+    ...     {'forward_seq': 'ATGC...', 'reverse_seq': 'CGTA...'},
+    ...     {'forward_seq': 'GCTA...', 'reverse_seq': 'TAGC...'}
+    ... ]
+    >>> compat = analyze_multiplex_compatibility(pairs)
+    >>> print(f"Multiplex compatible: {compat['is_compatible']}")
+    """
+
+    # Collect all primers
+    all_primers = []
+    primer_labels = []
+
+    for i, pair in enumerate(primer_pairs):
+        all_primers.append(pair['forward_seq'])
+        all_primers.append(pair['reverse_seq'])
+        primer_labels.append(f"Pair{i+1}_F")
+        primer_labels.append(f"Pair{i+1}_R")
+
+    # Analyze all interactions
+    dimer_analysis = analyze_dimers(
+        primer_list=all_primers,
+        temperature=temperature,
+        dg_threshold=dg_threshold
+    )
+
+    # Check Tm compatibility
+    tm_values = []
+    for pair in primer_pairs:
+        if 'forward_tm' in pair and 'reverse_tm' in pair:
+            tm_values.extend([pair['forward_tm'], pair['reverse_tm']])
+
+    tm_range = max(tm_values) - min(tm_values) if tm_values else 0
+    tm_compatible = tm_range <= 5.0  # All primers should have Tm within 5°C
+
+    # Compile multiplex results
+    is_compatible = not dimer_analysis['has_issues'] and tm_compatible
+
+    results = {
+        'is_compatible': is_compatible,
+        'num_pairs': len(primer_pairs),
+        'total_primers': len(all_primers),
+        'dimer_analysis': dimer_analysis,
+        'tm_range': round(tm_range, 2) if tm_values else None,
+        'tm_compatible': tm_compatible,
+        'recommendations': [],
+    }
+
+    # Add recommendations
+    if dimer_analysis['has_issues']:
+        results['recommendations'].append(
+            f"Remove or redesign primers with problematic dimers (ΔG < {dg_threshold} kcal/mol)"
+        )
+
+    if not tm_compatible:
+        results['recommendations'].append(
+            f"Adjust primer Tm values to be within 5°C (current range: {tm_range:.1f}°C)"
+        )
+
+    if is_compatible:
+        results['recommendations'].append("Primer set is compatible for multiplex PCR")
+
+    return results