Documentation #

BurstSort #

The core of burstH2MM, this module provides the base classes for performing and analyzing H2MM results of burst data provided by FRETBursts

class burstH2MM.BurstSort.BurstData(data, ph_streams=None, Aex_stream=None, Aex_shift=None, irf_thresh=None, conserve_memory=False)#

Class to organize a photon selection, functions to manage H2MM_list objects with different divisor schemes of a data set.

Parameters:

data (frb.Data) – The Data object from which to create the BurstData, will use the burst selection to generate times, indexes and nanotimes arrays for H2MM optimization.
ph_streams (list[frb.Ph_sel], optional) – Which Ph_sel streams to use to create the indices. If None, use the defaults of [DexDem, DexAem, AexAem] for ALEX data, and [DexDem, DexAem] for single laser excitation. The default is None
Aex_stream (frb.Ph_sel or list[frb.Ph_sel], optional) – For usALEX only. Which stream(s) to shift for usALEX data. If None, ignored for nsALEX data and AexAem for usALEX data. The default is None
Aex_shift (bool, str or None, optional) –
The method to shift Aex photons. Options are ‘shift’, ‘rand’ and ‘even’.
- ’shift’ merely shifts all Aex photons by the difference between the beginnings of the Donor and Acceptor excitation periods.
- ’rand’ randomly distributes Aex photons into the adjacent donor excitation period.
- ’even’ evenly distributes photons from adjacent acceptor excitation periods into the donor excitation period
The default is None
irf_thresh (list[int] or None, optional) – Nanotime bin for the threshold of the IRF. If None, can be set after object creation. The default is None
conserve_memory (bool, optional) – Not active at present. Will be used to indicate whether or not to automatically trim arrays after use to conserve memory usage. The default is False

property Aex_shift#: Boolean for whether acceptor excitation photons shifted into donor excitation window

property Aex_stream#: Which stream(s) used as acceptor excitation

auto_div(ndivs, name=None, include_irf_thresh=False)#

Create a new divisor scheme with the given number of divisors per stream

Parameters:

ndivs (int or array like) –
The number of divisors in each stream if an int, or per stream if list of numpy arrays. If an int :

Each stream will be divided by that many divisors, such that there is an equal probability of a photon arriving in each divisor for the entire data set.

If a array like:

The number of divisors per stream
name (str, optional) – The name of the key identifying the divisor scheme. If none specified, a name will be assigned automatically, as div{n} where n is an integer. The default is None.
include_irf_thresh (bool, optional) – Whether or not to include the IRF threshold as a separate divisor. The default is False.

Returns:

name – The key of the new divisor scheme.

Return type:

str

property data#: The Data object used to create the data

div_models#: dictiary of H2MM_list objects for each divisor

property irf_thresh#: The theshholds to exclude the IRF per stream

models#: The primary H2MM_list object, with no divisor scheme.

nanos#: list of burst photon nanotimes

new_div(divs, name=None, collapse=False, fix_divs=True)#

Set up a new set of divisors pusled laser excitation only

Parameters:

divs (list[numpy.ndarray]) – List of divisors, use 1 array per photon stream. Divisors must be in ascending order and within the excitation window of their given photon stream.
name (str, optional) – The name of the key identifying the divisor scheme. If none specified, a name will be assigned automatically, as div{n} where n is an integer. The default is None.
collapse (bool, optional) –
Whether to automatically remove unused indeces, if false, raises an error if there are missing indeces.

Note

if fix_divs is False, this check will not be performed.

The default is False.
fix_divs (bool, optional) – Whether to check for unused indeces. The default is True.

Returns:

name – The key of the new divisor scheme

Return type:

str

property nstream#: Number of photon streams in the bursts

property parent#: Returns self, so that [H2MM_list].parent.parent will return BurstData instead of error

particles#: list of burst photon particle ids if particles exist in source data

property ph_streams#: The photon streams used in analysis

times#: list of burst photon times

class burstH2MM.BurstSort.H2MM_list(parent, index, divisor_scheme=None, conserve_memory=False)#

Class for organizing optimized models under a divisor scheme.

Note

These objects are rarely created by the user, rather, they are created by BurstData upon initiation (stored in the BurstData.models attribute) or by BurstData.new_div() or BurstData.auto_div() for making the new divisor schemes.

Parameters:

parent (BurstData) – The creating BurstData object
index (list(numpy.ndarray)) – The photon indices, same shape as the BurstData.times list
divisor_scheme (list(np.ndarray), optional) – The position of divisors per stream. The default is None
conserve_memory (bool, optional) – Whether or not to clear dynamically calculated arrays

property BIC#: The BIC of the models, returns inf for non-existent models

property BICp#: The BIC’ of the models, returns inf for non-existent models

property E#: The FRET efficiency of each state in the ideal model

property E_corr#: The gamma corrected FRET efficiency of each state in the ideal model

property ICL#: The ICL of the models, returns inf for non-existent models

property S#: The stoichiometry of each state in the ideal model

property S_corr#: The gamma/beta corrected stoichiometry of each state in the ideal model

property burst_dwell_num#: Number of dwells in each burst for the ideal model

calc_models(min_state=1, to_state=4, max_state=8, models=None, conv_crit='ICL', thresh=None, **kwargs)#

Optimize h2mm models against data for increasing numbers of states until either maximum number reached, or convergence criterion met.

Parameters:

min_state (int, optional) – Number of states in model that is first optimized. The default is 1.
to_state (int, optional) – The minimum number of states in the model with the most states in the models optimized. Ensures even if convergence criterion already met that this state model will exist. The default is 4.
max_state (int, optional) – Maximum number of states in model that will be optimized, whether or not the convergence criterion have been met- sets upper bound on duration of while loop. The default is 8.
models (list[H2MM_C.h2mm_model], optional) – List of initial models to use. If models for given number of states do not exist in this list, the factory_h2mm_function will be used. The default is None.
conv_crit (str, optional) – Which of the build-in convergence criterion to use to evaluate if the ideal state model has been found. The default is ‘ICL’.
thresh (float, optional) – The threshold difference between statistical discriminators to determine if the convergence criterion have been met. The default is None.
**kwargs (dict) – Keyword arguments passed to optimization function, controls num_cores etc.

Returns:

ideal – The index of the ideal model based on the threshold

Return type:

int

conserve_memory#: whether or not to trim data of non-ideal H2MM_result

property div_map#: The indicies in the model where indices change stream

property divisor_scheme#: The divisor scheme used to make the current H2MM_list

property dwell_E#: The raw FRET efficiency of each dwell

property dwell_E_corr#: The FRET efficiency of each dwell, with corrections for background, leakage, direct excitation, and gamma applied, for the ideal model

property dwell_S#: The raw stoichiometry of each dwell, for the ideal model

property dwell_S_corr#: The stoichiometry of each dwell, with corrections for background, leakage, direct excitation, and gamma and beta applied, for the ideal model

property dwell_dur#: The duration of each dwell, in seconds, for the ideal model

property dwell_nano_mean#: Mean nanotime of each stream and dwell, organized [stream, dwell], for the ideal model

property dwell_params#: List of attributes that define dwells

property dwell_ph_counts#: The number of photons in a dwell, per stream, organized [stream, dwell], for the ideal model

property dwell_ph_counts_bg#: The background corrected number of photons in a dwell, per stream, organized [stream, dwell], for the ideal model

property dwell_pos#: The position within a burst of each dwell for the ideal model: 0: middle dwells 1: ending dwells 2: beginning dwells 3: whole burst dwells

property dwell_state#: State of each dewll for the ideal model

find_ideal(conv_crit, thresh=None, auto_set=False)#

Identify the ideal state model

Parameters:

conv_crit (str) – Which convergence criterion to use.
thresh (float, optional) – The threshold difference between statistical discriminators to determine if the convergence criterion have been met. The default is None.
auto_set (bool, optional) – Whether to set the ideal

Returns:

ideal – Index of ideal state model. Note: i+1 is the number of states (because python indexes from 0)

Return type:

int

free_data(save_ideal=True)#

Clear large data arrays from models

Parameters:: save_ideal (bool, optional) – Whether or not to keep the large data arrays for the ideal state model. The default is True.
Return type:: None.

index#: list of burst photon indeces, specific to divisor schem

property nanohist#: Histogram of nanotimes, sorted by state, organized [state, stream, nanotime], for the ideal model

property ndet#: Number of photon streams in the divisor scheme

property num_opt#: Number of optimizations conducted

optimize(model, replace=False, gamma=False, opt_array=False, **kwargs)#

Optimize a model against data, and add optimized data to .opts list

Parameters:

model (H2MM_C.h2mm_model) – Initial model to be optimized.
replace (bool, optional) – If an identical state model has been optimized, whether to replace with newly optimized model. If false, raises error indicating model already exists. The default is False.
**kwargs (dict) – Keyword arguments passed to optimization function, controls num_cores etc.

Raises:

Exception – Optimized model of given number of states already exists.

Return type:

None.

opts#: list storing H2MM_result objects, len is always maximum number of states, filled with None for state models not calculated

property path_BIC#: The Bayes Information Criterion of the most likely path

stat_disc_labels = {'BIC': 'BIC', 'BICp': "BIC'", 'ICL': 'ICL', 'path_BIC': 'path BIC'}#: dictionary of statistical discriminators as keys and labels for matplotlib axis as values

property state_nano_mean#: Mean nanotime of states based on dwell_nano_mean, based on BurstSort.H2MM_result.nanohist

property state_nano_mean_err#: Weighted (by number of photons) standard deviation of mean nanotime of dwells by state

property state_nano_mean_std#: Weighted (by number of photons) standard deviation of mean nanotime of dwells by state

property trans#: The Transition rate matrix of the ideal model, rates in s:sup:-1

property trans_locs#: List of numpy arrays, identifying the beginning of each new dwell in a burst, for the ideal model

class burstH2MM.BurstSort.H2MM_result(parent, model, gamma=None, **kwargs)#

Class to represent the results of analysis with H2MM and Viterbi

Note

This class is rarely created directly be the user, rather usually created by H2MM_list running H2MM_list.optimize() or H2MM_list.calc_models() and stored in the H2MM_list.opts list attribute.

Parameters:

parent (H2MM_list) – The creating H2MM_list object
model (H2MM_C.h2mm_model) – The H2MM_C.h2mm_model that has been optimized
**kwargs (dict) – Options passed to H2MM_C.viterbi_path

property E#: The FRET efficiency of each state in the model

property E_corr#: The gamma corrected FRET efficiency of each state in the model

property E_err_bs#: Error in FRET efficiency values as calcualted by the bootstrap method. Only accesible after H2MM_result.bootstrap_eval() has been run.

property E_std_bs#: Standard deviation in FRET efficiency values as calcualted by the bootstrap method. Only accesible after H2MM_result.bootstrap_eval() has been run.

property S#: The stoichiometry of each state in the model

property S__correrr_bs#: Standard deviation in stoichiometry values as calcualted by the bootstrap method. Only accesible after H2MM_result.bootstrap_eval() has been run.

property S_corr#: The gamma/beta corrected stoichiometry of each state in the model

property S_corr_std_bs#: Standard deviation in stoichiometry values as calcualted by the bootstrap method. Only accesible after H2MM_result.bootstrap_eval() has been run.

property S_err_bs#: Standard deviation in stoichiometry values as calcualted by the bootstrap method. Only accesible after H2MM_result.bootstrap_eval() has been run.

property S_std_bs#: Standard deviation in stoichiometry values as calcualted by the bootstrap method. Only accesible after H2MM_result.bootstrap_eval() has been run.

