Added missing documentation

Author: ianmkenney

multibind/multibind.py

@@ -7,14 +7,35 @@
 
 class MultibindDriver(object):
 
+    """Class to quickly run multibind over a range of pH values"""
+
     def __init__(self, multibind):
+        """
+        Parameters
+        ----------
+        multibind : Multibind
+            A multibind object with its states and graph attributed defined.
+
+        """
         if not type(multibind.states) is None and not type(multibind.graph) is None:
             self.multibind = multibind
         else:
             raise ValueError(
                 "Multibind driver must be passed a Multibind object that has states and a graph file loaded.")
 
     def create_tensor(self, pH_array):
+        """Create a tensor containing state free energies across a pH range.
+
+        Parameters
+        ----------
+        pH_array : iterable
+            An iterable containing the pH values to calculate binding free energies for.
+
+        Returns
+        -------
+        None
+
+        """
         num_states = self.multibind.states.name.shape[0]
         self.tensor = np.zeros((num_states, num_states, len(pH_array)))
 
@@ -28,8 +49,14 @@ def create_tensor(self, pH_array):
 class Multibind(object):
 
     def __init__(self, states_filename=None, graph_filename=None):
-        # If states are specified in a CSV, may as well fill them in
-        # here. The same goes for the graph information
+        """
+        Parameters
+        ----------
+        states_filename : str (optional)
+            Path the CSV containing the states of the graph.
+        graph_filename : str (optional)
+            Path to the CSV containing the graph data for the network.
+        """
         if states_filename:
             self.read_states(states_filename)
         else:
@@ -44,10 +71,20 @@ def __init__(self, states_filename=None, graph_filename=None):
         self.concentrations = {}
 
     def build_cycle(self, pH=5):
-        """Constructs the cycle used for calculation"""
+        """Constructs the cycle used for calculation
+
+        Parameters
+        ----------
+        pH : float | int
+            The pH to calculate binding free energies over.
+
+        Returns
+        -------
+        None
+        """
 
         # Determine if we have enough information to continue,
-        # ie states information and graph information
+        # i.e. states information and graph information
         if type(self.states) is None or type(self.graph) is None:
             msg = "Need to specify both the state and graph \
             information. Try using `read_states` and `read_graph`."
@@ -169,6 +206,16 @@ def jacobian(g_t):
 
     def MLE_dist(self, N_steps=int(1e6), nt=1):
         """Run Monte-Carlo steps to assess quality of MLE results.
+
+        Parameters
+        ----------
+        N_steps : int
+            The number of Monte-Carlo steps to perform.
+
+        Returns
+        -------
+        ndarray with the distribution of free energy values for the states.
+
         """
 
         def potential(g_t):
@@ -236,14 +283,17 @@ def effective_energy_difference(self, macrostate_class, state1, state2):
         """Calculate the effective binding energy between two states.
 
         Parameters
-        ==========
-        macrostate_class : name of macrostate class (i.e. number of protons)
-        state1 : first, 'starting' state
-        state2 : second, 'destination' state
+        ----------
+        macrostate_class : str
+            Name of macrostate class (i.e. number of protons)
+        state1 : str
+            first, 'starting' state
+        state2 : str
+            second, 'destination' state
 
         Returns
-        =======
-        float : binding free energy in kT
+        -------
+        float : macroscopic free energy difference in kT
         """
 
         macrostate_class = str(macrostate_class)
@@ -264,26 +314,31 @@ def _parse(self, filename, comment=None):
             raise e(f"Could not parse file {filename}")
 
     def read_states(self, filename, comment=None):
-        """Read in state information from a state CSV file
+        """Read in state information from a state CSV file.
 
         Parameters
-        ==========
-        filename : string with the file path
+        ----------
+        filename : str
+            Path to the state CSV file.
+
+        Returns
+        -------
+        None
         """
         self.states = self._parse(filename, comment=comment)
         self.states['name'] = self.states['name'].astype('str')
 
     def read_graph(self, filename, comment=None):
-        """Read in the graph information from a graph CSV file
+        """Read in the graph information from a graph CSV file.
 
         Parameters
-        ==========
-        filename : string with the file path
+        ----------
+        filename : str
+            File path of the graph CSV
 
         Returns
-        =======
-        DataFrame with graph information (accessible using `graph`
-        attribute)
+        -------
+        None
         """
         self.graph = self._parse(filename, comment=comment)
         self.graph['state1'] = self.graph['state1'].astype('str')

multibind/nonequilibrium.py

@@ -6,7 +6,10 @@
 
 
 def rate_matrix(filename: str):
-    """
+    """Build a rate matrix from a connectivity file with rates.
+
+    The rates are converted into free energy differences between states and
+    then made thermodynamically consistent.
 
     Parameters
     ----------
@@ -42,8 +45,7 @@ def rate_matrix(filename: str):
 
             # find all unique edges. Implicitly assumes that forward rates appear first...
             # todo add this to the docstring
-            _edges.append((state1, state2)) if (
-                        (state1, state2) not in _edges and (state2, state1) not in _edges) else None
+            _edges.append((state1, state2)) if ((state1, state2) not in _edges and (state2, state1) not in _edges) else None
 
         states = pd.DataFrame({'name': _states})  # create dataframe for states, which only needs the names
 
@@ -89,9 +91,6 @@ def rate_matrix(filename: str):
 
         states, connections, g = c.states.name.values, c.graph[['state1', 'state2']].values, c.g_mle
 
-        forward = []
-        reverse = []
-
         n = states.shape[0]
         _rate_matrix = np.zeros((n, n))
 
@@ -104,11 +103,11 @@ def rate_matrix(filename: str):
             b_weight = np.exp(-dg)
             try:
                 s_ijji = var_ij / var_ji
-            except ZeroDivisionError as e:
+            except ZeroDivisionError:
                 s_ijji = 1e12
             try:
                 s_jiij = 1 / s_ijji
-            except ZeroDivisionError as e:
+            except ZeroDivisionError:
                 s_jiij = 1e12
 
             _k_ji = k_ij / (b_weight + s_ijji / b_weight ** 2) + k_ji / (b_weight ** 2 * s_jiij + 1)