ChemData – Reference Guide

This guide is for versions 1.0 Beta 33+

Source code

Class ChemCore

    Core data about the chemical species, such as their names and indexes (position in their listing)

    Note: end users will generally utilize the class ChemData, which extends this one
    
nameargumentsreturns
__init__self

nameargumentsreturns
number_of_chemicalsselfint
        Return the number of registered chemicals - exclusive of water and of macro-molecules

        :return:    The number of registered chemicals - exclusive of water and of macro-molecules
        
nameargumentsreturns
assert_valid_species_indexself, species_index: intNone
        Raise an Exception if the specified species_index (meant to identify a chemical) isn't valid

        :param species_index:   An integer that indexes the chemical of interest (numbering starts at 0)
        :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
name_existsself, name :strbool
        Return True if the chemical with the given name exists (i.e. was registered),
        or False otherwise

        :param name:    The name of a chemical
        :return:        True if it exists, or False otherwise
        
nameargumentsreturns
get_nameself, species_index: intstr
        Return the name of the species with the given index.

        :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 missing or blank, an Exception is raised
        
nameargumentsreturns
get_all_namesself[str]
        Return a list with the names of all the chemical species, in their index order.
        If any is missing or blank, an Exception instead

        :return:    A list of strings with the chemical names,
                        in their registered index order
        
nameargumentsreturns
all_chemicalsselfpd.DataFrame
        Returns a Pandas dataframe with all the known information
        about all the registered chemicals (not counting macro-molecules),
        in their index order

        :return:    A Pandas dataframe
        
nameargumentsreturns
add_chemicalself, name :str, note=None, **kwargsint
        Register a new chemical species, with a name
        and (optionally) :
            - a note (will be stored in a "note" column)
            - any other named argument(s) that the user wishes to store (i.e. arbitrary-named arguments)

        EXAMPLE:  add_chemical("P1", note = "my note about P1", full_name = "protein P1")

        Note: if also wanting to set the diffusion rate in a single function call,
              use ChemData.add_chemical_with_diffusion() instead

        :param name:    Name of the new chemical species to register; names must be unique -
                            an Exception will be raised if the name was already registered
        :param note:    [OPTIONAL] String with note to attach to the chemical
        :param kwargs:  [OPTIONAL] Dictionary of named arguments (with any desired names)
        :return:        The integer index assigned to the newly-added chemical
        



Class Diffusion

    Extends its parent class, to manage diffusion-related data

    End users will generally utilize the class ChemData, which extends this one
    
nameargumentsreturns
__init__self

nameargumentsreturns
add_chemical_with_diffusionself, name :str, diff_rate :Union[float, int], note=None, **kwargsint
        Register a new chemical species, with a name, a diffusion rate (in water),
        and (optionally) :
            - a note
            - any other named argument(s) that the user wishes to store (i.e. arbitrary named arguments)

        EXAMPLE:  add_chemical("P1", diffusion_rate = 0.1,
                               note = "my note about P1", full_name = "protein P1")

        Note: if no diffusion is to be set, can also simply use ChemData.add_chemical()

        :param name:        Name of the new chemical species to register;
                                an Exception will be raised if the name was already registered
        :param diff_rate:   Floating-point number with the diffusion rate (in water) of this chemical
        :param note:        [OPTIONAL] String with note to attach to the chemical
        :param kwargs:      [OPTIONAL] Dictionary of named arguments (with any desired names)
        :return:            The integer index assigned to the newly-added chemical
        
nameargumentsreturns
set_diffusion_rateself, name :str, diff_rate :Union[float, int]None
        Set the diffusion rate of the given chemical species (identified by its name)

        :param name:        Name of a chemical species
        :param diff_rate:   Diffusion rate (in water) for the above chemical
        :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_diffusion_rateself, species_index=None, name=NoneUnion[float, int, None]
        Return the diffusion rate of the specified chemical species.
        If no value was assigned (but the chemical exists), return None.

        :param name:            Name of the chemical of interest
        :param species_index:   Alternate way to specify the chemical, using its zero-based index (order
                                    in which it was registered);
                                    `name` and `species_index` cannot be both specified, or an Exception will be raised
        :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 (or None values) with the diffusion rates
        
