BioSim1D – Reference Guide

This guide is for versions 1.0.0rc.4+ (Release Candidate)

Source code

Class BioSim1D

    1D simulations of diffusion and reactions,
    with optional membranes
    
nameargumentsreturns
__init__n_bins :int, chem_data=None, reaction_handler=None
        :param n_bins:          The number of compartments (bins) to use in the simulation

        [IMPORTANT: At least one of the 2 following arguments MUST be provided]
        :param chem_data:       [OPTIONAL] Object of class "ChemData";
                                    if not specified, it will get extracted
                                    from the "UniformCompartment" class (if passed to the next argument)
        :param reaction_handler:[OPTIONAL] Object of class "UniformCompartment";
                                    if not specified, it'll get instantiated here
        

VIEW/UPDATE SYSTEM

nameargumentsreturns
system_sizeint
        Return the number of bins in the system
        Note: the bin numbers will range between 0 and (system_size - 1)

        :return:    The number of bins in the system
        
nameargumentsreturns
get_chem_data
        Return all the associated chemical data,
        incl. diffusion rate constants (but EXCLUSIVE of reactions)

        :return:    An Object of type "ChemData"
        
nameargumentsreturns
get_reactions
        Return all the associated reactions

        :return:    Object ot type "Reactions" (with data about all the reactions)
        
nameargumentsreturns
get_reaction_handlerbin_address=0
        Return the object that manages the reactions.
        Note that for now just 1 object is present;
        in the future, it might be 1 per bin (or per bin cluster)

        :param bin_address: CURRENTLY NOT USED
        :return:            Object ot type "UniformCompartment"
        
nameargumentsreturns
reset_systemNone
        WARNING - THIS IS VERY PARTIAL.

        :return:    None
        
nameargumentsreturns
save_systemdict
        For now, just return a copy of self.system, with a "frozen" snapshot of the current system state

        :return:    A dict of (for now a part of) the elements needed to later restore the complete system state
        
nameargumentsreturns
restore_systemnew_state: dictNone
        Replace (some, for now, of) the various parts the System's internal state.
        For details of the data structure, see the class variable "system"

        :param new_state:   Numpy array containing the desired new System's internal state
        :return:
        
nameargumentsreturns
replace_systemnew_state: np.arrayNone
        Replace the System's internal state.
        For details of the data structure, see the class variable "system"
        IMPORTANT: membranes aren't handled. System length and global_Dx are currently not modified

        :param new_state:   Numpy array containing the desired new System's internal state
        :return:
        

SET/MODIFY CONCENTRATIONS

nameargumentsreturns
set_uniform_concentrationconc: float, chem_index=None, chem_label=NoneNone
        Assign the given concentration to all the bins of the specified chemical (identified by its index or name.)
        Any previous values get over-written

        :param conc:        The desired value of chemical concentration for the above species
        :param chem_index:  [OPTIONAL] Zero-based index to identify a specific chemical
        :param chem_label:  [OPTIONAL] If provided, it over-rides the value for chem_index
        :return:            None
        
nameargumentsreturns
set_all_uniform_concentrationsconc_list: Union[list, tuple], snapshot=TrueNone
        Set the concentrations of all chemical species at once, uniformly across all bins

        :param conc_list:   List or tuple of concentration values for each of the chemical species
        :param snapshot:    [OPTIONAL] DEPRECATED.  Being phased out.  If True (default), add to the history
                                a snapshot of this state being set
        :return:            None
        
nameargumentsreturns
set_bin_concbin_address: int, conc: float, chem_index=None, chem_label=NoneNone
        Assign the requested concentration value to the given bin, for the specified chemical species.

        :param bin_address:     The zero-based bin number of the desired compartment
        :param conc:            The desired concentration value to assign to the specified location
        :param chem_index:      Zero-based index to identify a specific chemical species
        :param chem_label:      [OPTIONAL] If provided, it over-rides the value for chem_index
        :return:                None
        
