Common

Shared data structures and utilities used across REvoDesign.

Mutant

The Mutant class extends RosettaPy's Mutant base, adding REvoDesign-specific properties for scoring, PDB file path management, and description.

REvoDesign.common.mutant.Mutant dataclass

Bases: Mutant

empty property

Checks whether the current object is empty.

This method examines the mutant_info attribute of the object to determine if it is empty. If mutant_info is empty or non-existent, the object is considered empty.

Returns:

Name	Type	Description
bool	bool	Returns True if the object is empty; False otherwise.

mutant_description property writable

Retrieves the description of the mutant.

This method is an instance method that doesn't require any explicit parameters (besides the implicit 'self', used to access instance attributes and methods), and returns a string representing the mutant's description.

Return

str: The description of the mutant as a string.

pdb_fp property writable

Retrieves the path to the PDB file.

This method checks if the internally stored PDB file path is valid (exists) and if not, sets it to an empty string. This could happen if the Mutant object has been transferred to another user or the PDB file has been deleted.

Returns:

Name	Type	Description
str	str	The path to the PDB file, or an empty string if the file doesn't exist.

raw_mutant_id property

Generates and returns a raw mutant identifier string by concatenating chain ID, wild-type residue, position, and mutated residue for each mutant in the mutant_info list.

Parameters:

Name	Type	Description	Default
self		An instance of the class containing the mutant_info attribute, which is a list of dictionaries representing mutant information.	required

Returns:

Name	Type	Description
_raw_mutant_id	str	A concatenated string of all mutant identifiers, separated by underscores.

short_mutant_id property

Generates a shortened mutant ID.

This method creates a short ID by taking the first 15 characters of the original mutant ID or its SHA-256 hash, followed by the mutant score. If the original ID is 15 characters or fewer, it uses the original ID directly.

Returns:

Name	Type	Description
str	str	Shortened mutant ID in the format "_".

mutant_score property writable

The mutant score property.

wt_score property writable

The wild-type score property.

mutant_sequences property

Generates a dictionary of mutant sequences for each chain.

Iterates through each chain in the original wt_sequences dictionary and retrieves the mutant sequence for that specific chain.

Returns:

Type	Description
RosettaPyProteinSequence	dict[str, str]: A dictionary where keys are chain IDs and values are the corresponding mutated sequences.

get_mutant_sequence_single_chain(chain_id, ignore_missing=False)

Generates a mutated sequence for a single chain based on the provided chain ID and mutation information.

Parameters: - chain_id: str, The ID of the chain. - ignore_missing: bool, If True, ignores 'X' residues in the sequence.

Returns: - str, The mutated sequence for the specified chain.

• issues.InvalidInputError: If the chain ID doesn't exist in the wild-type sequences, or there's no available mutant information or the wild-type sequence is empty.
• issues.MoleculeError: If the position is out of sequence range or the wild-type residue at the position doesn't match the mutant information.

Note: If ignore_missing is True, any 'X' residues in the sequence will be removed.

MutantTree

A hierarchical tree structure for organizing and navigating mutants across multiple named branches. Each branch holds a dictionary of Mutant objects keyed by unique mutant ID. Supports navigation (walk forward/backward), best-mutant jumping, tree comparison (diff), and parallel mutation execution.

REvoDesign.common.mutant_tree.MutantTree

A class representing a mutant tree.

asOneMutant property

This property method is used to create a single Mutant object from all the mutants in the tree. It combines the mutant info of all mutants into one.

refresh_mutants()

Refreshes mutant-related attributes in the MutantTree object.

Usage: tree.refresh_mutants()

get_branch_index(branch_id)

Gets the index of a branch ID in the MutantTree object.

Parameters: - branch_id (str): ID of the branch.

Usage: index = tree.get_branch_index('branch_id')

has(obj)

Check if the given object exists in the instance.

This function accepts an object of type string or Mutant and determines whether the object is present in the instance's mutant collection.

Parameters: - obj (Union[str, Mutant]): The object to check. It can be a string representing a mutant ID or a Mutant object.

Returns: - bool: True if the object is found in the instance, False otherwise.

