• Home
• uk.ac.sussex.gdsc
• gdsc-smlm
• 1.1
• source code
• fit.proto

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

uk.ac.sussex.gdsc.smlm.data.config.fit.proto Maven / Gradle / Ivy

syntax = "proto3";

// ProtoBuffer description file for configuration settings of the GDSC SMLM Java code.
// Authors: Alex Herbert, 2017
// License: GPL V3
package uk.ac.sussex.gdsc.smlm.data.config;

option java_outer_classname = "FitProtos";

// Define the fitting solver.
enum FitSolver {
  // Custom Levenberg-Marquardt least-squares estimation.
  // Uses the Hessian matrix with a Newton optimisation method that requires inversion of the Hessian.
  LVM_LSE = 0;
  // Custom Levenberg-Marquardt maximum-likelihood estimation for Poisson data using the method of Laurence & Chromy (2010) Nature Methods 7, 338-339.
  // Uses the Hessian matrix with a Newton optimisation method that requires inversion of the Hessian.
  // Parameters are bounded using a hard-stop limit to prevent negative function values being produced.
  LVM_MLE = 1;
  // Custom Levenberg-Marquardt weighted least-squares estimation for Poisson data using the method of Ruisheng, et al (2017) Optical Express 25, Issue 10, pp 11701-11716.
  // Uses the Hessian matrix with a Newton optimisation method that requires inversion of the Hessian.
  LVM_WLSE = 2;
  // Maximum Likelihood Estimator.
  // Uses a configurable noise model for the probability density function of the data.
  MLE = 3;
  // Maximum Likelihood Estimator for Poisson data using the method of Smith et al, (2010) Nature Methods 7, 373-375.
  // Uses a Newton-Raphson update step for fast convergence close to the optimum. The algorithm is unstable when the initial parameter estimate is poor.
  FAST_MLE = 4;
  // Maximum Likelihood Estimator for Poisson data using the method of Smith et al, (2010) Nature Methods 7, 373-375.
  // Uses a Newton-Raphson (NR) update step for fast convergence close to the optimum. The algorithm uses a backtracking algorithm to choose an appropriate step in the search direction when the NR step results in a worse estimation.
  BACKTRACKING_FAST_MLE = 5 [deprecated = true];
}

// Define the search method for the configurable maximum likelihood estimator.
enum SearchMethod
{
  // Search using Powell's conjugate direction method using hard limits to ensure a bounded search
  POWELL_BOUNDED = 0;
  // Search using Powell's conjugate direction method
  POWELL = 1;
  // Search using Powell's conjugate direction method using a mapping adapter to ensure a bounded search
  POWELL_ADAPTER = 2;
  // Search using Powell's Bound Optimization BY Quadratic Approximation (BOBYQA) algorithm.
  // BOBYQA could also be considered as a replacement of any derivative-based optimizer when the derivatives are
  // approximated by finite differences. This is a bounded search.
  BOBYQA = 3;
  // Search using active Covariance Matrix Adaptation Evolution Strategy (CMA-ES).
  // The CMA-ES is a reliable stochastic optimization method which should be applied if derivative-based methods,
  // e.g. conjugate gradient, fail due to a rugged search landscape. This is a bounded search.
  CMAES = 4;
  // Search using a non-linear conjugate gradient optimiser. Use the Fletcher-Reeves update formulas for the
  // conjugate search directions.
  // This is a bounded search using simple truncation of coordinates at the bounds of the search space.
  CONJUGATE_GRADIENT_FR = 5;
  // Search using a non-linear conjugate gradient optimiser. Use the Polak-Ribière update formulas for the
  // conjugate search directions.
  // This is a bounded search using simple truncation of coordinates at the bounds of the search space.
  CONJUGATE_GRADIENT_PR = 6;
  // Search using a Broyden-Fletcher-Goldfarb-Shanno (BFGS) gradient optimiser.
  BFGS = 7 [deprecated = true];
}

// Define the method to use when the Fast MLE line search direction is not in the same direction as
// that defined by the first derivative gradient.
enum LineSearchMethod
{
  // Do nothing to handle the incorrect orientation. The default solver action is taken.
  // This may cause the search to take an invalid move or it may error.
  NONE = 0;
  // Ignore any search direction that is in the opposite direction to the first derivative gradient.
  IGNORE = 1;
  // Progressively ignore any search direction that is in the opposite direction to the
  // first derivative gradient. Do this in order of the magnitude of the error.
  PARTIAL_IGNORE = 2;
}

