This guide is for versions 1.0 Beta 39+
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
| name | arguments | returns |
|---|---|---|
| __init__ | self | |
| name | arguments | returns |
|---|---|---|
| number_of_chemicals | self | int |
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
|
||
| name | arguments | returns |
|---|---|---|
| assert_valid_species_index | species_index: int | None |
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
|
||
| name | arguments | returns |
|---|---|---|
| get_label_mapping | self | dict |
Return a dict with all the mappings of the chemical names to the registered index
:return:
|
||
| name | arguments | returns |
|---|---|---|
| get_index | label :str | int |
Return the index of the chemical species with the given label.
If not found, an Exception is raised
:param label: Label of the chemical species of interest
:return: The index of the species with the given name
|
||
| name | arguments | returns |
|---|---|---|
| label_exists | label :str | bool |
Return True if the chemical with the given name exists (i.e. was registered),
or False otherwise
:param label: The label of a chemical
:return: True if it exists, or False otherwise
|
||
| name | arguments | returns |
|---|---|---|
| get_label | species_index: int | str |
Return the label 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
|
||
| name | arguments | returns |
|---|---|---|
| get_all_labels | self | [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
|
||
| name | arguments | returns |
|---|---|---|
| all_chemicals | self | pd.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
|
||
| name | arguments | returns |
|---|---|---|
| add_chemical | name :str, label=None, note=None, **kwargs | int |
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("Nicotinamide adenine dinucleotide",
label = "NAD", note = "my note about this substrate", CAS_number = "CAS 53-84-9")
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 label: [OPTIONAL] Typically, a short version of the name, or a stand-in for it;
if not provided, the name will be used as a label
: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
|
||
Extends its parent class, to manage diffusion-related data
End users will generally utilize the class ChemData, which extends this one
| name | arguments | returns |
|---|---|---|
| __init__ | self | |
| name | arguments | returns |
|---|---|---|
| add_chemical_with_diffusion | name :str, diff_rate :Union[float, int], label=None, note=None, **kwargs | int |
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: Label 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 label: [OPTIONAL] Typically, a short version of the name, or a stand-in for it;
if not provided, the name will be used as a label
: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
|
||
| name | arguments | returns |
|---|---|---|
| set_diffusion_rate | label :str, diff_rate :Union[float, int] | None |
Set the diffusion rate of the given chemical species (identified by its name)
:param label: Label of a chemical species
:param diff_rate: Diffusion rate (in water) for the above chemical
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| assert_valid_diffusion | diff | None |
Raise an Exception if the specified diffusion value isn't valid
:param diff: Diffusion rate
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| get_diffusion_rate | species_index=None, name=None | Union[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
|
||
| name | arguments | returns |
|---|---|---|
| get_all_diffusion_rates | self | list |
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
|
||
| name | arguments | returns |
|---|---|---|
| missing_diffusion_rate | self | bool |
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
|
||
Extends its parent class, to manage reaction-related data
End users will generally utilize the class ChemData, which extends this one
| name | arguments | returns |
|---|---|---|
| __init__ | self | |
| name | arguments | returns |
|---|---|---|
| number_of_reactions | include_inactive=False | int |
Return the number of registered chemical reactions
:param include_inactive:If True, disabled reactions are also included
:return: The number of registered chemical reactions
|
||
| name | arguments | returns |
|---|---|---|
| active_reaction_indices | self | [int] |
Return a list of the reaction index numbers of all the active reactions
:return: A list of integers, to identify the active reactions by their indices
|
||
| name | arguments | returns |
|---|---|---|
| assert_valid_rxn_index | index :int | None |
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
|
||
| name | arguments | returns |
|---|---|---|
| get_reaction | i :int | Reaction |
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
|
||
| name | arguments | returns |
|---|---|---|
| get_reactants | 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)
|
||
| name | arguments | returns |
|---|---|---|
| get_reactants_formula | i :int | str |
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
|
||
| name | arguments | returns |
|---|---|---|
| get_products | 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)
|
||
| name | arguments | returns |
|---|---|---|
| get_products_formula | i :int | str |
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
|
||
| name | arguments | returns |
|---|---|---|
| get_forward_rate | i :int | float |
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
|
||
| name | arguments | returns |
|---|---|---|
| get_reverse_rate | i :int | float |
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
|
||
| name | arguments | returns |
|---|---|---|
| get_chemicals_in_reaction | rxn_index :int | {int} |
Return a SET of indices (being a set, they're NOT in any particular order)
of all the chemicals participating 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
|
||
| name | arguments | returns |
|---|---|---|
| get_chemicals_indexes_in_reaction | rxn_index :int | [int] |
Return a sorted list of the indexes
of all the chemicals participating in the i-th reaction
:param rxn_index: An integer with the (zero-based) index to identify the reaction of interest
:return: A sorted list of indices of the chemicals involved in the above reaction
|
||
| name | arguments | returns |
|---|---|---|
| get_reactions_participating_in | 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
|
||
| name | arguments | returns |
|---|---|---|
| set_temp | 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
|
||
| name | arguments | returns |
|---|---|---|
| add_reaction | reactants: Union[int, str, list], products: Union[int, str, list], forward_rate=None, reverse_rate=None, delta_H=None, delta_S=None, delta_G=None | int |
Register a new SINGLE chemical reaction,
optionally including its kinetic and/or thermodynamic data.
All the involved chemicals can be either previously registered, or not.
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)
|
||
| name | arguments | returns |
|---|---|---|
| clear_reactions_data | self | None |
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
|
||
| name | arguments | returns |
|---|---|---|
| describe_reactions | concise=False | None |
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
|
||
| name | arguments | returns |
|---|---|---|
| multiple_reactions_describe | 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
|
||
| name | arguments | returns |
|---|---|---|
| single_reaction_describe | rxn_index: int, concise=False | str |
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
|
||
| name | arguments | returns |
|---|---|---|
| names_of_active_chemicals | self | Set[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)
|
||
| name | arguments | returns |
|---|---|---|
| number_of_active_chemicals | self | int |
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)
|
||
| name | arguments | returns |
|---|---|---|
| indexes_of_active_chemicals | self | [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.)
EXAMPLE: [2, 7, 8] if only those 3 chemicals (with indexes of, respectively, 2, 7 and 8)
are actively involved in ANY of the registered reactions
CAUTION: the concept of "active chemical" might change in future versions, where only SOME of
the reactions are simulated
|
||
| name | arguments | returns |
|---|---|---|
| names_of_enzymes | self | Set[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)
|
||
| name | arguments | returns |
|---|---|---|
| prepare_graph_network | self | dict |
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'
|
||
| name | arguments | returns |
|---|---|---|
| plot_reaction_network | graphic_component :str, unpack=False | None |
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
|
||
Used for binding of ligands to macromolecules (e.g. Transcription Factors to DNA)
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
| name | arguments | returns |
|---|---|---|
| __init__ | self | |
| name | arguments | returns |
|---|---|---|
| add_macromolecules | 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 UniformCompartment)
: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
|
||
| name | arguments | returns |
|---|---|---|
| get_macromolecules | self | [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
|
||
| name | arguments | returns |
|---|---|---|
| set_binding_site_affinity | macromolecule: str, site_number: int, ligand: str, Kd | None |
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
:param Kd: Dissociation constant, in units of concentration (typically microMolar).
Note that the dissociation constant is inversely proportional to the binding affinity
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| get_binding_site_affinity | macromolecule: str, site_number: int | ChemicalAffinity |
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
|
||
| name | arguments | returns |
|---|---|---|
| get_binding_sites | 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]
|
||
| name | arguments | returns |
|---|---|---|
| get_binding_sites_and_ligands | macromolecule | dict |
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"}
|
||
| name | arguments | returns |
|---|---|---|
| get_ligand_name | macromolecule: str, site_number: int | str |
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)
|
||
| name | arguments | returns |
|---|---|---|
| show_binding_affinities | self | None |
Print out the Dissociation Constant for each Binding Site in each Macromolecule
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| reset_macromolecule | macromolecule | None |
Erase all data for the specified macromolecule
:param macromolecule: The name of a macromolecule
:return: None
|
||
| name | arguments | returns |
|---|---|---|
| clear_macromolecules | self | None |
Reset all macromolecules to their original state
:return: None
|
||
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
| name | arguments | returns |
|---|---|---|
| __init__ | 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", ...
|
||
| name | arguments | returns |
|---|---|---|
| init_chemical_data | names=None, diffusion_rates=None | None |
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
|
||