Merge pull request #57 from BrainAnnex/dev

Fixed incorrect usage of "affinity" to "dissociation constant"

Author: BrainAnnex

README.md

@@ -1,4 +1,4 @@
-### BETA 28.1 (v0.28.1)
+### BETA 28.2 (v0.28.2)
 
 
 

experiments/reactions_single_compartment/macromolecules_1.ipynb

@@ -43,12 +43,12 @@
 chem.get_macromolecules()
 
 # %%
-chem.set_binding_site_affinity("M1", 3, "A", 1.0)
-chem.set_binding_site_affinity("M1", 8, "B", 3.2)
-chem.set_binding_site_affinity("M1", 15, "A", 10.0)
+chem.set_binding_site_affinity("M1", site_number=3,  ligand="A", Kd=1.0)
+chem.set_binding_site_affinity("M1", site_number=8,  ligand="B", Kd=3.2)
+chem.set_binding_site_affinity("M1", site_number=15, ligand="A", Kd=10.0)
 
-chem.set_binding_site_affinity("M2", 1, "C", 5.6)    # "M2" will get automatically added
-chem.set_binding_site_affinity("M2", 2, "A", 0.01)
+chem.set_binding_site_affinity("M2", site_number=1, ligand="C", Kd=5.6)    # "M2" will get automatically added
+chem.set_binding_site_affinity("M2", site_number=2, ligand="A", Kd=0.01)
 
 # %%
 chem.show_binding_affinities()        # Review the values we have given for the binding affinities
@@ -73,7 +73,7 @@
 aff.chemical
 
 # %%
-aff.affinity
+aff.Kd
 
 # %%
 
@@ -115,19 +115,19 @@
 dynamics.describe_state()
 
 # %%
-dynamics.chem_data.show_binding_affinities()        # Review the values the had given for the binding affinities
+dynamics.chem_data.show_binding_affinities()        # Review the values we had given for the dissociation constants
 
 # %% [markdown]
 # #### Notes:
 # **[B] = 0** => Occupancy of binding site 8 of M1 is also zero
 #
 # **[A] = 10.0** :   
-#             * 10x the binding affinity of A to site 3 of M1 (resulting in occupancy 0.9)  
-#             * same as the binding affinity of A to site 15 of M1 (occupancy 0.5)  
-#             * 1,000x the binding affinity of A to site 2 of M2 (occupancy almost 1, i.e. nearly saturated)
+#             * 10x the dissociation constant of A to site 3 of M1 (resulting in occupancy 0.9)  
+#             * same as the dissociation constant of A to site 15 of M1 (occupancy 0.5)  
+#             * 1,000x the dissociation constant of A to site 2 of M2 (occupancy almost 1, i.e. nearly saturated)
 #         
 #             
-# **[C] = 0.56** => 1/10 of the binding affinity of C to site 1 of M2 (occupancy 0.1)
+# **[C] = 0.56** => 1/10 of the dissociation constant of C to site 1 of M2 (occupancy 0.1)
 
 # %%
 
@@ -144,7 +144,7 @@
 dynamics.describe_state()
 
 # %% [markdown]
-# #### Note how all the various binding sites for ligand A, across all macromolecules, now have a different value for the fractional occupancy (very close to 1 because of the large value of [A] relative to each of the binding affinities for A.)
+# #### Note how all the various binding sites for ligand A, across all macromolecules, now have a different value for the fractional occupancy (very close to 1 because of the large value of [A] relative to each of the dissociation constants for A.)
 # The fractional occupancies for the other ligands (B and C) did not change
 
 # %%
@@ -159,7 +159,7 @@
 print(history)
 
 # %%
-# Generate a sweep of [A] values along a log scale
+# Generate a sweep of [A] values along a log scale, from very low to very high (relative to the dissociation constants)
 start = 0.001
 stop = 200.
 num_points = 100
@@ -214,11 +214,14 @@
 
 # Annotations (x values adjusted for the log scale)
 fig.add_annotation(x=-1.715, y=0.65, 
-                   text="Binding Affinity: 0.01", font=dict(size=12, color="seagreen"), showarrow=True, ax=-100, ay=-20)
+                   text="Dissociation constant: 0.01<br>(HIGHER Binding Affinity)", font=dict(size=12, color="seagreen"), showarrow=True, ax=-100, ay=-20)
 fig.add_annotation(x=0.3, y=0.65, 
-                   text="Binding Affinity: 1", font=dict(size=12, color="purple"), showarrow=True, ax=-100, ay=-20)
+                   text="Dissociation constant: 1", font=dict(size=12, color="purple"), showarrow=True, ax=-100, ay=-20)
 fig.add_annotation(x=0.6, y=0.3, 
-                   text="Binding Affinity: 10", font=dict(size=12, color="darkorange"), showarrow=True, ax=100, ay=20)
+                   text="Dissociation constant: 10<br>(LOWER Binding Affinity)", font=dict(size=12, color="darkorange"), showarrow=True, ax=100, ay=10)
+
+fig.add_annotation(x=1.8, y=0.51, 
+                   text="50% OCCUPANCY", font=dict(size=14, color="gray"), bgcolor="white", opacity=0.8, showarrow=False)
 
 # Customize y-axis tick values
 additional_y_values = [0.1, 0.5, 0.9]  # Additional values to show on y-axis
