Skip to content

Commit

Permalink
MAINT: Fix docstrings to follow NumPy formatting (#102)
Browse files Browse the repository at this point in the history 
* MAINT: Fix docstrings to follow NumPy formatting

* Fixes all function docstrings to consistently
use NumPy RST syntax when referring to variables,
giving examples, etc.

* Misc fixes to docstrings including removal of
returns/parameters that are no longer available
  • Loading branch information
@nawtrey
nawtrey authored Aug 9, 2024
1 parent a455dbf commit 4e79a64
Show file tree
Hide file tree
Showing 9 changed files with 394 additions and 353 deletions.
226 changes: 124 additions & 102 deletions kda/calculations.py
View file

Large diffs are not rendered by default.

12 changes: 6 additions & 6 deletions kda/core.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,20 +37,20 @@ class KineticModel(object):
All cycles in the kinetic diagram. This attribute becomes
available after running the
:meth:`~kda.core.KineticModel.build_cycles` method.
partial_diagrams : array of Networkx Graphs
partial_diagrams : ndarray of ``Networkx.Graph``
The set of partial diagrams (i.e. spanning trees) for the
kinetic diagram. This attribute becomes available after
running the :meth:`~kda.core.KineticModel.build_partial_diagrams`
method.
directional_diagrams : array of Networkx MultiDiGraphs
directional_diagrams : ndarray of ``Networkx.MultiDiGraph``
The set of directional diagrams for the kinetic diagram.
This attribute becomes available after running the
:meth:`~kda.core.KineticModel.build_directional_diagrams` method.
flux_diagrams : list of lists of Networkx MultiDiGraphs
flux_diagrams : list of lists of ``Networkx.MultiDiGraph``
The set of flux diagrams for each cycle in the kinetic
diagram. This attribute becomes available after running
the :meth:`~kda.core.KineticModel.build_flux_diagrams` method.
probabilities : array of floats or list of SymPy expressions
probabilities : array of floats or list of ``SymPy`` expressions
The steady-state probabilities for all states in the kinetic
diagram. Probabilities are either an array of numeric values
or the algebraic expressions. This attribute becomes available
Expand All @@ -69,8 +69,8 @@ def __init__(self, K=None, G=None):
``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)
Input diagram. Default is ``None``.
G : ``NetworkX.MultiDiGraph`` (optional)
A kinetic diagram. Default is ``None``.
Raises
======
Expand Down
120 changes: 61 additions & 59 deletions kda/diagrams.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,12 @@