get_a_branch(branch_id)

Gets a specific branch from the MutantTree object.

Parameters: - branch_id (str): ID of the branch.

Usage: branch = tree.get_a_branch('branch_id')

search_a_branch(branch_kw)

Searches for branches containing a specific keyword in the MutantTree object.

Parameters: - branch_kw (str): Keyword to search for in branch IDs.

Usage: matching_branches = tree.search_a_branch('keyword')

get_mutant_index_in_branch(branch_id, mutant_id)

Gets the index of a mutant in a specific branch of the MutantTree object.

Parameters: - branch_id (str): ID of the branch. - mutant_id (str): ID of the mutant.

Usage: index = tree.get_mutant_index_in_branch('branch_id', 'mutant_id')

get_mutant_index_in_all_mutants(mutant_id)

Gets the index of a mutant in all mutants of the MutantTree object.

Parameters: - mutant_id (str): ID of the mutant.

Usage: index = tree.get_mutant_index_in_all_mutants('mutant_id')

is_the_mutant_the_last_in_branch(branch_id, mutant_id)

Checks if the specified mutant is the last in a branch.

Parameters: - branch_id (str): ID of the branch. - mutant_id (str): ID of the mutant.

Usage: result = tree.is_the_mutant_the_last_in_branch('branch_id', 'mutant_id')

is_this_branch_empty(branch_id)

Checks if a specific branch in the MutantTree object is empty.

Parameters: - branch_id (str): ID of the branch.

Usage: result = tree.is_this_branch_empty('branch_id')

update_tree_with_new_branches(new_branches)

Update the MutantTree object with new branches.

Parameters: - new_branches (dict): Dictionary of new branches and their mutants.

Usage: tree.update_tree_with_new_branches({'new_branch': {'mutant1': info1, 'mutant2': info2}})

add_mutant_to_branch(branch, mutant, mutant_obj)

Adds a mutant to a specific branch in the MutantTree object.

Parameters: - branch (str): ID of the branch. - mutant (str): ID of the mutant. - mutant_info (object): Information about the mutant.

Usage: tree.add_mutant_to_branch('branch_id', 'mutant_id', mutant_info)

remove_mutant_from_branch(branch, mutant)

Removes a mutant from a specific branch in the MutantTree object.

Parameters: - branch (str): ID of the branch. - mutant (str): ID of the mutant.

Usage: tree.remove_mutant_from_branch('branch_id', 'mutant_id')

create_mutant_tree_from_list(mutant_id_list)

Creates a new MutantTree instance from a filtered list of mutant IDs.

Parameters: - mutant_id_list (list): List of mutant IDs.

Usage: new_tree = tree.create_mutant_tree_from_list(['mutant_id_1', 'mutant_id_2'])

jump_to_the_best_mutant_in_branch(branch_id, ascending_order=False)

Jumps to the best mutant in a specific branch based on scores.

Parameters: - branch_id (str): ID of the branch. - ascending_order (bool): Optional - Set to True to reverse sorting by sorting with assending order (from smaller to larger).

Usage: tree.jump_to_the_best_mutant_in_branch('branch_id')

walk_the_mutants(walf_forward=True)

Walks through mutants in the MutantTree object.

Parameters: - walf_forward (bool): Optional - Set to False to walk backward.

Usage: tree.walk_the_mutants()

jump_to_branch(branch_id)

Jumps to a specified branch in the MutantTree object.

Parameters: - branch_id (str): ID of the branch to jump to.

Usage: tree.jump_to_branch('branch_id')

diff_tree_from(incoming_tree)

Compares two MutantTree objects and returns the differences as a new MutantTree.

Args: - incoming_tree (MutantTree): The incoming MutantTree object to compare with.

Returns: - MutantTree or None: A MutantTree object containing the differences between self and other_tree, or None if there are no differences.

Raises: - ValueError: If the input other_tree is not a MutantTree object.

pop()

Pops out the last mutant from the last branch of the MutantTree object.

Returns: - Mutant or None: The last mutant in the last branch if it exists, otherwise None.

Usage: last_mutant = tree.pop()

Supporting Types

