Skip to content

DOC: Minor updates to docstrings #125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nawtrey merged 1 commit into from
Apr 21, 2025
Merged

DOC: Minor updates to docstrings #125

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 37 additions & 37 deletions kda/calculations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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``.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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``.

Expand Down Expand Up @@ -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
Expand All @@ -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``.

Expand Down
25 changes: 12 additions & 13 deletions kda/core.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)

Expand All @@ -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
=======
Expand Down Expand Up @@ -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
==========
Expand All @@ -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``.
"""
Expand Down Expand Up @@ -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``.

Expand Down Expand Up @@ -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

2 changes: 1 addition & 1 deletion kda/diagrams.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
12 changes: 6 additions & 6 deletions kda/graph_utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"``.
"""
Expand Down Expand Up @@ -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"``
Expand Down Expand Up @@ -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
----------
Expand Down
Loading