// Define the method to use for precision calculation.
enum PrecisionMethod
{
  // Not available. The results may have been loaded from a source where the precision was computed
  // using another method, or the results may have no precision.
  PRECISION_METHOD_NA = 0;
  // Estimate using the formula of Mortensen, et al (2010) Nature Methods 7, 377-383.
  // The background noise component (b2) is computed using the variance of the fit region.
  // Note that computation of precision using this formula is relevant only for (EM-)CCD cameras
  // with a single Gaussian 2D PSF in the region. The formula is exact if the data is a 2D Gaussian
  // but can be used to approximate localisation precision on any spot-type PSF. There are formulas
  // for least squares or maximum likelihood estimators.
  MORTENSEN = 1;
  // Estimate using the formula of Mortensen, et al (2010) Nature Methods 7, 377-383.
  // The background noise component (b2) is computed using the fitted background of the fit region.
  // Note that computation of precision using this formula is relevant only for (EM-)CCD cameras
  // with a single Gaussian 2D PSF in the region. The formula is exact if the data is a 2D Gaussian
  // but can be used to approximate localisation precision on any spot-type PSF. There are formulas
  // for least squares or maximum likelihood estimators.
  MORTENSEN_LOCAL_BACKGROUND = 2;
  // Compute the Cramér-Rao lower bound (CRLB) assuming a Poisson process. This uses the method of
  // Smith et al, (2010). Fast, single-molecule localisation that achieves theoretically minimum
  // uncertainty. Nature Methods 7, 373-375 (supplementary note), Eq. 9. It has been extended
  // to a per-pixel noise component in Huang et al, (2015). Video-rate nanoscopy using sCMOS
  // camera–specific single-molecule localization algorithms. Nature Methods 10, 653–658.
  // Note that this formula is good when the number of photons is high. Due to the approximation
  // of Gaussian noise as a Poisson distribution the likelihood function used to generate the
  // Fisher information is poor when the number of photons is low, leading to an approximation
  // of the true CRLB of a Poisson-Gaussian distribution.
  // This method is suitable for a CCD or sCMOS camera. The Poisson noise model is less suitable
  // for an EMCCD camera (since the EM component modelled by a Gamma distribution is neglected)
  // but may still be used as an approximation.
  POISSON_CRLB = 3;
}

// Define settings for the fit solver.
message FitSolverSettings {
  // Set to true to fix the PSF using the initial parameters
  bool fixed_psf = 1;
  // Set to true to disable background fitting
  bool disable_background_fitting = 2;
  // Set to true to disable signal intensity fitting
  bool disable_signal_fitting = 3;

  // The type of fit solver
  FitSolver fit_solver = 4;
  // Set to true to use a fixed number of iterations during fitting
  bool fixed_iterations = 5;
  // The maximum/fixed iterations to use during fitting.
  // If not using fixed iterations then fitting will fail if this limit is reached.
  int32 max_iterations = 6;
  // The relative threshold for convergence on the function score. Set to negative to disable.
  double relative_threshold = 7;
  // The absolute threshold for convergence on the function score. Set to negative to disable.
  double absolute_threshold = 8;
  // The relative threshold for convergence on the function parameters. Set to negative to disable.
  double parameter_relative_threshold = 9;
  // The absolute threshold for convergence on the function parameters. Set to negative to disable.
  double parameter_absolute_threshold = 10;

  // The initial lambda parameter for the Levenberg-Marquardt algorithm
  double lambda = 11;

  // The search method to use for the configurable maximum likelihood estimator
  SearchMethod search_method = 12;
  // Set to true to use the function gradient during line minimisation, i.e. find the
  // parameters where the gradient is zero. The default is the to minimise the function value.
  bool gradient_line_minimisation = 13;
  // Set to true to model the camera noise in the configurable maximum likelihood estimator.
  bool model_camera = 14;
  // The maximum number of function evaluations in the configurable maximum likelihood estimator.
  int32 max_function_evaluations = 15;

  // Set to true to use parameter clamping
  bool use_clamping = 16;
  // Set to true to use dynamic parameter clamping, i.e. update the clamp values when the step direction changes
  bool use_dynamic_clamping = 17;
  // The initial clamp values for each of the PSF parameters.
  repeated double clamp_values = 18;

  // The line search method to use for the Fast MLE estimator
  LineSearchMethod line_search_method = 19;
}

// Define the settings for filtering fit results.
message FilterSettings {
  // Computation of precision using the local background has been removed and
  // replaced by precision method
  reserved 5;
  reserved "precision_using_background";

    // The maximum amount a localisation can move from the initial estimate relative to the PSF width
  double shift_factor = 1;
  // The minimum Signal-to-Noise (SNR) threshold
  double signal_strength = 2;
  // The minimum number of photons threshold
  double min_photons = 3;
  // The maximum allowed localisation precision (expressed as the localisation standard deviation)
  double precision_threshold = 4;
  // The minimum allowed width relative to the initial width estimate
  double min_width_factor = 6;
  // The maximum allowed width relative to the initial width estimate
  double max_width_factor = 7;
  // Set to true to disable the use of simple filters
  bool disable_simple_filter = 8;
  // Set to true to use a smart filter
  bool smart_filter = 9;
  // The smart filter expressed as a serialised string
  string smart_filter_string = 10;
  // The type of precision filter
  PrecisionMethod precision_method = 11;
  // The minimum z-depth
  double min_z = 12;
  // The maximum z-depth
  double max_z = 13;
}