def _find_unique_edges(G):
"""
Creates list of unique edges for input diagram G. Effectively removes
duplicate edges such as '(1, 0)' from [(0, 1), (1, 0)].
Creates list of unique edges for input diagram ``G``. Effectively removes
duplicate edges such as ``(1, 0)`` from ``[(0, 1), (1, 0)]``.
Parameters
----------
G : NetworkX MultiDiGraph
G : ``NetworkX.MultiDiGraph``
Input diagram
"""
# since non-directional graphs cannot contain forward/reverse edges,
Expand Down Expand Up @@ -68,15 +68,15 @@ def _get_neighbor_dict(target, unique_edges):
----------
target : int
Index of target state
unique_edges : array
unique_edges : ndarray
Array of edges (made from 2-tuples) that are unique
to the diagram, (i.e. [[0, 1], [1, 2], ...]).
to the diagram, (e.g. ``[[0, 1], [1, 2], ...]``).
Returns
-------
Dictionary of directional connections, where node
indices are mapped to a list of their respective
neighbor node indices (i.e. {0: [1, 5], 1: [2], ...}).
neighbor node indices (e.g. ``{0: [1, 5], 1: [2], ...}``).
"""
# get the indices for each edge pair that contains the target state
adj_idx = np.nonzero(unique_edges == target)[0]
Expand Down Expand Up @@ -120,12 +120,12 @@ def _get_flux_path_edges(target, unique_edges):
Target state.
unique_edges : array
Array of edges (made from 2-tuples) that are unique to the
diagram (i.e. `(1, 2)` and `(2, 1)` are considered the same).
diagram (e.g. ``(1, 2)`` and ``(2, 1)`` are considered the same).
Returns
-------
path_edges : list
List of edge tuples (i.e. [(0, 1, 0), (1, 2, 0), ...]).
List of edge tuples (e.g. ``[(0, 1, 0), (1, 2, 0), ...]``).
"""
neighbors = _get_neighbor_dict(target, unique_edges)
path_edges = [(nbr, tgt, 0) for tgt in neighbors for nbr in neighbors[tgt]]
Expand All @@ -139,8 +139,8 @@ def _collect_sources(G):
Parameters
----------
G : NetworkX MultiDiGraph
Partial diagram.
G : ``NetworkX.Graph``
A partial diagram
Returns
-------
Expand All @@ -164,15 +164,15 @@ def _get_directional_path_edges(G, target):
Parameters
----------
G : NetworkX MultiDiGraph
Partial diagram.
G : ``NetworkX.MultiDiGraph``
A kinetic diagram
target : int
Target state.
Returns
-------
path_edges : list
List of edge tuples (i.e. [(0, 1, 0), (1, 2, 0), ...]).
List of edge tuples (e.g. ``[(0, 1, 0), (1, 2, 0), ...]``).
"""
sources = _collect_sources(G)
Expand Down Expand Up @@ -223,16 +223,16 @@ def _find_unique_uncommon_edges(G, cycle_edges):
Parameters
----------
G : NetworkX MultiDiGraph
Input diagram
G : ``NetworkX.MultiDiGraph``
A kinetic diagram
cycle_edges : list of tuples
List of edge tuples for a cycle of interest. Both forward and
reverse edges should be included (i.e. `(1, 0)` and `(0, 1)`).
reverse edges should be included (e.g. ``(1, 0)`` and ``(0, 1)``).
Returns
-------
edges : list of tuples
List of uncommon edges between G and "cycle_edges".
List of uncommon edges between ``G`` and ``cycle_edges``.
Since these should be unique edges (no reverse edges), these are the
unique uncommon edges between two diagrams (normal use case).
"""
Expand Down Expand Up @@ -277,10 +277,12 @@ def _flux_edge_conditions(edge_list, n_flux_edges):
def _append_reverse_edges(edge_list):
"""
Returns a list that contains original edges and reverse edges.
Parameters
----------
edge_list : list of edge tuples
List of unidirectional edges to have reverse edges appended to.
Returns
-------
new_edge_list : list of edge tuples
Expand All @@ -293,17 +295,18 @@ def _append_reverse_edges(edge_list):

def _get_cofactor_matrix(K_laplace):
"""
Helper function for `enumerate_partial_diagrams()`. Uses singular value
decomposition to get the cofactor matrix for the input Laplacian matrix.
Helper function for :meth:`~kda.diagrams.enumerate_partial_diagrams()`.
Uses singular value decomposition to get the cofactor matrix for
the input Laplacian matrix.
Parameters
----------
K_laplace : array
`NxN` Laplacian matrix, where 'N' is the number of nodes.
K_laplace : ndarray
``NxN`` Laplacian matrix, where ``N`` is the number of nodes.
Returns
-------
K_cof : array
K_cof : ndarray
Cofactor matrix for the input Laplacian matrix.
"""
U, w, Vt = np.linalg.svd(K_laplace)
Expand All @@ -319,12 +322,12 @@ def _get_cofactor_matrix(K_laplace):
def enumerate_partial_diagrams(G):
"""
Quantifies the number of partial diagrams (undirected spanning
trees) that can be generated from an input kinetic diagram `G`.
trees) that can be generated from a kinetic diagram.
Parameters
----------
G : NetworkX MultiDiGraph
Input diagram
G : ``NetworkX.MultiDiGraph``
A kinetic diagram
Returns
-------
Expand All @@ -342,7 +345,7 @@ def enumerate_partial_diagrams(G):
number of undirected spanning trees.
A more sophistocated version of this function is available in
the `NetworkX` library :footcite:`hagberg_exploring_2008`
the ``NetworkX`` library :footcite:`hagberg_exploring_2008`
(see `here <https://networkx.org/documentation/stable/reference/
algorithms/generated/networkx.algorithms.tree.mst.
number_of_spanning_trees.html>`_).
Expand Down Expand Up @@ -372,23 +375,24 @@ def enumerate_partial_diagrams(G):
def generate_partial_diagrams(G, return_edges=False):
"""
Generates all partial diagrams (undirected spanning trees)
for kinetic diagram `G`.
for a kinetic diagram.
Parameters
----------
G : NetworkX MultiDiGraph
Input diagram
G : ``NetworkX.MultiDiGraph``
A kinetic diagram
return_edges : bool
Binary used for determining whether to return NetworkX diagram objects
(primarily for plotting) or the edge tuples (generally for
calculations).
Binary used for determining whether to return ``NetworkX``
diagram objects (primarily for plotting) or the edge
tuples (generally for calculations).
Returns
-------
partials : array
Array of NetworkX MultiDiGraphs where each graph is a unique
partial diagram with no loops (return_edges=False), or a nested
array of unique edges for valid partial diagrams (return_edges=True).
partials : ndarray of ``NetworkX.Graph``
Array of ``NetworkX.Graph`` where each graph is a unique
partial diagram with no loops (``return_edges=False``), or
a nested array of unique edges for valid partial diagrams
(``return_edges=True``).
"""
# calculate number of edges needed for each partial diagram
n_edges = G.number_of_nodes() - 1
Expand Down Expand Up @@ -427,24 +431,22 @@ def generate_partial_diagrams(G, return_edges=False):