nameargumentsreturns
set_species_concconc_list: Union[list, tuple, np.ndarray], chem_index=None, chem_label=NoneNone
        Assign the requested list of concentration values to all the bins, in bin order,
        for the specified single chemical species.

        :param conc_list:   A list, tuple or Numpy array with the desired concentration values
                                to assign to all the bins.
                                The dimensions must match the system's dimensions.
        :param chem_index:  Zero-based index to identify a specific chemical species
        :param chem_label:  (OPTIONAL) If provided, it over-rides the value for chem_index
        :return:            None
        
nameargumentsreturns
inject_conc_to_binbin_address: int, delta_conc: float, chem_label=None, chem_index=None, zero_clip = FalseNone
        Add the requested concentration to the cell with the given address, for the specified chem species

        :param bin_address: The zero-based bin number of the desired cell
        :param chem_label:  String to identify the chemical of interest
        :param chem_index:  Alternate way to identify the chemical of interest, with a zero-based index
        :param delta_conc:  The concentration to add to the specified location
        :param zero_clip:   If True, any requested increment causing a concentration dip below zero, will make the concentration zero;
                                otherwise, an Exception will be raised
        :return:                None
        
nameargumentsreturns
inject_gradientchem_label, conc_left = 0., conc_right = 0.None
        Add to the concentrations of the specified chemical species a linear gradient spanning across all bins,
        with the indicated values at the endpoints of the system.

        :param chem_label:  The name of the chemical whose concentration we're modifying
        :param conc_left:   The desired amount of concentration to add to the leftmost bin (the start of the gradient)
        :param conc_right:  The desired amount of concentration to add to the rightmost bin (the end of the gradient)
        :return:            None
        
nameargumentsreturns
inject_sine_concchem_label, number_cycles, amplitude, bias=0, phase=0, zero_clip = FalseNone
        Add to the current concentrations of the specified chemical species
        a sinusoidal signal across all bins.

        Note:   A sine wave of the form  f(x) = A sin(B x - C)
                has an amplitude of A, a period of 2Pi/B and a right phase shift of C (in radians)

        In Mathematica:  Plot[Sin[B x - C] /. {B -> 2 Pi, C -> 0} , {x, 0, 1}, GridLines -> Automatic]

        :param chem_label:       The name of the chemical whose concentration we're modifying
        :param number_cycles:   Number of full waves along the length of the system
        :param amplitude:       Amplitude of the Sine wave.  Note that peak-to-peak values are double the amplitude
        :param bias:            Amount to be added to all values (akin to "DC bias" in electrical circuits)
        :param phase:           In degrees: phase shift to the RIGHT.  EXAMPLE: 180 to flip the Sine curve
        :param zero_clip:       If True, any requested change causing a concentration dip below zero,
                                    will make the concentration zero;
                                    otherwise, an Exception will be raised
        :return:                None
        
nameargumentsreturns
inject_bell_curvechem_label, mean=0.5, sd=0.15, amplitude=1., bias=0None
        Add to the current concentrations of the specified chemical species a signal across all bins in the shape of a Bell curve.
        The default values provide bell shape centered in the middle of the system, and fairly spread out
        (but pretty close to zero at the endpoints)

        :param chem_label:      The name of the chemical species whose concentration we're modifying
        :param mean:            A value, generally between 0 and 1, indication the spatial position of the mean
                                    relative to the bin system;
                                    if less than 0 or greater than 1, only one tail of the curve will be seen
        :param sd:              Standard deviation, in units of the system length
        :param amplitude:       Amount by which to multiply the standard normal curve signal before adding it to current concentrations
        :param bias:            Positive amount to be added to all values (akin to "DC bias" in electrical circuits)
        :return:                None
        
nameargumentsreturns
assert_valid_binbin_address: intNone
        Raise an Exception if the given bin number isn't valid

        :param bin_address: An integer that ought to be between 0 and (self.n_bins-1), inclusive
        :return:            None
        

LOOKUP CONCENTRATIONS

