similarity_utils

Similarity analysis utility functions for protein sequence analysis. These functions handle specific tasks following single responsibility principle.

Module Contents

similarity_utils.extract_protein_sequences_from_csv(csv_file) → List[str]

Extract protein sequences from uploaded CSV file.

Parameters:

csv_file – Uploaded CSV file object

Returns:

List of protein sequences

Raises:

ValueError – If CSV doesn’t contain required column or has no sequences

similarity_utils.create_unique_sequence_mapping(sequences: List[str]) → Tuple[List[str], Dict[str, str]]

Create mapping between original sequences and unique sequences to avoid redundant analysis.

Parameters:

sequences – List of protein sequences (may contain duplicates)

Returns:

Tuple of (unique_sequences_list, sequence_to_id_mapping)

similarity_utils.create_fasta_file(sequences: List[str], seq_to_id_mapping: Dict[str, str]) → str

Create a temporary FASTA file from protein sequences.

Parameters:

  • sequences – List of protein sequences

  • seq_to_id_mapping – Mapping from sequence to unique identifier

Returns:

Path to the created FASTA file

similarity_utils.create_mmseqs_database(fasta_file_path: str, session_id: str) → Tuple[str, str]

Create MMseqs2 database from FASTA file.

Parameters:

  • fasta_file_path – Path to input FASTA file

  • session_id – Session ID for logging

Returns:

Tuple of (query_db_path, temp_directory_path)

Run MMseqs2 search against target database.

Parameters:

  • query_db – Path to query database

  • target_db – Path to target database

  • method_name – Name of the method (for logging)

  • session_id – Session ID for logging

  • max_seqs – Max hits per query passed to –max-seqs (default 1000)

Returns:

Path to the result file

similarity_utils.parse_mmseqs_results(result_file: str, query_file_path: str) → Tuple[Dict[str, float], Dict[str, float]]

Parse MMseqs2 search results to extract identity scores.

Parameters:

  • result_file – Path to MMseqs2 result file

  • query_file_path – Path to original query FASTA file

Returns:

Tuple of (max_identity_dict, mean_identity_dict)

similarity_utils.parse_mmseqs_results_raw(result_file: str) → Dict[str, List[Tuple[str, float]]]

Parse MMseqs2 result file, keeping the target ID for each hit.

Used by the merged-DB path so hits can be filtered per database before aggregating to max/mean.

Parameters:

result_file – Path to MMseqs2 result file

Returns:

Dict mapping query_id -> [(target_id, pident), …]

similarity_utils.map_results_to_original_sequences(unique_results_max: Dict[str, float], unique_results_mean: Dict[str, float], original_sequences: List[str], seq_to_unique_id: Dict[str, str]) → Tuple[Dict[str, float], Dict[str, float]]

Map results from unique sequences back to all original sequences.

Parameters:

  • unique_results_max – Max identity results for unique sequences

  • unique_results_mean – Mean identity results for unique sequences

  • original_sequences – Original list of sequences (may have duplicates)

  • seq_to_unique_id – Mapping from sequence to unique identifier

Returns:

Tuple of (original_max_dict, original_mean_dict)

similarity_utils.calculate_identity_histogram(identity_values: Dict[str, float]) → Tuple[Dict[str, int], Dict[str, float]]

Calculate histogram of identity values rounded to nearest integer.

Parameters:

identity_values – Dictionary mapping sequence IDs to identity values

Returns:

Tuple of (count_histogram, percentage_histogram)

similarity_utils.calculate_average_similarity(identity_values: Dict[str, float]) → float

Calculate average similarity percentage from identity values.

Parameters:

identity_values – Dictionary mapping sequence IDs to identity values

Returns:

Average similarity as percentage (0-100)

similarity_utils.cleanup_temporary_files(*file_paths: str) → None

Clean up temporary files and directories.

Parameters:

file_paths – Paths to files/directories to remove