property bic#: The Bayes Information Criterion of the model

bootstrap_err#: organizes bootstrap uncertainty

bootstrap_eval(subsets=10)#

Perform bootstrap error evaluation. Divide bursts in subsets number of subsets, and run H:sup:2MM on each subset. Then take the variance of each model parameter value as the error on that parameter value.

This creates the H2MM_result.bootstrap_err, which makes the H2MM_result.E_std_bs, H2MM_result.S_std_bs, and H2MM_result.trans_std_bs properties available.

Warning

This method can take a significant amount of time to run, as an optimization must be run on each subset. This can be particularly prohibitive for models with a large number of states.

Parameters:

subsets (int, optional) – Number of subsets to divide bursts into. The larger the number the longer the calculation, though perhaps the better the error quantification. The default is 10.

Returns:

trans (numpy.ndarray) – Variance in transition rates among the subsets.
E (numpy.ndarray) – Variance in E values among the subsets
S (numpy.ndarray) – Variance in S values amont the subsets, will not be returned for models without A:sub:exA:sub:em stream

property burst_dwell_num#: Number of dwells in each burst

property burst_state_counts#: Counts of number of dwells in each state per burst

property burst_type#: Binary code indicating which states present in a burst. Functions as binary mask

calc_dwell_nanomean(ph_streams, irf_thresh)#

Generate the mean nanotimes of dwells, for given stream and IRF threshold

Parameters:

ph_streams (fretbursts.Ph_sel, or list[fretbursts.Ph_sel]) – The photon stream(s) for which the mean dwell nanotime is to be calculated
irf_thresh (int or iterable of int) – The threshold at which to include photons for calculation of mean nanotime Should be set to be at the end of the IRF

Returns:

dwell_nanomean – Mean nanotime of the given photon stream(s) in aggregate NOTE: different photon streams are not separated in calculation, must be called separately per stream to calculate each mean nanotime

Return type:

numpy.ndarray

property conf_thresh#: Threshhold for considering a photon nantotime in calculating dwell_nano_mean and nanohist

property dwell_E#: The raw FRET efficiency of each dwell

property dwell_E_corr#: The FRET efficiency of each dwell, with corrections for background, leakage, direct excitation, and gamma applied

property dwell_S#: The raw stoichiometry of each dwell

property dwell_S_corr#: The stoichiometry of each dwell, with corrections for background, leakage, direct excitation, and gamma and beta applied

property dwell_dur#: The duration of each dwell, in miliseconds

property dwell_nano_mean#: Mean nanotime of each stream and dwell, organized [stream, dwell]

dwell_params = {'dwell_E': 'ratio', 'dwell_E_corr': 'ratio', 'dwell_S': 'ratio', 'dwell_S_corr': 'ratio', 'dwell_dur': 'ratio', 'dwell_nano_mean': 'stream', 'dwell_ph_counts': 'stream', 'dwell_ph_counts_bg': 'stream', 'dwell_pos': 'bar', 'dwell_state': 'bar'}#: dictionary of dwell parameters as keys, and values the type of plot to use in scatter/histogram plotting

property dwell_ph_counts#: The number of photons in a dwell, per stream, organized [stream, dwell]

property dwell_ph_counts_bg#: The background corrected number of photons in a dwell, per stream, organized [stream, dwell]

property dwell_pos#: The position within a burst of each dwell: 0: middle dwells 1: ending dwells 2: beginning dwells 3: whole burst dwells

property dwell_state#: The state of each dwell

property dwell_trans_durs#: Masks of location of transitions from one state to another. Diagonal values indicate dwells at the end or whole-burst dwells

get_dwell_trans_mask(locs, include_beg=True, include_end=False)#

Geneate a mask of which dwells belong to a given type of transition. This allows selection of dwells of a given state, that transition to another specific state.

Parameters:

locs (int, 2-tuple) –
Defnition of which transitions to include in the mask. Normally a 2-tuple of ints, specifying the state of the dwell, and the next state.

For examining dwells without a subsequent transition, (whole burst, and optionally dwells at the end of a burst) specify as an int, 1-tuple, or 2-tuple with both elements the same.
include_beg (bool, optional) – Whether or not to have transitions where the dwell is an initial dwell set to true in the mask. Only used dwell and next state are different. The default is True.
include_end (bool, optional) – When locs is int, 1-tuple, or both elements are the same, (ignored otherwise) whether or not to include dwells at the end of bursts or the correct state. The default is False.

Returns:

dwell_trans_mask – Mask of dwells meeting the specified transitions.

Return type:

numpy.ndarray[bool]

icl#: Integrated Complete Likelihood (ICL) for the model

property k#: Number of free parameters in H2MM model

large_params = ('_gamma', '_path', '_scale', '_trans_locs', '_burst_dwell_num', '_dwell_pos', '_dwell_state', '_dwell_dur', '_dwell_ph_counts', '_dwell_ph_counts_bg', '_dwell_E', '_dwell_S', '_dwell_E_corr', '_dwell_S_corr', '_dwell_nano_mean', '_dwell_ph_counts_bg', '_nanohist', '_burst_state_counts')#: tuple of parameters that include dwell or photon information- cleared by trim data

ll_arr#: loglikelihood of path of each burst

property loglik#: The logliklihood of the model, no penalties for number of states etc.

loglik_err#: organizes loglikelihood uncertainty for all model parameters

model#: The optimized H2MM_C.h2mm_model representing the data

property nanohist#: Histogram of nanotimes, sorted by state, organized [state, stream, nanotime]

nanotime_params = (ResetTuple(attr='nanohist', subattrs=('_nanohist',)), ResetTuple(attr='dwell_nano_mean', subattrs='_dwell_nano_mean'), ResetTuple(attr='state_nano_mean', subattrs='_state_nano_mean'), ResetTuple(attr='state_nano_mean_std', subattrs=('_state_nano_mean_std', '_state_nano_mean_err')))#: List of all parameters dependent on lifetime information

property ndet#: Number of photon streams in divisor scheme

property nphot#: Total number of photons in the burst data

property nstate#: Number of states in model

param_labels = {'E': 'E$_{raw}$', 'E_corr': 'E', 'S': 'S$_{raw}$', 'S_corr': 'S', 'dwell_E': 'E$_{raw}$', 'dwell_E_corr': 'E', 'dwell_S': 'S$_{raw}$', 'dwell_S_corr': 'S', 'dwell_dur': 'ms', 'dwell_nano_mean': 'ns', 'dwell_ph_counts': 'counts', 'dwell_ph_counts_bg': 'counts', 'dwell_pos': 'dwell position', 'dwell_state': 'state', 'trans': 'transition rate ($s^{-1}$)'}#: dictionary of parameters as keys and axis labels as values

property path#: most likely state of each photon in each burst

path_bic#: BIC of most likely path

pd_disp(ph_min=5, min_dwell_cnt=10)#

Redurn a pandas.io.formats.style.Styler frame, showing basic statistics of H2MM_model object, with conditional highlighting of transition rates based on Viterbi based statstics.

Parameters:

ph_min (int, optional) – DESCRIPTION. The default is 5.
min_dwell_cnt (int, optional) – DESCRIPTION. The default is 10.

Returns:

rpr_style – Display of model stats with color coded numbers.

Return type:

pandas.io.formats.style.Styler

property scale#: posterior probability of each photon in each burst

property state_nano_mean#: Mean nanotime of states based on dwell_nano_mean, based on BurstSort.H2MM_result.nanohist

property state_nano_mean_err#: Weighted (by number of photons) standard deviation of mean nanotime of dwells by state

property state_nano_mean_std#: Weighted (by number of photons) standard deviation of mean nanotime of dwells by state

state_params = {'E': 'single', 'E_corr': 'single', 'S': 'single', 'S_corr': 'single', 'state_nano_mean': 'stream'}#: dictionary of state parameters as keys, and values the type of plot to use in axline

stats_frame(ph_min=5, exclude_beg=False)#

Generate a pandas dataframe containting stats on the model.

Parameters:

ph_min (int, optional) – Minimum number of photons for a given dwell to be included in statistics of Viterbi based results. The default is 5.
exclude_beg (bool, optional) – Whether or not to exclude beginning dwells from Viterbi based statistics. The default is False.

Returns:

dataframe – Dataframe of model statistics.

Return type:

pandas.DataFrame

property trans#: The Transition rate matrix, rates in s^{-1}

property trans_err_high_ll#

The fast transition rate error based on the loglikelihood method of error quantification.

That is the faster transition rate at which the loglikelihood is 0.5 less than the optimal model, unless the threshold was manually set to another value.

property trans_err_low_ll#

The slow transition rate error based on the loglikelihood method of error quantification.

That is the slower transition rate at which the loglikelihood is 0.5 less than the optimal model, unless the threshold was manually set to another value.

property trans_locs#: List of numpy arrays, identifying the beginning of each new dwell in a burst

property trans_std_bs#: Error in transition rate values as calcualted by the bootstrap method. Only accesible after H2MM_result.bootstrap_eval() has been run.

trim_data()#: Remove photon-level arrays, conserves memory for less important models

burstH2MM.BurstSort.calc_dwell_nanomean(model, ph_streams, irf_thresh, conf_thresh=None, gamma_thresh=None)#

Calculate the mean nanotimes of dwells for a given (amalgamated) set of photon streams, must define the irf_thresh to exclude the IRF

Parameters:

model (H2MM_result) – A h2mm state-model and Viterbi analysis
ph_streams (fretbursts.Ph_sel or list[fretbursts.Ph_sel]) – Either a Ph_sel object of the stream desired, or a list of Ph_sel objects defining all streams to take the aggregate mean over (generally not recommended)
irf_thresh (int, or iterable of ints) – The threshold of the IRF, all photons with nanotime before this threshold excluded from analysis
conf_thresh (float, optional) – The threshold of the H2MM_result.scale for a photon to be included in the nanotime histogram. If None, use H2MM_result.conf_thresh of model. The default is None

Returns:

dwell_nanomean – Mean nanotime of each dwell for the given photon streams, and IRF threshold

Return type:

numpy.ndarray

burstH2MM.BurstSort.calc_nanohist(model, conf_thresh=None, gamma_thresh=None)#

Generate the fluorescence decay per state per stream from the model/data

Parameters:

model (H2MM_result) – A h2mm state-model and Viterbi analysis
conf_thresh (float, optional) – The threshold of the H2MM_result.scale for a photon to be included in the nanotime histogram. If None, use H2MM_result.conf_thresh of model. The default is None
gamma_thresh (float, optional) – The threshold of the H2MM_result.gamma for a photon to be included in the nanotime histogram. If None, use H2MM_result.gamma_thresh of model. The default is None

Returns:

nanohist – A 3-D numpy array, containing fluorescence decays per state per stream array indexed as follows: [state, stream, nanotime_bin]

Return type:

numpy.ndarray

burstH2MM.BurstSort.find_ideal(model_list, conv_crit, thresh=None)#

Identify the ideal state model

Parameters:

model_list (H2MM_list) – The set of optimizations for which the ideal models is to be determined
conv_crit (str) – Which convergence criterion to use.
thresh (float, optional) – The threshold difference between statistical discriminators to determine if the convergence criterion have been met. The default is None.

Returns:

ideal – Index of ideal state model. Note: i+1 is the number of states (because python indexes from 0)

Return type:

int

burstH2MM.BurstSort.make_divisors(data, ndiv, include_irf_thresh=False)#

Automatically make a set of divisors evenly dividing the nanotime by ndiv divisors

Parameters:

data (BurstData) – Data object of bursts with defined streams
ndiv (int or numpy array) – Either an int splitting all photon streams by ndiv divisors, or a numpy array where each element defines the number of divisors for each stream
include_irf_thresh (bool, optional) – Whether or not to add the irf_threshold of the stream as an additional divisor. The default is False.

Raises:

ValueError – When incorrect number of streams specified for the BurstData object.

Returns:

divs – The new set of divisors.

Return type:

list[numpy.ndarray]

burstH2MM.BurstSort.trans_stats(model, ph_min=0)#

Generate statistics about transitions and dwells.

Parameters:

model (H2MM_model) –
H2MM_model object to calculate Viterbi transition statistics. Calculates the number of times specific transitions occur, and mean dwell times for said transitions.

Note

Values on diagonals are modified to report useful statistics, instead of self transition values. For counts the diagonal represents the number of whole-burst dwells (bursts with only one state), and for the mean dwell duration, diagonal values are the mean of all dwells in the state, no matter the following dwell.
ph_min (int, optional) – Minimum number of photons to include a dwell in statistical analysis. The default is 0.

Returns:

trans_cnts (numpy.ndarray) – Number of times a specific transition [from state, to state]. Values on the diagonal indicate the number of bursts entirely in the given state.
trans (numpy.ndarray) – Mean duration (in milliseconds) of dwells in a given state that transition to each state [dwell state, next state]. Diagonal values are the mean of all dwells in that state.

Plotting #

This section provides all the plotting functions for burstH2MM. Most functions take a H2MM_result object as input, and customization is provided through various keyword arguments.

burstH2MM.Plotting.BIC_plot(model_list, highlight_ideal=False, ideal_kwargs=None, ax=None, **kwargs)#

Plot the Bayes Information Criterion of each state model.

Parameters:

model (H2MM_list) – The set of optimizations to be compared, a H2MM_list object (a divisor scheme).
highlight_ideal (bool, optional) – Whether or not to plot the ideal/selected model separately. The default is False.
ideal_kwargs (dict or None, optional) – The kwargs to be passed specifically to the ideal model point. The default is None.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – kwargs to be passed to ax.scatter

Returns:

collections – list of collections produced by the scatter plot

Return type:

list[matplotlib.collections.PathCollection]

burstH2MM.Plotting.BICp_plot(model_list, highlight_ideal=False, ideal_kwargs=None, ax=None, **kwargs)#

Plot the modified Bayes Information Criterion of each state model.

Parameters:

model (H2MM_list) – The set of optimizations to be compared, a H2MM_list object (a divisor scheme).
highlight_ideal (bool, optional) – Whether or not to plot the ideal/selected model separately. The default is False.
ideal_kwargs (dict or None, optional) – The kwargs to be passed specifically to the ideal model point. The default is None.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – kwargs to be passed to ax.scatter

Returns:

collections – list of collections produced by the scatter plot

Return type:

list[matplotlib.collections.PathCollection]

burstH2MM.Plotting.ICL_plot(model_list, highlight_ideal=False, ideal_kwargs=None, ax=None, **kwargs)#

Plot the ICL of each state model.

Parameters:

model (H2MM_list) – The set of optimizations to be compared, a H2MM_list object (a divisor scheme).
highlight_ideal (bool, optional) – Whether or not to plot the ideal/selected model separately. The default is False.
ideal_kwargs (dict or None, optional) – The kwargs to be passed specifically to the ideal model point. The default is None.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – kwargs to be passed to ax.scatter

Returns:

collections – list of collections produced by the scatter plot

Return type:

list[matplotlib.collections.PathCollection]

burstH2MM.Plotting.axline_E(model, ax=None, add_corrections=False, horizontal=False, states=None, state_kwargs=None, **kwargs)#

Add bars to plot indicating the FRET efficiency of states

Note

If the ax kwarg is used, it is assumed to be used in conjunction with other plots, and thus the xlim and ylim values will not be set

Parameters:

model (H2MM_result) – Model to plot values of E
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw scatterplot in. The default is None.
add_corrections (bool, optional) – Use the corrected (True) or raw (False) E values. The default is False.
horizontal (bool, optional) – Whether to plot the bars horizontally (True) or vertically (False) The default is False.
states (array-like, optional) – Which states to plot, identified as array of states, boolean mask or int. The default is None
state_kwargs (list[dict], optional) – Keyword arguments per state passed to ax.axvline/ax.axhline. The default is None.
**kwargs (dict) – passed to ax.axvline/ax.axhline as kwargs

Returns:

lines – List of Lines returned by ax.axvline/ax.axhline

Return type:

list[matplotlib.lines.Line2D]

burstH2MM.Plotting.axline_S(model, ax=None, add_corrections=False, horizontal=False, states=None, state_kwargs=None, **kwargs)#

Add bars to plot indicating the Stoichiometry of states

Note

If the ax kwarg is used, it is assumed to be used in conjunction with other plots, and thus the xlim and ylim values will not be set

Parameters:

model (H2MM_result, H2MM_list, BurstData) – Model to plot values of S
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw scatterplot in. The default is None.
add_corrections (bool, optional) – Use the corrected (True) or raw (False) S values. The default is False.
horizontal (bool, optional) – Whether to plot the bars horizontally (True) or vertically (False) The default is False.
states (array-like, optional) – Which states to plot, identified as array of states, boolean mask or int. The default is None
state_kwargs (list[dict], optional) – Keyword arguments per state passed to ax.axvline/ax.axhline. The default is None.
**kwargs (dict) – passed to ax.axvline/ax.axhline as kwargs

Returns:

lines – List of Lines returned by ax.axvline

Return type:

list[matplotlib.lines.Line2D]

burstH2MM.Plotting.axline_divs(model_list, horizontal=False, stream_kwargs=None, ax=None, **kwargs)#

Plot lines indicating the positions of divisors for the given H2MM_list with a divisor scheme

Parameters:

model_list (H2MM_list) – The H2MM_list for which to show positions of the divisors
horizontal (bool, optional) – Plot the lines vertically (False) or horizontally (True). The default is False.
stream_kwargs (list[dict], optional) – List of keyword arguments to pass the axvline or axhline per stream. The default is None.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – Keyword arguments to pass to axvline or axhline.

Raises:

ValueError – Incorrect format for stream_kwargs, most likely due to length.

Returns:

lines – List of lists of Lines returned by ax.axvline

Return type:

list[list[matplotlib.lines.Line2D]]

burstH2MM.Plotting.axline_irf_thresh(data, horizontal=False, stream_kwargs=None, raw_bin=True, ax=None, **kwargs)#

Plot lines indicating the positions of the IRF thresholds

Parameters:

data (BurstData) – The BurstData for which to show the IRF thresholds.
horizontal (bool, optional) – Plot the lines vertiaclly (False) or horizontally (True). The default is False.
stream_kwargs (list[dict], optional) – List of keyword arguments to pass the axvline or axhline per stream. The default is None.
raw_bin (bool, optional) – Whether to plot the raw nanotime bin (True, default) or convert into units of ns (False). The default is True.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – Keyword arguments to pass to axvline or axhline.

Raises:

ValueError – Incorrect format for stream_kwargs, most likely due to length.

Returns:

lines – List of Lines returned by ax.axvline

Return type:

list[matplotlib.lines.Line2D]

burstH2MM.Plotting.axline_nano_mean(model, ax=None, horizontal=False, states=None, state_kwargs=None, streams=[<Mock name='mock.Ph_sel()' id='139962736809008'>], stream_kwargs=None, kwarg_arr=None, **kwargs)#

Draw lines across the axis for the mean nanotime of each state.

Parameters:

model (H2MM_result, H2MM_list, BurstData) – Model for which to plot the mean nanotimes of states.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw axes lines in. The default is None.
horizontal (bool, optional) – Whether to plot the bars horizontally (True) or vertically (False) The default is False.
states (array-like, optional) – Which states to plot, identified as array of states, boolean mask or int. The default is None
state_kwargs (list[dict], optional) – Keyword arguments per state passed to ax.axvline/ax.axhline. The default is None.
streams (list[fretbursts.Ph_sel], optional) – Photon streams to include mean nanotimes. The default is [frb.Ph_sel(Dex=’Dem’)].
stream_kwargs (list[dict], optional) – Keyword arguments per stream bassed to ax.axvline/ax.axhline. The default is None.
kwarg_arr (array of kwarg dicts, optional) – Array of dicts to use as kwargs for specific combinations of states/streams in data. Cannot be specified at same time as state_kwargs. If 2D, then will overwrite stream_kwargs, 2nd dimension, if exists specifies stream kwargs The default is None.
**kwargs (dict) – Universal keyword agruments, passed to all calls of ax.axvline/ax.axhline.

Returns:

lines – DESCRIPTION.

Return type:

list[list[matplotlib.lines.Line2D]]

burstH2MM.Plotting.burst_ES_scatter(model, add_corrections=False, flatten_dynamics=False, type_kwargs=None, label_kwargs=None, ax=None, **kwargs)#

Plot E-S scatter plot of bursts, colored based on states present in dwell.

Parameters:

model (H2MM_result) – Model of data to be plotted .
add_corrections (bool, optional) – Whether to use the corrected E/S values of bursts, or to include background, leakage, direct excitation, gamma and beta value corrections. The default is False.
flatten_dynamics (bool, optional) – If True, bursts with multiple states are all plotted together. Useful for models with many numbers of states If False, every unique combination of states in burst are plotted separately. The default is False.
type_kwargs (list[dict], optional) –
List or tuple of dictionaries with burst-type specific arguments handed to ax.scatter.

Note