@@ -232,13 +235,19 @@
 fig.show()
 
 # %% [markdown]
-# Note that fractional occupancy 0.1 occurs at ligand concentrations of 1/10 the binding affinity;   
-# occupancy 0.5 occurs at ligand concentrations equals to the binding affinity;  
-# occupancy 0.9 occurs at ligand concentrations of 10x the binding affinity
+# #### When the binding affinity is lower (i.e. higher Dissociation Constant, Kd, orange curve), it takes higher ligand concentrations to attain the same fractional occupancies
+
+# %% [markdown]
+# Note that fractional occupancy 0.1 occurs at ligand concentrations of 1/10 the dissociation constant (Kd);   
+# occupancy 0.5 occurs at ligand concentrations equals to the dissociation constant;  
+# occupancy 0.9 occurs at ligand concentrations of 10x the dissociation constant.  
 
 # %% [markdown]
 # ## The above simulation captures what's shown on Fig. 3A of 
 # #### https://doi.org/10.1146/annurev-cellbio-100617-062719 
-# ("Low-Affinity Binding Sites and the Transcription Factor Specificity Paradox in Eukaryotes"), which it is based on
+# ("Low-Affinity Binding Sites and the Transcription Factor Specificity Paradox in Eukaryotes"), a paper that guided this simulation
+
+# %% [markdown]
+# #### In upcoming versions of Life123, the fractional occupancy values will regulate the rates of reactions catalyzed by the macromolecules...
 
 # %%

experiments/reactions_single_compartment/macromolecules_1.py

@@ -529,9 +529,9 @@ def single_reaction_describe(self, rxn_index: int, concise=False) -> str:
 
 
 class ChemicalAffinity(NamedTuple):
-    # Used for binding to macromolecules (e.g. Transcription Factors to DNA)
-    chemical: str
-    affinity: float
+    # Used for binding of ligands to macromolecules (e.g. Transcription Factors to DNA)
+    chemical: str   # Name of ligand
+    Kd: float       # Dissociation constant; inversely related to binding affinity
 
 
 
@@ -548,23 +548,22 @@ def __init__(self):
         super().__init__()          # Invoke the constructor of its parent class
 
 
-        self.macro_molecules = []   # List of names.  EXAMPLE: ["M1", "M2"]
+        self.macromolecules = []    # List of names.  EXAMPLE: ["M1", "M2"]
                                     # The position in the list is referred to as the "index" of that macro-molecule
-                                    # Names will be enforced to be unique
+                                    # Names are enforced to be unique
 
-        self.binding_sites = {}     # A dict whose keys are macromolecule names.  The values are in turn dicts, indexed by site number.
+        self.binding_sites = {}     # A dict whose keys are macromolecule names.
+                                    # The values are in turn dicts, indexed by binding-site number.
         # EXAMPLE:
         #       {"M1": {1: ChemicalAffinity("A", 2.4), 2: ChemicalAffinity("C", 5.1)},
         #        "M2": {1: ChemicalAffinity("C", 9.1), 2: ChemicalAffinity("B", 0.3), 3: ChemicalAffinity("A", 1.8), 4: ChemicalAffinity("C", 2.3)}
         #        }
         #       where "M1", "M2" are macro-molecules, and "A", "B", "C" are bulk chemicals (such as transcription factors),
         #           all previously-declared;
-        #           the various ChemicalAffinity's are NamedTuples (objects) storing a bulk-chemical name and its affinity at that site.
+        #           the various ChemicalAffinity's are NamedTuples (objects) storing a ligand name and its dissociation constant at that site.
 
         # Info on Binding Site Affinities : https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6787930/
 
-        #       OLD: {"M1": {"A": 2.4, "B": 853.} }       # Alt: [("A", 2.4), ("B", 853.)]
-
 
 
 
@@ -581,11 +580,11 @@ def add_macromolecules(self, names: Union[str, List[str]]) -> None:
             names = [names]
 
         for m in names:
-            if m in self.macro_molecules:
+            if m in self.macromolecules:
                 # Warn of redundant attempt to re-register an existing macromolecule name
                 print(f"WARNING: Macromolecule `{m}` was already registered.  Skipped...")
             else:
-                self.macro_molecules.append(m)  # Grow the list of registered macromolecules
+                self.macromolecules.append(m)  # Grow the list of registered macromolecules
 
 
 