REvoDesign.common.mutant_tree.MutantDict

Bases: TypedDict

REvoDesign.common.mutant_tree.MutateRunner

Bases: Protocol

MultiMutantDesigner

Interactive multi-mutant design workflow controller. Reads parameters from ConfigBus and manages the step-by-step process of selecting compatible mutants from a design pool, evaluating them via an external scorer, and exporting the final design variants.

REvoDesign.common.multi_mutant_designer.MultiMutantDesigner

refresh_design_color()

Refreshes the color representation of designed mutants.

This method updates the color representation based on scores or other criteria for the designed mutants.

evaluate_design()

Evaluate the designed mutant.

Args: - design: A list of Mutant objects representing the designed mutants.

Returns: - Mutant: The evaluated Mutant object with a calculated score.

start_new_design()

Starts a new mutant design.

This method initiates the start of a new mutant design process.

pick_next_mutant()

Picks the next mutant for design.

This method selects the next mutant to be included in the design process.

undo_previous_mutant()

Undoes the last mutant addition in the design.

This method removes the last mutant added to the design.

terminate_picking(continue_design=True)

Completes the current design and starts a new one.

Args: - continue_design: Boolean flag to continue the design process.

This method finalizes the current design, starts a new one if requested, and evaluates the designed mutants.

export_designed_variant()

Exports the designed variants.

Args: - save_mutant_table: File path to save the mutant variants.

This method exports the designed mutant variants to a specified file path.

MutantVisualizer

Workhorse for creating PyMOL visualizations of designed mutants. Parses mutation data from various file formats (CSV, TSV, FASTA, Excel), computes scores via profile scoring or external scorers, runs sidechain repacking, and produces colored PyMOL sessions showing the mutated residues.

REvoDesign.common.mutant_visualise.MutantVisualizer

process_mutant(mutant_obj)

Process a specific position based on the information in the Mutant object.

Args: - self: Instance of the class containing the method. - mutant_obj (Mutant): Mutant object containing information about the position.

Returns: - temp_session_path (str): Filepath to the temporary session containing processed data.

Notes: - Loads the input session, hides surface, visualizes the mutant, and creates mutagenesis objects. - Saves the processed session data to a temporary file and returns the file path.

create_mutagenesis_objects(mutant_obj, color, in_place=True)

Creates mutagenesis objects in PyMOL based on explicit mutagenesis descriptions.

Args: - self: Instance of the class containing the method. - mutant_obj (Mutant): Mutant object containing explicit mutagenesis description. - color: Color to assign to the mutagenesis objects. - inplace: ask PyMOL mutate runner to not stay in place after mutate is done

Returns: - None

Notes: - Creates mutagenesis objects in PyMOL based on the provided Mutant object. - Handles explicit mutagenesis descriptions by applying mutations and assigning colors.

parse_profile(profile_fp, profile_format)

Parse the profile data based on the specified format and return the processed DataFrame.

Args: - profile_fp (str): File path of the profile data. - profile_format (str): Format of the profile data (e.g., 'PSSM', 'CSV', 'TSV').

Returns: - DataFrame: Processed DataFrame based on the profile format.

Notes: - Parses the profile data based on the specified format and returns a processed DataFrame. - Handles different formats (PSSM, CSV, TSV) and processes the data accordingly. - Initializes and uses external designers if available for specific profile formats. - Logs debug information during the processing for easier debugging. - Returns the processed DataFrame or None based on the profile format.

run()

Runs mutation tasks.

Reads mutation data from different file formats (CSV, TXT, FASTA) and performs mutation-related operations. Calculates scores for mutants and adds them to the mutant tree. Determines the range for the color bar based on mutant scores. Adjusts score ranges based on certain conditions.

Raises: - ValueError: If an invalid file format is encountered or if required columns are missing in the data.

run_mutagenesis_tasks()

Runs mutagenesis tasks based on the MutantTree.

Args: - self: Instance of the class containing the method.

