API Reference

class blinx.HyperParameters(min_y=1, num_guesses=1, epoch_length=1000, is_done_limit=1e-05, is_done_window=10, step_sizes=Parameters(mu=1.0, mu_bg=1.0, sigma=0.001, p_on=0.001, p_off=0.001), distribution_threshold=0.1, max_x=None, num_x_bins=1024, p_outlier=0.1)

Hyperparameters used for maximum likelihood optimization.

Args:

min_y (float, default=1):

The minimum number of emitters expected to be in the system

num_guesses (int, default=1):

The number of parameter guesses to start maximum likelihood optimization from.

epoch_length (int, default=1000):

The length of an “epoch”. This is used to break the optimization into smaller stretches (epochs). Convergence is tested for at the end of each epoch.

is_done_limit (float, default=1e-5):

the minimum relative change in log_likelihood between iterations, below which a plateau is reached and optimization stopped

is_done_window (int, default=10):

The number of previous iterations to consider when determining if an optimization plateau is reached

step_sizes (Parameters, defaults=(mu=1.0, mu_bg=1.0, sigma=1e-3, p_on=1e-3, p_off=1e-3)):

The gradient step size used in sgd optimization, individually specified for each parameter in Parameters

Importantly all values must be type: float for gradietns to be calculated

distribution_threshold (float, default=1e-1):

Used in post_process to compare distribution of optimal states to the stady state distribution. Useful in filtering bad fits

max_x (float):

The maximum intensity value observed in the trace. Used to discritize the trace and calculate individual measurement probabilities

num_x_bins (int, default=1024):

number of bins to use when discretizing the trace and calcualting individual measurement probabilities

p_outlier (float, default=0.1):

a weight to account for outlier, or out of distribution intensity measurements. Occasional measurements contain extreme noise and this sets a minimum possible probability

class blinx.ParameterRanges(mu_range=(100, 30000), mu_bg_range=(5000, 5000), sigma_range=(0.1, 0.1), p_on_range=(0.0001, 1.0), p_off_range=(0.0001, 1.0), mu_step=100, mu_bg_step=1, sigma_step=1, p_on_step=20, p_off_step=20)

Min/max and number of values to explore by the optimizer.

Args:

mu_range (tuple):

The min and max mean intensity values of a single emitter to grid search over

mu_bg_range (tuple):

The min and max background intensity values to grid search over

sigma_range (tuple):

The min and max values of the std of the intensity of a single emitter to grid search over

p_on_range (tuple):

the min and max p_on values to grid search over

p_off_range (tuple):

the min and max p_on values to grid search over

mu_step (int):

The number of values to grid search over for Parameters mu

mu_bg_step (int):

The number of values to grid search over for Parameters mu_bg

sigma_step (int):

The number of values to grid search over for Parameters sigma

p_on_step (int):

The number of values to grid search over for Parameters p_on

p_off_step (int):

The number of values to grid search over for Parameters p_on

blinx.estimate_parameters(traces, y, parameter_ranges, hyper_parameters)

Fit the fluorescence and trace model to the given traces, assuming that y fluorophores are present in each trace.

Args:

traces (tensor of shape (n, t)):

A list of n intensity traces over time.

y (int):

The number of fluorophores to consider.

parameter_ranges (ParameterRanges):

The fitting bounds for parameter optimization

hyper_parameters (HyperParameters):

The hyper-parameters used for the maximum likelihood estimation.

Returns:

parameters (Parameters):

the optimal set of fluorescence and kinetic model parameters for each trace (shape (n, k)), where k is the number of parameters.

log_likelihoods (array):

the maximum log likelihood for each trace (shape (n,))

blinx.estimate_y(traces, max_y, parameter_ranges=None, hyper_parameters=None)

Infer the most likely number of fluorophores for the given traces.

Args:

traces (tensor of shape (n, t)):

A list of n intensity traces over time.

max_y (int):

The maximal y (number of fluorophores) to consider.

parameter_ranges (ParameterRanges, optional):

The fitting bounds for each parameter to be optimized

hyper_parameters (HyperParameters, optional):

The hyper-parameters used for the maximum likelihood estimation.

Returns:

max_likelihood_y (array):

the maximum log likelihood solution for each trace (shape (n,))

parameters (Parameters):

the optimal set of fluorescence and kinetic model parameters for each trace and possible y (shape (n, m, k)), where m is the number of ys considered and k the number of parameters

log_likelihoods (array):

the maximum log likelihood for each trace and y (shape (n, m))