nameargumentsreturns
chem_quantitychem_label=None, chem_index=None
        Return the total quantity, across all bins, of the given chemical

        :param chem_label:
        :param chem_index:
        :return:
        
nameargumentsreturns
lookup_specieschem_index=None, chem_label=None, copy=Falsenp.array
        Return the NumPy array of concentration values across the all bins (from left to right)
        for the single specified chemical species.
        NOTE: what is being returned NOT a copy, unless specifically requested

        :param chem_index:   The index order of the chemical species of interest
        :param chem_label:    (OPTIONAL) If provided, it over-rides the value for chem_index
        :param copy:            If True, an independent numpy array will be returned: a *copy* rather than a view
        :return:                A NumPy 1-D array of concentration values across the bins (from left to right);
                                    the size of the array is the number of bins
        
nameargumentsreturns
system_snapshot_arrchem_label=None, chem_index=Nonenp.ndarray
        Return a snapshot of all the concentrations of the given chemical species,
        across ALL BINS, as a 1D Numpy array.
        If a Pandas dataframe is desired, use system_snapshot()

        :param chem_label:  String with the label to identify the chemical of interest
        :param chem_index:  Integer to identify the chemical of interest.  Cannot specify both chem_label and chem_index
        :return:            A 1-D Numpy array of concentration values along bin coordinates
        
nameargumentsreturns
system_snapshotpd.DataFrame
        Return a snapshot of all the concentrations of all the species, across all bins
        as a Pandas dataframe

        :return:    A Pandas dataframe: each row is a bin,
                        and each column a chemical species
        
nameargumentsreturns
bin_concentrationbin_address: int, chem_index=None, species_label=Nonefloat
        Return the concentration at the requested bin of the specified chemical species

        :param bin_address:     The bin number
        :param chem_index:      The index order of the chemical species of interest
        :param species_label:   [OPTIONAL] If provided, it over-rides the value for chem_index
        :return:                A concentration value at the indicated bin, for the requested species
        
nameargumentsreturns
bin_snapshotbin_address: intdict
        Extract the concentrations of all the chemical species at the specified bin,
        as a dict whose keys are the names of the species
        EXAMPLE:  {'A': 10.0, 'B': 50.0}

        :param bin_address: An integer with the bin number
        :return:            A dict of concentration values; the keys are the names of the species
        
nameargumentsreturns
bin_snapshot_arraybin_address: intnp.array
        Extract the concentrations of all the chemical species at the specified bin,
        as a Numpy array in the index order of the species
        EXAMPLE: np.array([10., 50.)]

        :param bin_address: An integer with the bin number
        :return:            A Numpy array  of concentration values, in the index order of the species
        
nameargumentsreturns
show_system_snapshotpd.DataFrame
        Print a header, and return a dataframe

        :return:    A Pandas dataframe
        
nameargumentsreturns
selected_concentrationsbins=None, chem_labels=Nonedict
        Extract and return the concentration values of one or more (use None for all) chemicals,
        in one or more bins.
        The value is returned as a dictionary where the keys are bin addresses, and the values are dicts of
        concentration values for the various chemicals (identified by their labels)
            EXAMPLE:
                    {   5: {"A": 1.3, "B": 3.9},
                        8: {"A": 4.6, "B": 2.7}
                    }

            TODO: alternate returned structure - a Pandas dataframe such as
                    BIN ADDRESS      A       B
                        5           1.3     3.9
                        8           4.6     2.7

        :param bins:        Bin address (integer), or list of bin addresses. Use None to indicate all
        :param chem_labels: Chemical label, or list of labels. Use None to indicate all
        :return:            A dict indexed by bin address
        
nameargumentsreturns
describe_stateconcise=FalseUnion[pd.DataFrame, None]
        A simple printout of the state of the system, for now useful only for small systems.

        EXAMPLE (concise):
            SYSTEM STATE at Time t = 0:
            [[0. 0. 0. 0.]
             [0. 0. 0. 0.]]
            Membranes: [(1, 2)]

        EXAMPLE (not concise):
            SYSTEM STATE at Time t = 0:
            4 bins and 2 chemical species
            Membranes present:  [(12, 25)]
            

        :param concise: If True, only produce a minimalist printout with just the concentration values
        :return:        None, if concise=True; a Pandas dataframe otherwise
        