The order is based on the order in which the burst-types are plotted. This will depend on whether flatten_dynamics is True or False If True the order is the states, and finally dynamics (thus the length will be # of state + 1). If False, then the order is that of burst_type, i.e. bitmap representation. Thus, the order will mix single and multiple states. Be careful your order.

The default is None.
label_kwargs (dict, optional) – Dictionary of keyword arguments to pass to ax.label
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw scatterplot in. The default is None.
**kwargs (dict) – Dictionary of keyword arguments handed to ax.scatter.

Raises:

ValueError – Incorrect length of type_kwargs.

Returns:

collections – List of PathCollections returned by ax.scatter.

Return type:

list[matplotlib.collections.PathCollection]

burstH2MM.Plotting.covar_E_ll_scatter(err, state, ax=None, add_corrections=False, **kwargs)#

Plot the loglikelihood of the covariance of E along a given state.

Parameters:

err (Loglik_Error) – Error object to plot.
state (int) – Which state to plot with optimization holding E of that state fixed.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – Dictionary of keyword arguments passed to ax.scatter.

Returns:

Path collection returned by ax.scatter.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.covar_S_ll_scatter(err, state, ax=None, add_corrections=False, **kwargs)#

Plot the loglikelihood of the covariance of S along a given state.

Parameters:

err (Loglik_Error) – Error object to plot.
state (int) – Which state to plot with optimization holding S of that state fixed.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – Dictionary of keyword arguments passed to ax.scatter.

Returns:

Path collection returned by ax.scatter.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.covar_param_ll_scatter(err, param, state, ax=None, label_kwargs=None, **kwargs)#

Plot the loglikelihood of the covariance of a given parameter type and state/ transition.

Parameters:

err (Loglik_Error) – Error object to plot.
param (str) – parameter to plot, one of the parameters of ModelSet.
state (tuple[int] or tuple[int, int]) – State or transition to plot (the state/transition which was fixed for the given parameter type during optimizations).
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
label_kwargs (dict) – Keyword arguments passed to ax.set_xlabel and ax.set_ylabel
**kwargs (dict) – Dictionary of keyword arguments passed to ax.scatter.

Returns:

Path collection returned by ax.scatter.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.covar_trans_ll_scatter(err, from_state, to_state, ax=None, **kwargs)#

Plot the loglikelihood of the covariance of transition rate along a given transition.

Parameters:

err (Loglik_Error) – Error object to plot.
from_state (int) – State from which the system transitions.
to_state (int) – State to which the system transitions.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – Dictionary of keyword arguments passed to ax.scatter.

Returns:

Path collection returned by ax.scatter.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.dwell_ES_scatter(model, ax=None, plot_type='scatter', states=None, state_kwargs=None, add_corrections=False, label_kwargs=None, dwell_pos=None, **kwargs)#

Dwell based ES scatter plot

Parameters:

model (H2MM_result) – Source of data.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
plot_type (str, optional) – ‘scatter’ or ‘kde’ whether to plot with ax.scatter or sns.kdeplot. The default is ‘scatter’
states (numpy.ndarray, optional) – Which states to plot, if None, all states plotted. The default is None.
state_kwargs (list of kwarg dicts, optional) – Kwargs passed per state. The default is None.
add_corrections (bool, optional) – Use corrected or raw E values. The default is False.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
dwell_pos (int, list, tuple, numpy array or mask_generating callable, optional) – Which dwell position(s) to include.If None, do not filter by burst position. The default is None.
**kwargs (dict) – Universal kwargs for ax.hist.

Returns:

collections – List of matplotlib PathCollections return by ax.scatter

Return type:

list[matplotlib.collections.PathCollection]

burstH2MM.Plotting.dwell_E_hist(model, ax=None, add_corrections=False, states=None, state_kwargs=None, label_kwargs=None, dwell_pos=None, **kwargs)#

Plot histogram of dwell FRET efficiency per state

Parameters:

model (H2MM_result) – Source of data.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
add_corrections (bool, optional) – Use corrected or raw E values. The default is False.
states (numpy.ndarray, optional) – Which states to plot, if None, all states plotted. The default is None.
state_kwargs (list of kwarg dicts, optional) – Kwargs passed per state. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
dwell_pos (int, list, tuple, numpy array or mask_generating callable, optional) – Which dwell position(s) to include.If None, do not filter by burst position. The default is None.
**kwargs (dict) – Universal kwargs for ax.hist.

Returns:

collections – list of bar containers produced by the ax.hist

Return type:

list[matplotlib.container.BarContainer]

burstH2MM.Plotting.dwell_E_tau_scatter(model, ax=None, plot_type='scatter', add_corrections=False, streams=[<Mock name='mock.Ph_sel()' id='139962736809008'>], states=None, state_kwargs=None, stream_kwargs=None, label_kwargs=None, dwell_pos=None, kwarg_arr=None, **kwargs)#

E-tau_D scatter plot

Parameters:

model (H2MM_result) – Source of data.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
plot_type (str, optional) – ‘scatter’ or ‘kde’ whether to plot with ax.scatter or sns.kdeplot. The default is ‘scatter’
add_corrections (bool, optional) – Use corrected or raw E values. The default is False.
streams (list of fretbursts.Ph_sel, optional) – The stream(s) to inlcude. The default is [frb.Ph_sel(Dex=”Dem”), ].
states (numpy.ndarray, optional) – Which states to plot, if None, all states plotted. The default is None.
state_kwargs (list of kwarg dicts, optional) – Kwargs passed per state. The default is None.
stream_kwargs (list of kwarg dict, optional) – List of per-stream kwargs to pass to scatter or kdeplot. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
dwell_pos (int, list, tuple, numpy array or mask_generating callable, optional) – Which dwell position(s) to include.If None, do not filter by burst position. The default is None.
kwarg_arr (array of kwargs dicts, optional) – Array of dicts to use as kwargs for specific combinations of states/streams in data. Cannot be specified at same time as state_kwargs. If 2D, then will overwrite stream_kwargs, 2nd dimension, if exists specifies stream kwargs The default is None.
**kwargs (TYPE) – Universal kwargs handed to ax.hist.

Returns:

collections – List of lists of matplotlib PathCollections return by ax.scatter Organized as [state][streams]

Return type:

list[list[matplotlib.collections.PathCollection]]

burstH2MM.Plotting.dwell_S_hist(model, ax=None, states=None, state_kwargs=None, add_corrections=False, label_kwargs=None, dwell_pos=None, **kwargs)#

Plot histogram of dwell stoichiometry per state

Parameters:

model (H2MM_result, H2MM_list, BurstData) – Model for which to plot histogram of stoiciometries.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
add_corrections (bool, optional) – Use corrected or raw E values. The default is False.
states (numpy.ndarray, optional) – Which states to plot, if None, all states plotted. The default is None.
state_kwargs (list of kwarg dicts, optional) – Kwargs passed per state. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
dwell_pos (int, list, tuple, numpy array or mask_generating callable, optional) – Which dwell position(s) to include.If None, do not filter by burst position. The default is None.
**kwargs – Universal kwargs for ax.hist.

Returns:

collections – list of lists of bar containers produced by the ax.hist organized as [states][streams]

Return type:

list[matplotlib.container.BarContainer]

burstH2MM.Plotting.dwell_dur_hist(model, ax=None, states=None, state_kwargs=None, label_kwargs=None, dwell_pos=None, **kwargs)#

Plot histogram of dwell durations per state

Parameters:

model (H2MM_result, H2MM_list, BurstData) – Model for which to plot histogram of dwell durations.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
states (numpy.ndarray, optional) – Which states to plot, if None, all states plotted. The default is None.
state_kwargs (list of kwarg dicts, optional) – Kwargs passed per state. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
dwell_pos (int, list, tuple, numpy array or mask_generating callable, optional) – Which dwell position(s) to include.If None, do not filter by burst position. The default is None.
**kwargs – Universal kwargs for ax.hist.

Returns:

collections – list of lists of bar containers produced by the ax.hist organized as [states][streams]

Return type:

list[matplotlib.container.BarContainer]

burstH2MM.Plotting.dwell_param_hist(model, param, streams=None, dwell_pos=None, states=None, state_kwargs=None, stream_kwargs=None, label_kwargs=None, kwarg_arr=None, ax=None, **kwargs)#

Generate histograms of specified parameter of given model for states and streams of model

Parameters:

model (H2MM_result) – Source of data.
param (str) – Name of parameter to be histogramed.
streams (list of frebursts.Ph_sel, optional) – The streams to use, ignored if param is not stream based. If None, take all streams in BurstData The default is None.
dwell_pos (int, list, tuple, numpy array or mask_generating callable, optional) – Which dwell position(s) to include.If None, do not filter by burst position. The default is None.
states (numpy.ndarray, optional) – The states to include, if None, all states are used. The default is None.
state_kwargs (list of kwarg dicts, optional) – List of kwargs of same length as states, specifies specific additional kwargs passed to hist for each state. The default is None.
stream_kwargs (list of kwarg dicts, optional) – List of kwargs of same length as streams, specifies specific additional kwargs passed to hist for each stream. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
kwarg_arr (array of kwargs dicts, optional) – Array of dicts to use as kwargs for specific combinations of states/streams in data. Cannot be specified at same time as state_kwargs. If 2D, then will overwrite stream_kwargs, 2nd dimension, if exists specifies stream kwargs The default is None.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
**kwargs (keyword arguments) – Universal kwargs handed to ax.hist.

Raises:

ValueError – Unacceptable set of kwargs specified.

Returns:

collections – list of lists of bar containers produced by the ax.hist organized as [states][streams]

Return type:

list[list[matplotlib.container.BarContainer]]

burstH2MM.Plotting.dwell_param_transition(model, param, include_edge=True, plt_type='scatter', ax=None, from_state=None, to_state=None, trans_mask=None, state_kwargs=None, streams=None, stream_kwargs=None, label_kwargs=None, kwarg_arr=None, **kwargs)#

Plot transition map, separating different state to state transitions, either as scatter or kdeplot

Parameters:

model (H2MM_result or H2MM_list) – Source of data.
param (str) – Name of parameter to be plotted .
include_edge (TYPE, optional) – Whether or not to include transitions at the edges of bursts in dwells. The default is True.
plt_type (str, optional) – “scatter” or “kde”, specify whether to plot as scatter plot or kde-plot The default is scatter.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
from_state (numpy.ndarray, optional) – States of origin dwell to include. If None, all states included. The default is None.
to_state (numpy.ndarray, optional) – States of destination dwell to include. If None, all states included. The default is None.
trans_mask (bool np.ndarray, optional) – Mask of particular transitions to include. If None, all transitions included (Note: transitions from a state to the same state do not exist so diagonal values automatically False) The default is None.
state_kwargs (2D array of kwarg dicts, optional) – 2D array in shape of from_state X to_state of kwargs to pass to each combination of transitions scatter or kde-plots. The default is None.
streams (frebrursts.Ph_sel or list thereof, optional) – Which streams to include, if None, all streams included. Ignored if param is not stream-based. Generally recommended to select a single stream to prevent confusion between state transitions and different streams. The default is None.
stream_kwargs (list of kwarg dict, optional) – List of per-stream kwargs to pass to scatter or kdeplot. The default is None.
kwarg_arr (array of kwarg dicts, optional) – Array (2 or 3D) of arguments to pass per individual plot organized as from_state X to_state (optional X stream). Cannot be specified at same time as state_kwargs, if 3D, stream_kwargs ignored. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
**kwargs (TYPE) – Universal kwargs handed to ax.hist.

Raises:

ValueError – Incompatible keyword arguments specified.

Returns:

collections – The collections or axes returned by each call to ax.scatter or sns.kdeplot organized [from_state][to_state][stream]

Return type:

list[list[list[matplotlib.collections.PathCollection or matplotlib.axes._subplots.AxesSubplot]]]

burstH2MM.Plotting.dwell_param_transition_kde_plot(model, param, include_edge=True, ax=None, stream=<Mock name='mock.Ph_sel()' id='139962736809008'>, states=None, label_kwargs=None, **kwargs)#

Make kdeplot of transitions, without separating different types of transitions

Parameters:

model (H2MM_result) – Source of data.
param (str) – Name of parameter to be plotted .
include_edge (TYPE, optional) – Whether or not to include transitions at the edges of bursts in dwells. The default is True.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
stream (fretbursts.Ph_sel, optional) – Which stream to plot for stream based parameters, ignored for non-stream parameters. The default is fretbursts.Ph_sel(Dex=”Dem”).
states (bool numpy.ndarray, square, optional) – Which from-to transitions to include. If None, all transitions plotted. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
**kwargs (TYPE) – kwargs passed to kdeplot.

Raises:

ValueError – Incompatible kwargs passed.

Returns:

collection – Returned from sns.kdeplot

Return type:

matplotlib.axes._subplots.AxesSubplot

burstH2MM.Plotting.dwell_params_scatter(model, paramx, paramy, states=None, state_kwargs=None, dwell_pos=None, streams=None, stream_kwargs=None, label_kwargs=None, kwarg_arr=None, ax=None, plot_type='scatter', **kwargs)#

Generate a plot of one parameter against another of dwells in a H2MM_result

Parameters:

model (H2MM_result) – Source of data.
paramx (str) – Name of parameter to be plotted along x-axis.
paramy (str) – Name of parameter to be plotted along y-axis
states (numpy.ndarray, optional) – The states to include, if None, all states are used. The default is None.
state_kwargs (list of kwarg dicts, optional) – List of kwargs of same length as states, specifies specific additional kwargs passed to hist for each state. The default is None.
dwell_pos (int, list, tuple, numpy array or mask_generating callable, optional) – Which dwell position(s) to include.If None, do not filter by burst position. The default is None.
streams (list of frebursts.Ph_sel, optional) – The streams to use, ignored if param is not stream based. If None, take all streams in BurstData The default is None.
stream_kwargs (list of kwarg dicts, optional) – List of kwargs of same length as streams, specifies specific additional kwargs passed to hist for each stream. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
kwarg_arr (array of kwargs dicts, optional) – Array of dicts to use as kwargs for specific combinations of states/streams in data. Cannot be specified at same time as state_kwargs. If 2D, then will overwrite stream_kwargs, 2nd dimension, if exists specifies stream kwargs The default is None.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
plot_type (str, optional) – ‘scatter’ or ‘kde’ whether to plot with ax.scatter or sns.kdeplot. The default is ‘scatter’
**kwargs (TYPE) – Universal kwargs handed to ax.hist.

Raises:

ValueError – Unacceptable set of kwargs specified..

Returns:

collections – List of lists of matplotlib PathCollections return by ax.scatter Organized as [state][streams]

Return type:

list[list[matplotlib.collections.PathCollection]]

burstH2MM.Plotting.dwell_tau_hist(model, ax=None, streams=[<Mock name='mock.Ph_sel()' id='139962736809008'>], states=None, state_kwargs=None, stream_kwargs=None, label_kwargs=None, dwell_pos=None, kwarg_arr=None, **kwargs)#

Plot histograms of mean nanotimes of each state. Default is to plot only D_exD_em stream.

Parameters:

model (H2MM_result) – Source of data.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
streams (list of fretbursts.Ph_sel, optional) – The stream(s) to inlcude. The default is [frb.Ph_sel(Dex=”Dem”), ].
states (numpy.ndarray, optional) – Which states to plot, if None, all states plotted. The default is None.
state_kwargs (list of kwarg dicts, optional) – Kwargs passed per state. The default is None.
stream_kwargs (list of kwarg dict, optional) – List of per-stream kwargs to pass to scatter or kdeplot. The default is None.
label_kwargs (dict, optional) – Keyword arguments to pass to ax.label. The default is None
dwell_pos (int, list, tuple, numpy array or mask_generating callable, optional) – Which dwell position(s) to include.If None, do not filter by burst position. The default is None.
kwarg_arr (array of kwargs dicts, optional) – Array of dicts to use as kwargs for specific combinations of states/streams in data. Cannot be specified at same time as state_kwargs. If 2D, then will overwrite stream_kwargs, 2nd dimension, if exists specifies stream kwargs The default is None.
**kwargs (dict) – Universal kwargs for ax.hist.

Returns:

collections – list of lists of bar containers produced by the ax.hist organized as [states][streams]

Return type:

list[list[matplotlib.container.BarContainer]]

burstH2MM.Plotting.dwell_trans_dur_hist(model, from_state=None, to_state=None, from_state_kwargs=None, to_state_kwargs=None, include_beg=True, kwarg_arr=None, ax=None, **kwargs)#

Plot histograms of dwell durations sorted by state of the dwell and the state of the subsequent dwell.

Parameters:

model (H2MM_result, H2MM_list, BurstData) – Model for which to plot the histograms of durations of dwells.
from_state (int, array-like[int],, optional) – State(s) of current dwell. The default is None.
to_state (int, array-like[int], optional) – State(s) of dwell to which plotted duration transitions. The default is None.
from_state_kwargs (array-like[dict], optional) – Array of keyword arguments of same size of to_state passed for a given originating state to ax.hist. The default is None.
to_state_kwargs (array-like[dict], optional) – Array of keyword arguments of same size of to_state passed for a given destination state to ax.hist. The default is None.
include_beg (bool, optional) – Whether or not to include beginning dwells in analysis. The default is True.
kwarg_arr (array-like[array-like[dict]], optional) – Array of arrays organized [from_state, to_state] specifying keyword arguments passed to each specific [from_state, to_state] combinations of dwell durations. The default is None.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw histogram(s) in. The default is None.
**kwargs (dict) – Keyword arguments forwarded to ax.hist.

Raises:

ValueError – Incorrect specification of one or more keyword arguments.

Returns:

collections – list of lists of return values of ax.hist.

Return type:

list[list[matplotlib.container.BarContainer]]

burstH2MM.Plotting.ll_E_scatter(err, state, ax=None, rng=None, steps=20, **kwargs)#

Plot how the loglikelihood decreases when varying the FRET efficiency of a specified state away from the optimal value.

Note

This method is a wrapper around ll_param_scatter()

Parameters:

err (H2MM_result or Loglik_Error) – Model or loglik_error object to plot variability of loglikelihood along specified parameter.
state (int) – State for which to plot the variability of loglikelihood with varied E
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S vals, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.
space_kwargs (dict, optional) – Dictionary of keyword arguments passed to the respective E/S/trans_space() function. These are rng to specify the range of values to scan, and steps, which specifies how many points to place evenly within the range. The default is None
rng_only (bool, optional) – If True only plot the specified range around the optimal parameter (the result of the burstH2MM.ModelError.Loglik_Error.E_space(), burstH2MM.ModelError.Loglik_Error.S_space() or burstH2MM.ModelError.Loglik_Error.trans_space() functions), if False plot all values evaluated ever for the logliklihood varried across the given parameter. The default is True.
label_kwargs (dict) – Keyword arguments passed to ax.set_xlabel and ax.set_ylabel
**kwargs (dict) – Keyword arguments passed to ax.scatter.

Raises:

ValueError – Invalid input to state.

Returns:

ret – Path collection returned by ax.scatter.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.ll_S_scatter(err, state, ax=None, rng=None, steps=20, **kwargs)#

Plot how the loglikelihood decreases when varying the stoichiometry of a specified state away from the optimal value.

Note

This method is a wrapper around ll_param_scatter()

Parameters:

err (H2MM_result or Loglik_Error) – Model or loglik_error object to plot variability of loglikelihood along specified parameter.
state (int) – State for which to plot the variability of loglikelihood with varied E
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S vals, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.
rng_only (bool, optional) – If True only plot the specified range around the optimal parameter (the result of the burstH2MM.ModelError.Loglik_Error.E_space(), burstH2MM.ModelError.Loglik_Error.S_space() or burstH2MM.ModelError.Loglik_Error.trans_space() functions), if False plot all values evaluated ever for the logliklihood varried across the given parameter. The default is True.
label_kwargs (dict) – Keyword arguments passed to ax.set_xlabel and ax.set_ylabel
**kwargs (dict) – Keyword arguments passed to ax.scatter.

Raises:

ValueError – Invalid input to state.

Returns:

ret – Path collection returned by ax.scatter.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.ll_param_scatter(err, param, loc, ax=None, flex=None, thresh=None, space_kwargs=None, rng_only=True, logscale=False, label_kwargs=None, **kwargs)#

Generic function for plotting 1D scatter of how loglikelihood varies along a given model parameter

Parameters:

err (H2MM_result or Loglik_Error) – Model or loglik_error object to plot variability of loglikelihood along specified parameter.
param (str) – which parameter to plot
loc (tuple[int] or tuple[int, int]) – the state or transition to plot
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.
space_kwargs (dict, optional) – Dictionary of keyword arguments passed to the respective E/S/trans_space() function. These are rng to specify the range of values to scan, and steps, which specifies how many points to place evenly within the range. The default is None
rng_only (bool, optional) – If True only plot the specified range around the optimal parameter (the result of the burstH2MM.ModelError.Loglik_Error.E_space(), burstH2MM.ModelError.Loglik_Error.S_space() or burstH2MM.ModelError.Loglik_Error.trans_space() functions), if False plot all values evaluated ever for the logliklihood varried across the given parameter. The default is True.
logscale (bool, optional) – Whether or not to plot the x axis in a log-scale. The default is False.
label_kwargs (dict) – Keyword arguments passed to ax.set_xlabel and ax.set_ylabel
**kwargs (dict) – Keyword arguments passed to ax.scatter.

Returns:

ret – Path collection returned by ax.scatter.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.ll_trans_scatter(err, from_state, to_state, ax=None, rng=None, steps=20, logscale=True, **kwargs)#

Plot how the loglikelihood decreases when varying the transition rate of a specified (from_state to_state) pair away from the optimal value.

Note

This method is a wrapper around ll_param_scatter()

Parameters:

err (H2MM_result or Loglik_Error) – Model or loglik_error object to plot variability of loglikelihood along specified parameter.
from_state (int) – The state the system transitions from.
to_state (int) – The state the system transitions to.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S vals, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.
logscale (bool, optional) – Whether or not to plot the x axis in a log-scale. The default is True.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.
rng_only (bool, optional) – If True only plot the specified range around the optimal parameter (the result of the bursH2MM.ModelError.Loglik_Error.E_space(), burstH2MM.ModelError.Loglik_Error.S_space() or burstH2MM.ModelError.Loglik_Error.trans_space() functions), if False plot all values evaluated ever for the logliklihood varried across the given parameter. The default is True.
label_kwargs (dict) – Keyword arguments passed to ax.set_xlabel and ax.set_ylabel
**kwargs (dict) – Keyword arguments passed to ax.scatter.

Raises:

ValueError – Invalid input to either from_state or to_state.

Returns:

Path collection returned by ax.scatter.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.path_BIC_plot(model_list, highlight_ideal=False, ideal_kwargs=None, ax=None, **kwargs)#

Plot the Bayes Information Criterion of the most likely path of each state model.

Parameters:

model (H2MM_list) – The set of optimizations to be compared, a H2MM_list object (a divisor scheme).
highlight_ideal (bool, optional) – Whether or not to plot the ideal/selected model separately. The default is False.
ideal_kwargs (dict or None, optional) – The kwargs to be passed specifically to the ideal model point. The default is None.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – kwargs to be passed to ax.scatter

Returns:

collections – list of collections produced by the scatter plot

Return type:

list[matplotlib.collections.PathCollection]

burstH2MM.Plotting.plot_burst_index(data, burst, ax=None, colapse_div=False, streams=None, stream_pos=None, stream_color=None, rng=None, invert=False, stream_labels=None, stream_edge=None, **kwargs)#

Plot indexes of a given burst

Parameters:

data (H2MM_resutl, H2MM_list or BurstData) – Parent data object, either H2MM_list or BurstData, if the later will use non-divisor models indexes, if the former, then will divide streams by the divisor scheme used.
burst (int) – Which burst to plot.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
colapse_div (bool, optional) – If using a divisor scheme, whether or not to transform into the base photon streams without divisors. The default is False.
streams (list[fretbursts.Ph_sel], optional) – Which streams to plot, if None will use all streams in input data. The default is None.
stream_pos (dict or numpy.ndarray, optional) – Dictionary of {stream:position} identifying the y location for each photon index. The default is None.
stream_color (dict or array-like, optional) – Colors for each index. The default is None.
rng (array-like, optional) – If stream_pos not specified, the range over which the indexes will be distributed. The default is None.
invert (bool, optional) – If True, then indexes plotted from top to bottom, if False, first indexes plotted from bottom to top. The default is False.
stream_labels (bool, dict, optional) – Whether or not to display tick labels on y-axis, provided as dictionary: {stream:label} where stream is either fretbursts.Ph_sel or int, and label is str. The default is None.
stream_edge (dict or array-like, optional) – Edge-colors for each index. The default is None.
**kwargs (dict) – Kwargs passed to ax.scatter() .

Raises:

ValueError – Invalid values in one or more kwargs
TypeError – Incorrect type for one or more kwargs.

Returns:

ret – Result of ax.scatter for plotting photons.

Return type:

matplotlib.collections.PathCollection

burstH2MM.Plotting.plot_burst_path(model, burst, param='E', ax=None, state_color=None, linewidth=None, stream=None, capstyle='round', **kwargs)#

Plot the state trajectory of a burst in a model.

Parameters:

model (H2MM_result) – The H2MM_result object from which to plot the state path of the specified burst.
burst (int) – Index of the burst.
param (str, optional) – Name of the parameter to use as the parameter value to plot for each state. The default is ‘E’.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
state_color (1-D array-like, optional) – Color of lines for each state. The default is None.
linewidth (1-D array-like, optional) – Width of each state. The default is None.
**kwargs (dict) – kwargs passed to maptlotlib.collections.LineCollection.

Returns:

matplotlib.collections.LineCollections – The line collection added to the axes.
l

burstH2MM.Plotting.plot_burstjoin(model, burst, ax=None, add_corrections=False, state_color=None, stream_color=None, path_kwargs=None, index_kwargs=None)#

Wrapper function plots a burst with E, S paths and burst photons.

Parameters:

model (H2MM_result) – The H2MM_result object from which to plot the state path of the specified burst.
burst (int or str) – Index of the burst, or one of {‘states’, ‘transitions’} to find the burst with either the most states, or transitions automatically.
add_corrections (bool, optional) – Plot correct E/S values or raw. The default is False.
state_color (1-D array-like, optional) – Color of lines for each state. The default is None.
stream_color (dict, optional) – Color for each stream, given as dict {stream:color} where stream is fretbursts.Ph_sel and color is a matplotlib color specification. The default is None.
path_kwargs (dict) – Keyword arguments passed to plot_burst_path. The default is None
index_kwargs (dict) – Keyword arguments passed to plot_burst_index. The default is None

Return type:

None.

burstH2MM.Plotting.raw_nanotime_hist(data, streams=None, stream_kwargs=None, ax=None, yscale='linear', raw_bin=True, normalize=False, **kwargs)#

Plot the histogram of nanotimes of photons (in bursts) per stream. Usefull for visualizing the fluorescence decays, and deciding where to place the IRF thresh

Parameters:

data (BurstData) – The BurstData object for which the nanotime histogram will be plotted.
streams (fretbursts.Ph_sel or list[fretbursts.Ph_sel], optional) – The stream(s) for which the nanotime is to be plotted, must be with the photon selection of the BurstData object. If None, will plot all streams in data. The default is None.
stream_kwargs (dict or list[dict], optional) – Per stream kwargs, passed to ax.plot, must match streams. If None, no stream specific kwargs passed to ax.plot. The default is None.
yscale (str optional) – The argument passed to the ax.set_yscale function. Primary options are ‘linear’ (default) and ‘log’. The default is ‘linear’
raw_bin (bool, optional) – Whether to plot the raw nanotime bin (True, default) or convert into units of ns (False). The default is True.
normalize (bool, optional) – Whether to plot normalize the number of counts to the maximum per stream. The default is False.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – Kwargs passed to all plots.

Raises:

ValueError – Mismatched streams and stream_kwargs lengths

Returns:

collections (list[matplotlib.collections.PathCollection]) – List of path collections, per stream, from ax.plot of each nanotime decay.
leg (matplotlib.legend.Legend) – Legend object

burstH2MM.Plotting.scatter_ES(model, ax=None, add_corrections=False, states=None, errorbar=False, errorbar_kwargs=None, **kwargs)#

Plot the position of all states in E and S

Note

If the ax kwarg is used, it is assumed to be used in conjunction with other plots, and thus the xlim and ylim values will not be set

Parameters:

model (H2MM_result) – Model to plot values of E/S.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw scatterplot in. The default is None.
add_corrections (bool, optional) – Use the corrected (True) or raw (False) E/S values. The default is False.
states (array-like, optional) – A mask for which states to use. May be a 1-D integer array of states, or boolean mask of which states to plot, in the latter case, must be of the same size as the number of states in the model. The default is None
errorbar (bool or str, optional) – Whether or not to add error bars to based on chosen type of error. Optional types The default is False
errorbar_kwargs (dict) – Keyword arguments passed to ax.errorbar
**kwargs (keyword arguments) – Keyword arguments passed to ax.scatter to control the plotting

Returns:

collection – The path collection the scatter plot method returns, or, if errorbar is used, a tuple of collectiosn, one for scatter the other for errorbar

Return type:

matplotlib.collections.PathCollection or tuple

burstH2MM.Plotting.state_nanotime_hist(model, states=None, state_kwargs=None, streams=<Mock name='mock.Ph_sel()' id='139962736809008'>, stream_kwargs=None, kwarg_arr=None, yscale='log', raw_bin=False, normalize=False, ax=None, **kwargs)#

Plot the nanotime decays per state per stream of a given model.

Parameters:

model (H2MM_result) – The model containing the data to be plotted
states (numpy.ndarray, optional) – Which states to plot, if None, all states plotted. The default is None.
state_kwargs (list of kwarg dicts, optional) – Kwargs passed per state. The default is None.
streams (list of fretbursts.Ph_sel, optional) – The stream(s) to inlcude. The default is [frb.Ph_sel(Dex=”Dem”), ].
stream_kwargs (list of kwarg dict, optional) – List of per-stream kwargs to pass to scatter or kdeplot. The default is None.
kwarg_arr (array of kwargs dicts, optional) – Array of dicts to use as kwargs for specific combinations of states/streams in data. Cannot be specified at same time as state_kwargs. If 2D, then will overwrite stream_kwargs, 2nd dimension, if exists specifies stream kwargs The default is None.
yscale (str, optional) – Agrument passed to ax.set_yscale, primary options are ‘log’ and ‘linear. The default is ‘log’.
raw_bin (bool, optional) – Whether to plot the raw nanotime bin (True) or convert into units of ns (False, default). The default is False.
normalize (bool, optional) – Whether to plot normalize the number of counts to the maximum per stream. The default is False.
ax (matplotlib.axes or None, optional) – The axes where the plot will be placed. The default is None.
**kwargs (dict) – Additional keyword arguments, passed to ax.plot.

Returns:

collections – A list of lists of path collections returned by ax.plot, per state per stream.

Return type:

list[list[matplotlib.collections.PathCollection]]

burstH2MM.Plotting.trans_arrow_ES(model, ax=None, add_corrections=False, min_rate=10.0, states=None, positions=0.5, rotate=True, sep=0.02, fstring='3.0f', unit=False, from_arrow='-', from_props=None, to_arrow='-|>', to_props=None, arrowprops=None, state_kwargs=None, **kwargs)#

Generate arrows between states in E-S plot indicating the transition rate.

Parameters:

model (H2MM_result) – H2MM_result to plot the transition rate arrows.
ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to draw scatterplot in. The default is None.
add_corrections (bool, optional) – Use the corrected (True) or raw (False) E values. The default is False.
min_rate (float, optional) – Minimum transition rate (in seconds) to plot, ignored if states is specified. The default is 1e1.
states (tuple[tuple[int, int]], optional) – Manually specify which transition rate to plot. Specify as tuple of 2 tuples, each 2 tuple as (from_state, to_state). If None, automatically generate transition rates. The default is None.
positions (float or numpy.ndarray, optional) – The position of the transition rate label, specified as fraction of distance between states of transition rate. If specified as float, same position is used for all rates, if specified as numpy.ndarray, then each rate is specified as matrix [from_state][to_state] (diagonals ignored). The default is 0.5.
rotate (bool, optional) – Whether or not to rotate the transition rate label. The default is True.
sep (float, optional) – When transition rates [i,j] and [j,i] are specified, the offset in data points, to add to the positions (to prevent overlap between foroward and backward transition rates). The default is 2e-2.
fstring (str, optional) – The format string defining how to format the transition rate. The default is ‘3.0f’
unit (bool or str, optional) – The unit to display for transition rates. If False, no unit is displayed. If True, show s^-1, if a string (not recomended) this string will be appended to the end of all transition rates. The default is False
from_arrow (str, optional) – Format string for arrow pointing to from_state (value passed to ‘arrowstyle’). The default is ‘-‘.
from_props – The default is None
to_arrow (str, optional) – Format string for arrow pointing to to_state (value passed to ‘arrowstyle’). The default is ‘-|>’.
to_props – The default is None
state_kwargs (tuple[tuple[dict]], optional) – Transition specific keyword arguments to be passed to ax.annotate(). The default is None.
**kwargs (dict) – keyword arguments passed to ax.annotate().

Raises:

ValueError – One or more keyword arguments contains invalid types or is of invalid length.

Returns:

annos – List of list of annotations added to the plot.

Return type:

list[list[matplotlib.text.Annotation]]

Selections #

Functions for selecting types of bursts and photons

burstH2MM.Masking.begin_dwell(model)#

Return mask of all dwells at the beginning of bursts, not including bursts with a single state

Parameters:: model (H2MM_result) – Model to make mask.
Returns:: end_dwells – Mask of beginning-dwells.
Return type:: bool np.ndarray

burstH2MM.Masking.burst_begin_dwell(model)#

Return mask of all dwells that start at the beginning of a burst, including bursts with a single state.

Parameters:: model (H2MM_result) – Model to make mask.
Returns:: init_dwells – Mask of begin and whole-bursts-dwells.
Return type:: bool np.ndarray

burstH2MM.Masking.burst_dwell(model)#

Return mask of all dwells the span the entire bursts

Parameters:: model (H2MM_result) – Model to make mask.
Returns:: burst_dwells – Mask of burst-dwells.
Return type:: bool np.ndarray

burstH2MM.Masking.burst_end_dwell(model)#

Return mask of all dwells that end at the end of bursts (whole-burst and end dwells)

Parameters:: model (H2MM_result) – Model to make mask.
Returns:: burst_end_dwells – Mask of end-dwells and whole burst dwells.
Return type:: bool np.ndarray

burstH2MM.Masking.dwell_size(model, ph_min, ph_max=<Mock name='mock.inf' id='139962736810928'>, streams=None)#

Return a mask of dwells with a minimum number of photons, can also specify a maximum value through ph_max, and isolate from a set stream with stream.

Uses the uncorrected photon counts.

Parameters:

model (H2MM_result) – Model to make mask.
ph_min (int) – Minimum number of photons in a dwell.
ph_max (int, optional) –
Maximum number of photons in a dwell.

Note

Default is np.inf to establish no maximum value. float values are allowed, but discouraged.

The default is np.inf.
stream (fretbursts.Ph_sel, or list[fretbursts.Ph_sel] optional) – The desired photon stream(s), if None, takes sum in all photon streams. The default is None.

Raises:

TypeError – Stream is not frb.Ph_sel.

Returns:

mask – Mask of dwells fitting the input criterion.

Return type:

numpy.ndarray dtype=bool

burstH2MM.Masking.dwell_trans(model, to_state, include_beg=True)#

Geneate a mask of which dwells belong to a given type of transition. This allows selection of dwells of a given state, that transition to another specific state.

Parameters:

model (H2MM_model) – The model for which the mask is generated
to_state (int) – The state of the subsequent dwell for the mask to return true
include_beg (bool, optional) – Whether or not to have transitions where the dwell is an initial dwell set to true in the mask. The default is True.

Returns:

dwell_trans_mask – Mask of dwells meeting the specified transitions.

Return type:

numpy.ndarray[bool]

burstH2MM.Masking.dwell_trans_from(model, from_state, include_end=True)#

Geneate a mask of which dwells belong to a given type of transition. This allows selection of dwells of a given state, that transition to another specific state.

Parameters:

model (H2MM_model) – The model for which the mask is generated
from_state (int) – The state of the previous dwell for the mask to return true
include_end (bool, optional) – Whether or not to have transitions where the dwell is an end dwell set to true in the mask. The default is True.

Returns:

dwell_trans_mask – Mask of dwells meeting the specified transitions.

Return type:

numpy.ndarray[bool]

burstH2MM.Masking.edge_dwell(model)#

Return mask of all dwells at the beginning and end of bursts

Parameters:: model (H2MM_result) – Model to make mask.
Returns:: edge_dwells – Mask of dwells at beginning and end of bursts
Return type:: bool np.ndarray

burstH2MM.Masking.end_dwell(model)#

Return mask of all dwells at the end of bursts

Parameters:: model (H2MM_result) – Model to make mask.
Returns:: end_dwells – Mask of end-dwells.
Return type:: bool np.ndarray

burstH2MM.Masking.mid_dwell(model)#

Return mask of all middle dwells in model (not whole, beginning or end)

Parameters:: model (H2MM_result) – Model to make mask.
Returns:: mid_dwells – Mask of mid-dwells.
Return type:: bool np.ndarray

burstH2MM.Masking.not_mid_dwell(model)#

Return mask of all dwells that are not in the middle of bursts

Parameters:: model (H2MM_result) – Model to make mask.
Returns:: not_mid_dwells – Mask of all dwells not in the middle of bursts.
Return type:: bool np.ndarray

Uncertainties #

Note

These classes are intended to be accessed primarily through the H2MM_list object and should rarely be interacted with directly by the user

class burstH2MM.ModelError.Bootstrap_Error(parent, models)#

Internal class for storing bootstrap error calculations.

This class is usually created when the burstH2MM.BurstSort.H2MM_result.bootstrap_eval() method is called, and stored under burstH2MM.BurstSort.H2MM_result.bootstrap_err

burstH2MM.BurstSort.H2MM_result has several propery aliases for the different error values stored by this class.

Note

The standard init method is rarely used, rather, this is usually instantiated with Bootstrap_Error.model_eval() instead.

Parameters:

parent (H2MM_model) – H2MM_model object for which the error was generated
models (list[H2MM_C.h2mm_model]) – The H2MM_C.h2mm_model objects of each subset

property E_corr_err#: Standard error of corrected FRET efficiencies

property E_corr_std#: Standard deviation of corrected FRET efficiencies

property E_err#: Standard error of FRET efficiencies

property E_std#: Standard deviation of FRET efficiencies

property S_corr_err#: Standard error of corrected stoichiometries

property S_corr_std#: Standard deviation of corrected stoichiometries

property S_err#: Standard error of stoichiometries

property S_std#: Standard deviation of stoichiometries

classmethod model_eval(model, subsets=10)#

Standard way of creating Bootstrap_Error objects, takes a model and subdivides the data into subsets number of subsets, and runs separate optimizations on each subset, with the original model as an initial model, then takes the standard deviation of all model values across the separate optimizations, to evaluate the model error.

Parameters:

model (H2MM_result) – The model for which to calculate the bootstrap error.
subsets (int, optional) – Number of subsets to divide the data into to calculate the bootstrap error. The default is 10.

Returns:

Object organizing the error calculation.

Return type:

Bootstrap_Error

models#: list of optimized models of subsets

property obs_err#: Standard error of emission probabilities

property obs_std#: Standard deviation of emission probabilities

parent#: parent burstH2MM.BurstSort.H2MM_result object

property prior_err#: Standard error of initial probabilities

property prior_std#: Standard deviation of initial probabilities

property trans_err#: Standard error of transition rates

property trans_std#: Standard deviation of transition rates

burstH2MM.ModelError.E_space(err, state, rng=None, steps=20)#

Calculate the loglikelihoods of models with a range E values of state. By default, takes a range twice as large as the calculated error, and divides into 20 steps.

Parameters:

err (Loglik_Error) – Error object to use as input.
state (int) – Which state to evaluate.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S vals, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.

Raises:

ValueError – Impropper rng input.

Returns:

rng_arr (numpy.ndarray) – E values of evaluated models.
ll_arr (numpy.ndarray) – loglikelihoods of evaluated models.

class burstH2MM.ModelError.Loglik_Error(parent)#

Object for evaluation of error by comparing loglikelihoods of models with parameters offset and the optimial model.

Created from burstH2MM.BurstData.H2MM_result object, with empty arrays allocated, but values are only calcualted when various methods are called.

property E#: Estimated error based on the loglikelihood range of low/high E values of calculated error

E_covar#: Array of covarience calculations of FRET efficiency

E_eval(locs=None, flex=None, step=0.01, max_iter=100, thresh=None)#

Evaluate the loglike based error for FRET efficiency

Parameters:

locs (iterable[float]) – The states for which to evaluate the loglik error. If None, will calculate all states. The default is None.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
step (float, optional) – Shift in E for initial search. The default is 1e-2.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.

property E_lh#: Uncertainty in E given as low/high values, shape [state, 2]

E_ll#: loglikelihoods of low/high values of evaluated E error

E_ll_rng#: loglikelihoods of all FRET efficiencies evalated so far, oranized as numpy.ndarray of numpy.ndarrays

E_rng#: all FRET efficiencies evalated so far, oranized as numpy.ndarray of numpy.ndarrays

E_space(state, rng=None, steps=20)#

Calculate the loglikelihoods of models with a range E values of state. By default, takes a range twice as large as the calculated error, and divides into 20 steps.

Parameters:

err (Loglik_Error) – Error object to produce parameter range.
state (int) – State to evaluate.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S vals, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.

Returns:

rng (numpy.ndarray) – 1D array of the transition rate evaluated
ll (numpy.ndarray) – 1D array of the loglikelihoods of the resultant models

property S#: Estimated error based on the loglikelihood range of low/high S values of calculated error

S_covar#: Covariant optimizations of stoichiometries

S_eval(locs=None, flex=None, step=0.01, max_iter=100, thresh=None)#

Evaluate the loglike based error for Stoichiometry

Parameters:

locs (iterable[float]) – The states for which to evaluate the loglik error. If None, will calculate all states. The default is None.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
step (float, optional) – Shift in E for initial search. The default is 1e-2.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.

property S_lh#: Uncertainty in S given as low/high values, shape [state, 2]

S_ll#: loglikelihoods of low/high values S error

S_ll_rng#: loglikelihoods of all stoichiometries evalated so far, oranized as numpy.ndarray of numpy.ndarrays

S_rng#: all stoichiometries evalated so far, oranized as numpy.ndarray of numpy.ndarrays

S_space(state, rng=None, steps=20)#

Calculate the loglikelihoods of models with a range S values of state. By default, takes a range twice as large as the calculated error, and divides into 20 steps.

Parameters:

err (Loglik_Error) – Error object to produce parameter range.
state (int) – State to evaluate.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S vals, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.

Returns:

rng (numpy.ndarray) – 1D array of the transition rate evaluated
ll (numpy.ndarray) – 1D array of the loglikelihoods of the resultant models

all_eval(flex=None, thresh=None, trans_kw=None, E_kw=None, S_kw=None)#

Evaluate loglik error for all available parameters

Parameters:

flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.
trans_kw (dict, optional) – Keyword argument dictionary, passed to burstH2MM.ModelError.Loglik_Error.get_trans_err(). The default is None.
E_kw (dict, optional) – Keyword argument dictionary, passed to burstH2MM.ModelError.Loglik_Error.get_E_err(). The default is None.
S_kw (dict, optional) – Keyword argument dictionary, passed to burstH2MM.ModelError.Loglik_Error.get_S_err(). The default is None.

clear_E()#: Clear all FRET efficiency related uncertainty values

Note

Does not clear range arrays.

clear_S()#: Clear all stoichiometry related uncertainty values

Note

Does not clear range arrays.

clear_all()#: Clear all uncertainty values.

Note

Does not clear range arrays.

clear_trans()#: Clear all transition rate related uncertainty values

Note

Does not clear range arrays.

covar_E(state, rng=None, steps=10, **kwargs)#

Calculate the covariance of a given state along E. Runs optimizations with the given E parameter fixed to the value returned by burstH2MM.ModelError.Loglik_Error.E_space(), and stores models in cooresponding element of burstH2MM.ModelError.Loglik_Error.E_covar

Parameters:

state (int) – State along which to run optimizations with fixed values of E.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) E values, or factor by which to multiply error range, or array of E values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 10.
**kwargs (dict) – Arguments passed to H2MM_C.h2mm_model.optimize.

