diff --git a/docs/docs/api_reference/CatalyticEvent.md b/docs/docs/api_reference/CatalyticEvent.md index 3a5a54f..a67081a 100644 --- a/docs/docs/api_reference/CatalyticEvent.md +++ b/docs/docs/api_reference/CatalyticEvent.md @@ -13,8 +13,9 @@ It contains multiple functions which enable easy mapping and handling of one Eve class CatalyticEvent(Object) ``` -CatalyticEvent is a class for holding information regarding the catalysis of a Reaction in a cobra.Model object. -It serves as an interface between the metabolic reaction and the associated enzyme constraints and variables. +CatalyticEvent is a class for holding information regarding the +catalysis of a Reaction in a cobra.Model object. It serves as an interface +between the metabolic reaction and the associated enzyme constraints and variables. **Notes**: @@ -142,13 +143,14 @@ constraint expressions related to the enzyme. def change_kcat_values(enzyme_kcat_dict: dict) ``` -Change kcat values for the enzyme variable. +changes kcat values for the enzyme variable **Arguments**: -- `enzyme_kcat_dict` - Dict[str, Dict[str, float]] - A nested dictionary with enzyme identifiers as keys and kcat dictionaries as values. - The kcat dictionary should have `f` and `b` keys for the forward and backward reactions, respectively. +- `enzyme_kcat_dict` - nested Dict + A Dict with enzyme_id, kcat key, value pairs to connect the + enzyme with the associated reaction the kcat is another dict with 'f' and 'b' + for the forward and backward reactions respectively. #### \_\_copy\_\_ diff --git a/docs/docs/api_reference/Enzyme.md b/docs/docs/api_reference/Enzyme.md index 5104f38..918dd74 100644 --- a/docs/docs/api_reference/Enzyme.md +++ b/docs/docs/api_reference/Enzyme.md @@ -89,6 +89,34 @@ Adds a catalytic event associated with a reaction to an enzyme. - `NoneType` - None +#### add\_genes + +```python +def add_genes(gene_list: list, + gene_length: list, + relation: str = 'OR') -> None +``` + +Add genes to the enzyme and the model related to the enzyme if applicable + +**Arguments**: + +- `gene_list` _list_ - A list of gene identifiers to be added. +- `gene_length` _list_ - A list of lengths corresponding to each gene. +- `relation` _str, optional_ - The relationship between genes in gene_list. + Defaults to 'OR'. Possible values: 'OR' or 'AND'. + + +**Raises**: + +- `ValueError` - If an invalid relation is provided. + + +**Notes**: + + If relation is 'OR', each gene in gene_list will be treated as coding for an individual isozyme + If relation is 'AND', all genes in gene_list will be treated as coding for peptides in an enzyme complex + #### create\_catalytic\_event ```python @@ -311,13 +339,107 @@ The enzyme concentration equals the flux value. - `float` - Enzyme concentration in mmol/gDW. +#### concentration + +```python +@concentration.setter +def concentration(conc: Union[float, int]) -> None +``` + +Sets the concentration of the enzyme by creating or updating a constraint +that enforces the concentration to be equal to the sum of the forward and reverse +variable primals. + +**Arguments**: + + conc : float, int + The concentration value to be set for the enzyme. This value will be used + as both the lower and upper bound for the constraint, effectively fixing the + concentration to this value. + + Notes + ----- + - If a concentration constraint for the enzyme does not already exist in the model, + this function creates a new constraint named '<enzyme_id>_conc'. + - The concentration constraint is defined as: + concentration = forward_variable.primal + reverse_variable.primal + - If the constraint already exists, the linear coefficients for the forward and reverse + variables are updated to ensure the constraint remains valid. + + Raises + ------ + ValueError + If `conc` is not a valid numerical value. + +#### set\_forward\_concentration + +```python +def set_forward_concentration(conc: Union[float, int]) -> None +``` + +Sets the concentration of the enzyme by creating or updating a constraint +that enforces the concentration to be equal to the sum of only the forward +variable primals. This forces a reaction to be active in the forward direction. +It used the concentration setter functionality and subsequently sets the +coefficient for the reverse variable in the constraint to 0. + +**Arguments**: + + conc : float, int + The concentration value to be set for the enzyme. This value will be used + as both the lower and upper bound for the constraint, effectively fixing the + concentration to this value. + + Notes + ----- + - If a concentration constraint for the enzyme does not already exist in the model, + this function creates a new constraint named '<enzyme_id>_conc'. + - The concentration constraint is defined as: + concentration = forward_variable.primal + + Raises + ------ + ValueError + If `conc` is not a valid numerical value. + +#### set\_reverse\_concentration + +```python +def set_reverse_concentration(conc: Union[float, int]) -> None +``` + +Sets the concentration of the enzyme by creating or updating a constraint +that enforces the concentration to be equal to the sum of only the reverse +variable primals. This forces a reaction to be active in the reverse direction. +It used the concentration setter functionality and subsequently sets the +coefficient for the forward variable in the constraint to 0. + +**Arguments**: + + conc : float, int + The concentration value to be set for the enzyme. This value will be used + as both the lower and upper bound for the constraint, effectively fixing the + concentration to this value. + + Notes + ----- + - If a concentration constraint for the enzyme does not already exist in the model, + this function creates a new constraint named '<enzyme_id>_conc'. + - The concentration constraint is defined as: + concentration = reverse_variable.primal + + Raises + ------ + ValueError + If `conc` is not a valid numerical value. + #### add\_catalytic\_events ```python def add_catalytic_events(catalytic_events: list, kcats: list) ``` -Adding catalytic events to an enzyme variable. +Adding a catalytic event to an enzyme variable **Arguments**: diff --git a/docs/docs/api_reference/EnzymeSectors.md b/docs/docs/api_reference/EnzymeSectors.md index 9939cae..6348890 100644 --- a/docs/docs/api_reference/EnzymeSectors.md +++ b/docs/docs/api_reference/EnzymeSectors.md @@ -61,7 +61,9 @@ mean enzymes mass E.coli [g/mol] #### \_\_init\_\_ ```python -def __init__(rxn2protein: dict, configuration: Config = Config) +def __init__(rxn2protein: dict, + protein2gene: dict = {}, + configuration: Config = Config) ``` _summary_ @@ -73,8 +75,9 @@ _summary_ with information about the enzyme as values. The information included in this dict includes the turnover number for the forward and backward reaction (1/s), molar mass of the enzyme (mol/g), gene identifiers related to the enzyme, and with which other enzymes it forms a complex. -- `configuration` _Config object, optional_ - Information about the general configuration of the model, including identifier conventions. - Default is as defined in the `PAModelpy.configuration` script for the E.coli iML1515 model. +- `protein2gene` - dict + enzyme_id, gene_list key, value pairs for each enzyme.The gene_list value is a list of lists which indicates + 'and' or 'or' relationships between the genes which code for the enzyme(complex). **Example**: @@ -83,33 +86,62 @@ _summary_ For the Parameter rxn2protein a dictionary may look like this: { 'R1': - { - 'E1': {'f': forward kcat, 'b': backward kcat, 'molmass': molar mass, 'genes': ['G1', 'G2'], - 'complex_with': 'E2'}, - 'E2': {'f': forward kcat, 'b': backward kcat, 'molmass': molar mass, 'genes': ['G3', 'G4'], - 'complex_with': 'E1'} + {E1: + {'f': forward kcat, 'b': backward kcat, 'molmass': molar mass, 'genes': [G1, G2], + 'protein_reaction_association': [[E1, E2]] + }, + E2: + {'f': forward kcat, 'b': backward kcat, 'molmass': molar mass, 'genes': [G3, G4], + 'protein_reaction_association': [[E1, E2]] } } + + For the Parameter protein2gene a dictionary may look like this: + {E1: + [[gene1], [gene2, gene3]], + E2: + [[gene4]] + } + where the gene-protein-reaction associations are the following: + E1: gene1 or (gene2 and gene3) + E2: gene4 ``` +**Arguments**: + + rxn2protein : nested dict + reaction id, enzymes_dict key, value pairs for each reaction in the active_enzyme sector. + The enzymes_dict contains the enzyme identifiers of the enzymes which are related to the specific reaction + as keys and a dict with information about the enzyme as values. The information included in this dict is: + turnover number for forward and backward reaction [1/s], molar mass of the enzyme [mol/g], gene identifiers + related to the enzyme, with which other enzymes it forms a complex. + +- `protein2gene` - dict + enzyme_id, gene_list key, value pairs for each enzyme.The gene_list value is a list of lists which indicates + 'and' or 'or' relationships between the genes which code for the enzyme(complex). + +- `configuration` - Config object, optional + Information about general configuration of the model including identifier conventions. + Default as defined in the `PAModelpy.configuration` script for the E.coli iML1515 model. + #### check\_kcat\_values ```python -def check_kcat_values(model, reaction, kcat) +def check_kcat_values(model, reaction, enzyme_dict) ``` -Function to check if the kcat values provided for an enzyme are consistent with the direction of the reaction. +Function to check if the kcat values provided for an enzyme are consistent with the direction of the reaction **Arguments**: - `model` _cobra.Model or PAModel_ - Model to which the kcat values should be added. - `reaction` _cobra.Reaction_ - Reaction that is catalyzed with the enzyme related to the kcats. -- `kcat` _dict_ - A dictionary with the turnover values for the forward and/or backward reaction for different enzymes [/s]. +- `enzyme_dict` _dict_ - A dictionary with the turnover values for the forward and/or backward reaction for different enzymes [/s]. **Example**: - Example dictionary for the `kcat` parameter + Example dictionary for the `enzyme_dict` parameter ``` {'E1': {'f': forward kcat, 'b': backward kcat}} ``` diff --git a/docs/docs/api_reference/PAModel.md b/docs/docs/api_reference/PAModel.md index 9305f5c..b06cd59 100644 --- a/docs/docs/api_reference/PAModel.md +++ b/docs/docs/api_reference/PAModel.md @@ -56,7 +56,7 @@ def __init__(id_or_model: Union[str, "Model", None] = None, active_sector: Optional[ActiveEnzymeSector] = None, translational_sector: Optional[TransEnzymeSector] = None, unused_sector: Optional[UnusedEnzymeSector] = None, - custom_sectors: Union[List, CustomSector] = None, + custom_sectors: Optional[CustomSector] = [None], configuration=Config) ``` @@ -237,15 +237,15 @@ def make_enzyme_min_max_constraint(m: Optional[Model], enz: Enzyme, lower_bound: float, upper_bound: float) ``` -Adding variables and constraints for the lower and upper bounds of an enzyme's concentration to a model. -When solving the model, shadow prices for the lower and upper bounds will be calculated. -This allows for the calculation of sensitivity coefficients. +Adding variables and constraints for the lower and upperbounds of an Enzyme to a model. +When solving the model, shadow prices for the lower and upperbounds will be calculated. +This allows for the calculation of sensitivity coefficients. The constraints are formulated as follows: **Notes**: The constraints are formulated as follows: - - `E_ub: E <= Emax` - - `E_lb: -E <= -Emin` + - `enz_max : E <= Emax` + - `enz_min : -E <= -Emin` **Arguments**: @@ -292,12 +292,59 @@ Capacity Sensitivity Coefficient = constraint_UB * shadowprice / obj_value - `mu_ec_f` _DataFrame_ - Shadow prices for the constraints related to enzymatic catalysis of the forward reaction. - `mu_ec_b` _DataFrame_ - Shadow prices for the constraints related to enzymatic catalysis of the backward reaction. + Results will be saved in the self.capacity_sensitivity_coefficients attribute as a dataframe + -**Returns**: +**Arguments**: - None - - Results are saved in the `self.capacity_sensitivity_coefficients` attribute as a DataFrame. +- `obj_value` - Float: optimal objective value, commonly maximal growth rate under specific conditions +- `mu` - DataFrame: shadowprices for all constraints +- `mu_ub` - DataFrame: Shadowprices for the reaction UB constraints +- `mu_lb` - DataFrame: Shadowprices for the reaction LB constraints +- `mu_ec_f` - DataFrame: Shadowprices for the constraint related to an enzymatic catalysis of the forward reaction +- `mu_ec_b` - DataFrame: Shadowprices for the constraint related to an enzymatic catalysis of the backward reaction + +#### calculate\_csc\_for\_molecule + +```python +def calculate_csc_for_molecule(molecule: Union[Enzyme], mu_min: pd.DataFrame, + mu_max: pd.DataFrame, obj_value: float, + constraint_type: str, + associated_reactions: str) +``` + +Calculate the capacity sensitivity coefficients (CSCs) for constraints related to a biomolecule, +such as enzymes. These coefficients reflect the effect of infitesmal changes in the constraint bounds +on the objective function. + +The coefficients and associated reactions will be saved in the capacity_sensitivity_coefficients dataframe. + +**Arguments**: + +- `enzyme:Enzyme` - enzyme object to calculate CSC for +- `mu_min` - DataFrame: Shadowprices for the constraint related to a lower bound/minimum +- `mu_max` - DataFrame: Shadowprices for the constraint related to an upper bound/maximum +- `obj_value` - float: optimal objective value, commonly maximal growth rate under specific conditions + +#### calculate\_enzyme\_csc + +```python +def calculate_enzyme_csc(enzyme: Enzyme, mu_ec_f: pd.DataFrame, + mu_ec_b: pd.DataFrame, obj_value: float) +``` + +Calculate the capacity sensitivity coefficients (CSCs) for constraints related to enzyme. These coefficients +reflect the effect of infitesmal changes in the constraint bounds on the objective function. The coefficients +and associated reactions will be saved in the capacity_sensitivity_coefficients dataframe. + +The function makes use of the abstracted function calculate_csc_for_molecule + +**Arguments**: + +- `enzyme:Enzyme` - enzyme object to calculate CSC for +- `mu_ec_f` - DataFrame: Shadowprices for the constraint related to an enzymatic catalysis of the forward reaction +- `mu_ec_b` - DataFrame: Shadowprices for the constraint related to an enzymatic catalysis of the backward reaction +- `obj_value` - float: optimal objective value, commonly maximal growth rate under specific conditions #### calculate\_esc @@ -365,6 +412,20 @@ constraints are adjusted. - `lower_bound` _float, optional_ - The new value for the lower bound of the reaction (default is None). - `upper_bound` _float, optional_ - The new value for the upper bound of the reaction (default is None). +#### get\_reaction\_bounds + +```python +def get_reaction_bounds(rxn_id: str) -> Tuple[Union[float, int]] +``` + +Get the reaction bounds. If there should be a sensitivity analysis, the bounds of the upper and lower bound +constraints returned + +**Arguments**: + +- `rxn_id` - str + string of reaction id to return + #### change\_enzyme\_bounds ```python @@ -385,7 +446,7 @@ the upper bound of the minimum and maximum enzyme concentration constraints are #### get\_enzymes\_with\_reaction\_id ```python -def get_enzymes_with_reaction_id(rxn_id: str) +def get_enzymes_with_reaction_id(rxn_id: str) -> DictList ``` Return Enzyme objects associated with the reaction identifier through CatalyticEvent objects. @@ -458,6 +519,23 @@ Remove enzymes from the model. The change is reverted upon exit when using the model as a context. +#### remove\_enzyme\_reaction\_association + +```python +def remove_enzyme_reaction_association(enzyme: Union[str, Enzyme], + reaction: Union[str, Reaction]) -> None +``` + +Remove an enzyme-reaction association from the model. Adapted from the cobra.core.remove_reactions() function. +If the reaction is not catalyzed by any enzyme anymore, the reaction ub will become 0 + +**Arguments**: + + enzyme : Enzyme or str + An enzyme, or the enzyme id for which the association should be removed to remove. + reaction : Reaction or str + A reaction, or the reaction id for which the association should be removed to remove. + #### remove\_reactions ```python @@ -524,6 +602,55 @@ Also removes associated CatalyticEvents if they exist. or their IDs, to remove. A single sector will be placed in a list. Strings will be placed in a list and used to find the sector in the model. +#### remove\_active\_enzymes\_sector + +```python +def remove_active_enzymes_sector(sector: ActiveEnzymeSector) -> None +``` + +Remove an active enzyme sector from the model. + +This function performs the following steps: +1. Removes all enzymes associated with the sector. +2. Removes all catalytic events associated with the sector. +3. If a total protein constraint exists, it removes this constraint. +4. Deletes the sector constraint from the model's easy lookup. +5. Removes the sector from the model and disconnects its link to the model. + +**Arguments**: + +- `sector` _ActiveEnzymeSector_ - The active enzyme sector to be removed. + + +**Returns**: + + None + +#### remove\_linear\_sector + +```python +def remove_linear_sector( + sector: Union[UnusedEnzymeSector, TransEnzymeSector, + CustomSector]) -> None +``` + +Remove a linear sector from the model. + +This function performs the following steps: +1. If a total protein constraint exists, it adjusts the constraint to remove the sector's contribution. +2. Removes the associated constraints and variables. +3. Deletes the sector constraint from the model's easy lookup. +4. Removes the sector from the model and disconnects its link to the model. + +**Arguments**: + +- `sector` _Union[UnusedEnzymeSector, TransEnzymeSector, CustomSector]_ - The linear sector to be removed. + + +**Returns**: + + None + #### test ```python