This guide is for versions 1.0.0rc.2+ (Release Candidate)
Core data about the chemical species, such as their names, labels
and indexes (position in their listing)
Note: End users will typically utilize the class ChemData, which extends this one
| name | arguments | returns |
|---|---|---|
| __init__ | ||
| name | arguments | returns |
|---|---|---|
| number_of_chemicals | 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 | 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.
Indexes are the integers assigned, in autoincrement order,
at the time each chemical is first registered.
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 | [str] | |
Return a list with the labels of all the chemical species,
in their index order of registration.
If any label is missing or blank, an Exception is raised
:return: A list of strings with the chemical names,
in their registered index order
|
||
| name | arguments | returns |
|---|---|---|
| all_chemicals | pd.DataFrame | |
Returns a Pandas dataframe with all the known information
about all the registered chemicals (not counting macro-molecules),
in their registration index order
:return: A Pandas dataframe
|
||
| name | arguments | returns |
|---|---|---|
| add_chemical | name :str, label=None, note=None, plot_color=None, **kwargs | int |
Register a new chemical species, with a name
and (optionally) :
- a label (typically, a short version of the name, or a stand-in for it)
- a note (will be stored in a "note" column)
- a color value used in visualizations
- 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 as a name or as a label
:param label: [OPTIONAL] Typically, a short version of the name, or a stand-in for it.
If provided, it must be unique, and cannot be identical to the name of another chemical;
if not provided, the name will be used as a label
:param note: [OPTIONAL] String with note to attach to the chemical
:param plot_color: [OPTIONAL] String with color value to attach to the chemical for visualizations
:param kwargs: [OPTIONAL] Dictionary of named arguments (with any desired names)
:return: The integer index assigned to the newly-added chemical
|
||
| name | arguments | returns |
|---|---|---|
| get_plot_color | label :str | Union[str, None] |
Return the name of the plot color previously associated to the given chemical
:param label: A string to identify a particular chemical
:return: The name of the associated plot color, or None if not found
|
||
| name | arguments | returns |
|---|---|---|
| get_registered_colors | chem_labels :Union[None, list[str]] | Union[None, list[str]] |
Return a list of the colors registered for the specified chemicals or, if not specified, for all chemicals.
If not a single color is registered, return None
:param chem_labels: List of chemical labels; use None to mean ALL chemicals
:return: List of color names, with as many entries as the chemicals of interest;
any of the entries might be None.
However, if zero colors are found, return None
|
||
| name | arguments | returns |
|---|---|---|
| get_color_mapping_by_label | dict | |
EXAMPLE: {"A": "red", "B": "orange", "C": "green"}
:return: A dict of plot colors, indexed by chemical labels
|
||
| name | arguments | returns |
|---|---|---|
| get_color_mapping_by_index | dict | |
EXAMPLE: {0: 'red', 1: 'orange', 2: 'green'}
:return: A dict of plot colors, indexed by chemical index
|
||
| name | arguments | returns |
|---|---|---|
| get_all_colors | list | |
:return: A list of all colors, in the index position of their respective chemicals
|
||
Extends its parent class, to manage diffusion-related data
End users will typically utilize the class ChemData, which extends this one
| name | arguments | returns |
|---|---|---|
| __init__ | ||
| 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(label = "P1", diff_rate = 0.1,
note = "my note about P1", 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 coefficient (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.
Valid values are non-negative numbers (integer, float or numpy integers/floats)
: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 | 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 | 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
|
||
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 typically utilize the class ChemData, which extends this one
| name | arguments | returns |
|---|---|---|
| __init__ | ||
| 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 | [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 respective 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 | 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 | 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)
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 <- Macromolecules <- ChemData
| name | arguments | returns |
|---|---|---|
| __init__ | names=None, labels=None, diffusion_rates=None, plot_colors=None | |
Any non-None arguments MUST all have the same length (and appear in the same order), or all be scalars.
It's ok to skip passing any data at instantiation, and later add it, with calls to add_chemical().
Reactions, if applicable, need to be added later by means of calls to add_reaction()
Macro-molecules, if applicable, need to be added later.
If no names nor labels are provided, but diffusion rate or plot colors are given,
the strings "Chemical 1", "Chemical 2", ..., are used
:param names: [OPTIONAL] A single name, or list or tuple of names, of the chemicals.
If not provided, the names are made equal to the labels.
If neither names nor labels is provided, "Chemical 1", "Chemical 2", ..., are used
(as many as the diffusion rates or plot colors)
:param labels: [OPTIONAL] A single label, or list or tuple of labels, of the chemicals,
in the same order as the names (if provided).
If not provided, the labels are made equal to the names.
If neither names nor labels is provided, "Chemical 1", "Chemical 2", ..., are used
(as many as the diffusion rates or plot colors)
:param diffusion_rates: [OPTIONAL] A non-negative number, or a list/tuple/Numpy array with the diffusion rates of the chemicals,
in the same order as the names/labels (if provided).
:param plot_colors: [OPTIONAL] A single name, or list or tuple of names, of the plotting colors for the chemicals,
in the same order as the names/labels (if provided).
|
||