covar_S(state, rng=None, steps=10, **kwargs)#

Calculate the covariance of a given state along S. Runs optimizations with the given S parameter fixed to the value returned by burstH2MM.ModelError.Loglik_Error.S_space(), and stores models in cooresponding element of burstH2MM.ModelError.Loglik_Error.S_covar

Parameters:

state (int) – State along which to run optimizations with fixed values of S.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S values, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 10.
**kwargs (dict) – Arguments passed to H2MM_C.h2mm_model.optimize.

covar_trans(*args, rng=None, steps=10, **kwargs)#

Calculate the covariance of a given transition rate. Runs optimizations with the given transition rate fixed to the value returned by burstH2MM.ModelError.Loglik_Error.trans_space(), and stores models in cooresponding element of burstH2MM.ModelError.Loglik_Error.trans_covar

Parameters:

from_state (int) – State from which the system is transitioning.
to_state (int) – State to which the system is transitioning.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) transition rates, or factor by which to multiply error range, or array of transition rates. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 10.
**kwargs (dict) –
Arguments passed to H2MM_C.h2mm_model.optimize.

Note

To reduce the time that these evaluations, if not over-ridden in keyword arguments, max_iter=400 and converged_min=1e-6*self.flex

property flex#: Accuracy to which the threshold must be found