nameargumentsreturns
missing_diffusion_rateselfbool
        Determine whether any of the registered chemicals has a missing diffusion rates

        :return:    True if any of the diffusion rates (for all the registered chemicals) is missing;
                        False otherwise
        



Class AllReactions

    Extends its parent class, to manage reaction-related data

    End users will generally utilize the class ChemData, which extends this one
    
nameargumentsreturns
__init__self

nameargumentsreturns
number_of_reactionsself, include_inactive=Falseint
        Return the number of registered chemical reactions

        :param include_inactive:If True, disabled reactions are also included
        :return:                The number of registered chemical reactions
        
nameargumentsreturns
active_reaction_indicesself[int]
        Return a list of the reaction index numbers of all the active reactions

        :return:
        
nameargumentsreturns
assert_valid_rxn_indexself, index :intNone
        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
get_reactionself, i :intReaction
        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, i :intstr
        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:    A string with a user-friendly form of the left (reactants) side of the chemical reaction
        
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, i :intstr
        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:    A string with a user-friendly form of the right (products) side of the chemical reaction
        
nameargumentsreturns
get_forward_rateself, i :intfloat
        Return the value of the forward rate constant of the i-th reaction

        :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
        Return the value of the reverse (back) rate constant of the i-th reaction

        :param i:   The integer index (0-based) to identify the reaction of interest
        :return:    The 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, they're NOT in any particular order)
        of all the chemicals in the i-th 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[Reaction]
        Return a list of all the reactions that the given chemical species
        is involved in

        :param species_index:
        :return:                List of "Reaction" objects
        
nameargumentsreturns
set_tempself, temp :Union[float, int], units="K"None
        Specify the temperature of the environment
        (for now assumed uniform everywhere)

        :param temp:    Temperature, in Kelvins, or None
        :param units:   Not yet implemented
        :return:        None
        
nameargumentsreturns
add_reactionself, reactants: Union[int, str, list], products: Union[int, str, list], forward_rate=None, reverse_rate=None, delta_H=None, delta_S=None, delta_G=Noneint
        Register a new SINGLE chemical reaction,
        optionally including its kinetic and/or thermodynamic data.
        All the involved chemicals must be already registered - use add_chemical() if needed.

        NOTE: in the reactants and products, if the stoichiometry coefficients aren't specified,
              they're assumed to be 1.
              The reaction orders, if not specified, are assumed to be equal to their corresponding
              stoichiometry coefficients.

              The full structure of each term in the list of reactants and of products
              is the triplet:  (stoichiometry coefficient, name, reaction order)

              EXAMPLES of formats to use for each term in the lists of the reactants and of the products:
                "F"         is taken to mean (1, "F", 1) - default stoichiometry and reaction order
                (2, "F")    is taken to mean (2, "F", 2) - stoichiometry coefficient used as default for reaction order
                (2, "F", 1) means stoichiometry coefficient 2 and reaction order 1 - no defaults invoked
              It's equally acceptable to use LISTS in lieu of tuples for the pair or triplets

        :param reactants:       A list of triplets (stoichiometry, species name, reaction order),
                                    or simplified terms in various formats; for details, see above.
                                    If not a list, it will get turned into one
        :param products:        A list of triplets (stoichiometry, species name, reaction order of REVERSE reaction),
                                    or simplified terms in various formats; for details, see above.
                                    If not a list, it will get turned into one
        :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:                Integer index of the newly-added reaction
                                    (in the list self.reaction_list, stored as object variable)
        
nameargumentsreturns
clear_reactions_dataselfNone
        Get rid of all the reactions; start again with "an empty slate" (but still with reference
        to the same data object about the chemicals and their properties)

        :return:    None
        
nameargumentsreturns
inactivate_reactionself, i :intNone
        Mark the i-th reaction as "inactive/disabled" (essentially, "deleted", but holding its positional
        index, to avoid a change in index in other reactions)

        TODO: Not yet supported by the dynamical modules; DON'T USE YET in simulations!

        :param i:   Zero-based index of the reaction to disable
        :return:    None
        

