Source code

Class ChemData

    Data about all the chemicals and (if applicable) reactions,
    including:
        - names
        - diffusion rates
        - macro-molecules Binding Site Affinities (for Transcription Factors)
        - reaction data (see also class "Reaction", in "reaction_data.py")


    Notes:  - for now, the temperature is assumed constant everywhere, and unvarying (or very slowly varying)
nameargumentsreturns
__init__self, names=None, diffusion_rates=None
        If chemical names and their diffusion rates are both provided, they must have the same count,
        and appear in the same order.
        It's ok not to pass any data, and later add it.
        Reactions can be added later by means of calls to add_reaction()

        :param names:           [OPTIONAL] A list with the names of the chemicals
        :param diffusion_rates: [OPTIONAL] A list or tuple with the diffusion rates of the chemicals

        
nameargumentsreturns
number_of_chemicalsselfint
nameargumentsreturns
number_of_reactionsselfint
nameargumentsreturns
assert_valid_species_indexself, species_index: intNone
        Raise an Exception if the specified species_index isn't valid

        :param species_index:   An integer that indexes the chemical of interest (numbering starts at 0)
        :return:                None
        
nameargumentsreturns
assert_valid_rxn_indexself, indexNone
        Raise an Exception if the specified reaction index isn't valid

        :param index:   An integer that indexes the reaction of interest (numbering starts at 0)
        :return:        None
        
nameargumentsreturns
assert_valid_diffusionself, diffNone
        Raise an Exception if the specified diffusion value isn't valid

        :param diff:    Diffusion rate
        :return:        None
        
nameargumentsreturns
get_indexself, name: strint
        Return the index of the chemical species with the given name.
        If not found, an Exception is raised

        :param name:    Name of the chemical species of interest
        :return:        The index of the species with the given name
        
nameargumentsreturns
get_nameself, species_index: intUnion[str, None]
        Return the name of the species with the given index.
        If no name was assigned, return None.

        :param species_index:   An integer (starting with zero) corresponding to the
                                    original order with which the chemical species were first added
        :return:                The name of the species with the given index if present,
                                    or None if not
        
nameargumentsreturns
get_all_namesself[Union[str, None]]
        Return a list with the names of all the chemical species, in their index order.
        If any is missing, None is used

        :return:    A list of strings
        
nameargumentsreturns
get_diffusion_rateself, species_index: intUnion[str, None]
        Return the diffusion rate of the species with the given index.
        If no name was assigned, return None.

        :param species_index:   An integer (starting with zero) corresponding to the
                                    original order with which the chemical species were first added
        :return:                The value of the diffusion rate for the species with the given index if present,
                                    or None if not
        
nameargumentsreturns
get_all_diffusion_ratesselflist
        Return a list of the diffusion rates of all the chemicals,
        in the order of their indexes.

        If any value is missing, None is used for it

        :return:    A list of numbers with the diffusion rates
        
nameargumentsreturns
missing_diffusion_rateselfbool
        Return True if any of the diffusion rates is missing; False otherwise
        :return:
        
nameargumentsreturns
get_reactionself, i: intdict
        Return the data structure of the i-th reaction,
        in the order in which reactions were added (numbering starts at 0)

        :param i:   An integer that indexes the reaction of interest (numbering starts at 0)
        :return:    A dictionary with 4 keys ("reactants", "products", "kF", "kR"),
                    where "kF" is the forward reaction rate constant, and "kR" the back reaction rate constant
        
nameargumentsreturns
get_reactantsself, i: int[(int, int, int)]
        Return a list of triplets with details of the reactants of the i-th reaction

        :param i:   The index (0-based) to identify the reaction of interest
        :return:    A list of triplets of the form (stoichiometry, species index, reaction order)
        
nameargumentsreturns
get_reactants_formulaself, istr
        Return a string with a user-friendly form of the left (reactants) side of the reaction formula

        :param i:   The index (0-based) to identify the reaction of interest
        :return:
        
nameargumentsreturns
get_productsself, i: int[(int, int, int)]
        Return a list of triplets with details of the products of the i-th reaction

        :param i:   The index (0-based) to identify the reaction of interest
        :return:    A list of triplets of the form (stoichiometry, species index, reaction order)
        
nameargumentsreturns
get_products_formulaself, istr
        Return a string with a user-friendly form of the right (products) side of the reaction formula

        :param i:   The index (0-based) to identify the reaction of interest
        :return:
        
nameargumentsreturns
get_forward_rateself, i: intfloat

        :param i:   The integer index (0-based) to identify the reaction of interest
        :return:    The value of the forward rate constant for the above reaction
        
nameargumentsreturns
get_reverse_rateself, i: intfloat

        :param i:   The integer index (0-based) to identify the reaction of interest
        :return:    he value of the reverse (back) rate constant for the above reaction
        