Notes: - This method initiates and manages the execution of mutagenesis tasks using parallel processing if self.parallel_run is True. - The method uses multiprocessing for parallel execution of tasks. - If parallel_run is True: - It initializes a ParallelExecutor with specified parameters and starts the execution. - Handles the results obtained from parallel execution. - If parallel_run is False: - Executes mutagenesis tasks sequentially without parallel processing. - After executing mutagenesis tasks, it performs merging sessions via command line.

merge_sessions_via_commandline()

To call this commandline interface of session merger:

Instantialize MutantVisualizer. molecule and chain_id can be set as empty str.

session_merger=MutantVisualizer(molecule=self.molecule, chain_id=self.chain_id)

input and output

session_merger.input_session=self.input_pse session_merger.save_session=self.output_pse

all mutagenesis sessions

session_merger.mutagenesis_sessions=self.results

run the session merger

session_merger.merge_sessions_via_commandline()

session merger will save a temperal sesion based on given output session file path.

Profile Parsers

Parser classes for loading mutagenesis profiles from various file formats.

ProfileParserAbstract

REvoDesign.common.profile_parsers.ProfileParserAbstract

Bases: ABC

ProfileParserAbstract is an abstract base class designed to parse profile data associated with molecular structures.

Attributes: - profile_input: str, the path to the input profile file. - molecule: str, the name of the molecule. - chain_id: str, identifier for a specific chain within the molecule's structure. - sequence: str, the amino acid or nucleotide sequence related to the profile. - df: pd.DataFrame, optional, stores parsed data; default is None.

Abstract Methods: - parse(): Must be implemented by subclasses to parse the profile data into a DataFrame.

Properties: - score_max_abs: float, computes the maximum absolute value from the parsed DataFrame's min and max values. - min_score_profile: float, derived from score_max_abs, represents the minimum possible score for the profile. - max_score_profile: float, derived from score_max_abs, represents the maximum possible score for the profile. - profile_input_bn: str, returns the basename of profile_input if it exists as a file. - is_valid_profile: bool, checks if the profile_input file exists.

score_max_abs property

Computes the maximum absolute value between the minimum and maximum values of the DataFrame.

Returns: - float, maximum absolute value found in the DataFrame.

Raises: - UnexpectedWorkflowError: If the DataFrame is not properly initialized or empty.

min_score_profile property

Calculates the minimum possible score for the profile based on score_max_abs.

Returns: - float, representing the minimum score.

max_score_profile property

Calculates the maximum possible score for the profile based on score_max_abs.

Returns: - float, representing the maximum score.

profile_input_bn property

Retrieves the basename of the profile_input file if it exists.

Returns: - str, the basename of the input file.

Raises: - InvalidInputError: If profile_input does not point to an existing file.

is_valid_profile property

Validates whether the profile_input file exists.

Returns: - bool, True if the file exists, False otherwise.

parse() abstractmethod

Abstract method to be implemented by subclasses that parses the profile data and returns it as a DataFrame.

Returns: - pd.DataFrame, containing the parsed profile data.

PSSM_Parser

REvoDesign.common.profile_parsers.PSSM_Parser

Bases: ProfileParserAbstract

convert_PSSM_file_to_df(input_pssm_file) staticmethod

Converts a PSSM file to a pandas DataFrame.

Args: - self: Instance of the class containing the method. - input_pssm_file (str): Path to the input PSSM file.

Returns: - df (DataFrame): Pandas DataFrame containing the parsed PSSM data.

Notes: - Reads the PSSM file, parses the table header, defines column specifications, and reads the table data. - Transposes the DataFrame and drops NaN values to clean the data before returning.

CSVProfileParser

REvoDesign.common.profile_parsers.CSVProfileParser

Bases: ProfileParserAbstract

TSVProfileParser

REvoDesign.common.profile_parsers.TSVProfileParser

Bases: ProfileParserAbstract

ProfileManager

REvoDesign.common.profile_parsers.ProfileManager

File Extensions

Predefined FileExtensionCollection instances defined in REvoDesign.common.file_extensions for common file types used throughout the UI. Each instance bundles related extensions with human-readable descriptions for Qt file dialogs.

Collections

