Add amino acid mutation frequency visualization from FASTA files

[zorian15]

Amino Acid Mutation Frequency Visualization Plan

Overview

Create a visualization pipeline that processes FASTA files from antigen-prime and generates heatmaps showing mutation frequencies at each amino acid site.

Workflow Pipeline

1. FASTA Processing

# Read sequences from FASTA file
sequences = read_fasta("sequences.fasta")

# Translate DNA to amino acid sequences
aa_sequences = [translate_dna_to_aa(seq) for seq in sequences]

2. Mutation Frequency Calculation

# Steps:
# a) Identify reference sequence (consensus or specified)
# b) Compare each sequence to reference
# c) Count mutations at each position
# d) Calculate frequencies

3. Data Structure

Position | AA_Ref | AA_Alt | Count | Frequency
---------|--------|--------|-------|----------
1        | M      | L      | 45    | 0.15
1        | M      | V      | 30    | 0.10
2        | A      | T      | 120   | 0.40
...

4. Visualization Options

Option A: Simple Heatmap

• X-axis: Amino acid positions
• Y-axis: Different amino acid variants
• Color intensity: Mutation frequency

Option B: Stacked Bar Chart

• X-axis: Amino acid positions
• Y-axis: Frequency
• Stacked bars for different mutations at each site

Option C: Logo Plot Style

• Similar to sequence logos but showing mutation frequencies
• Height represents total variation at site
• Letter size represents frequency of each amino acid

Implementation Steps

Phase 1: Core Functions

def fasta_to_aa_mutations(fasta_file, reference_seq=None):
    """
    Process FASTA file and calculate mutation frequencies
    
    Args:
        fasta_file: Path to FASTA file
        reference_seq: Optional reference sequence (if None, use consensus)
    
    Returns:
        DataFrame with mutation frequencies per position
    """
    pass

def calculate_mutation_matrix(aa_sequences, reference):
    """
    Create position x amino acid mutation matrix
    
    Returns:
        Matrix where rows are positions, columns are amino acids
    """
    pass

Phase 2: Visualization Function

def plot_mutation_heatmap(mutation_df, 
                         figsize=(20, 8),
                         cmap='viridis',
                         show_only_mutations=True):
    """
    Create heatmap of mutation frequencies
    
    Args:
        mutation_df: DataFrame from fasta_to_aa_mutations
        figsize: Figure dimensions
        cmap: Colormap for heatmap
        show_only_mutations: If True, only show sites with mutations
    """
    pass

Example Usage

from antigentools.mutations import fasta_to_aa_mutations, plot_mutation_heatmap

# Process FASTA file
mutation_df = fasta_to_aa_mutations("antigen_prime_output.fasta")

# Create visualization
plot_mutation_heatmap(mutation_df, 
                     figsize=(30, 10),
                     show_only_mutations=True)

# Optional: Focus on specific region
plot_mutation_heatmap(mutation_df, 
                     positions=range(140, 200),  # HA1 antigenic sites
                     cmap='Reds')

Integration Points

1. Use existing functions:

   • translate_dna_to_aa() from utils.py
   • hamming_distance() for quick mutation detection

2. Extend plot.py:

   • Add mutation heatmap functions
   • Reuse existing styling/formatting

3. Create new module:

   • antigentools/mutations.py for mutation analysis functions

Considerations

1. Performance: For large FASTA files, consider:

   • Chunked processing
   • Parallel computation for mutation counting
   • Caching processed results

2. Reference Selection:

   • Consensus sequence (most common at each position)
   • User-specified reference
   • First sequence in file

3. Filtering Options:

   • Minimum frequency threshold
   • Specific positions of interest
   • Remove conserved sites

4. Output Formats:

   • Interactive HTML (using plotly)
   • Static PNG/PDF
   • CSV export of mutation frequencies

Next Steps

1. Review existing antigen-prime output format
2. Prototype basic FASTA → mutation frequency function
3. Test with sample data
4. Refine visualization based on user feedback