get_E_err(*args, flex=None, step=0.01, max_iter=100, thresh=None, simple=True)#

Retrieve or calculate the loglikelihood error of specific FRET efficiency(s).

Parameters:

*args (location specifier) – State(s) as integer or slice of FRET efficiency(s) for which the error should be retrieved/calculated.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
factor (float, optional) – Factor by which to offset the transition rate for initial search. The default is 1e-1.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.
simple (bool, optional) – Whether to return 1 (True) or 2 (False) values showing half the difference, or the low and high values of the requested states

Returns:

Array of loglikelihood errors of requested FRET efficiency(s).

Return type:

numpy.ndarray

get_S_err(*args, flex=None, step=0.01, max_iter=100, thresh=None, simple=True)#

Retrieve or calculate the loglikelihood error of specific stoichiometry(s).

Parameters:

*args (location specifier) – State(s) as integer or slice of stoichiometries(s) for which the error should be retrieved/calculated.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
step (float, optional) – Shift in S for initial search. The default is 1e-2.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.
simple (bool, optional) – Whether to return 1 (True) or 2 (False) values showing half the difference, or the low and high values of the requested states

Returns:

Array of loglikelihood errors of requested stoichiometry(s).

Return type:

numpy.ndarray

get_trans_err(*args, flex=None, factor=0.1, max_iter=100, thresh=None)#

