DOC: Minor updates to docstrings (#125)

* Fixes incorrect usage of `(optional)` instead of `, optional`
for optional parameters in function/method docstrings

* Updates docstrings with `key` parameter to correctly
list them as an `optional` parameter

* Updates function, method, and class references to use their
correct tag (i.e. `:func:` for functions, `:class:` for classes)
instead of using `:meth:`

Author: nawtrey

kda/calculations.py

@@ -109,23 +109,23 @@ def calc_sigma(G, dir_edges=None, key="name", output_strings=True, **kwargs):
     ----------
     G : ``NetworkX.MultiDiGraph``
         A kinetic diagram
-    dir_edges : ndarray (optional)
+    dir_edges : ndarray, optional
         Array of all directional diagram edges (made from 2-tuples)
         for the input diagram ``G``. Created using
-        :meth:`~kda.diagrams.generate_directional_diagrams`
+        :func:`~kda.diagrams.generate_directional_diagrams`
         with ``return_edges=True``.
-    key : str (optional)
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the normalization
         factor using numbers. If ``True``, this will assume the input
         ``'key'`` will return strings of variable names to join into the
         analytic cycle flux function.
-    kwargs : dict (optional)
+    kwargs : dict, optional
         Additional keyword arguments. Note that the alias
         ``dirpar_edges`` is deprecated; please use ``dir_edges``.
 
@@ -228,13 +228,13 @@ def calc_sigma_K(G, cycle, flux_diags, key="name", output_strings=True):
         indices does not matter but should not contain all nodes.
     flux_diags : list
         List of relevant directional flux diagrams for input cycle.
-    key : str
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
         Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the sum of all
         directional flux diagrams using numbers. If ``True``, this will assume
@@ -325,18 +325,18 @@ def calc_pi_difference(G, cycle, order, key="name",
         List of integers of length 2 (e.g. ``[0, 1]``), where the integers are
         nodes in ``cycle``. The pair of nodes should be ordered such that
         a counter-clockwise path is followed.
-    key : str
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the difference
         using numbers. If ``True``, this will assume the input ``'key'``
         will return strings of variable names to join into the analytic
         function.
-    net : bool (optional)
+    net : bool, optional
         Used to determine whether to return the forward cycle product
         (i.e., ``net=False``) or the difference of the forward and reverse
         cycle products (i.e., ``net=True``). Default is ``True``.
@@ -418,13 +418,13 @@ def calc_thermo_force(G, cycle, order, key="name", output_strings=True):
         List of integers of length 2 (e.g. ``[0, 1]``), where the integers are
         nodes in ``cycle``. The pair of nodes should be ordered such that
         a counter-clockwise path is followed.
-    key : str
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
         Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the thermodynamic
         force using numbers. If ``True``, this will assume the input
@@ -499,21 +499,21 @@ def calc_state_probs(G, key="name", output_strings=True, dir_edges=None):
     ----------
     G : ``NetworkX.MultiDiGraph``
         A kinetic diagram
-    key : str
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the state
         probabilities using numbers. If ``True``, this will assume the input
         ``'key'`` will return strings of variable names to join into the
         analytic state multplicity and normalization function.
-    dir_edges : ndarray (optional)
+    dir_edges : ndarray, optional
         Array of all directional diagram edges (made from 2-tuples)
         for the input diagram ``G``. Created using
-        :meth:`~kda.diagrams.generate_directional_diagrams`
+        :func:`~kda.diagrams.generate_directional_diagrams`
         with ``return_edges=True``.
 
     Returns
@@ -613,25 +613,25 @@ def calc_cycle_flux(G, cycle, order, key="name",
         List of integers of length 2 (e.g. ``[0, 1]``), where the integers are
         nodes in ``cycle``. The pair of nodes should be ordered such that
         a counter-clockwise path is followed.
-    key : str
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the cycle flux
         using numbers. If ``True``, this will assume the input ``'key'``
         will return strings of variable names to join into the analytic
         cycle flux function.
-    dir_edges : ndarray (optional)
+    dir_edges : ndarray, optional
         Array of all directional diagram edges (made from 2-tuples)
         for the input diagram ``G``. Given as an option for performance reasons
         (when calculating net cycle fluxes for multiple cycles it is best to
         generate the directional diagram edges up front and provide them).
-        Created using :meth:`~kda.diagrams.generate_directional_diagrams`
+        Created using :func:`~kda.diagrams.generate_directional_diagrams`
         with ``return_edges=True``.
-    net : bool (optional)
+    net : bool, optional
         Used to determine whether to return the one-way or net cycle flux.
         Default is ``True`` (i.e., to generate the net cycle flux).
 
@@ -700,24 +700,24 @@ def calc_net_cycle_flux(G, cycle, order, key="name",
         List of integers of length 2 (e.g. ``[0, 1]``), where the integers are
         nodes in ``cycle``. The pair of nodes should be ordered such that
         a counter-clockwise path is followed.
-    key : str (optional)
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
         Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the cycle flux
         using numbers. If ``True``, this will assume the input ``'key'``
         will return strings of variable names to join into the analytic
         cycle flux function.
-    dir_edges : ndarray (optional)
+    dir_edges : ndarray, optional
         Array of all directional diagram edges (made from 2-tuples)
         for the input diagram ``G``. Given as an option for performance reasons
         (when calculating net cycle fluxes for multiple cycles it is best to
         generate the directional diagram edges up front and provide them).
-        Created using :meth:`~kda.diagrams.generate_directional_diagrams`
+        Created using :func:`~kda.diagrams.generate_directional_diagrams`
         with ``return_edges=True``.
 
     Returns
@@ -764,7 +764,7 @@ def calc_state_probs_from_diags(
     method developed by King and Altman :footcite:`king_schematic_1956` and
     Hill :footcite:`hill_studies_1966`. If directional diagram edges are already
     generated this offers better performance than
-    :meth:`~kda.calculations.calc_state_probs`.
+    :func:`~kda.calculations.calc_state_probs`.
 
     .. deprecated:: 0.3.0
        ``calc_state_probs_from_diags`` is deprecated and will be removed in
@@ -775,23 +775,23 @@ def calc_state_probs_from_diags(
     ----------
     G : ``NetworkX.MultiDiGraph``
         A kinetic diagram
-    dir_edges : array (optional)
+    dir_edges : array, optional
         Array of all directional diagram edges (made from 2-tuples)
         for the input diagram ``G``.  Created using
-        :meth:`~kda.diagrams.generate_directional_diagrams`
+        :func:`~kda.diagrams.generate_directional_diagrams`
         with ``return_edges=True``.
-    key : str (optional)
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the state
         probabilities using numbers. If ``True``, this will assume the input
         ``'key'`` will return strings of variable names to join into the
         analytic state multplicity and normalization functions.
-    kwargs : dict (optional)
+    kwargs : dict, optional
         Additional keyword arguments. Note that the alias
         ``dirpar_edges`` is deprecated; please use ``dir_edges``.
 
@@ -850,7 +850,7 @@ def calc_net_cycle_flux_from_diags(
     """Generates the expression for the net cycle flux for some ``cycle``
     in kinetic diagram ``G``. If directional diagram edges are already
     generated this offers better performance than
-    :meth:`~kda.calculations.calc_cycle_flux`.
+    :func:`~kda.calculations.calc_cycle_flux`.
 
     .. deprecated:: 0.3.0
        ``calc_net_cycle_flux_from_diags`` is deprecated and will be removed
@@ -868,23 +868,23 @@ def calc_net_cycle_flux_from_diags(
         List of integers of length 2 (e.g. ``[0, 1]``), where the integers are
         nodes in ``cycle``. The pair of nodes should be ordered such that
         a counter-clockwise path is followed.
-    dir_edges : ndarray (optional)
+    dir_edges : ndarray, optional
         Array of all directional diagram edges (made from 2-tuples)
         for the input diagram ``G``. Created using
-        :meth:`~kda.diagrams.generate_directional_diagrams`
+        :func:`~kda.diagrams.generate_directional_diagrams`
         with ``return_edges=True``.
-    key : str (optional)
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
         (for the rate constant values, e.g. ``100``). Default is ``"name"``.
-    output_strings : bool (optional)
+    output_strings : bool, optional
         Used to denote whether values or strings will be combined. Default
         is ``False``, which tells the function to calculate the cycle flux
         using numbers. If ``True``, this will assume the input ``'key'``
         will return strings of variable names to join into the analytic
         cycle flux function.
-    kwargs : dict (optional)
+    kwargs : dict, optional
         Additional keyword arguments. Note that the alias
         ``dirpar_edges`` is deprecated; please use ``dir_edges``.
 

kda/core.py

@@ -63,13 +63,13 @@ def __init__(self, K=None, G=None):
 		"""
 		Parameters
 		==========
-		K : ndarray (optional)
+		K : ndarray, optional
 			``NxN`` array where ``N`` is the number of nodes in the
 			diagram ``G``. Adjacency matrix for ``G`` where each element
 			``kij`` is the edge weight (i.e. transition rate constant).
 			For example, for a 2-state model with ``k12=3`` and ``k21=4``,
 			``K=[[0, 3], [4, 0]]``. Default is ``None``.
-		G : ``NetworkX.MultiDiGraph`` (optional)
+		G : ``NetworkX.MultiDiGraph``, optional
 			A kinetic diagram. Default is ``None``.
 
 		Raises
@@ -100,30 +100,30 @@ def __init__(self, K=None, G=None):
 
 	def build_cycles(self):
 		"""Builds all cycles from the kinetic diagram using
-		:meth:`~kda.graph_utils.find_all_unique_cycles()`.
+		:func:`~kda.graph_utils.find_all_unique_cycles()`.
 		"""
 		self.cycles = graph_utils.find_all_unique_cycles(self.G)
 
 
 	def build_partial_diagrams(self):
 		"""Builds the partial diagrams for the kinetic diagram using
-		:meth:`~kda.diagrams.generate_partial_diagrams()`.
+		:func:`~kda.diagrams.generate_partial_diagrams()`.
 		"""
 		self.partial_diagrams = diagrams.generate_partial_diagrams(
 			self.G, return_edges=False)
 
 
 	def build_directional_diagrams(self):
 		"""Builds the directional diagrams for the kinetic diagram using
-		:meth:`~kda.diagrams.generate_directional_diagrams()`.
+		:func:`~kda.diagrams.generate_directional_diagrams()`.
 		"""
 		self.directional_diagrams = diagrams.generate_directional_diagrams(
 			self.G, return_edges=False)
 
 
 	def build_flux_diagrams(self):
 		"""Builds the flux diagrams for the kinetic diagram using
-		:meth:`~kda.diagrams.generate_all_flux_diagrams()`.
+		:func:`~kda.diagrams.generate_all_flux_diagrams()`.
 		"""
 		self.flux_diagrams = diagrams.generate_all_flux_diagrams(self.G)
 
@@ -135,7 +135,7 @@ def get_partial_diagram_count(self):
 		have already been generated with
 		:meth:`~kda.core.KineticModel.build_partial_diagrams()`
 		the count will simply be returned. Otherwise
-		:meth:`~kda.diagrams.enumerate_partial_diagrams()` is used.
+		:func:`~kda.diagrams.enumerate_partial_diagrams()` is used.
 
 		Returns
 		=======
@@ -172,7 +172,7 @@ def get_directional_diagram_count(self):
 	def get_flux_diagrams(self, cycle):
 		"""
 		Retrieves the flux diagrams for a specific cycle using
-		:meth:`~kda.diagrams.generate_flux_diagrams()`.
+		:func:`~kda.diagrams.generate_flux_diagrams()`.
 
 		Parameters
 		==========
@@ -193,12 +193,12 @@ def get_flux_diagrams(self, cycle):
 	def build_state_probabilities(self, symbolic=True):
 		"""
 		Builds the state probabilities for the kinetic diagram using
-		:meth:`~kda.calculations.calc_state_probs()`. Probabilities
+		:func:`~kda.calculations.calc_state_probs()`. Probabilities
 		can be stored as raw values or symbolic algebraic expressions.
 
 		Parameters
 		==========
-		symbolic : bool (optional)
+		symbolic : bool, optional
 			Used to determine whether raw values or symbolic
 			expressions will be stored. Default is ``True``.
 		"""
@@ -228,11 +228,11 @@ def get_transition_flux(self, state_i, state_j, net=True, symbolic=True):
 			The index (index 1) of the initial state.
 		state_j : integer
 			The index (index 1) of the final state.
-		net : bool (optional)
+		net : bool, optional
 			Used to determine whether one-way transition fluxes
 			or net transition fluxes will be returned. Default
 			is ``True``.
-		symbolic : bool (optional)
+		symbolic : bool, optional
 			Used to determine whether raw values or symbolic
 			expressions will be returned. Default is ``True``.
 
@@ -305,4 +305,3 @@ def get_transition_flux(self, state_i, state_j, net=True, symbolic=True):
 				return j_ij - j_ji
 			else:
 				return j_ij
-

kda/diagrams.py

@@ -233,7 +233,7 @@ def _append_reverse_edges(edge_list):
 
 def _get_cofactor_matrix(K_laplace):
     """
-    Helper function for :meth:`~kda.diagrams.enumerate_partial_diagrams()`.
+    Helper function for :func:`~kda.diagrams.enumerate_partial_diagrams()`.
     Uses singular value decomposition to get the cofactor matrix for
     the input Laplacian matrix.
 

kda/graph_utils.py

@@ -64,15 +64,15 @@ def generate_edges(G, vals, names=None, val_key="val", name_key="name"):
         the kinetic rate *values* for each transition in ``G``. For example,
         assuming we have some values ``k12_val`` and ``k21_val``, for a
         2-state diagram ``vals = [[0, k12_val], [k21_val, 0]]``.
-    names : ndarray (optional)
+    names : ndarray, optional
         ``NxN`` array where ``N`` is the number of nodes in ``G``. Contains
         the kinetic rate *variable names* (as strings) for each transition
         in ``G``. For example, for a 2-state diagram
         ``names = [[0, "k12"], ["k21", 0]]``.
-    val_key : str (optional)
+    val_key : str, optional
         Attribute key used to retrieve kinetic rate *values* from the
         edge data stored in ``G.edges``. The default is ``"val"``.
-    name_key : str (optional)
+    name_key : str, optional
         Attribute key used to retrieve kinetic rate *variable names* from
         the edge data stored in ``G.edges``. The default is ``"name"``.
     """
@@ -101,7 +101,7 @@ def retrieve_rate_matrix(G, key="val"):
     ----------
     G : ``NetworkX.MultiDiGraph``
         A kinetic diagram
-    key : str
+    key : str, optional
         Attribute key used to retrieve edge data from ``G.edges``. The default
         ``NetworkX`` edge key is ``"weight"``, however the ``kda`` edge keys
         are ``"name"`` (for rate constant names, e.g. ``"k12"``) and ``"val"``
@@ -177,8 +177,8 @@ def _is_ccw(cycle, start, end):
 def get_ccw_cycle(cycle, order):
     """
     Function used for obtaining the CCW version of an input cycle, primarily
-    used for :meth:`~kda.calculations.calculate_pi_difference()` and
-    :meth:`~kda.calculations.calculate_thermo_force()`.
+    used for :func:`~kda.calculations.calculate_pi_difference()` and
+    :func:`~kda.calculations.calculate_thermo_force()`.
 
     Parameters
     ----------