Name	Extensions	Purpose
Session	.pze, .pse	PyMOL sessions
Mutable	.txt, .mut.txt, .csv, .tsv, .xlsx, .xls	Mutant tables
PDB	.pdb, .ent, .cif, .mmcif	Protein structures
PDB_STRICT	.pdb	Strict PDB only
MOL	.mol, .sdf	Small molecule files
SDF	.sdf	SDF files
PSSM	.csv, .pssm	Position-specific scoring matrices
CSV	.csv	CSV files
MSA	.fas, .fasta, .a3m	Multiple sequence alignments
A3M	.a3m	HH-suite A3M format
TXT	.txt	Plain text files
Any	* *	Catch-all filter
Compressed	.zip, .tar.gz, .tgz, .tar.bz2, .tbz, .tar.xz, .txz, .tar, .gz, .bz2, .xz, .rar	Archives
PickledObject	.pkl	Pickled Python objects
YAML	.yaml	YAML config files
JSON	.json	JSON files
RosettaParams	.params	Rosetta parameter files
Pictures	.png, .jpg, .jpeg, .gif, .bmp, .tiff, .tif, .svg, .pdf	Images
XvgGromacs	.xvg	Gromacs XVG format

Supporting Classes

REvoDesign.basic.FileExtension dataclass

Represents a file extension, including its technical details and human-readable description.

Attributes:

Name	Type	Description
ext	str	The file extension, such as 'txt', 'md', etc.
description	str	A brief description of the file type, such as 'Text File' or 'Markdown File'.

filter_string property

Generates a file filter string for this file extension.

Returns:

Name	Type	Description
str	str	A file filter string in the format 'Description (*.[ext])', used in file dialog filters.

REvoDesign.basic.FileExtensionCollection dataclass

Represents a collection of file extensions, used to manage multiple file types.

Attributes:

Name	Type	Description
extensions	tuple[FileExtension, ...]	A tuple containing a series of FileExtension objects.

list_all property

Returns a list of all file extensions.

This property method iterates over the self.extensions list, extracting the 'ext' attribute from each extension object.

list_dot_ext property

Returns a list of string extensions prefixed with a dot.

Returns:

Type	Description
list[str]	list[str]: A list of string extensions, each prefixed with a dot.

filter_string property

Generates a combined file filter string for all file extensions in the collection.

Returns:

Name	Type	Description
str	str	A combined file filter string, with each file extension's filter string separated by ';;'.

match(ext)

Check if the given file extension matches any of the extensions in the current object's list.

Parameters: ext (Union[FileExtension, str]): The file extension to check, can be a FileExtension enum or a string.

Returns: bool: True if the extension matches, False otherwise.

squeeze(exts) classmethod

Merge file extensions from multiple FileExtensionCollection instances and remove duplicates.

This method takes a tuple of FileExtensionCollection instances and combines their extensions using set union operations to ensure that the resulting collection contains only unique extensions.

exts (tuple[FileExtensionCollection]): A tuple containing multiple FileExtensionCollection instances whose extensions are to be merged.

FileExtensionCollection: A new FileExtensionCollection instance containing all unique extensions from the input instances.

basename_stem(fname)

Extracts the stem (base name without extension) from a file name.

Parameters: fname (str): The file name to extract the stem from.

Returns: str: The base name (stem) of the file name without the extension.

Resolver

REvoDesign.basic.extensions.resolve_extension(extension)

Converts an extension string into an FileExtensionCollection object for file type handling.

This function supports two types of input:

1. Predefined Extension:

2. If the input matches a predefined attribute in Fext, it returns the corresponding value directly.

3. Custom Extension:

4. If the input does not match any predefined attribute, it treats the input as a custom extension string, splits it by semicolons (;), and constructs a dictionary mapping lowercase extensions to user-friendly names with a prefix 'Customized - '.

Parameters:

Name	Type	Description	Default
extension	str	The extension string to be resolved. It can be a predefined name or a custom list like "pdb;csv".	required

Returns:

Type	Description
FileExtensionCollection	Fext.ExtColl: An object representing the file extension collection, either from predefined values or custom input.

Example

Given input "pdb;csv", this will generate: {'pdb': 'PDB File', 'csv': 'CSV File'} under a custom prefix.