MEMBRANES

nameargumentsreturns
uses_membranesbool
        Return True if membranes are part of the system

        :return:    True if any membrane was created in the system; False otherwise
        
nameargumentsreturns
set_membranesmembranes: ListNone
        Define the position of all membranes in the system.

        IMPORTANT: any previously-set membrane information is lost.

        :param membranes:       List of pairs of bin coordinates.  Use an empty list to clear all membranes.
                                    All integer values must be between 0 and self.n_bins, both inclusive,
                                    and be sorted in increasing order order.
                                    Membrane positions are identified by the index of the bin to their RIGHT side.
                                    Membranes cannot intersect, nor touch!
                                    EXAMPLE: if the system contains bins 0 thru 30 (i.e 31 bins),
                                             then a possible list of membranes is  [ (0, 8) , (17, 31) ]
        :return:                None
        
nameargumentsreturns
set_permeabilitypermeability :dictNone

        :param permeability:    Dictionary mapping chemical labels
                                    to the membranes' permeability to them (in passive transport)
        :return:                None
        
nameargumentsreturns
change_permeabilitychem_label :str, permeability :floatNone

        :param chem_label:
        :param permeability:
        :return:            None
        
nameargumentsreturns
membranes_list[int]
        Return a flattened version of the membrane data structure

        :return: A (possibly empty) sorted list of integers
        
nameargumentsreturns
membrane_on_leftbin_address :intbool
        Return True if there's a membrane to the immediate left of the given bin (specified by its index)

        :param bin_address:
        :return:
        
nameargumentsreturns
membrane_on_rightbin_address :intbool
        Return True if there's a membrane to the immediate right of the given bin (specified by its index)

        :param bin_address:
        :return:
        

SPATIAL ELEMENTS

nameargumentsreturns
set_dimensionslengthNone
        Set the overall length of the system.
        Doing so, will permit to convert bin numbers to positional values

        :param length:
        :return:
        
nameargumentsreturns
x_coordbin_address
        Return the x coordinate of the middle of the specified bin.
        By convention, for the leftmost bin, it's zero,
        and for the rightmost, it's the overall length of the system
        
nameargumentsreturns
increase_spatial_resolutionfactor:intNone
        Increase the spatial resolution of the system by cloning and repeating
        each bin, by the specified number of times.
        Replace the System's internal state
        (note that the number of bins will increase by the requested factor)

        EXAMPLE: if the (2-chemicals) system is
                        [[11. 12. 13.]
                         [ 5. 15. 25.]]
                and factor=2, then the result will be
                        [[11. 11. 12. 12. 13. 13.]
                         [ 5.  5. 15. 15. 25. 25.]]

        :param factor:  Number of bins into which to split each bin (replicating their concentration values)
        :return:        None
        