@@ -595,11 +594,11 @@ def get_macromolecules(self) -> [str]:
 
         :return:    A (possibly empty) list of the names of all the registered macromolecules
         """
-        return self.macro_molecules
+        return self.macromolecules
 
 
 
-    def set_binding_site_affinity(self, macromolecule: str, site_number: int, chemical: str, affinity) -> None:
+    def set_binding_site_affinity(self, macromolecule: str, site_number: int, ligand: str, Kd) -> None:
         """
         Set the values of the binding affinity of the given macromolecule, at the indicated site on it,
         for the specified chemical species.
@@ -616,18 +615,19 @@ def set_binding_site_affinity(self, macromolecule: str, site_number: int, chemic
         :param macromolecule:   Name of a macromolecule; if not previously-declared,
                                     it will get added to the list of registered macromolecules
         :param site_number:     Unique integer to identify a binding site on the macromolecule
-        :param chemical:        Name of a previously-declared (bulk) chemical;
+        :param ligand:          Name of a previously-declared (bulk) chemical;
                                     if not found, an Exception will be raised       TODO: inconsistent with "macromolecule" arg
-        :param affinity:        A number, in units of concentration
+        :param Kd:              Dissociation constant, in units of concentration (typically microMolar).
+                                    Note that the dissociation constant is inversely proportional to the binding affinity
         :return:                None
         """
-        assert chemical in self.get_all_names(), \
-            f"set_binding_site_affinity(): no chemical named `{chemical}` found; use add_chemical() first"
+        assert ligand in self.get_all_names(), \
+            f"set_binding_site_affinity(): no chemical named `{ligand}` found; use add_chemical() first"
 
         assert type(site_number) == int, \
             f"set_binding_site_affinity(): the argument `site_number` must be an integer"
 
-        if macromolecule not in self.macro_molecules:
+        if macromolecule not in self.macromolecules:
             self.add_macromolecules([macromolecule])
 
         if self.binding_sites.get(macromolecule) is None:
@@ -637,12 +637,12 @@ def set_binding_site_affinity(self, macromolecule: str, site_number: int, chemic
 
         if site_number in binding_data:
             existing_affinity_data = binding_data[site_number]
-            if existing_affinity_data.chemical != chemical:
+            if existing_affinity_data.chemical != ligand:
                 raise Exception(f"set_binding_site_affinity(): "
                                 f"site number {site_number} of macromolecule `{macromolecule}` was previously associated to chemical `{existing_affinity_data.chemical}` "
-                                f"(attempting to set an affinity value for chemical `{chemical}`)")
+                                f"(attempting to set an affinity value for chemical `{ligand}`)")
 
-        binding_data[site_number] = ChemicalAffinity(chemical=chemical, affinity=affinity)
+        binding_data[site_number] = ChemicalAffinity(chemical=ligand, Kd=Kd)
 
 
 
@@ -653,10 +653,10 @@ def get_binding_site_affinity(self, macromolecule: str, site_number: int) -> Che
 
         :param macromolecule:   Name of a macromolecule; if not found, an Exception will get raised
         :param site_number:     Integer to identify a binding site on the macromolecule
-        :return:                The NamedTuple (chemical, affinity)
+        :return:                The NamedTuple (ligand name, dissociation constant)
                                     if no value was previously set, an Exception is raised
         """
-        assert macromolecule in self.macro_molecules, \
+        assert macromolecule in self.macromolecules, \
             f"get_binding_site_affinity(): no macromolecule named `{macromolecule}` found"
 
         assert type(site_number) == int, \
@@ -742,6 +742,7 @@ def get_ligand_name(self, macromolecule: str, site_number: int) -> str:
         return  ligand_data.chemical
 
 
+
     def show_binding_affinities(self) -> None:
         """
 
@@ -752,7 +753,7 @@ def show_binding_affinities(self) -> None:
             print(mm, " :")
             for site_number in self.get_binding_sites(mm):
                 aff = self.get_binding_site_affinity(macromolecule=mm, site_number=site_number)
-                print(f"   Site {site_number} - Binding affinity for {aff.chemical} : {aff.affinity}")
+                print(f"   Site {site_number} - Kd (dissociation const) for {aff.chemical} : {aff.Kd}")
 
 
 
@@ -774,7 +775,7 @@ def clear_macromolecules(self) -> None:
 
         :return:    None
         """
-        self.macro_molecules = []
+        self.macromolecules = []
         self.binding_sites = {}
 
 

src/modules/chemicals/chem_data.py

@@ -1608,7 +1608,7 @@ def update_occupancy(self) -> None:
             for (site_number, ligand) in d.items():
                 aff_data = self.chem_data.get_binding_site_affinity(mm, site_number)
                 conc = self.get_chem_conc(ligand)
-                fractional_occupancy = self.sigmoid(conc=conc, Kd=aff_data.affinity)
+                fractional_occupancy = self.sigmoid(conc=conc, Kd=aff_data.Kd)
 
                 self.set_occupancy(macromolecule=mm, site_number=site_number, fractional_occupancy=fractional_occupancy)