// Define the settings for fitting. These settings are used to fit a PSF to an
// extracted region from the input data and validate the fit.
message FitSettings {
  // The fit solver settings
  FitSolverSettings fit_solver_settings = 1;

  // The filter settings
  FilterSettings filter_settings = 2;
}

// Define the type of filter used for identifying candidate peaks.
enum DataFilterType
{
  // Use a single filter
  SINGLE = 0;
  // Use a difference filter (the second subtracted from the first)
  DIFFERENCE = 1;
  // Use a jury of multiple filters
  JURY = 2;
}

// Define the method used to filter the input data before identifying candidate peaks
enum DataFilterMethod
{
  // Use a mean within a specified area
  MEAN = 0;
  // Use a mean within a specified box area. The box has integer size.
  BLOCK_MEAN = 1;
  // Use a mean within a specified circle area
  CIRCULAR_MEAN = 2;
  // Use a Gaussian with a specified radius
  GAUSSIAN = 3;
  // Use a median within a specified box area. The box has integer size.
  MEDIAN = 4;
}

// Define a parameter used during fitting that can be absolute of relative to the PSF width
message RelativeParameter {
  // The value of the parameter
  double value = 1;
  // Set to true to use the absolute value. The default is relative to the PSF width.
  bool absolute = 2;
}

// Define a data filter
message DataFilter {
  // The method used by the data filter
  DataFilterMethod data_filter_method = 1;
  // Any parameters used by the data filter. These can be in pixels
  // or relative to the PSF width.
  repeated RelativeParameter parameters = 2;
}

// Define the settings for filtering data to identify candidates.
message DataFilterSettings {
  // The type of data filter
  DataFilterType data_filter_type = 1;
  // The data filter
  repeated DataFilter data_filters = 2;
}

// Define the methods for noise estimation.
enum NoiseEstimatorMethod {
  // Use all pixels
  ALL_PIXELS = 0;
  // Use a range around the lowest pixel in the image
  LOWEST_PIXELS = 1;
  // Use the psuedo-residuals and calculate the least median of squares
  RESIDUALS_LEAST_MEDIAN_OF_SQUARES = 2;
  // Use the psuedo-residuals and calculate the least trimmed of squares
  RESIDUALS_LEAST_TRIMMED_OF_SQUARES = 3;
  // Use the psuedo-residuals and calculate the least mean of squares
  RESIDUALS_LEAST_MEAN_OF_SQUARES = 4;
  // Use the psuedo-residuals ignoring image border and calculate the least median of squares
  QUICK_RESIDUALS_LEAST_MEDIAN_OF_SQUARES = 5;
  // Use the psuedo-residuals ignoring image border and calculate the least trimmed of squares
  QUICK_RESIDUALS_LEAST_TRIMMED_OF_SQUARES = 6;
  // Use the psuedo-residuals ignoring image border and calculate the least mean of squares
  QUICK_RESIDUALS_LEAST_MEAN_OF_SQUARES = 7;
}

// Define the settings for the fit engine. These settings are used to identify
// candidates in the input data, extract regions for fitting, fit using various
// methods (single, multiple, doublet) and select the best fit.
message FitEngineSettings {
  // The fit settings
  FitSettings fit_settings = 1;

  // the method for estimating noise in the entire frame
  NoiseEstimatorMethod noise_method = 2;

  // The data filter settings
  DataFilterSettings data_filter_settings = 3;

  // The square radius to use to identify local maxima (candidates)
  RelativeParameter search = 4;
  // The border to ignore at the edge of the image
  RelativeParameter border = 5;
  // The square radius to use for fitting around each candidate
  RelativeParameter fitting = 6;

  // Set to true to include neighbours during fitting
  bool include_neighbours = 7;
  // The height threshold for including neighbours expressed relative to the current candidate
  double neighbour_height_threshold = 8;
  // The residuals threshold for refitting a single peak as a doublet following analysis of the symmetry of the fit residuals.
  double residuals_threshold = 9;
  // The distance to categorise localisations as duplicates and ignore them.
  RelativeParameter duplicate_distance = 10;

  // The number of consecutive failures to allow before stopping fitting of the remaining candidates.
  // Set to negative to disable.
  int32 failures_limit = 11;

  // The pass rate (range 0-1) to continue fitting. If the fraction of accepted fits falls below
  // this threshold then stop fitting of the remaining candidates. Set to zero to disable.
  double pass_rate = 12;
}