def generate_directional_diagrams(G, return_edges=False):
"""
Generates all directional diagrams for kinetic diagram `G`.
Generates all directional diagrams for a kinetic diagram.
Parameters
----------
partials : list
List of NetworkX MultiDiGraphs where each graph is a unique partial
diagram with no loops.
G : ``NetworkX.MultiDiGraph``
A kinetic diagram
return_edges : bool
Binary used for determining whether to return NetworkX diagram objects
(primarily for plotting) or the edge tuples (generally for
calculations).
Binary used for determining whether to return ``NetworkX`` graph
objects (primarily for plotting) or the edge tuples (generally
for calculations).
Returns
-------
directional_partial_diagrams : list
List of all directional diagrams for a given set of partial
diagrams.
directional_partial_diagram_edges : array
directional_diagrams : ndarray of ``NetworkX.MultiDiGraph``
Array of all directional diagrams for ``G``.
directional_diagram_edges : ndarray
Array of edges (made from 2-tuples) for valid directional
diagrams.
"""
Expand Down Expand Up @@ -481,22 +483,22 @@ def generate_directional_diagrams(G, return_edges=False):

def generate_flux_diagrams(G, cycle):
"""
Generates all flux diagrams for `cycle` in the kinetic diagram `G`.
Generates all flux diagrams for a specific cycle in the kinetic diagram.
Parameters
----------
G : NetworkX MultiDiGraph Object
Input diagram
G : ``NetworkX.MultiDiGraph``
A kinetic diagram
cycle : list of int
List of node indices for cycle of interest, index zero. Order of node
indices does not matter.
Returns
-------
flux_diagrams : list of NetworkX MultiDiGraph objects
flux_diagrams : list of ``NetworkX.MultiDiGraph``
List of flux diagrams. Diagrams contain the input cycle
where remaining edges follow path pointing to cycle.
Cycle nodes are labeled by attribute 'is_target'.
where remaining edges follow path pointing to ``cycle``.
Cycle nodes are labeled by attribute ``'is_target'``.
"""
if sorted(cycle) == sorted(G.nodes):
print(
Expand Down Expand Up @@ -541,18 +543,18 @@ def generate_flux_diagrams(G, cycle):

def generate_all_flux_diagrams(G):
"""
Generates all flux diagrams for the kinetic diagram `G`.
Generates all flux diagrams for a kinetic diagram.
Parameters
----------
G : NetworkX MultiDiGraph Object
Input diagram
G : ``NetworkX.MultiDiGraph``
A kinetic diagram
Returns
-------
all_flux_diagrams : list of lists of NetworkX MultiDiGraph objects
List of lists of flux diagrams, where each list is for a different cycle
in G.
all_flux_diagrams : list of lists of ``NetworkX.MultiDiGraph``
List of lists of flux diagrams, where each list
is for a different cycle in ``G``.
"""
all_cycles = graph_utils.find_all_unique_cycles(G)
n_nodes = G.number_of_nodes()
Expand Down
2 changes: 1 addition & 1 deletion kda/exceptions.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"""
Kinetic Diagram Analysis (kda) Exceptions
=========================================================================
This file contains a host of custom exception classes for kda.core.
This file contains a host of custom exception classes.
"""


Expand Down
19 changes: 8 additions & 11 deletions kda/expressions.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
"""
Algebraic Expressions
=========================================================================
This file contains a host of functions aimed at creating SymPy/Python
functions from algebraic expressions in string form.
The :mod:`~kda.expressions` module contains code to convert KDA-generated
string expressions into SymPy symbolic expressions.
.. autofunction:: construct_sympy_prob_funcs
.. autofunction:: construct_sympy_net_cycle_flux_func
Expand All @@ -27,16 +27,13 @@ def construct_sympy_prob_funcs(state_mult_funcs):
Parameters
----------
state_mult_funcs : list of str
List of length 'N', where N is the number of states, that contains the
analytic multiplicity function for each state
norm_func : str
Sum of all state multiplicity functions, the normalization factor to
calculate the state probabilities
List of length ``N`` (``N`` is the number of states) which contains
the algebraic multiplicity expressions for each state.
Returns
-------
sympy_funcs : list
List of analytic state probability SymPy functions.
List of Sympy symbolic state probability expressions.
"""
# convert the state multiplicity strings into sympy expressions
parsed_mult_funcs = [parse_expr(e) for e in state_mult_funcs]
Expand All @@ -61,8 +58,8 @@ def construct_sympy_net_cycle_flux_func(pi_diff_str, sigma_K_str, sigma_str):
Sum of rate products of directional flux diagram edges pointing to
input cycle in string form.
sigma_str : str
Sum of rate products of all directional diagrams for input
diagram G, in string form.
Sum of rate products of all directional diagrams for the kinetic
diagram, in string form.
Returns
-------
Expand All @@ -89,7 +86,7 @@ def construct_lambda_funcs(sympy_funcs, rate_names):
List of SymPy functions.
rate_names : list
List of strings, where each element is the name of the variables for
the input probability functions, ["x12", "x21", "x23", ...].
the input probability functions (e.g. ``["k12", "k21", "k23", ...]``).
Returns
-------
Expand Down
Loading

0 comments on commit 4e79a64

Please sign in to comment.