nameargumentsreturns
double_spatial_resolution_linearNone
        Increase the spatial resolution of the system by inserting between bins
        their average value (of concentrations, for every chemical species.)
        Replace the System's internal state
        (note that if the number of bins is initially N, it'll become 2N-1).
        If the system has fewer than 2 bins, an Exception will be raised.

        EXAMPLE: if the (2-chemicals) system is
                        [[11. 12. 13.]
                         [ 5. 15. 25.]]
                then the result will be
                        [[11.  11.5 12.  12.5 13. ]
                         [ 5.  10.  15.  20.  25. ]]

        :return:    None
        
nameargumentsreturns
decrease_spatial_resolutionfactor:intNone

        TODO: eliminate the restriction that the number of bins must be a multiple of the given factor

        EXAMPLE: if the system is
                        [[10., 20., 30., 40., 50., 60.]
                         [ 2., 8.,   5., 15., 4.,   2.]]
                and factor=2, then the result will be
                        [[15., 35., 55.]
                         [ 5., 10.,  3.]]

        :param factor:
        :return:
        
nameargumentsreturns
smooth_spatial_resolutionNone
        EXAMPLE: if the system is
                        [[10., 20., 30.]
                         [ 2., 8.,   4.]]
                then the result will be
                        [[10., 15., 20., 25., 30.]
                         [ 2.,  5.,  8.,  6.,  4.]]

        :return:
        

UTILITIES

nameargumentsreturns
check_mass_conservationexpected :float, chem_label=None, chem_index=Nonebool
        Check whether the sum of all the concentrations of the specified chemical,
        across all bins, adds up to the passed value

        :param expected:    Value that the sum of all the bin concentrations of the specified chemical should add up to
        :param chem_label:  String with the label to identify the chemical of interest
        :param chem_index:  Integer to identify the chemical of interest.
                                Cannot specify both `chem_label` and `chem_index`

        :return:
        
nameargumentsreturns
reaction_in_equilibriumbin_address: int, rxn_index :int, tolerance=1, explain=Truebool
        Ascertain whether the given system concentrations are in equilibrium at the given bin,
        for the specified reactions (by default, check all reactions)

        :param bin_address: The zero-based bin number of the desired compartment
        :param rxn_index:   The integer index (0-based) to identify the reaction of interest;
                                if None, then check all the reactions
        :param tolerance:   Allowable relative tolerance, as a PERCENTAGE,
                                to establish satisfactory match with expected values
        :param explain:     If True, print out details about the analysis,
                                incl. the formula(s) being used to check the equilibrium
                                EXAMPLES:   "([C][D]) / ([A][B])"
                                            "[B] / [A]^2"

        :return:            Return True if ALL the reactions are close enough to an equilibrium,
                                as allowed by the requested tolerance;
                                otherwise, return a dict of the form {False: [list of reaction indexes]}
                                for all the reactions that failed the criterion
                                EXAMPLE:  {False: [3, 6]}
        

HISTORY

nameargumentsreturns
enable_historybins=None, frequency=1, chem_labels=None, take_snapshot=False, caption=NoneNone
        Request history capture, with the specified parameters.
        If history was already enabled, this function can be used to alter its capture parameters.

        :param bins:            Bin address (integer), or list of bin addresses. Use None to indicate all
        :param frequency:       [OPTIONAL] How many simulation cycles to wait until taking another data snapshot
        :param chem_labels:     [OPTIONAL] List of chemicals to include in the history;
                                    if None (default), include them all.
        :param take_snapshot:   If True, a snapshot of the system's current configuration
                                    is immediately added to the history
        :param caption:         [OPTIONAL] String to save alongside this snapshot, if taken (only applicable
                                    if `take_snapshot` is True

        :return:                None
        
nameargumentsreturns
capture_snapshotstep_count=None, caption=""None
        Preserve some data values (based on specs given at the time history was enabled),
        linked to the current System Time.

        :param step_count:
        :param caption:     [OPTIONAL] String to save alongside this snapshot
        :return:            None
        
nameargumentsreturns
get_bin_historybin_address :int, include_captions=Truepd.DataFrame
        Get the concentration history at the given bin(s) of all the chemicals
        whose history was requested by a call of enable_history()

        :param bin_address:         A single bin address (an integer)
        :param include_captions:    If True, the captions are returned as an extra "caption" column at the end
        :return:                    A Pandas data frame
        
nameargumentsreturns
add_snapshotdata_snapshot: dict, caption =""None
        TODO: OBSOLETE.  Being phased out in favor of capture_snapshot()
        Preserve some data value (passed as dictionary) in the history, linked to the
        current System Time.

        EXAMPLE:  add_snapshot(data_snapshot = {"concentration_A": 12.5, "concentration_B": 3.7},
                                caption="Just prior to infusion")

        IMPORTANT: if the data is not immutable, then it ought to be cloned first,
                   to preserve it from possible later modifications

        :param data_snapshot:   A dictionary of data to preserve for later use
        :param caption:         Optional caption to attach to this preserved data
        :return:                None
        
nameargumentsreturns
get_historypd.DataFrame
        TODO: being phased out
        Retrieve and return a Pandas dataframe with the system history that had been saved
        using add_snapshot()

        :return:        a Pandas dataframe
        

SIMULATIONS

nameargumentsreturns
diffusetotal_duration=None, time_step=None, n_steps=None, delta_x=1, algorithm=Nonedict
        Uniform-step diffusion, with 2 out of 3 criteria specified:
            1) until reaching, or just exceeding, the desired time duration
            2) using the given time step
            3) carrying out the specified number of steps

        :param total_duration:  The overall time advance (i.e. time_step * n_steps)
        :param time_step:       The size of each time step
        :param n_steps:         The desired number of steps
        :param delta_x:         Distance between consecutive bins
        :param algorithm:          (Optional) code specifying the method to use to solve the diffusion equation.
                                    Currently available options: "5_1_explicit"

        :return:                A dictionary with data about the status of the operation
                                    "steps":        the number of steps that were run
                                    "system time":  the system time at the end of the operation
        