Retrieve or calculate the loglikelihood error of specific transition rate(s).

Parameters:

*args (location specifier) – Transition from_state to_state as integers or slices of transition rates for which the error should be retrieved/calculated.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
factor (float, optional) – Factor by which to offset the transition rate for initial search. The default is 1e-1.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.

Returns:

Array of low/high bounds of the loglikelihood error of the requested transition rates.

Return type:

numpy.ndarray

property model#: Parent burstH2MM.BurstSort.H2MM_result object

property nstate#: Nubmer of states in model

t_ll_rng#: loglik of all transition rates evalated so far, oranized as numpy.ndarray of numpy.ndarrays

t_rate_rng#: all transition rates evalated so far, oranized as numpy.ndarray of numpy.ndarrays

property thresh#: The threshold in loglikelihood to consider the uncertainty range

property trans#: [nstate, nstate, 2] matrix of low/high error transition rates

trans_covar#: Covariant optimizations of FRET efficiencies

trans_eval(locs=None, flex=None, factor=0.1, max_iter=100, thresh=None)#

Evaluate the loglikelihood based error for transition rates.

Parameters:

locs (tuple[tuple[int, int] ...], optional) – Locations of trans errors to evaluate, if None, will evaluate all transition rates. The default is None.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. If None use default. The default is None.
factor (float, optional) – Factor by which to offset the transition rate for initial search. The default is 1e-1.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is None.

