# **PepFlex: A Modular Framework for Peptide Screening and Evolution**
PepFlex is a Python module designed to provide a flexible and extensible framework for in silico peptide screening and evolutionary studies. It offers tools for managing amino acid data, assembling peptides, applying various genetic operations (mutations and crossovers), and processing evolutionary rounds through a customizable evaluation pipeline.
**Note on RDKit Dependency:** PepFlex utilizes RDKit for chemical functionalities, including SMILES canonicalization and peptide assembly. If RDKit is not installed, these functionalities will be limited, and a warning will be issued upon module import.
### **1\. Amino Acid DataFrame Utilities and Conversions**
PepFlex maintains a global DataFrame, AMINO\_ACID\_DF, which stores information about standard amino acids, including their one-letter, three-letter, and SMILES representations. This DataFrame can be extended to include non-canonical or modified amino acids.
* **AMINO\_ACID\_DF (Global DataFrame)**
* **Description:** A pandas DataFrame indexed by the 3-letter code, containing 1L (one-letter code), SMILES (original SMILES string), and SMILES\_Canon (canonical RDKit SMILES).
* **Purpose:** Serves as the central repository for amino acid data, facilitating conversions and lookups.
* **\_canonicalize\_smiles(smiles: str) \-\> str**
* **Description:** Converts a SMILES string to its canonical RDKit form for reliable comparison. This is an internal helper function.
* **Arguments:**
* smiles (str): The SMILES string to canonicalize.
* **Returns:** str: The canonical SMILES string, or an empty string if invalid or RDKit is not available.
* **add\_amino\_acid(three\_letter\_code: str, one\_letter\_code: str, smiles: str)**
* **Description:** Adds a new amino acid or updates an existing one in the AMINO\_ACINO\_DF using its 3-letter code as the primary key.
* **Arguments:**
* three\_letter\_code (str): The 3-letter code (e.g., "Ala", "Cys").
* one\_letter\_code (str): The 1-letter code (e.g., "A", "C").
* smiles (str): The SMILES string representation.
* **Behavior:** Prints a warning if the code already exists and updates it. Prints an error if the provided SMILES is invalid.
* **get\_smiles\_from\_3L(three\_letter\_code: str) \-\> str**
* **Description:** Retrieves the original SMILES for a given 3-letter code.
* **Arguments:**
* three\_letter\_code (str): The 3-letter code of the amino acid.
* **Returns:** str: The SMILES string.
* **Raises:** ValueError: If the 3-letter code is not found.
* **get\_1L\_from\_3L(three\_letter\_code: str) \-\> str**
* **Description:** Retrieves the 1-letter code for a given 3-letter code.
* **Arguments:**
* three\_letter\_code (str): The 3-letter code of the amino acid.
* **Returns:** str: The 1-letter code.
* **Raises:** ValueError: If the 3-letter code is not found.
* **get\_smiles\_from\_1L(one\_letter\_code: str) \-\> str**
* **Description:** Retrieves the SMILES for a given 1-letter code.
* **Arguments:**
* one\_letter\_code (str): The 1-letter code of the amino acid.
* **Returns:** str: The SMILES string.
* **Raises:** ValueError: If the 1-letter code is not found.
* **get\_3L\_from\_1L(one\_letter\_code: str) \-\> str**
* **Description:** Retrieves the 3-letter code for a given 1-letter code.
* **Arguments:**
* one\_letter\_code (str): The 1-letter code of the amino acid.
* **Returns:** str: The 3-letter code.
* **Raises:** ValueError: If the 1-letter code is not found.
* **get\_1L\_from\_smiles(smiles: str) \-\> str**
* **Description:** Retrieves the 1-letter code for a given SMILES, using its canonical form for lookup.
* **Arguments:**
* smiles (str): The SMILES string of the amino acid.
* **Returns:** str: The 1-letter code.
* **Raises:** ValueError: If the SMILES is invalid or not found.
* **get\_3L\_from\_smiles(smiles: str) \-\> str**
* **Description:** Retrieves the 3-letter code for a given SMILES, using its canonical form for lookup.
* **Arguments:**
* smiles (str): The SMILES string of the amino acid.
* **Returns:** str: The 3-letter code.
* **Raises:** ValueError: If the SMILES is invalid or not found.
* **save\_amino\_acid\_data(file\_path: str, file\_format: str \= 'csv')**
* **Description:** Saves the AMINO\_ACID\_DF to a specified file.
* **Arguments:**
* file\_path (str): The path to save the file.
* file\_format (str): The format to save the file ('csv' or 'parquet'). Defaults to 'csv'.
* **load\_amino\_acid\_data(file\_path: str, file\_format: str \= 'csv', overwrite: bool \= True)**
* **Description:** Loads amino acid data from a file and updates the global AMINO\_ACID\_DF.
* **Arguments:**
* file\_path (str): The path to the file.
* file\_format (str): The format of the file ('csv' or 'parquet'). Defaults to 'csv'.
* overwrite (bool): If True, overwrites the existing AMINO\_ACID\_DF. If False, merges the loaded data, keeping the last duplicate entry.
### **2\. Peptide Assembler (Beta)**
This function allows the construction of a complete peptide molecule from a sequence of amino acid SMILES strings.
* **assemble\_peptide(residue\_list: Union\[List\[str\], str\], input\_type: int \= 0\) \-\> Optional\[Chem.Mol\]**
* **Description:** Assembles a peptide from a list of amino acid SMILES strings (N- to C-terminus order) or a hyphen-separated string of 3-letter codes. Each input SMILES must represent an amino acid with free N and C termini (e.g., N\[C@@H\](R)C(=O)O).
* **Arguments:**
* residue\_list (Union\[List\[str\], str\]): A list of SMILES strings or a string of 3-letter codes (e.g., "Ala-Glu-Asp-Gly").
* input\_type (int): 0 for a list of SMILES (default), 1 for a 3-letter code string.
* **Returns:** Optional\[Chem.Mol\]: An RDKit Mol object representing the assembled peptide, or None if the input list is empty.
* **Raises:**
* ValueError: If RDKit is not installed, SMILES cannot be parsed, or a 3-letter code is not found.
* RuntimeError: If peptide bond formation fails between residues.
### **3\. Miscellaneous Utilities**
This section includes functions for converting peptide sequences between different amino acid representations and a function for performing genetic crossover operations.
* **convert\_1L\_to\_smiles\_list(one\_letter\_str: str) \-\> List\[str\]**
* **Description:** Converts a string of 1-letter amino acid codes to a list of their corresponding SMILES strings.
* **Arguments:**
* one\_letter\_str (str): A string of 1-letter codes (e.g., "AEDG").
* **Returns:** List\[str\]: A list of SMILES strings.
* **convert\_smiles\_list\_to\_3L(smiles\_list: List\[str\]) \-\> str**
* **Description:** Converts a list of SMILES strings to a hyphen-separated string of 3-letter amino acid codes.
* **Arguments:**
* smiles\_list (List\[str\]): A list of SMILES strings.
* **Returns:** str: A string of 3-letter codes (e.g., "Ala-Glu-Asp-Gly").
* **convert\_1L\_str\_to\_3L(one\_letter\_str: str) \-\> str**
* **Description:** Converts a 1-letter amino acid string to a hyphen-separated 3-letter amino acid string. This only works for canonical amino acids present in the global DataFrame.
* **Arguments:**
* one\_letter\_str (str): A string of 1-letter codes (e.g., "AEDG").
* **Returns:** str: A string of 3-letter codes (e.g., "Ala-Glu-Asp-Gly").
* **convert\_3L\_str\_to\_1L(three\_letter\_str: str) \-\> str**
* **Description:** Converts a hyphen-separated 3-letter amino acid string to a 1-letter amino acid string. This only works for canonical amino acids present in the global DataFrame.
* **Arguments:**
* three\_letter\_str (str): A string of 3-letter codes (e.g., "Ala-Glu-Asp-Gly").
* **Returns:** str: A string of 1-letter codes (e.g., "AEDG").
* **convert\_smiles\_list\_to\_1L(smiles\_list: List\[str\]) \-\> str**
* **Description:** Converts a list of SMILES strings to a 1-letter amino acid string. This only works for canonical amino acids present in the global DataFrame.
* **Arguments:**
* smiles\_list (List\[str\]): A list of SMILES strings.
* **Returns:** str: A string of 1-letter amino acid codes (e.g., "AEDG").
* **peptide\_crossover(parent1\_smiles: List\[str\], parent2\_smiles: List\[str\]) \-\> Tuple\[List\[str\], List\[str\]\]**
* **Description:** Performs a single-point crossover operation between two parent peptides. The cut-off point is determined as the middle of each peptide, with a random choice for odd-length peptides. The segments are then exchanged to form two child peptides. Handles empty or very short peptides.
* **Arguments:**
* parent1\_smiles (List\[str\]): The SMILES sequence of the first parent.
* parent2\_smiles (List\[str\]): The SMILES sequence of the second parent.
* **Returns:** Tuple\[List\[str\], List\[str\]\]: A tuple containing the SMILES sequences of the two child peptides.
### **4\. Peptide Mutator**
The PeptideMutator class enables the application of various mutation rules to peptide sequences. It supports predefined mutation types and allows for custom user-defined mutation functions.
* **class PeptideMutator**
* **\_\_init\_\_(self)**
* **Description:** Initializes the PeptideMutator with an empty list of mutation rules and sets the default amino acid DataFrame.
* **add\_mutation\_rule(self, mutation\_type: Union\[str, Callable\], probability: float, \*\*kwargs)**
* **Description:** Adds a mutation rule to the mutator.
* **Arguments:**
* mutation\_type (Union\[str, Callable\]): The type of mutation. Can be a string for predefined rules or a callable function for custom rules.
* **Predefined Types:** 'intra\_sequence\_suppression', 'n\_terminal\_suppression', 'c\_terminal\_suppression', 'n\_terminal\_addition', 'c\_terminal\_addition', 'intra\_sequence\_addition', 'inter\_mutation', 'n\_terminal\_mutation', 'c\_terminal\_mutation', 'segment\_duplication', 'segment\_inversion', 'segment\_translocation'.
* **Custom Functions:** Should accept smiles\_list: List\[str\] as the first argument and \*\*kwargs for additional parameters, returning a List\[str\].
* probability (float): The probability (0.0 to 1.0) of applying this rule.
* \*\*kwargs: Additional parameters specific to the mutation rule. For predefined rules, these might include allowed\_amino\_acids\_df, source\_amino\_acids\_df, target\_amino\_acids\_df, min\_length, max\_length.
* **Raises:**
* ValueError: If probability is out of range or mutation type is unknown.
* TypeError: If DataFrame parameters are not pandas.DataFrame.
* **apply\_mutations(self, initial\_smiles\_list: list) \-\> list**
* **Description:** Applies all configured mutation rules to a given peptide SMILES sequence based on their defined probabilities.
* **Arguments:**
* initial\_smiles\_list (List\[str\]): The initial SMILES sequence of the peptide.
* **Returns:** List\[str\]: The mutated SMILES sequence.
### **5\. Peptide Class**
The Peptide class encapsulates all information related to a single peptide, including its sequence, unique identifier, creation date, and a history of events.
* **class Peptide**
* **\_\_init\_\_(self, smiles\_sequence: list, peptide\_id: str \= None, creation\_date: datetime \= None, history: list \= None, source\_generation\_params: dict \= None)**
* **Description:** Initializes a Peptide object.
* **Arguments:**
* smiles\_sequence (list): A list of SMILES strings representing the amino acid sequence.
* peptide\_id (str, optional): Unique identifier for the peptide. Generated if None.
* creation\_date (datetime, optional): Timestamp of peptide creation. Defaults to now.
* history (list, optional): A list of dictionaries detailing events in the peptide's lifecycle.
* source\_generation\_params (dict, optional): Parameters related to how the peptide was generated.
* **set\_sequences\_from\_global\_converter(self)**
* **Description:** Sets the 1-letter and 3-letter sequence representations using global conversion functions. Handles cases where SMILES might not be recognized by marking them as "N/A" and logging.
* **one\_letter\_sequence (property)**
* **Description:** Returns the 1-letter code sequence of the peptide.
* **three\_letter\_sequence (property)**
* **Description:** Returns the 3-letter code sequence of the peptide.
* **add\_history\_entry(self, event\_type: str, details: dict)**
* **Description:** Adds an entry to the peptide's history log.
* **Arguments:**
* event\_type (str): The type of event (e.g., "mutation", "crossover", "replenishment").
* details (dict): A dictionary containing event-specific details.
* **to\_dict(self) \-\> Dict**
* **Description:** Converts the Peptide object to a dictionary representation.
* **Returns:** Dict: A dictionary containing all peptide attributes.
* **from\_dict(cls, data: Dict) \-\> 'Peptide' (classmethod)**
* **Description:** Creates a Peptide object from a dictionary representation.
* **Arguments:**
* data (Dict): A dictionary containing peptide data.
* **Returns:** Peptide: A new Peptide instance.
* **\_\_repr\_\_(self) \-\> str**
* **Description:** Provides a string representation of the Peptide object for debugging.
* **\_\_eq\_\_(self, other: object) \-\> bool**
* **Description:** Defines equality comparison based on peptide\_id.
* **\_\_hash\_\_(self) \-\> int**
* **Description:** Defines the hash for the object based on peptide\_id.
### **6\. PeptidePoolManager Class**
The PeptidePoolManager class is responsible for managing a collection of Peptide objects, providing functionalities to add, retrieve, remove, and persist the peptide pool.
* **class PeptidePoolManager**
* **\_\_init\_\_(self)**
* **Description:** Initializes an empty dictionary to store Peptide objects, keyed by their peptide\_id.
* **add\_peptide(self, peptide: Peptide)**
* **Description:** Adds a Peptide object to the pool.
* **Arguments:**
* peptide (Peptide): The Peptide object to add.
* **Raises:** TypeError: If the object is not a Peptide instance.
* **get\_peptide(self, peptide\_id: str) \-\> Optional\[Peptide\]**
* **Description:** Retrieves a peptide by its ID.
* **Arguments:**
* peptide\_id (str): The ID of the peptide.
* **Returns:** Optional\[Peptide\]: The Peptide object if found, else None.
* **get\_all\_peptides(self) \-\> List\[Peptide\]**
* **Description:** Returns a list of all Peptide objects currently in the pool.
* **Returns:** List\[Peptide\]: A list of Peptide objects.
* **remove\_peptide(self, peptide\_id: str)**
* **Description:** Removes a peptide from the pool by its ID.
* **Arguments:**
* peptide\_id (str): The ID of the peptide to remove.
* **clear\_pool(self)**
* **Description:** Clears all peptides from the pool.
* **get\_pool\_size(self) \-\> int**
* **Description:** Returns the current number of peptides in the pool.
* **Returns:** int: The number of peptides.
* **to\_dataframe(self) \-\> pd.DataFrame**
* **Description:** Converts the peptide pool into a pandas DataFrame. History and source generation parameters are serialized to JSON strings for storage.
* **Returns:** pd.DataFrame: A DataFrame representation of the pool.
* **from\_dataframe(self, df: pd.DataFrame)**
* **Description:** Loads peptides into the pool from a pandas DataFrame. History and source generation parameters are deserialized from JSON strings.
* **Arguments:**
* df (pd.DataFrame): The DataFrame containing peptide data.
* **save\_pool(self, file\_path: str, file\_format: str \= 'parquet')**
* **Description:** Saves the current peptide pool to a file.
* **Arguments:**
* file\_path (str): The path to save the file.
* file\_format (str): The format to save the file ('parquet', 'csv', or 'json'). Defaults to 'parquet'.
* **load\_pool(self, file\_path: str, file\_format: str \= 'parquet')**
* **Description:** Loads a peptide pool from a file into the current manager.
* **Arguments:**
* file\_path (str): The path to the file to load.
* file\_format (str): The format of the file ('parquet', 'csv', or 'json'). Defaults to 'parquet'.
### **7\. Evaluator**
The Evaluator class manages the evaluation pipeline for peptides. It converts peptides to DataFrames, applies user-defined processing steps (En), and ranks them using a specified ranker function. Intermediate DataFrames can be saved for logging and debugging.
* **class Evaluator**
* **\_\_init\_\_(self, evaluation\_pipeline: List\[Callable\[\[pd.DataFrame\], pd.DataFrame\]\], ranker\_function: Callable\[\[pd.DataFrame\], Tuple\[List\['Peptide'\], Optional\[List\[float\]\]\]\]):**
* **Description:** Initializes the Evaluator with a pipeline of evaluation steps and a ranker function.
* **Arguments:**
* evaluation\_pipeline (List\[Callable\[\[pd.DataFrame\], pd.DataFrame\]\]): A list of functions (En steps). Each function takes a DataFrame and returns a DataFrame. These functions define the sequence of data processing and feature generation.
* ranker\_function (Callable\[\[pd.DataFrame\], Tuple\[List\['Peptide'\], Optional\[List\[float\]\]\]\]): A function that takes the final processed DataFrame and returns a tuple: (List\[Peptide\] of ranked peptides, Optional\[List\[float\]\] of their corresponding scores). This function is responsible for the final selection/ordering of peptides.
* **\_e0\_to\_dataframe(self, peptides: List\['Peptide'\]) \-\> pd.DataFrame**
* **Description:** Converts a list of Peptide objects into the initial DataFrame (E0 step). Each row represents a peptide, with its full data. This is an internal helper function.
* **Arguments:**
* peptides (List\['Peptide'\]): The list of Peptide objects.
* **Returns:** pd.DataFrame: The initial DataFrame for evaluation.
* **\_save\_dataframe(self, df: pd.DataFrame, step\_name: str, round\_identifier: str \= None)**
* **Description:** Saves an intermediate DataFrame to a CSV file for logging and debugging. Filename includes peptide count, feature count, round identifier, step name, and a hash. This is an internal helper function.
* **Arguments:**
* df (pd.DataFrame): The DataFrame to save.
* step\_name (str): The name of the evaluation step (for filename).
* round\_identifier (str, optional): An identifier for the current round (for filename).
* **evaluate(self, peptides: List\['Peptide'\], round\_identifier: str \= None) \-\> Tuple\[List\['Peptide'\], Optional\[List\[float\]\]\]**
* **Description:** Executes the evaluation pipeline on a list of peptides and returns the ranked peptides.
* **Arguments:**
* peptides (List\['Peptide'\]): The list of Peptide objects to evaluate.
* round\_identifier (str, optional): An identifier for the current round, used for logging.
* **Returns:** Tuple\[List\['Peptide'\], Optional\[List\[float\]\]\]: A tuple containing:
* A list of Peptide objects, ranked according to the ranker\_function.
* An optional list of scores corresponding to the ranked peptides (used for truncation).
### **8\. Round Processor (Evolution Logic)**
The PoolRoundProcessor orchestrates a single round of peptide evolution, applying a sequence of mutation, crossover, evaluation, replenishment, and truncation steps as defined by its pipeline.
* **class PoolRoundProcessor**
* **\_\_init\_\_(self)**
* **Description:** Initializes the round processor with an empty pipeline and no generation function set.
* **add\_pipeline\_step(self, step\_type: str, step\_function: Callable, name: str, \*\*params)**
* **Description:** Adds a step to the round processing pipeline.
* **Arguments:**
* step\_type (str): The type of step ('mutation', 'crossover', 'evaluation', 'replenishment', 'truncation', 'custom').
* step\_function (Callable): The function to execute for this step. Its signature depends on step\_type.
* name (str): A descriptive name for the step.
* \*\*params: Parameters specific to the step\_function.
* **Raises:** TypeError: If step\_function is not callable.
* **set\_generation\_function(self, gen\_func: Callable\[\[int\], list\['Peptide'\]\])**
* **Description:** Sets a function to generate new peptides if the pool is too small (used by the replenishment step).
* **Arguments:**
* gen\_func (Callable\[\[int\], list\['Peptide'\]\]): A function that takes the number of peptides to generate and returns a list of Peptide objects.
* **\_execute\_mutation\_step(self, peptides: List\['Peptide'\], mutator: 'PeptideMutator', probability\_of\_application: float) \-\> List\['Peptide'\]**
* **Description:** Internal helper to apply mutations to a list of peptides.
* **\_execute\_crossover\_step(self, peptides: List\['Peptide'\], num\_crossovers: int, crossover\_probability\_per\_pair: float) \-\> List\['Peptide'\]**
* **Description:** Internal helper to apply crossover to a list of peptides.
* **\_execute\_evaluation\_step(self, peptides: List\['Peptide'\], evaluator\_instance: 'Evaluator', round\_identifier: str) \-\> Tuple\[List\['Peptide'\], Optional\[List\[float\]\]\]**
* **Description:** Internal helper to execute the evaluation pipeline.
* **\_execute\_replenishment\_step(self, peptides: List\['Peptide'\], target\_size: int, gen\_func: Callable) \-\> List\['Peptide'\]**
* **Description:** Internal helper to replenish the pool to a target size using the provided generation function.
* **\_execute\_truncation\_step(self, peptides: List\['Peptide'\], max\_size: int, scores: Optional\[List\[float\]\]) \-\> List\['Peptide'\]**
* **Description:** Internal helper to truncate the pool to a maximum size, optionally using scores for selection.
* **run\_round(self, input\_pool\_manager: 'PeptidePoolManager', round\_name: str \= "Evolution Round") \-\> Tuple\['PeptidePoolManager', pd.DataFrame\]**
* **Description:** Executes a complete evolutionary round on the peptide pool based on the configured pipeline.
* **Arguments:**
* input\_pool\_manager (PeptidePoolManager): The PeptidePoolManager of the (n-1) pool.
* round\_name (str): Name of this round for logs and evaluator logging.
* **Returns:** Tuple\[PeptidePoolManager, pd.DataFrame\]: The resulting (n) pool and a DataFrame of logs for this round.
### **9\. Peptide Generator**
The PeptideGenerator class provides a utility to create random peptide SMILES sequences, useful for initializing peptide pools.
* **class PeptideGenerator**
* **\_\_init\_\_(self)**
* **Description:** Initializes the generator with the default amino acids from AMINO\_ACID\_DF.
* **generate\_random\_peptides(self, num\_peptides: int, min\_length: int, max\_length: int) \-\> List\[List\[str\]\]**
* **Description:** Generates a list of random peptide SMILES sequences.
* **Arguments:**
* num\_peptides (int): The number of peptides to generate.
* min\_length (int): The minimum length for generated peptides.
* max\_length (int): The maximum length for generated peptides.
* **Returns:** List\[List\[str\]\]: A list where each element is a list of SMILES strings representing a peptide sequence.
### **10\. Full Pipeline Examples**
This section provides examples of how to use the various components of PepFlex to construct a complete peptide screening or evolution pipeline.
#### **Example 1: Custom Mutation Function**
This demonstrates how to define and use a custom mutation rule with the PeptideMutator.
* **custom\_reverse\_segment(smiles\_list: List\[str\], start\_idx: int \= 0, end\_idx: Optional\[int\] \= None) \-\> List\[str\]**
* **Description:** A custom mutation rule that reverses a segment of the peptide. This function illustrates how a user can define their own mutation logic.
* **Arguments:**
* smiles\_list (List\[str\]): The SMILES sequence of the peptide.
* start\_idx (int): The starting index of the segment to reverse.
* end\_idx (Optional\[int\]): The ending index (exclusive) of the segment to reverse. Defaults to the end of the list.
* **Returns:** List\[str\]: The peptide SMILES sequence with the specified segment reversed.
#### **Example 2: Evaluator Pipeline Steps**
These functions are examples of steps that can be included in the evaluation\_pipeline of the Evaluator class.
* **add\_length\_feature(df: pd.DataFrame) \-\> pd.DataFrame**
* **Description:** Evaluator pipeline step: Adds a 'length' column to the DataFrame based on smiles\_sequence length.
* **Arguments:**
* df (pd.DataFrame): The input DataFrame.
* **Returns:** pd.DataFrame: The DataFrame with the 'length' column added.
* **add\_dummy\_score\_feature(df: pd.DataFrame) \-\> pd.DataFrame**
* **Description:** Evaluator pipeline step: Adds a 'dummy\_score' column for demonstration. This simulates calculating a score based on peptide properties or external models.
* **Arguments:**
* df (pd.DataFrame): The input DataFrame.
* **Returns:** pd.DataFrame: The DataFrame with the 'dummy\_score' column added.
* **filter\_by\_length\_in\_df(df: pd.DataFrame, min\_len: int \= 7\) \-\> pd.DataFrame**
* **Description:** Evaluator pipeline step: Filters the DataFrame to keep peptides above a minimum length.
* **Arguments:**
* df (pd.DataFrame): The input DataFrame.
* min\_len (int): The minimum length to filter by.
* **Returns:** pd.DataFrame: The filtered DataFrame.
#### **Example 3: Ranker Function for Evaluator**
This is an example of a ranker\_function that can be passed to the Evaluator class.
* **rank\_by\_dummy\_score\_and\_reconstruct(df: pd.DataFrame, n\_to\_keep: int \= 20\) \-\> Tuple\[List\['Peptide'\], Optional\[List\[float\]\]\]**
* **Description:** Ranker function: Ranks peptides by 'dummy\_score' and reconstructs Peptide objects. Returns the top N peptides and their scores.
* **Arguments:**
* df (pd.DataFrame): The final processed DataFrame from the evaluation pipeline.
* n\_to\_keep (int): The number of top peptides to return.
* **Returns:** Tuple\[List\['Peptide'\], Optional\[List\[float\]\]\]: A tuple containing:
* A list of Peptide objects, ranked by score.
* A list of their corresponding scores.
#### **Example 4: Setting up and Running an Evolutionary Pipeline**
This example demonstrates how to combine the PeptideGenerator, PeptideMutator, Evaluator, and PoolRoundProcessor to run a multi-round evolutionary simulation.
import pandas as pd
import numpy as np \# Needed for np.random.rand
import random
from datetime import datetime
import copy
import json
import uuid
from typing import List, Tuple, Dict, Callable, Optional, Union
\# Assuming pepflex.py is available and contains all necessary classes and functions.
\# In a real application, you would import directly from your pepflex module:
\# from pepflex import (
\# AMINO\_ACID\_DF, get\_3L\_from\_smiles, get\_1L\_from\_smiles,
\# Peptide, PeptidePoolManager, PeptideMutator, Evaluator, PoolRoundProcessor, PeptideGenerator,
\# add\_length\_feature, add\_dummy\_score\_feature, filter\_by\_length\_in\_df,
\# rank\_by\_dummy\_score\_and\_reconstruct, peptide\_crossover
\# )
\# 1\. Initialize Peptide Generator ( You can use your own \- this one if for reference only )
peptide\_gen \= PeptideGenerator()
\# 2\. Create an initial pool of peptides
initial\_smiles\_lists \= peptide\_gen.generate\_random\_peptides(num\_peptides=50, min\_length=5, max\_length=15)
initial\_pool\_manager \= PeptidePoolManager()
for i, smiles\_list in enumerate(initial\_smiles\_lists):
initial\_pool\_manager.add\_peptide(Peptide(smiles\_list, peptide\_id=f"initial\_pep\_{i}"))
print(f"Initial pool size: {initial\_pool\_manager.get\_pool\_size()}")
\# 3\. Configure the Mutator
mutator \= PeptideMutator()
mutator.add\_mutation\_rule(mutation\_type='n\_terminal\_addition', probability=0.3)
mutator.add\_mutation\_rule(mutation\_type='inter\_mutation', probability=0.5)
\# 4\. Configure the Evaluator
\# Define the evaluation pipeline steps
evaluation\_pipeline\_steps \= \[
add\_length\_feature,
add\_dummy\_score\_feature,
lambda df: filter\_by\_length\_in\_df(df, min\_len=7) \# Using a lambda for parameter passing
\]
\# Define the ranker function
ranker \= lambda df: rank\_by\_dummy\_score\_and\_reconstruct(df, n\_to\_keep=20)
evaluator \= Evaluator(evaluation\_pipeline=evaluation\_pipeline\_steps, ranker\_function=ranker)
\# 5\. Set up the PoolRoundProcessor
round\_processor \= PoolRoundProcessor()
\# Set the generation function for replenishment
round\_processor.set\_generation\_function(
lambda num: \[Peptide(s, source\_generation\_params={"type": "replenishment"}) for s in peptide\_gen.generate\_random\_peptides(num, 5, 15)\]
)
\# Add pipeline steps to the round processor
\# Note: The step\_function for mutation and crossover needs to be the internal helper,
\# not the class instance itself, as the helper functions expect \`peptides\` as the first arg.
\# We pass the mutator instance and other parameters via \*\*step\_params.
round\_processor.add\_pipeline\_step(
step\_type='mutation',
step\_function=round\_processor.\_execute\_mutation\_step,
name='Apply Mutations',
mutator=mutator,
probability\_of\_application=0.8 \# Probability that a given peptide will be mutated
)
round\_processor.add\_pipeline\_step(
step\_type='crossover',
step\_function=round\_processor.\_execute\_crossover\_step,
name='Perform Crossover',
num\_crossovers=10, \# Number of crossover events to attempt
crossover\_probability\_per\_pair=0.7 \# Probability that a selected pair will actually crossover
)
round\_processor.add\_pipeline\_step(
step\_type='evaluation',
step\_function=round\_processor.\_execute\_evaluation\_step,
name='Evaluate and Rank Peptides',
evaluator\_instance=evaluator
)
round\_processor.add\_pipeline\_step(
step\_type='replenishment',
step\_function=round\_processor.\_execute\_replenishment\_step,
name='Replenish Pool',
target\_size=50 \# Maintain a pool size of 50
)
round\_processor.add\_pipeline\_step(
step\_type='truncation',
step\_function=round\_processor.\_execute\_truncation\_step,
name='Truncate Pool',
max\_size=50 \# Truncate to 50 after all operations
)
\# 6\. Run multiple rounds of evolution
current\_pool\_manager \= initial\_pool\_manager
all\_round\_logs\_df \= pd.DataFrame()
num\_evolution\_rounds \= 3
print("\\n--- Starting Evolutionary Simulation \---")
for i in range(num\_evolution\_rounds):
print(f"\\n===== Running Evolution Round {i+1} \=====")
new\_pool\_manager, round\_logs \= round\_processor.run\_round(current\_pool\_manager, round\_name=f"Round\_{i+1}")
current\_pool\_manager \= new\_pool\_manager
all\_round\_logs\_df \= pd.concat(\[all\_round\_logs\_df, round\_logs\], ignore\_index=True)
print(f"End of Round {i+1}. Current pool size: {current\_pool\_manager.get\_pool\_size()}")
print("\\n--- Evolutionary Simulation Finished \---")
\# 7\. Display final results
print("\\nFinal Top Peptides:")
final\_peptides \= current\_pool\_manager.get\_all\_peptides()
for peptide in final\_peptides\[:10\]: \# Display top 10 from final pool
print(f"- ID: {peptide.peptide\_id\[:8\]}..., 1L: {peptide.one\_letter\_sequence}, 3L: {peptide.three\_letter\_sequence}, Length: {peptide.length}")
print("\\nEvolutionary Round Logs:")
print(all\_round\_logs\_df)
**Explanation of the Example:**
1. **Initialization:**
* A PeptideGenerator is created to generate random peptide sequences.
* An initial\_pool\_manager is populated with 50 randomly generated Peptide objects.
2. **Mutator Configuration:**
* A PeptideMutator is initialized.
* Two mutation rules are added: n\_terminal\_addition (adds an amino acid to the N-terminus) and inter\_mutation (substitutes an amino acid within the sequence). Each has a defined probability of occurring.
3. **Evaluator Configuration:**
* The evaluation\_pipeline\_steps list defines the sequence of operations the Evaluator will perform on the peptide DataFrame. Here, it adds a 'length' column, a 'dummy\_score' (simulating a real scoring function), and then filters peptides based on a minimum length.
* The ranker function is set to rank\_by\_dummy\_score\_and\_reconstruct, which sorts peptides by their 'dummy\_score' and returns the top 20\.
* An Evaluator instance is created with these pipeline steps and the ranker.
4. **PoolRoundProcessor Setup:**
* A PoolRoundProcessor is initialized.
* A generation\_function is set, which the replenishment step will use to create new random peptides if the pool size drops below a target.
* Various pipeline steps are added to the round\_processor:
* **mutation**: Applies the configured mutations from the mutator to the peptides.
* **crossover**: Performs crossover operations between peptides to generate new genetic combinations.
* **evaluation**: Runs the Evaluator to score and rank peptides. This step is crucial for selection.
* **replenishment**: Adds new randomly generated peptides if the pool size falls below target\_size.
* **truncation**: Reduces the pool size to max\_size by keeping the highest-scoring peptides.
5. **Running Evolutionary Rounds:**
* The code then enters a loop to run num\_evolution\_rounds (e.g., 3 rounds).
* In each round, round\_processor.run\_round() is called with the current peptide pool.
* The run\_round method orchestrates the execution of all defined pipeline steps in order.
* The current\_pool\_manager is updated with the output of each round, simulating evolution.
* Logs from each round are collected.
6. **Displaying Results:**
* Finally, the example prints the details of the top 10 peptides from the final evolved pool and a DataFrame containing the logs from all evolutionary rounds.
This example provides a hands-on illustration of how to set up and execute a basic peptide evolution simulation using PepFlex's modular components. Users can easily modify the mutation rules, evaluation criteria, and round parameters to design more complex and targeted screening pipelines.
Raw data
{
"_id": null,
"home_page": null,
"name": "pepflex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "peptide, screening, evolution, bioinformatics, chemistry, rdkit",
"author": null,
"author_email": "Kyllian De Vos <kdevospro@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b6/ac/755450ee189dd32504bdcb8130edae7dbaf89513cee56a7c59e6833698af/pepflex-0.0.1.tar.gz",
"platform": null,
"description": "# **PepFlex: A Modular Framework for Peptide Screening and Evolution**\n\nPepFlex is a Python module designed to provide a flexible and extensible framework for in silico peptide screening and evolutionary studies. It offers tools for managing amino acid data, assembling peptides, applying various genetic operations (mutations and crossovers), and processing evolutionary rounds through a customizable evaluation pipeline. \n**Note on RDKit Dependency:** PepFlex utilizes RDKit for chemical functionalities, including SMILES canonicalization and peptide assembly. If RDKit is not installed, these functionalities will be limited, and a warning will be issued upon module import.\n\n### **1\\. Amino Acid DataFrame Utilities and Conversions**\n\nPepFlex maintains a global DataFrame, AMINO\\_ACID\\_DF, which stores information about standard amino acids, including their one-letter, three-letter, and SMILES representations. This DataFrame can be extended to include non-canonical or modified amino acids.\n\n* **AMINO\\_ACID\\_DF (Global DataFrame)** \n * **Description:** A pandas DataFrame indexed by the 3-letter code, containing 1L (one-letter code), SMILES (original SMILES string), and SMILES\\_Canon (canonical RDKit SMILES). \n * **Purpose:** Serves as the central repository for amino acid data, facilitating conversions and lookups. \n* **\\_canonicalize\\_smiles(smiles: str) \\-\\> str** \n * **Description:** Converts a SMILES string to its canonical RDKit form for reliable comparison. This is an internal helper function. \n * **Arguments:** \n * smiles (str): The SMILES string to canonicalize. \n * **Returns:** str: The canonical SMILES string, or an empty string if invalid or RDKit is not available. \n* **add\\_amino\\_acid(three\\_letter\\_code: str, one\\_letter\\_code: str, smiles: str)** \n * **Description:** Adds a new amino acid or updates an existing one in the AMINO\\_ACINO\\_DF using its 3-letter code as the primary key. \n * **Arguments:** \n * three\\_letter\\_code (str): The 3-letter code (e.g., \"Ala\", \"Cys\"). \n * one\\_letter\\_code (str): The 1-letter code (e.g., \"A\", \"C\"). \n * smiles (str): The SMILES string representation. \n * **Behavior:** Prints a warning if the code already exists and updates it. Prints an error if the provided SMILES is invalid. \n* **get\\_smiles\\_from\\_3L(three\\_letter\\_code: str) \\-\\> str** \n * **Description:** Retrieves the original SMILES for a given 3-letter code. \n * **Arguments:** \n * three\\_letter\\_code (str): The 3-letter code of the amino acid. \n * **Returns:** str: The SMILES string. \n * **Raises:** ValueError: If the 3-letter code is not found. \n* **get\\_1L\\_from\\_3L(three\\_letter\\_code: str) \\-\\> str** \n * **Description:** Retrieves the 1-letter code for a given 3-letter code. \n * **Arguments:** \n * three\\_letter\\_code (str): The 3-letter code of the amino acid. \n * **Returns:** str: The 1-letter code. \n * **Raises:** ValueError: If the 3-letter code is not found. \n* **get\\_smiles\\_from\\_1L(one\\_letter\\_code: str) \\-\\> str** \n * **Description:** Retrieves the SMILES for a given 1-letter code. \n * **Arguments:** \n * one\\_letter\\_code (str): The 1-letter code of the amino acid. \n * **Returns:** str: The SMILES string. \n * **Raises:** ValueError: If the 1-letter code is not found. \n* **get\\_3L\\_from\\_1L(one\\_letter\\_code: str) \\-\\> str** \n * **Description:** Retrieves the 3-letter code for a given 1-letter code. \n * **Arguments:** \n * one\\_letter\\_code (str): The 1-letter code of the amino acid. \n * **Returns:** str: The 3-letter code. \n * **Raises:** ValueError: If the 1-letter code is not found. \n* **get\\_1L\\_from\\_smiles(smiles: str) \\-\\> str** \n * **Description:** Retrieves the 1-letter code for a given SMILES, using its canonical form for lookup. \n * **Arguments:** \n * smiles (str): The SMILES string of the amino acid. \n * **Returns:** str: The 1-letter code. \n * **Raises:** ValueError: If the SMILES is invalid or not found. \n* **get\\_3L\\_from\\_smiles(smiles: str) \\-\\> str** \n * **Description:** Retrieves the 3-letter code for a given SMILES, using its canonical form for lookup. \n * **Arguments:** \n * smiles (str): The SMILES string of the amino acid. \n * **Returns:** str: The 3-letter code. \n * **Raises:** ValueError: If the SMILES is invalid or not found. \n* **save\\_amino\\_acid\\_data(file\\_path: str, file\\_format: str \\= 'csv')** \n * **Description:** Saves the AMINO\\_ACID\\_DF to a specified file. \n * **Arguments:** \n * file\\_path (str): The path to save the file. \n * file\\_format (str): The format to save the file ('csv' or 'parquet'). Defaults to 'csv'. \n* **load\\_amino\\_acid\\_data(file\\_path: str, file\\_format: str \\= 'csv', overwrite: bool \\= True)** \n * **Description:** Loads amino acid data from a file and updates the global AMINO\\_ACID\\_DF. \n * **Arguments:** \n * file\\_path (str): The path to the file. \n * file\\_format (str): The format of the file ('csv' or 'parquet'). Defaults to 'csv'. \n * overwrite (bool): If True, overwrites the existing AMINO\\_ACID\\_DF. If False, merges the loaded data, keeping the last duplicate entry.\n\n### **2\\. Peptide Assembler (Beta)**\n\nThis function allows the construction of a complete peptide molecule from a sequence of amino acid SMILES strings.\n\n* **assemble\\_peptide(residue\\_list: Union\\[List\\[str\\], str\\], input\\_type: int \\= 0\\) \\-\\> Optional\\[Chem.Mol\\]** \n * **Description:** Assembles a peptide from a list of amino acid SMILES strings (N- to C-terminus order) or a hyphen-separated string of 3-letter codes. Each input SMILES must represent an amino acid with free N and C termini (e.g., N\\[C@@H\\](R)C(=O)O). \n * **Arguments:** \n * residue\\_list (Union\\[List\\[str\\], str\\]): A list of SMILES strings or a string of 3-letter codes (e.g., \"Ala-Glu-Asp-Gly\"). \n * input\\_type (int): 0 for a list of SMILES (default), 1 for a 3-letter code string. \n * **Returns:** Optional\\[Chem.Mol\\]: An RDKit Mol object representing the assembled peptide, or None if the input list is empty. \n * **Raises:** \n * ValueError: If RDKit is not installed, SMILES cannot be parsed, or a 3-letter code is not found. \n * RuntimeError: If peptide bond formation fails between residues.\n\n### **3\\. Miscellaneous Utilities**\n\nThis section includes functions for converting peptide sequences between different amino acid representations and a function for performing genetic crossover operations.\n\n* **convert\\_1L\\_to\\_smiles\\_list(one\\_letter\\_str: str) \\-\\> List\\[str\\]** \n * **Description:** Converts a string of 1-letter amino acid codes to a list of their corresponding SMILES strings. \n * **Arguments:** \n * one\\_letter\\_str (str): A string of 1-letter codes (e.g., \"AEDG\"). \n * **Returns:** List\\[str\\]: A list of SMILES strings. \n* **convert\\_smiles\\_list\\_to\\_3L(smiles\\_list: List\\[str\\]) \\-\\> str** \n * **Description:** Converts a list of SMILES strings to a hyphen-separated string of 3-letter amino acid codes. \n * **Arguments:** \n * smiles\\_list (List\\[str\\]): A list of SMILES strings. \n * **Returns:** str: A string of 3-letter codes (e.g., \"Ala-Glu-Asp-Gly\"). \n* **convert\\_1L\\_str\\_to\\_3L(one\\_letter\\_str: str) \\-\\> str** \n * **Description:** Converts a 1-letter amino acid string to a hyphen-separated 3-letter amino acid string. This only works for canonical amino acids present in the global DataFrame. \n * **Arguments:** \n * one\\_letter\\_str (str): A string of 1-letter codes (e.g., \"AEDG\"). \n * **Returns:** str: A string of 3-letter codes (e.g., \"Ala-Glu-Asp-Gly\"). \n* **convert\\_3L\\_str\\_to\\_1L(three\\_letter\\_str: str) \\-\\> str** \n * **Description:** Converts a hyphen-separated 3-letter amino acid string to a 1-letter amino acid string. This only works for canonical amino acids present in the global DataFrame. \n * **Arguments:** \n * three\\_letter\\_str (str): A string of 3-letter codes (e.g., \"Ala-Glu-Asp-Gly\"). \n * **Returns:** str: A string of 1-letter codes (e.g., \"AEDG\"). \n* **convert\\_smiles\\_list\\_to\\_1L(smiles\\_list: List\\[str\\]) \\-\\> str** \n * **Description:** Converts a list of SMILES strings to a 1-letter amino acid string. This only works for canonical amino acids present in the global DataFrame. \n * **Arguments:** \n * smiles\\_list (List\\[str\\]): A list of SMILES strings. \n * **Returns:** str: A string of 1-letter amino acid codes (e.g., \"AEDG\"). \n* **peptide\\_crossover(parent1\\_smiles: List\\[str\\], parent2\\_smiles: List\\[str\\]) \\-\\> Tuple\\[List\\[str\\], List\\[str\\]\\]** \n * **Description:** Performs a single-point crossover operation between two parent peptides. The cut-off point is determined as the middle of each peptide, with a random choice for odd-length peptides. The segments are then exchanged to form two child peptides. Handles empty or very short peptides. \n * **Arguments:** \n * parent1\\_smiles (List\\[str\\]): The SMILES sequence of the first parent. \n * parent2\\_smiles (List\\[str\\]): The SMILES sequence of the second parent. \n * **Returns:** Tuple\\[List\\[str\\], List\\[str\\]\\]: A tuple containing the SMILES sequences of the two child peptides.\n\n### **4\\. Peptide Mutator**\n\nThe PeptideMutator class enables the application of various mutation rules to peptide sequences. It supports predefined mutation types and allows for custom user-defined mutation functions.\n\n* **class PeptideMutator** \n * **\\_\\_init\\_\\_(self)** \n * **Description:** Initializes the PeptideMutator with an empty list of mutation rules and sets the default amino acid DataFrame. \n * **add\\_mutation\\_rule(self, mutation\\_type: Union\\[str, Callable\\], probability: float, \\*\\*kwargs)** \n * **Description:** Adds a mutation rule to the mutator. \n * **Arguments:** \n * mutation\\_type (Union\\[str, Callable\\]): The type of mutation. Can be a string for predefined rules or a callable function for custom rules. \n * **Predefined Types:** 'intra\\_sequence\\_suppression', 'n\\_terminal\\_suppression', 'c\\_terminal\\_suppression', 'n\\_terminal\\_addition', 'c\\_terminal\\_addition', 'intra\\_sequence\\_addition', 'inter\\_mutation', 'n\\_terminal\\_mutation', 'c\\_terminal\\_mutation', 'segment\\_duplication', 'segment\\_inversion', 'segment\\_translocation'. \n * **Custom Functions:** Should accept smiles\\_list: List\\[str\\] as the first argument and \\*\\*kwargs for additional parameters, returning a List\\[str\\]. \n * probability (float): The probability (0.0 to 1.0) of applying this rule. \n * \\*\\*kwargs: Additional parameters specific to the mutation rule. For predefined rules, these might include allowed\\_amino\\_acids\\_df, source\\_amino\\_acids\\_df, target\\_amino\\_acids\\_df, min\\_length, max\\_length. \n * **Raises:** \n * ValueError: If probability is out of range or mutation type is unknown. \n * TypeError: If DataFrame parameters are not pandas.DataFrame. \n * **apply\\_mutations(self, initial\\_smiles\\_list: list) \\-\\> list** \n * **Description:** Applies all configured mutation rules to a given peptide SMILES sequence based on their defined probabilities. \n * **Arguments:** \n * initial\\_smiles\\_list (List\\[str\\]): The initial SMILES sequence of the peptide. \n * **Returns:** List\\[str\\]: The mutated SMILES sequence.\n\n### **5\\. Peptide Class**\n\nThe Peptide class encapsulates all information related to a single peptide, including its sequence, unique identifier, creation date, and a history of events.\n\n* **class Peptide** \n * **\\_\\_init\\_\\_(self, smiles\\_sequence: list, peptide\\_id: str \\= None, creation\\_date: datetime \\= None, history: list \\= None, source\\_generation\\_params: dict \\= None)** \n * **Description:** Initializes a Peptide object. \n * **Arguments:** \n * smiles\\_sequence (list): A list of SMILES strings representing the amino acid sequence. \n * peptide\\_id (str, optional): Unique identifier for the peptide. Generated if None. \n * creation\\_date (datetime, optional): Timestamp of peptide creation. Defaults to now. \n * history (list, optional): A list of dictionaries detailing events in the peptide's lifecycle. \n * source\\_generation\\_params (dict, optional): Parameters related to how the peptide was generated. \n * **set\\_sequences\\_from\\_global\\_converter(self)** \n * **Description:** Sets the 1-letter and 3-letter sequence representations using global conversion functions. Handles cases where SMILES might not be recognized by marking them as \"N/A\" and logging. \n * **one\\_letter\\_sequence (property)** \n * **Description:** Returns the 1-letter code sequence of the peptide. \n * **three\\_letter\\_sequence (property)** \n * **Description:** Returns the 3-letter code sequence of the peptide. \n * **add\\_history\\_entry(self, event\\_type: str, details: dict)** \n * **Description:** Adds an entry to the peptide's history log. \n * **Arguments:** \n * event\\_type (str): The type of event (e.g., \"mutation\", \"crossover\", \"replenishment\"). \n * details (dict): A dictionary containing event-specific details. \n * **to\\_dict(self) \\-\\> Dict** \n * **Description:** Converts the Peptide object to a dictionary representation. \n * **Returns:** Dict: A dictionary containing all peptide attributes. \n * **from\\_dict(cls, data: Dict) \\-\\> 'Peptide' (classmethod)** \n * **Description:** Creates a Peptide object from a dictionary representation. \n * **Arguments:** \n * data (Dict): A dictionary containing peptide data. \n * **Returns:** Peptide: A new Peptide instance. \n * **\\_\\_repr\\_\\_(self) \\-\\> str** \n * **Description:** Provides a string representation of the Peptide object for debugging. \n * **\\_\\_eq\\_\\_(self, other: object) \\-\\> bool** \n * **Description:** Defines equality comparison based on peptide\\_id. \n * **\\_\\_hash\\_\\_(self) \\-\\> int** \n * **Description:** Defines the hash for the object based on peptide\\_id.\n\n### **6\\. PeptidePoolManager Class**\n\nThe PeptidePoolManager class is responsible for managing a collection of Peptide objects, providing functionalities to add, retrieve, remove, and persist the peptide pool.\n\n* **class PeptidePoolManager** \n * **\\_\\_init\\_\\_(self)** \n * **Description:** Initializes an empty dictionary to store Peptide objects, keyed by their peptide\\_id. \n * **add\\_peptide(self, peptide: Peptide)** \n * **Description:** Adds a Peptide object to the pool. \n * **Arguments:** \n * peptide (Peptide): The Peptide object to add. \n * **Raises:** TypeError: If the object is not a Peptide instance. \n * **get\\_peptide(self, peptide\\_id: str) \\-\\> Optional\\[Peptide\\]** \n * **Description:** Retrieves a peptide by its ID. \n * **Arguments:** \n * peptide\\_id (str): The ID of the peptide. \n * **Returns:** Optional\\[Peptide\\]: The Peptide object if found, else None. \n * **get\\_all\\_peptides(self) \\-\\> List\\[Peptide\\]** \n * **Description:** Returns a list of all Peptide objects currently in the pool. \n * **Returns:** List\\[Peptide\\]: A list of Peptide objects. \n * **remove\\_peptide(self, peptide\\_id: str)** \n * **Description:** Removes a peptide from the pool by its ID. \n * **Arguments:** \n * peptide\\_id (str): The ID of the peptide to remove. \n * **clear\\_pool(self)** \n * **Description:** Clears all peptides from the pool. \n * **get\\_pool\\_size(self) \\-\\> int** \n * **Description:** Returns the current number of peptides in the pool. \n * **Returns:** int: The number of peptides. \n * **to\\_dataframe(self) \\-\\> pd.DataFrame** \n * **Description:** Converts the peptide pool into a pandas DataFrame. History and source generation parameters are serialized to JSON strings for storage. \n * **Returns:** pd.DataFrame: A DataFrame representation of the pool. \n * **from\\_dataframe(self, df: pd.DataFrame)** \n * **Description:** Loads peptides into the pool from a pandas DataFrame. History and source generation parameters are deserialized from JSON strings. \n * **Arguments:** \n * df (pd.DataFrame): The DataFrame containing peptide data. \n * **save\\_pool(self, file\\_path: str, file\\_format: str \\= 'parquet')** \n * **Description:** Saves the current peptide pool to a file. \n * **Arguments:** \n * file\\_path (str): The path to save the file. \n * file\\_format (str): The format to save the file ('parquet', 'csv', or 'json'). Defaults to 'parquet'. \n * **load\\_pool(self, file\\_path: str, file\\_format: str \\= 'parquet')** \n * **Description:** Loads a peptide pool from a file into the current manager. \n * **Arguments:** \n * file\\_path (str): The path to the file to load. \n * file\\_format (str): The format of the file ('parquet', 'csv', or 'json'). Defaults to 'parquet'.\n\n### **7\\. Evaluator**\n\nThe Evaluator class manages the evaluation pipeline for peptides. It converts peptides to DataFrames, applies user-defined processing steps (En), and ranks them using a specified ranker function. Intermediate DataFrames can be saved for logging and debugging.\n\n* **class Evaluator** \n * **\\_\\_init\\_\\_(self, evaluation\\_pipeline: List\\[Callable\\[\\[pd.DataFrame\\], pd.DataFrame\\]\\], ranker\\_function: Callable\\[\\[pd.DataFrame\\], Tuple\\[List\\['Peptide'\\], Optional\\[List\\[float\\]\\]\\]\\]):** \n * **Description:** Initializes the Evaluator with a pipeline of evaluation steps and a ranker function. \n * **Arguments:** \n * evaluation\\_pipeline (List\\[Callable\\[\\[pd.DataFrame\\], pd.DataFrame\\]\\]): A list of functions (En steps). Each function takes a DataFrame and returns a DataFrame. These functions define the sequence of data processing and feature generation. \n * ranker\\_function (Callable\\[\\[pd.DataFrame\\], Tuple\\[List\\['Peptide'\\], Optional\\[List\\[float\\]\\]\\]\\]): A function that takes the final processed DataFrame and returns a tuple: (List\\[Peptide\\] of ranked peptides, Optional\\[List\\[float\\]\\] of their corresponding scores). This function is responsible for the final selection/ordering of peptides. \n * **\\_e0\\_to\\_dataframe(self, peptides: List\\['Peptide'\\]) \\-\\> pd.DataFrame** \n * **Description:** Converts a list of Peptide objects into the initial DataFrame (E0 step). Each row represents a peptide, with its full data. This is an internal helper function. \n * **Arguments:** \n * peptides (List\\['Peptide'\\]): The list of Peptide objects. \n * **Returns:** pd.DataFrame: The initial DataFrame for evaluation. \n * **\\_save\\_dataframe(self, df: pd.DataFrame, step\\_name: str, round\\_identifier: str \\= None)** \n * **Description:** Saves an intermediate DataFrame to a CSV file for logging and debugging. Filename includes peptide count, feature count, round identifier, step name, and a hash. This is an internal helper function. \n * **Arguments:** \n * df (pd.DataFrame): The DataFrame to save. \n * step\\_name (str): The name of the evaluation step (for filename). \n * round\\_identifier (str, optional): An identifier for the current round (for filename). \n * **evaluate(self, peptides: List\\['Peptide'\\], round\\_identifier: str \\= None) \\-\\> Tuple\\[List\\['Peptide'\\], Optional\\[List\\[float\\]\\]\\]** \n * **Description:** Executes the evaluation pipeline on a list of peptides and returns the ranked peptides. \n * **Arguments:** \n * peptides (List\\['Peptide'\\]): The list of Peptide objects to evaluate. \n * round\\_identifier (str, optional): An identifier for the current round, used for logging. \n * **Returns:** Tuple\\[List\\['Peptide'\\], Optional\\[List\\[float\\]\\]\\]: A tuple containing: \n * A list of Peptide objects, ranked according to the ranker\\_function. \n * An optional list of scores corresponding to the ranked peptides (used for truncation).\n\n### **8\\. Round Processor (Evolution Logic)**\n\nThe PoolRoundProcessor orchestrates a single round of peptide evolution, applying a sequence of mutation, crossover, evaluation, replenishment, and truncation steps as defined by its pipeline.\n\n* **class PoolRoundProcessor** \n * **\\_\\_init\\_\\_(self)** \n * **Description:** Initializes the round processor with an empty pipeline and no generation function set. \n * **add\\_pipeline\\_step(self, step\\_type: str, step\\_function: Callable, name: str, \\*\\*params)** \n * **Description:** Adds a step to the round processing pipeline. \n * **Arguments:** \n * step\\_type (str): The type of step ('mutation', 'crossover', 'evaluation', 'replenishment', 'truncation', 'custom'). \n * step\\_function (Callable): The function to execute for this step. Its signature depends on step\\_type. \n * name (str): A descriptive name for the step. \n * \\*\\*params: Parameters specific to the step\\_function. \n * **Raises:** TypeError: If step\\_function is not callable. \n * **set\\_generation\\_function(self, gen\\_func: Callable\\[\\[int\\], list\\['Peptide'\\]\\])** \n * **Description:** Sets a function to generate new peptides if the pool is too small (used by the replenishment step). \n * **Arguments:** \n * gen\\_func (Callable\\[\\[int\\], list\\['Peptide'\\]\\]): A function that takes the number of peptides to generate and returns a list of Peptide objects. \n * **\\_execute\\_mutation\\_step(self, peptides: List\\['Peptide'\\], mutator: 'PeptideMutator', probability\\_of\\_application: float) \\-\\> List\\['Peptide'\\]** \n * **Description:** Internal helper to apply mutations to a list of peptides. \n * **\\_execute\\_crossover\\_step(self, peptides: List\\['Peptide'\\], num\\_crossovers: int, crossover\\_probability\\_per\\_pair: float) \\-\\> List\\['Peptide'\\]** \n * **Description:** Internal helper to apply crossover to a list of peptides. \n * **\\_execute\\_evaluation\\_step(self, peptides: List\\['Peptide'\\], evaluator\\_instance: 'Evaluator', round\\_identifier: str) \\-\\> Tuple\\[List\\['Peptide'\\], Optional\\[List\\[float\\]\\]\\]** \n * **Description:** Internal helper to execute the evaluation pipeline. \n * **\\_execute\\_replenishment\\_step(self, peptides: List\\['Peptide'\\], target\\_size: int, gen\\_func: Callable) \\-\\> List\\['Peptide'\\]** \n * **Description:** Internal helper to replenish the pool to a target size using the provided generation function. \n * **\\_execute\\_truncation\\_step(self, peptides: List\\['Peptide'\\], max\\_size: int, scores: Optional\\[List\\[float\\]\\]) \\-\\> List\\['Peptide'\\]** \n * **Description:** Internal helper to truncate the pool to a maximum size, optionally using scores for selection. \n * **run\\_round(self, input\\_pool\\_manager: 'PeptidePoolManager', round\\_name: str \\= \"Evolution Round\") \\-\\> Tuple\\['PeptidePoolManager', pd.DataFrame\\]** \n * **Description:** Executes a complete evolutionary round on the peptide pool based on the configured pipeline. \n * **Arguments:** \n * input\\_pool\\_manager (PeptidePoolManager): The PeptidePoolManager of the (n-1) pool. \n * round\\_name (str): Name of this round for logs and evaluator logging. \n * **Returns:** Tuple\\[PeptidePoolManager, pd.DataFrame\\]: The resulting (n) pool and a DataFrame of logs for this round.\n\n### **9\\. Peptide Generator**\n\nThe PeptideGenerator class provides a utility to create random peptide SMILES sequences, useful for initializing peptide pools.\n\n* **class PeptideGenerator** \n * **\\_\\_init\\_\\_(self)** \n * **Description:** Initializes the generator with the default amino acids from AMINO\\_ACID\\_DF. \n * **generate\\_random\\_peptides(self, num\\_peptides: int, min\\_length: int, max\\_length: int) \\-\\> List\\[List\\[str\\]\\]** \n * **Description:** Generates a list of random peptide SMILES sequences. \n * **Arguments:** \n * num\\_peptides (int): The number of peptides to generate. \n * min\\_length (int): The minimum length for generated peptides. \n * max\\_length (int): The maximum length for generated peptides. \n * **Returns:** List\\[List\\[str\\]\\]: A list where each element is a list of SMILES strings representing a peptide sequence.\n\n### **10\\. Full Pipeline Examples**\n\nThis section provides examples of how to use the various components of PepFlex to construct a complete peptide screening or evolution pipeline.\n\n#### **Example 1: Custom Mutation Function**\n\nThis demonstrates how to define and use a custom mutation rule with the PeptideMutator.\n\n* **custom\\_reverse\\_segment(smiles\\_list: List\\[str\\], start\\_idx: int \\= 0, end\\_idx: Optional\\[int\\] \\= None) \\-\\> List\\[str\\]** \n * **Description:** A custom mutation rule that reverses a segment of the peptide. This function illustrates how a user can define their own mutation logic. \n * **Arguments:** \n * smiles\\_list (List\\[str\\]): The SMILES sequence of the peptide. \n * start\\_idx (int): The starting index of the segment to reverse. \n * end\\_idx (Optional\\[int\\]): The ending index (exclusive) of the segment to reverse. Defaults to the end of the list. \n * **Returns:** List\\[str\\]: The peptide SMILES sequence with the specified segment reversed.\n\n#### **Example 2: Evaluator Pipeline Steps**\n\nThese functions are examples of steps that can be included in the evaluation\\_pipeline of the Evaluator class.\n\n* **add\\_length\\_feature(df: pd.DataFrame) \\-\\> pd.DataFrame** \n * **Description:** Evaluator pipeline step: Adds a 'length' column to the DataFrame based on smiles\\_sequence length. \n * **Arguments:** \n * df (pd.DataFrame): The input DataFrame. \n * **Returns:** pd.DataFrame: The DataFrame with the 'length' column added. \n* **add\\_dummy\\_score\\_feature(df: pd.DataFrame) \\-\\> pd.DataFrame** \n * **Description:** Evaluator pipeline step: Adds a 'dummy\\_score' column for demonstration. This simulates calculating a score based on peptide properties or external models. \n * **Arguments:** \n * df (pd.DataFrame): The input DataFrame. \n * **Returns:** pd.DataFrame: The DataFrame with the 'dummy\\_score' column added. \n* **filter\\_by\\_length\\_in\\_df(df: pd.DataFrame, min\\_len: int \\= 7\\) \\-\\> pd.DataFrame** \n * **Description:** Evaluator pipeline step: Filters the DataFrame to keep peptides above a minimum length. \n * **Arguments:** \n * df (pd.DataFrame): The input DataFrame. \n * min\\_len (int): The minimum length to filter by. \n * **Returns:** pd.DataFrame: The filtered DataFrame.\n\n#### **Example 3: Ranker Function for Evaluator**\n\nThis is an example of a ranker\\_function that can be passed to the Evaluator class.\n\n* **rank\\_by\\_dummy\\_score\\_and\\_reconstruct(df: pd.DataFrame, n\\_to\\_keep: int \\= 20\\) \\-\\> Tuple\\[List\\['Peptide'\\], Optional\\[List\\[float\\]\\]\\]** \n * **Description:** Ranker function: Ranks peptides by 'dummy\\_score' and reconstructs Peptide objects. Returns the top N peptides and their scores. \n * **Arguments:** \n * df (pd.DataFrame): The final processed DataFrame from the evaluation pipeline. \n * n\\_to\\_keep (int): The number of top peptides to return. \n * **Returns:** Tuple\\[List\\['Peptide'\\], Optional\\[List\\[float\\]\\]\\]: A tuple containing: \n * A list of Peptide objects, ranked by score. \n * A list of their corresponding scores.\n\n#### **Example 4: Setting up and Running an Evolutionary Pipeline**\n\nThis example demonstrates how to combine the PeptideGenerator, PeptideMutator, Evaluator, and PoolRoundProcessor to run a multi-round evolutionary simulation. \nimport pandas as pd \nimport numpy as np \\# Needed for np.random.rand \nimport random \nfrom datetime import datetime \nimport copy \nimport json \nimport uuid \nfrom typing import List, Tuple, Dict, Callable, Optional, Union\n\n\\# Assuming pepflex.py is available and contains all necessary classes and functions. \n\\# In a real application, you would import directly from your pepflex module: \n\\# from pepflex import ( \n\\# AMINO\\_ACID\\_DF, get\\_3L\\_from\\_smiles, get\\_1L\\_from\\_smiles, \n\\# Peptide, PeptidePoolManager, PeptideMutator, Evaluator, PoolRoundProcessor, PeptideGenerator, \n\\# add\\_length\\_feature, add\\_dummy\\_score\\_feature, filter\\_by\\_length\\_in\\_df, \n\\# rank\\_by\\_dummy\\_score\\_and\\_reconstruct, peptide\\_crossover \n\\# )\n\n\\# 1\\. Initialize Peptide Generator ( You can use your own \\- this one if for reference only ) \npeptide\\_gen \\= PeptideGenerator()\n\n\\# 2\\. Create an initial pool of peptides \ninitial\\_smiles\\_lists \\= peptide\\_gen.generate\\_random\\_peptides(num\\_peptides=50, min\\_length=5, max\\_length=15) \ninitial\\_pool\\_manager \\= PeptidePoolManager() \nfor i, smiles\\_list in enumerate(initial\\_smiles\\_lists): \n initial\\_pool\\_manager.add\\_peptide(Peptide(smiles\\_list, peptide\\_id=f\"initial\\_pep\\_{i}\"))\n\nprint(f\"Initial pool size: {initial\\_pool\\_manager.get\\_pool\\_size()}\")\n\n\\# 3\\. Configure the Mutator \nmutator \\= PeptideMutator() \nmutator.add\\_mutation\\_rule(mutation\\_type='n\\_terminal\\_addition', probability=0.3) \nmutator.add\\_mutation\\_rule(mutation\\_type='inter\\_mutation', probability=0.5)\n\n\\# 4\\. Configure the Evaluator \n\\# Define the evaluation pipeline steps \nevaluation\\_pipeline\\_steps \\= \\[ \n add\\_length\\_feature, \n add\\_dummy\\_score\\_feature, \n lambda df: filter\\_by\\_length\\_in\\_df(df, min\\_len=7) \\# Using a lambda for parameter passing \n\\] \n\\# Define the ranker function \nranker \\= lambda df: rank\\_by\\_dummy\\_score\\_and\\_reconstruct(df, n\\_to\\_keep=20)\n\nevaluator \\= Evaluator(evaluation\\_pipeline=evaluation\\_pipeline\\_steps, ranker\\_function=ranker)\n\n\\# 5\\. Set up the PoolRoundProcessor \nround\\_processor \\= PoolRoundProcessor()\n\n\\# Set the generation function for replenishment \nround\\_processor.set\\_generation\\_function( \n lambda num: \\[Peptide(s, source\\_generation\\_params={\"type\": \"replenishment\"}) for s in peptide\\_gen.generate\\_random\\_peptides(num, 5, 15)\\] \n)\n\n\\# Add pipeline steps to the round processor \n\\# Note: The step\\_function for mutation and crossover needs to be the internal helper, \n\\# not the class instance itself, as the helper functions expect \\`peptides\\` as the first arg. \n\\# We pass the mutator instance and other parameters via \\*\\*step\\_params. \nround\\_processor.add\\_pipeline\\_step( \n step\\_type='mutation', \n step\\_function=round\\_processor.\\_execute\\_mutation\\_step, \n name='Apply Mutations', \n mutator=mutator, \n probability\\_of\\_application=0.8 \\# Probability that a given peptide will be mutated \n)\n\nround\\_processor.add\\_pipeline\\_step( \n step\\_type='crossover', \n step\\_function=round\\_processor.\\_execute\\_crossover\\_step, \n name='Perform Crossover', \n num\\_crossovers=10, \\# Number of crossover events to attempt \n crossover\\_probability\\_per\\_pair=0.7 \\# Probability that a selected pair will actually crossover \n)\n\nround\\_processor.add\\_pipeline\\_step( \n step\\_type='evaluation', \n step\\_function=round\\_processor.\\_execute\\_evaluation\\_step, \n name='Evaluate and Rank Peptides', \n evaluator\\_instance=evaluator \n)\n\nround\\_processor.add\\_pipeline\\_step( \n step\\_type='replenishment', \n step\\_function=round\\_processor.\\_execute\\_replenishment\\_step, \n name='Replenish Pool', \n target\\_size=50 \\# Maintain a pool size of 50 \n)\n\nround\\_processor.add\\_pipeline\\_step( \n step\\_type='truncation', \n step\\_function=round\\_processor.\\_execute\\_truncation\\_step, \n name='Truncate Pool', \n max\\_size=50 \\# Truncate to 50 after all operations \n)\n\n\\# 6\\. Run multiple rounds of evolution \ncurrent\\_pool\\_manager \\= initial\\_pool\\_manager \nall\\_round\\_logs\\_df \\= pd.DataFrame()\n\nnum\\_evolution\\_rounds \\= 3\n\nprint(\"\\\\n--- Starting Evolutionary Simulation \\---\") \nfor i in range(num\\_evolution\\_rounds): \n print(f\"\\\\n===== Running Evolution Round {i+1} \\=====\") \n new\\_pool\\_manager, round\\_logs \\= round\\_processor.run\\_round(current\\_pool\\_manager, round\\_name=f\"Round\\_{i+1}\") \n current\\_pool\\_manager \\= new\\_pool\\_manager \n all\\_round\\_logs\\_df \\= pd.concat(\\[all\\_round\\_logs\\_df, round\\_logs\\], ignore\\_index=True) \n print(f\"End of Round {i+1}. Current pool size: {current\\_pool\\_manager.get\\_pool\\_size()}\")\n\nprint(\"\\\\n--- Evolutionary Simulation Finished \\---\")\n\n\\# 7\\. Display final results \nprint(\"\\\\nFinal Top Peptides:\") \nfinal\\_peptides \\= current\\_pool\\_manager.get\\_all\\_peptides() \nfor peptide in final\\_peptides\\[:10\\]: \\# Display top 10 from final pool \n print(f\"- ID: {peptide.peptide\\_id\\[:8\\]}..., 1L: {peptide.one\\_letter\\_sequence}, 3L: {peptide.three\\_letter\\_sequence}, Length: {peptide.length}\")\n\nprint(\"\\\\nEvolutionary Round Logs:\") \nprint(all\\_round\\_logs\\_df)\n\n**Explanation of the Example:**\n\n1. **Initialization:** \n * A PeptideGenerator is created to generate random peptide sequences. \n * An initial\\_pool\\_manager is populated with 50 randomly generated Peptide objects. \n2. **Mutator Configuration:** \n * A PeptideMutator is initialized. \n * Two mutation rules are added: n\\_terminal\\_addition (adds an amino acid to the N-terminus) and inter\\_mutation (substitutes an amino acid within the sequence). Each has a defined probability of occurring. \n3. **Evaluator Configuration:** \n * The evaluation\\_pipeline\\_steps list defines the sequence of operations the Evaluator will perform on the peptide DataFrame. Here, it adds a 'length' column, a 'dummy\\_score' (simulating a real scoring function), and then filters peptides based on a minimum length. \n * The ranker function is set to rank\\_by\\_dummy\\_score\\_and\\_reconstruct, which sorts peptides by their 'dummy\\_score' and returns the top 20\\. \n * An Evaluator instance is created with these pipeline steps and the ranker. \n4. **PoolRoundProcessor Setup:** \n * A PoolRoundProcessor is initialized. \n * A generation\\_function is set, which the replenishment step will use to create new random peptides if the pool size drops below a target. \n * Various pipeline steps are added to the round\\_processor: \n * **mutation**: Applies the configured mutations from the mutator to the peptides. \n * **crossover**: Performs crossover operations between peptides to generate new genetic combinations. \n * **evaluation**: Runs the Evaluator to score and rank peptides. This step is crucial for selection. \n * **replenishment**: Adds new randomly generated peptides if the pool size falls below target\\_size. \n * **truncation**: Reduces the pool size to max\\_size by keeping the highest-scoring peptides. \n5. **Running Evolutionary Rounds:** \n * The code then enters a loop to run num\\_evolution\\_rounds (e.g., 3 rounds). \n * In each round, round\\_processor.run\\_round() is called with the current peptide pool. \n * The run\\_round method orchestrates the execution of all defined pipeline steps in order. \n * The current\\_pool\\_manager is updated with the output of each round, simulating evolution. \n * Logs from each round are collected. \n6. **Displaying Results:** \n * Finally, the example prints the details of the top 10 peptides from the final evolved pool and a DataFrame containing the logs from all evolutionary rounds.\n\nThis example provides a hands-on illustration of how to set up and execute a basic peptide evolution simulation using PepFlex's modular components. Users can easily modify the mutation rules, evaluation criteria, and round parameters to design more complex and targeted screening pipelines.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modular framework for in silico peptide screening and evolution.",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/Kdevos12/PepFlex/issues",
"Homepage": "https://github.com/Kdevos12/PepFlex/"
},
"split_keywords": [
"peptide",
" screening",
" evolution",
" bioinformatics",
" chemistry",
" rdkit"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3c901edd5973abd4dde8afd41bc5d9e9bf2fc73f2ffdb7f3acecb7bb7ec808df",
"md5": "863e07094adc20a68b15e635f00db9e7",
"sha256": "c28aa1d85ed8f1709a37372130b221a589258f38d65ebfd0f873495cd9470a46"
},
"downloads": -1,
"filename": "pepflex-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "863e07094adc20a68b15e635f00db9e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26071,
"upload_time": "2025-07-13T17:41:20",
"upload_time_iso_8601": "2025-07-13T17:41:20.377995Z",
"url": "https://files.pythonhosted.org/packages/3c/90/1edd5973abd4dde8afd41bc5d9e9bf2fc73f2ffdb7f3acecb7bb7ec808df/pepflex-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b6ac755450ee189dd32504bdcb8130edae7dbaf89513cee56a7c59e6833698af",
"md5": "305dfcc0141e3d89394bd36e75532021",
"sha256": "13841419298bce1328ba18962c5142c16c07f2aa8c476c3579305dc91cf3e2b4"
},
"downloads": -1,
"filename": "pepflex-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "305dfcc0141e3d89394bd36e75532021",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42419,
"upload_time": "2025-07-13T17:41:22",
"upload_time_iso_8601": "2025-07-13T17:41:22.181188Z",
"url": "https://files.pythonhosted.org/packages/b6/ac/755450ee189dd32504bdcb8130edae7dbaf89513cee56a7c59e6833698af/pepflex-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 17:41:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kdevos12",
"github_project": "PepFlex",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pepflex"
}
JSON