nameargumentsreturns
get_chemicals_in_reactionself, rxn_index: int{int}
        Return a SET of indices (being a set, it's NOT in any particular order)
        of all the chemicals in the specified reaction

        :param rxn_index:   An integer with the (zero-based) index to identify the reaction of interest
        :return:            A SET of indices of the chemicals involved in the above reaction
                                Note: being a set, it's NOT in any particular order
        
nameargumentsreturns
get_reactions_participating_inself, species_index: int[int]
        Return a list of all the reactions that the given chemical species
        is involved in

        :param species_index:
        :return:
        
nameargumentsreturns
init_chemical_dataself, names=None, diffusion_rates=NoneNone
        Initialize the names (if provided) and diffusion rates (if provided)
        of all the chemical species, in the given order.
        If no names are provided, the strings "Chemical 1", "Chemical 2", ..., are used

        IMPORTANT: this function can be invoked only once, before any chemical data is set.
                   To add new chemicals later, use add_chemical()

        :param names:           [OPTIONAL] List or tuple of the names of the chemical species
        :param diffusion_rates: [OPTIONAL] A list or tuple with the diffusion rates of the chemicals,
                                           in the same order as the names
        :return:                None
        
nameargumentsreturns
add_chemicalself, name: str, diffusion_rate=None, note=NoneNone
        Register a new chemical species, with a name and (optionally) a diffusion rate.

        :param name:            Name of the chemical species to add
        :param diffusion_rate:  [OPTIONAL] Floating-point number with the diffusion rate (in water) of this chemical
        :param note:            [OPTIONAL] Note to attach to the chemical
        :return:                None
        
nameargumentsreturns
set_diffusion_rateself, name, diff_rate
        Set the diffusion rate of the given chemical species

        :param name:
        :param diff_rate:
        :return:
        
nameargumentsreturns
set_tempself, temp, units="K"

        :param temp:    Temperature, in Kelvins, or None
        :param units:   Not yet implemented
        :return:
        
nameargumentsreturns
add_reactionself, reactants: Union[int, str, tuple, list], products: Union[int, str, tuple, list], forward_rate=None, reverse_rate=None, Delta_H=None, Delta_S=None, Delta_G=NoneNone
        Add the parameters of a SINGLE reaction, optionally including kinetic and/or thermodynamic data.
        The involved chemicals must be already registered - use add_chemical() if needed.

        NOTE: in the reactants and products, if the stoichiometry and/or reaction order aren't specified,
              they're assumed to be 1.
              Their full structure is the triplet (stoichiometry coefficient, name, reaction order)

        EXAMPLES of formats for reactants and products (*assuming* that the chemical species with index 5 is called "F"):
                    "F"         gets turned into:   (1, 5, 1)
                    (3, "F")                        (3, 5, 1)
                    (3, "F", 2)                     (3, 5, 2)
                    It's equally acceptable to use LISTS in lieu of tuples

        :param reactants:       A list of triplets (stoichiometry, species name or index, reaction order),
                                    or simplified terms in various formats; for details, see above
        :param products:        A list of triplets (stoichiometry, species name or index, reaction order of REVERSE reaction),
                                    or simplified terms in various formats; for details, see above
        :param forward_rate:    [OPTIONAL] Forward reaction rate constant
        :param reverse_rate:    [OPTIONAL] Reverse reaction rate constant
        :param Delta_H:         [OPTIONAL] Change in Enthalpy (from reactants to products)
        :param Delta_S:         [OPTIONAL] Change in Entropy (from reactants to products)
        :param Delta_G:         [OPTIONAL] Change in Free Energy (from reactants to products)
        :return:                None
        
nameargumentsreturns
clear_reactions_dataselfNone
        Get rid of all reactions; start again with "an empty slate" (but still with reference
        to the same data object about the chemicals)
        :return:    None
        
nameargumentsreturns
describe_reactionsself, concise=FalseNone
        Print out a user-friendly plain-text form of all the reactions.
        If wanting to describe just 1 reaction, use single_reaction_describe()

        EXAMPLE (not concise):
            Number of reactions: 2 (at temp. 25 C)
            (0) CH4 + 2 O2 <-> CO2 + 2 H2O  (kF = 3.0 / kR = 2.0 / Delta_G = -1,005.13 / K = 1.5) | 1st order in all reactants & products"
            (1) A + B <-> C  (kF = 5.0 / kR = 1.0 / Delta_G =  / K = 5.0) | 1st order in all reactants & products"

        :param concise:     If True, less detail is shown
        :return:            None
        
nameargumentsreturns
multiple_reactions_describeself, rxn_list=None, concise=False[str]
        The counterpart of single_reaction_describe() for many reactions

        :param rxn_list:    Either a list of integers, to identify the reactions of interest,
                                or None, meaning ALL reactions
        :param concise:     If True, less detail is shown
        :return:            A list of strings
        
nameargumentsreturns
single_reaction_describeself, rxn_index: int, concise=Falsestr
        Return as a string, a user-friendly plain-text form of the given reaction
        EXAMPLE (concise):      "CH4 + 2 O2 <-> CO2 + 2 H2O"
        EXAMPLE (not concise):  "(0) CH4 + 2 O2 <-> CO2 + 2 H2O  (kF = 3.0 / kR = 2.0 / Delta_G = -1,005.13 / K = 1.5) | 1st order in all reactants & products"

        :param rxn_index:   Integer to identify the reaction of interest
        :param concise:     If True, less detail is shown
        :return:            A string with a description of the specified reaction
        
nameargumentsreturns
prepare_graph_networkselfdict

        :return:    A dictionary with 2 keys: 'graph' and 'color_mapping'
        
nameargumentsreturns
create_graph_network_dataself[{}]
        Encode the reaction data in a form suitable for visualization
        with the graph module "vue_cytoscape"

        :return:    A list of dictionaries.  Each dictionary must have an 'id' key with a unique value.
                    EXAMPLE, for an  A <-> B reaction:
                       [{'id': 0, 'label': 'Chemical', 'name': 'A', 'diff_rate': None, 'stoich': 1, 'rxn_order': 1},
                        {'id': 1, 'label': 'Chemical', 'name': 'B', 'diff_rate': None, 'stoich': 1, 'rxn_order': 1},

                        {'id': 2, 'label': 'Reaction', 'name': 'RXN', 'kF': 3.0, 'kR': 2.0, 'K': 1.5, 'Delta_G': -1005.13},

                        {'id': 3, 'name': 'produces', 'source': 2, 'target': 1},
                        {'id': 4, 'name': 'reacts', 'source': 0, 'target': 2}
                       ]
        
nameargumentsreturns
assign_color_mappingself