property trans_high#: Transition rates higher than the optimal that have loglikelihood thresh lower than the optimal

trans_ll#: loglikelihoods of the low/high transision rate error range

property trans_low#: Transition rates lower than the optimal that have loglikelihood thresh lower than the optimal

trans_space(trans, rng=None, steps=20)#

Calculate the loglikelihoods of models with a range transition rate values of a given transition. By default, takes a range twice as large as the calculated error, and divides into 20 steps.

Parameters:

err (Loglik_Error) – Error object to produce parameter range.
trans ([int, int]) – Transition (from_state, to_state) to evaluate
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) transition rate values, or factor by which to multiply error range, or array of transition rate values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.

Returns:

rng (numpy.ndarray) – 1D array of the transition rate evaluated
ll (numpy.ndarray) – 1D array of the loglikelihoods of the resultant models

class burstH2MM.ModelError.ModelSet(modlist, models)#

Internal class used to organize multiple H²MM models, which are connected to the same data and divisor scheme, and with the same number of states. Used for comparing models with slightly different values.

Parameters:

modlist (H2MM_list) – The list object defining the divisor scheme
models (sequence [H2MM_C.h2mm_model]) – The models to compare/organize

property E#: FRET efficiencies of models in Set, organized [model, state]

property E_corr#: Corrected FRET efficiencies of models in Set, organized [model, state]

property S#: Stoichiometries of models in Set, organized [model, state]

property S_corr#: Corrected stoichiometries of models in Set, organized [model, state]

add_model(model)#

Add a model to the set of models.

Parameters:

model (H2MM_C.h2mm_model) – Model to add to the set.

Raises:

TypeError – Incorrect type.
ValueError – Model not of same dimensions as other input.

property loglik#: Loglikelihoods of models in Set

property models#: tuple of H2MM_C.h2mm_model objects in set

property ndet#: Number of photon streams in parent burstH2MM.BurstSort.BurstData object.

property nstate#: Number of states of all models in set

property obs#: Emission proabilities of models in Set, organized [model, state, stream]

property prior#: Initial proabilities of models in Set, organized [model, state]

property trans#: Transition rate of models in Set, organized [model, from_state, to_state]

burstH2MM.ModelError.S_space(err, state, rng=None, steps=20)#

Calculate the loglikelihoods of models with a range S values of state. By default, takes a range twice as large as the calculated error, and divides into 20 steps.

Parameters:

err (Loglik_Error) – Error object to produce parameter range.
state (int) – State to evaluate.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S vals, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.

Raises:

ValueError – Impropper rng input.

Returns:

rng_arr (numpy.ndarray) – S values of evaluated models.
ll_arr (numpy.ndarray) – loglikelihoods of evaluated models.

burstH2MM.ModelError.covar_E(err, state, rng=None, steps=10, **kwargs)#

Parameters:

err (Loglik_Error) – Logklik_Error to calculate the covariance of.
state (int) – State along which to run optimizations with fixed values of E.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) E values, or factor by which to multiply error range, or array of E values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 10.
**kwargs (dict) – Arguments passed to H2MM_C.h2mm_model.optimize.

Returns:

ModelSet of optimized models.

Return type:

ModelSet

burstH2MM.ModelError.covar_S(err, state, rng=None, steps=10, **kwargs)#

Parameters:

err (Loglik_Error) – Logklik_Error to calculate the covariance of.
state (int) – State along which to run optimizations with fixed values of S.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) S values, or factor by which to multiply error range, or array of S values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 10.
**kwargs (dict) – Arguments passed to H2MM_C.h2mm_model.optimize.

Returns:

ModelSet of optimized models.

Return type:

ModelSet

burstH2MM.ModelError.covar_trans(err, trans, rng=None, steps=10, **kwargs)#

Calculate the covariance of a given transition. Runs optimizations with the given transition parameter fixed to the value returned by burstH2MM.ModelError.Loglik_Error.trans_space(), and stores models in cooresponding element of burstH2MM.ModelError.Loglik_Error.trans_covar

Parameters:

err (Loglik_Error) – Logklik_Error to calculate the covariance of.
trans (tuple(int, int)) – Transition along which to run optimizations with fixed values of transition rate.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) E vals, or factor by which to multiply error range, or array of E values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 10.
**kwargs (dict) – Arguments passed to H2MM_C.h2mm_model.optimize.

Returns:

ModelSet of optimized models.

Return type:

ModelSet

burstH2MM.ModelError.err_E_search(err, state, flex=0.05, step=0.01, max_iter=100, thresh=0.5)#

Base function for calculating the loglikelihood error of the E of a particular state.

Parameters:

model (Loglik_Error) – Loglik_Error for which to calculate the loglikelihood error.
state (int) – state to evaluate loglikelihood error of E.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. The default is 5e-2.
step (float, optional) – Amount to shift E in each iteration before low/high bounds have been found. The default is 1e-2.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is 0.5.

Returns:

ll_rt (numpy.ndarray) – low/high E values with target loglikelihoods.
ll_lh (numpy.ndarray) – Actual loglikelihoods of low/high E values.
rate_array (numpy.ndarray) – All rates attempted in search.
ll_array (numpy.ndarray) – All loglikelihoods attempted in search.

burstH2MM.ModelError.err_S_search(err, state, flex=0.05, step=0.01, max_iter=100, thresh=0.5)#

Base function for calculating the loglikelihood error of the S of a particular state.

Parameters:

err (Loglik_Error) – Loglik_Error for which to calculate the loglikelihood error.
state (int) – state to evaluate loglikelihood error of S.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. The default is 5e-2.
step (float, optional) – Amount to shift E in each iteration before low/high bounds have been found. The default is 1e-2.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is 0.5.

Returns:

ll_rt (numpy.ndarray) – low/high S values with target loglikelihoods.
ll_lh (numpy.ndarray) – Actual loglikelihoods of low/high S values.
rate_array (numpy.ndarray) – All rates attempted in search.
ll_array (TYPE) – All loglikelihoods attempted in search.

burstH2MM.ModelError.err_param_search(err, state, flex, step, max_iter, thresh, param)#

Base function for calculating the loglikelihood error of the given param of a particular state.

Parameters:

err (Loglik_Error) – Loglik_Error for which to calculate the loglikelihood error.
state (int) – state to evaluate loglikelihood error of param.
flex (float) – Allowed variability in target decrease in loglikelihood.
step (float) – Amount to shift param in each iteration before low/high bounds have been found.
max_iter (int) – maximum number of attempts to try in finding target transition rate.
thresh (float) – Decrease in loglikelihood of adjusted model to target as characterizing the error.

Returns:

ll_rt (numpy.ndarray) – low/high param values with target loglikelihoods.
ll_lh (numpy.ndarray) – Actual loglikelihoods of low/high param values.
rate_array (numpy.ndarray) – All rates attempted in search.
ll_array (numpy.ndarray) – All loglikelihoods attempted in search.

burstH2MM.ModelError.err_trans_search(model, loc, flex=0.05, factor=0.1, max_iter=100, thresh=0.5)#

Search for the deviation above and bellow the optimizal

Parameters:

model (H2MM_result) – Optimization result for which to calculate the error in transition rates.
loc (tuple[int, int]) – Transition rate (from_state, to_state) for which to calculate the error.
flex (float, optional) – Allowed variability in target decrease in loglikelihood. The default is 5e-2.
factor (float, optional) – Factor by which to offset the transition rate for initial search. The default is 1e-1.
max_iter (int, optional) – maximum number of attempts to try in finding target transition rate. The default is 100.
thresh (float, optional) – Decrease in loglikelihood of adjusted model to target as characterizing the error. The default is 0.5.

Returns:

ll_rt (numpy.ndarray) – low/high transition rates with target loglikelihoods.
ll_lh (numpy.ndarray) – Actual loglikelihoods of low/high transition rates.
rate_array (numpy.ndarray) – All rates attempted in search.
ll_array (TYPE) – All loglikelihoods attempted in search.

burstH2MM.ModelError.trans_space_ll(err, trans, rng=None, steps=20)#

Calculate the loglikelihoods of models with a range trans values of state. By default, takes +/- 10 times the optimal transition rate. into 20 steps.

Parameters:

err (Loglik_Error) – Error object to use as input.
trans ([int, int]) – Which state to evaluate.
rng (tuple[int, int], int, float, numpy.ndarray, optional) – Custom range specified by (low, high) trans vals, or factor by which to multiply error range, or array of trans values. The default is None.
steps (int, optional) – Number of models to evaluate. The default is 20.

Raises:

ValueError – Impropper rng input.

Returns:

rng_arr (numpy.ndarray) – trans values of evaluated models.
ll (numpy.ndarray) – loglikelihoods of evaluated models.

Simulations #

Module for generating simulated data sets, allowing comparison of simulated data to real data.

class burstH2MM.Simulations.Sim_Result(base, sim_times, sim_states, sim_dets)#

Base class for storing and calculating parameters of simulated data.

Note

This is usually created using the simulate() function, and not with the default constructor

Parameters:

parent (H2MM_result) – The H2MM_result object containing the model from which simulated data was created.
sim_times (list[numpy.ndarray]) – The list of burst times of simulated data
sim_states (list[numpy.ndarray]) – The list of simulated photon states, stored in the .path attribute
sim_dets (list[numpy.ndarray]) – The list of simulated photon indices, stored in the .parent.index attribute

property conf_thresh#: Threshhold for considering a photon nantotime in calculating dwell_nano_mean and nanohist

property dwell_nano_mean#: Mean nanotime of each stream and dwell, organized [stream, dwell]

property nanohist#: Histogram of nanotimes, sorted by state, organized [state, stream, nanotime]

trim_data()#: Remove photon-level arrays, conserves memory for less important models

burstH2MM.Simulations.simulate(model, times=None)#

Genearte a Monete-Carlo simulation based on an H2MM_model object. By defualt takes the photon arrival times of the data used in the optimization. However, a custom set of arrival times may be inputed through the times keyword argument.

Parameters:

model (H2MM_result) – A H2MM_result object, from which a simulated dataset will be generated.
times (list[np.ndarray], optional) – If given, simulation will use these times instead of the arrival times of the original data as a starting point. The default is None.

Returns:

sim_result – A data object containing the simulaetd data, behaves essentially identically to a H2MM_result except without photon nanotimes.

Return type:

Sim_Result

Documentation#

BurstSort#

Plotting#

Selections#

Uncertainties#

Simulations#

Documentation #

BurstSort #

Plotting #

Selections #

Uncertainties #

Simulations #