nameargumentsreturns
diffuse_steptime_step :float, delta_x=1, algorithm=NoneNone
        Diffuse all the chemical species for the given time step, across all bins;
        clear the self.delta_diffusion array, and then re-compute it from all the species.

        IMPORTANT: the actual system concentrations are NOT changed.

        :param time_step:   Time step over which to carry out the diffusion
                            If too large - as determined by the method is_excessive() - an Exception will be raised
        :param delta_x:     Spatial distance between consecutive bins
        :param algorithm:   [OPTIONAL] String indicating the desired method to use to solve the diffusion equation.
                                Currently available option: "5_1_explicit";
                                if not specified, thr default method diffuse_step_single_species() is used
        :return:            None (the array in the class variable "delta_diffusion" gets set)
        
nameargumentsreturns
is_excessivetime_step, diff_rate, delta_xbool
        Use a loose heuristic to determine if the requested time step is too long,
        given the diffusion rate and delta_x.
        This is also based on the "Von Neumann stability analysis"
        (an explanation can be found at: https://www.youtube.com/watch?v=QUiUGNwNNmo)

        :param time_step:
        :param diff_rate:
        :param delta_x:
        :return:
        
nameargumentsreturns
max_time_stepdiff_rate, delta_xfloat
        Determine a reasonable upper bound on the time step, for the given diffusion rate and delta_x
        This is also based on the "Von Neumann stability analysis"
        (an explanation can be found at: https://www.youtube.com/watch?v=QUiUGNwNNmo)

        :param diff_rate:   The diffusion rate of the chemical under consideration
        :param delta_x:     The spatial dimension of the bin
        :return:            A reasonably safe max length for a single time step of the simulation,
                                to try to steer clear of instabilities
        
nameargumentsreturns
reacttotal_duration=None, time_step=None, n_steps=None, snapshots=None, silent=FalseNone
        Update the system concentrations as a result of all the reactions in all bins - taking
        the presence of membranes into account, if applicable.

        CAUTION : NO diffusion is performed. Use this function
                  only if you intend to do reactions without diffusion!

        The duration and granularity of the reactions is specified with 2 out of the 3 parameters:
            total_duration, time_step, n_steps

        For each bin, or each membrane-separated side of bin, (or combined group of bins - not currently implemented),
        process all the reactions in it - based on
        the INITIAL concentrations (prior to this reaction step),
        which are used as the basis for all the reactions.

        Optionally, save some data from the individual reaction steps

        TODO: in case of any Exception, the state of the system is still valid, as of the time before this call

        :param total_duration:  The overall time advance (i.e. time_step * n_steps)
        :param time_step:       The size of each time step
        :param n_steps:         The desired number of steps

        :param snapshots:       OBSOLETE!
                                OPTIONAL dict that may contain any the following keys:
                                        -"frequency"
                                        -"sample_bin" (Required integer; if not present, no snapshots are taken)
                                        -"species" (NOT YET IMPLEMENTED)
                                        -"initial_caption" (default blank. NOT YET IMPLEMENTED)
                                        -"final_caption" (default blank. NOT YET IMPLEMENTED)
                                    If provided, take a system snapshot after running a multiple
                                    of "frequency" run steps (default 1, i.e. at every step.)
                                    EXAMPLE: snapshots={"frequency": 2, "sample_bin": 0}

        :param silent:
        :return:                None
        
nameargumentsreturns
reaction_stepdelta_time: floatNone
        Compute and store the incremental concentration changes in all bins,
        from all reactions,
        for a single time step of duration delta_time.

        The incremental concentration changes are stored in the class variable
        "delta_reactions", which contains a Numpy array that gets cleared and set.

        IMPORTANT: the actual system concentrations are NOT changed.

        For each bin, process all the reactions in it - based on
        the INITIAL concentrations (prior to this reaction step),
        which are used as the basis for all the reactions.

        TODO: parallelize the computation over the separate bins
        TODO: explore looping over reactions first, and then over bins

        :param delta_time:  The time duration of the reaction step - assumed to be small enough that the
                            concentration won't vary significantly during this span
        :return:            None (note: the class variable "delta_reactions" gets updated)
        
nameargumentsreturns
react_diffusetotal_duration=None, time_step=None, n_steps=None, delta_x = 1None
        It expects 2 out of the following 3 arguments:  total_duration, time_step, n_steps
        Perform a series of reaction and diffusion constant time steps.

        :param total_duration:  The overall time advance (i.e. time_step * n_steps)
        :param time_step:       The size of each constant time step
        :param n_steps:         The desired number of constant steps
        :param delta_x:         Distance between consecutive bins
        :return:                None
        

VISUALIZATION

nameargumentsreturns
visualize_systemtitle_prefix=None, colors=None, show=Falsepgo.Figure
        Visualize the current state of the system of all the chemicals as a combined line plot,
        using plotly.
        The x-axis is the bin coordinate, and the y-axis are the concentrations of each of the chemicals.

        :param title_prefix:[OPTIONAL] A string to prefix to the auto-generated title
        :param colors:      [OPTIONAL] If None, then use the registered colors (if specified),
                                or the hardwired defaults as a last resort
        :param show:        [OPTIONAL] If True, the plot will be shown
                                Note: on JupyterLab, simply returning a plot object (without assigning it to a variable)
                                      leads to it being automatically shown

        :return:            A Plotly "Figure" object
        
nameargumentsreturns
system_heatmapschem_labels=None, colors=None, title_prefix ="", **kwargspgo.Figure

        :param chem_labels: [OPTIONAL] NOT YET USED.  For now, ALL chemicals get shown
        :param colors:      [OPTIONAL] If None, then use the registered colors (if specified),
                                or the hardwired defaults as a last resort
                                (but only if more than 1 chemical; if only 1, go monochromatic)
        :param title_prefix:[OPTIONAL] A string to prefix to the auto-generated title
        :param kwargs:      [OPTIONAL] Other named arguments to pass to PlotlyHelper.heatmap_stack_1D()
                                For list, see documentation of method PlotlyHelper.heatmap_stack_1D

        :return:            A Plotly "Figure" object containing a stack of Heatmaps
        
nameargumentsreturns
single_species_heatmapspecies_index: int, heatmap_pars: dict, graphic_component, header=NoneNone
        DEPRECATED!

        Send to the HTML log, a heatmap representation of the concentrations of
        the single requested species.  Note: if using in Jupyterlab, this image will NOT be displayed there

        IMPORTANT: must first call GraphicLog.config(), or an Exception will be raised

        :param species_index:       Index identifying the species of interest
        :param heatmap_pars:        A dictionary of parameters for the heatmap
        :param graphic_component:   A string with the name of the graphic module to use.  EXAMPLE: "vue_heatmap_11"
        :param header:              Optional string to display just above the heatmap
        :return:                    None
        
nameargumentsreturns
single_species_line_plotspecies_index: int, plot_pars: dict, graphic_component, header=NoneNone
        DEPRECATED

        Send to the HTML log, a line plot representation of the concentrations of
        the single requested species.  To plot more than 1 species, use line_plot() instead

        IMPORTANT: must first call GraphicLog.config(), or an Exception will be raised

        :param species_index:       Index identifying the species of interest
        :param plot_pars:           A dictionary of parameters for the plot
        :param graphic_component:   A string with the name of the graphic module to use.  EXAMPLE: "vue_curves_3"
        :param header:              Optional string to display just above the plot
        :return:                    None
        
nameargumentsreturns
line_plotplot_pars: dict, graphic_component, header=None, color_mapping=NoneNone
        Send to the HTML log, a line plot representation of the concentrations of
        all the chemical species species.

        IMPORTANT: must first call GraphicLog.config(), or an Exception will be raised

        :param plot_pars:           A dictionary of parameters (such as "outer_width") for the plot
        :param graphic_component:   A string with the name of the graphic module to use.  EXAMPLE: "vue_curves_4"
        :param header:              [OPTIONAL] String to display just above the plot
        :param color_mapping:       [OPTIONAL] Dict mapping index numbers to color names or RBG hex values.
                                        If not provided, the colors associated to the chemicals are used, if any
        :return:                    None
        
nameargumentsreturns
plot_history_single_binbin_address :int, colors=None, title_prefix=None, title=None, smoothed=False, vertical_lines_to_add=Nonepgo.Figure
        Using plotly, draw the plots of chemical concentration values over time at the specified bin,
        based on the historical data that was saved when running simulations.

        Note: if this plot is to be later combined with others, use PlotlyHelper.combine_plots()

        :param bin_address: A single bin address (an integer)
        :param colors:      [OPTIONAL] List of CSS color names for each of the heatmaps.
                                If provided, its length must match that of the data;
                                if None, then use the registered colors (if specified),
                                or the hardwired defaults as a last resort
        :param title_prefix:[OPTIONAL] Prefix to the default auto-generated title
        :param title:       [OPTIONAL] If set, it over-rides `title_prefix.  If not passed, a default one is used
        :param smoothed:    [OPTIONAL] If True, a spline is used to smooth the lines;
                                otherwise (default), line segments are used
        :param vertical_lines_to_add: [OPTIONAL] List or tuple or Numpy array or Pandas series
                                    of x-coordinates at which to draw thin vertical dotted gray lines.
                                    If the number of vertical lines is so large as to overwhelm the plot,
                                    only a sample of them is shown.
                                    Note that vertical lines, if requested, go into the plot's "layout";
                                    as a result they might not appear if this plot is later combined with another one.

        :return:            A plotly "Figure" object; an Exception is raised if no historical data is found
        
nameargumentsreturns
frequency_analysischem_label: str, threshold = 0.001, n_largest = Nonepd.DataFrame
        Return the individual frequencies, and their relative amplitudes,
        in the concentration values of the specified chemical species.
        A Discrete Fourier Transform is used for the computation.

        :param chem_label:  The name of the chemical whose concentration we want to analyze
        :param threshold:   Minimum amplitudes of the frequency components to be considered non-zero
                                (NOTE: these are the raw values returned by the DFT - not the normalized ones.)
        :param n_largest:   If specified, only the rows with the given number of largest amplitudes gets returned
                                (if there are fewer rows to start with, they all get returned)

        :return:            A Pandas dataframe with 2 columns, "Frequency" and "Relative Amplitude";
                                amplitudes are relative the the smallest nonzero frequency (which is taken to be 1.0)
                                EXAMPLE:
                                               Frequency  Relative Amplitude
                                            0        0.0                 3.0
                                            1        2.0                 1.0
                                            2        4.0                 0.5
                                            3        8.0                 0.2