DESCRIBE RXNS

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
            Set of chemicals involved in the above reactions: {'CH4', 'O2', 'H2O', 'A', 'B', 'C'}

        :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.
        Return a list of strings, each string being a (concise or not) user-friendly plain-text form of
        each of the 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; each string is the description of one of the reactions
        
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):  "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
names_of_active_chemicalsselfSet[str]
        Return the set of the names of all the chemicals
        involved in ANY of the registered reactions,
        but NOT counting chemicals that always appear in a catalytic role in all the reactions they
        participate in
        (if a chemical participates in a non-catalytic role in ANY reaction, it'll appear here)
        
nameargumentsreturns
number_of_active_chemicalsselfint
        Return the number of all the chemicals
        involved in ANY of the registered reactions,
        but NOT counting chemicals that always appear in a catalytic role in all the reactions they
        participate in
        (if a chemical participates in a non-catalytic role in ANY reaction, it'll appear here)
        
nameargumentsreturns
indexes_of_active_chemicalsself[int]
        Return the ordered list (numerically sorted) of the index numbers of all the chemicals
        involved in ANY of the registered reactions,
        but NOT counting chemicals that always appear in a catalytic role in all the reactions they
        participate in
        (if a chemical participates in a non-catalytic role in ANY reaction, it'll appear here)
        
nameargumentsreturns
names_of_enzymesselfSet[str]
        Return the set of the names of the enzymes (catalysts) involved
        in any of the registered reactions
        (regardless of whether they might participate in a non-enzymatic role in other reactions)
        

NETWORK DIAGRAMS

nameargumentsreturns
prepare_graph_networkselfdict
        Prepare and return a data structure with chemical-reaction data in a network format,
        ready to be passed to the front end, for network-diagram visualization with the Cytoscape.js library
        (in the graph module "vue_cytoscape")

        EXAMPLE of the graph structure part of the returned object for an  A <-> B reaction:
           [{'id': 'C-0', 'labels': ['Chemical'], 'name': 'A', 'diff_rate': None},
            {'id': 'C-1', 'labels': ['Chemical'], 'name': 'B', 'diff_rate': None},

            {'id': 'R-0', 'labels': ['Reaction'], 'name': 'RXN', 'kF': 3.0, 'kR': 2.0, 'K': 1.5, 'Delta_G': -1005.13},

            {'id': 'edge-1', 'name': 'produces', 'source': 'R-0', 'target': 'C-1', 'stoich': 1, 'rxn_order': 1},
            {'id': 'edge-2', 'name': 'reacts',   'source': 'C-0', 'target': 'R-0', 'stoich': 1, 'rxn_order': 1}
           ]

        :return:    A dictionary with 3 keys: 'structure', 'color_mapping', 'caption_mapping'
        
nameargumentsreturns
plot_reaction_networkself, graphic_component :str, unpack=FalseNone
        Send a plot of the network of reactions to the HTML log file,
        also including a brief summary of all the reactions

        EXAMPLE of usage:  plot_reaction_network("vue_cytoscape_2")

        :param graphic_component:   The name of a Vue component that accepts a "graph_data" argument,
                                        an object with the following keys
                                        'structure', 'color_mapping' and 'caption_mapping'
                                        For more details, see ChemData.prepare_graph_network()
        :param unpack:              Use True for Vue components that require their data unpacked into individual arguments;
                                        False for that accept a single data argument, named "graph_data"
        :return:                    None
        



Class ChemicalAffinity

    Used for binding of ligands to macromolecules (e.g. Transcription Factors to DNA)
    



Class Macromolecules

    Extends its parent class to manage modeling of large molecules (such as DNA)
    with multiple binding sites (for example, for Transcription Factors)

    End users will generally utilize the class ChemData, which extends this one
    
nameargumentsreturns
__init__self

nameargumentsreturns
add_macromoleculesself, names: Union[str, List[str]]None
        Register one or more macromolecule species, specified by their name(s)
        Note: this is a register of names, NOT of dynamical information
              about counts of macromolecules in the system (which is the domain of the class ReactionDynamics)

        :param names:   A string, or list of strings, with the name(s) of the macromolecule(s)
        :return:        None.  The object attribute self.macro_molecules will get modified
        
nameargumentsreturns
get_macromoleculesself[str]
        Return a list of the names of all the registered macromolecules

        :return:    A (possibly empty) list of the names of all the registered macromolecules
        
nameargumentsreturns
set_binding_site_affinityself, macromolecule: str, site_number: int, ligand: str, KdNone
        Set the values of the binding affinity of the given macromolecule, at the indicated site on it,
        for the specified chemical species.

        Any previously-set value (for that macromolecule/site_number/chemical) will get over-written.

        IMPORTANT: Only 1 chemical (ligand type) can be associated to a particular site of a given macromolecule; attempting
        to associate another one will result in error.  In case multiple ligands can bind to the same physical site on
        the macromolecule, simply assign multiple site numbers for each of them

        NOTE: at present, no allowance is made for the fact that if the macromolecule is already bound
              to chemical "X" then its affinity of "Y" might be different than in the absence of "X"

        :param macromolecule:   Name of a macromolecule; if not previously-declared,
                                    it will get added to the list of registered macromolecules
        :param site_number:     Unique integer to identify a binding site on the macromolecule
        :param ligand:          Name of a previously-declared (bulk) chemical;
                                    if not found, an Exception will be raised       TODO: inconsistent with "macromolecule" arg
        :param Kd:              Dissociation constant, in units of concentration (typically microMolar).
                                    Note that the dissociation constant is inversely proportional to the binding affinity
        :return:                None
        
nameargumentsreturns
get_binding_site_affinityself, macromolecule: str, site_number: intChemicalAffinity
        Return the value of the binding affinity of the given macromolecule.
        If no value was previously set, an Exception is raised

        :param macromolecule:   Name of a macromolecule; if not found, an Exception will get raised
        :param site_number:     Integer to identify a binding site on the macromolecule
        :return:                The NamedTuple (ligand name, dissociation constant)
                                    if no value was previously set, an Exception is raised
        
nameargumentsreturns
get_binding_sitesself, macromolecule[int]
        Get a list of all the binding-site numbers of the given macromolecule.
        If the requested macromolecule isn't registered, an Exception will be raised

        :param macromolecule:   The name of a macromolecule
        :return:                A (possibly empty) list of integers, representing the binding-site numbers.
                                    EXAMPLE: [1, 2]
        
nameargumentsreturns
get_binding_sites_and_ligandsself, macromoleculedict
        Return a mapping (python dict) from binding-site number to ligand species, for the given macromolecule
        If the requested macromolecule isn't registered, an Exception will be raised

        :param macromolecule:   The name of a macromolecule
        :return:                A dict whose keys are binding-site numbers and values are their respetive ligands
                                    EXAMPLE: {1: "A", 2: "C"}
        
nameargumentsreturns
get_ligand_nameself, macromolecule: str, site_number: intstr
        Return the name of the ligand associated to the specified site
        on the given macromolecule.
        If not found, an Exception is raised

        :param macromolecule:   The name of a macromolecule
        :param site_number:     Integer to identify a binding site on the macromolecule
        :return:                The name of the ligand (chemical species)
        
nameargumentsreturns
show_binding_affinitiesselfNone
        Print out the Dissociation Constant for each Binding Site in each Macromolecule

        :return:    None
        
nameargumentsreturns
reset_macromoleculeself, macromoleculeNone
        Erase all data for the specified macromolecule

        :param macromolecule:   The name of a macromolecule
        :return:                None
        
nameargumentsreturns
clear_macromoleculesselfNone
        Reset all macromolecules to their original state

        :return:    None
        



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)

            - we're using a "daisy chain" of classes extending the previous one, starting from ChemCore
              and ending in this user-facing class:
                    ChemCore <- Diffusion <- AllReactions <- Macromolecules <- ChemData
    
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 to avoid passing any data at instantiation, and later add it.
        Reactions, if applicable, need to be added later by means of calls to add_reaction()
        Macro-molecules, if applicable, need to be added later

        :param names:           [OPTIONAL] A single name, or list or tuple of names, of the chemicals
        :param diffusion_rates: [OPTIONAL] A list or tuple with the diffusion rates of the chemicals
                                           If diffusion rates are provided, but no names given, the names will be
                                           auto-assigned as "Chemical 1", "Chemical 2", ...
        TODO: allow a way to optionally pass macromolecules as well
        
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] A single name, or list or tuple of names, of the chemicals
        :param diffusion_rates: [OPTIONAL] A list or tuple with the diffusion rates of the chemicals,
                                           in the same order as the names
        :return:                None