cicobase package

Submodules

cicobase.get_endpoint module

cicobase.get_endpoint.get_endpoint(theta_init, theta_num, loss_func, method, direction='right', loss_crit=0.0, scale=[], theta_bounds=[], scan_bound=None, scan_tol=0.001, loss_tol=0.001, local_alg=28, **kwargs)

Calculates right or left endpoint of CI for parameter component. It is a wripper of get_right_endpoint functions for selection of direction and using different transformations for faster optimization.

Parameters:

  • theta_init (Array[Float64]) – starting values of parameter vector \(\Theta\). The starting values is not necessary to be the optimum values for loss_func but it the value of loss_func must be lower than loss_crit.

  • theta_num (Int) – number \(n\) of vector component to compute confidence interval \(\Theta^n\).

  • loss_func (Function) – loss function \(\Lambda\left(\Theta\right)\) the profile of which is analyzed. Usually we use log-likelihood for profile analysis in form \(\Lambda( \theta ) = - 2 ln\left( L(\Theta) \right)\).

  • method (String) – computational method to evaluate interval endpoint. Currently the following methods are implemented: "CICO_ONE_PASS", "LIN_EXTRAPOL", "QUADR_EXTRAPOL".

  • direction (String) – "right" or "left" endpoint to estimate.

  • loss_crit (Float64) – critical level of loss function. The endpoint of CI for selected parameter is the value at which profile likelihood meets the value of loss_crit.

  • scale (String) – vector of scale transformations for each component. Possible values: "direct", "log", "logit". This option can make optimization much more faster, especially for wide theta_bounds. The default value is "direct" (no transformation) for all components.

  • theta_bounds (Array[Array[Float64,Float64]]) – vector of bounds for each component in format \((left_border, right_border)\). This bounds define the ranges for possible parameter values. The defaults are the non-limited values taking into account the scale, i.e. \((0, Inf)\) for "log" scale.

  • scan_bounds (Array[Float64,Float64]) – vector of scan bound for theta_num component. It must be within the theta_bounds for the scanned component. The defaults are (-9., 9.) for transformed values, i.e. :math:`(1e-9, 1e9) for "log" scale.

  • scan_tol (Float64) – Absolute tolerance of scanned component (stop criterion).

  • loss_tol (Float64) – Absolute tolerance of loss_func at loss_crit (stop criterion). Restriction. Currently is not effective for nlopt.CICO_ONE_PASS methods because of limitation in nlopt.LN_AUGLAG interface.

  • local_alg (Function) – algorithm of optimization. Currently the local derivation free algorithms form NLOPT pack were tested. The methods: nlopt.LN_NELDERMEAD, nlopt.LN_COBYLA, nlopt.LN_PRAXIS show good results. Methods: nlopt.LN_BOBYQA, nlopt.LN_SBPLX, nlopt.LN_NEWUOA is not recommended.

  • **kwargs (Any) – the additional keyword arguments passed to get_right_endpoint for specific method.

Returns:

object storing confidence endpoint and profile points found on fly.

Return type:

class EndPoint

cicobase.get_interval module

class cicobase.get_interval.ParamInterval(input, loss_init, method, result)

Bases: object

Structure storing result of parameter interval calculation

Parameters:
plot()
class cicobase.get_interval.ParamIntervalInput(theta_init, theta_num, loss_func, loss_crit, scale, theta_bounds, scan_bounds, scan_tol, loss_tol, local_alg, fitter_options)

Bases: object

Calculates right or left endpoint of CI for parameter component. It is a wripper of get_right_endpoint functions for selection of direction and using different transformations for faster optimization.

Parameters:

  • theta_init (Array[Float64]) – initial parameters vector

  • theta_num (Int) – number of the parameter for analysis

  • loss_func (Function) – loss function

  • loss_crit (Float64) – loss function maximum value, “identifiability level

  • scale (Array[String])

  • theta_bounds (Array[[Float64, Float64]]) – search bounds for id parameter

  • scan_bounds (Float64)

  • scan_tol (Float64) – fitting tolerance for local optimizer (default - 1e-3)

  • loss_tol (Float64) – constraints tolerance

  • local_alg (Function) – local fitting algorithm (default - LN_NELDERMEAD)

  • fitter_options (Any)

cicobase.get_interval.get_interval(theta_init, theta_num, loss_func, method, loss_crit=0.0, scale=[], theta_bounds=[], scan_bounds=None, scan_tol=0.001, loss_tol=0.001, local_alg=28, **kwargs)

Computes confidence interval for single component theta_num of parameter vector and loss_func according to loss_crit level.

Parameters:

  • theta_init (Array[Float64]) – starting values of parameter vector \(\Theta\). The starting values is not necessary to be the optimum values for loss_func but it the value of loss_func must be lower than loss_crit.

  • theta_num (Int) – number n of vector component to compute confidence interval \(\Theta^n\).

  • loss_func (Function) – loss function \(\Lambda\left(\theta\right)\) the profile of which is analyzed. Usually we use log-likelihood for profile analysis in form \(\Lambda( \theta ) = - 2 ln\left( L(\theta) \right)\).

  • method (String) – computational method to evaluate interval endpoint. Currently the following methods are implemented: CICO_ONE_PASS, LIN_EXTRAPOL, QUADR_EXTRAPOL.

  • loss_crit (Float64) – critical level of loss function. The endpoint of CI for selected parameter is the value at which profile likelihood meets the value of loss_crit.

  • scale (String) – vector of scale transformations for each component. Possible values: "direct", "log", "logit". This option can make optimization much more faster, especially for wide theta_bounds. The default value is "direct" (no transformation) for all components.

  • theta_bounds (Array[Array[Float64,Float64]]) – vector of bounds for each component in format \((left_border, right_border)\). This bounds define the ranges for possible parameter values. The defaults are the non-limited values taking into account the scale, i.e. \((0, Inf)\) for "log" scale.

  • scan_bounds (Array[Float64,Float64]) – vector of scan bound for theta_num component. It must be within the theta_bounds for the scanned component. The defaults are (-9., 9.) for transformed values, i.e. :math:`(1e-9, 1e9) for "log" scale.

  • scan_tol (Float64) – Absolute tolerance of scanned component (stop criterion).

  • loss_tol (Float64) – Absolute tolerance of loss_func at loss_crit (stop criterion). Restriction. Currently is not effective for nlopt.CICO_ONE_PASS methods because of limitation in nlopt.LN_AUGLAG interface.

  • local_alg (Function) – algorithm of optimization. Currently the local derivation free algorithms form NLOPT pack were tested. The methods: nlopt.LN_NELDERMEAD, nlopt.LN_COBYLA, nlopt.LN_PRAXIS show good results. Methods: nlopt.LN_BOBYQA, nlopt.LN_SBPLX, nlopt.LN_NEWUOA is not recommended.

  • **kwargs (Any) – the additional keyword arguments passed to get_right_endpoint for specific method.

Returns:

structure storing all input data and estimated confidence interval.

Return type:

ParamInterval

cicobase.get_right_endpoint module

cicobase.get_right_endpoint.get_right_endpoint(theta_init, theta_num, loss_func, method='CICO_ONE_PASS', theta_bounds=[], scan_bound=9.0, scan_tol=0.001, loss_tol=None, scan_hini=1.0, scan_hmax=inf, local_alg=28, max_iter=100000, ftol_abs=0.001, **kwargs)

Interface for current and future methods for endpoint estimation.

Parameters:

  • theta_init (Array[Flaot64]) – theta_init: starting values of parameter vector \(\Theta\). The starting values is not necessary to be the optimum values for loss_func but it the value of loss_func must be lower than loss_crit.

  • theta_num (Int) – number \(n\) of vector component to compute confidence interval \(\Theta^n\).

  • loss_func (Function) – loss function the profile of which is analyzed, see get_interval. In this function loss crit is always equal 0 for code simplification.

  • method (String) – this value is always fixed. Implemented methods are: "CICO_ONE_PASS". It is implemented for easy switching between different implemented and future methods.

  • theta_bounds (Array[Array[Float64, Float64]]) – vector of bounds for each component in format \((left_bound, right_bound)\). This bounds define the ranges for possible parameter values.

  • scan_bound (Float64) – right scan bound for theta_num component. It must be within the theta_bounds for the scanned component.

  • scan_tol (Float64) – Absolute tolerance of scanned component (stop criterion).

  • loss_tol (Float64) – Absolute tolerance of loss_func at loss_crit (stop criterion). Restriction. Currently is not effective for nlopt.CICO_ONE_PASS methods because of limitation in nlopt.LN_AUGLAG interface.

  • local_alg (Function) – algorithm of optimization. Currently the local derivation free algorithms form NLOPT pack were tested. The methods: nlopt.LN_NELDERMEAD, nlopt.LN_COBYLA, nlopt.LN_PRAXIS show good results. Methods: nlopt.LN_BOBYQA, nlopt.LN_SBPLX, nlopt.LN_NEWUOA is not recommended.

  • **kwargs (Any) – the additional keyword arguments passed to get_right_endpoint for specific method.

Returns:

  • Right end point value: Float64.

  • Profile points estimated on fly: Array[ ProfilePoint, 1]

  • Status of sulution: String. One of values: "BORDER_FOUND_BY_SCAN_TOL", "SCAN_BOUND_REACHED".

Return type:

Array

cicobase.profile module

cicobase.profile.profile(theta_init, theta_num, loss_func, skip_optim=False, theta_bounds=None, local_alg=28, ftol_abs=0.001, **kwargs)

Short summary.

It generates the profile function based on loss_func. Used internally in methods "LIN_EXTRAPOL", "QUADR_EXTRAPOL".

theta_initArray[Float64]

starting values of parameter vector \(\Theta\). The starting values is not necessary to be the optimum values for loss_func but it the value of loss_func must be lower than loss_crit.

theta_numInt

number \(n\) of vector component to compute confidence interval \(\Theta^n\).

loss_funcFunction

loss function \(\Lambda\left(\Theta\right)\) the profile of which is analyzed. Usually we use log-likelihood for profile analysis in form \(\Lambda( \theta ) = - 2 ln\left( L(\Theta) \right)\).

skip_optimBool

set True if you need marginal profile, i.e. profile without optimization. Default is False.

theta_bounds :Array[Array[Float64,Float64]]

vector of bounds for each component in format \((left_border, right_border)\). This bounds define the ranges for possible parameter values. The defaults are the non-limited values taking into account the scale, i.e. \((0, Inf)\) for "log" scale.

local_algFunction

algorithm of optimization. Currently the local derivation free algorithms form NLOPT pack were tested. The methods: nlopt.LN_NELDERMEAD, nlopt.LN_COBYLA, nlopt.LN_PRAXIS show good results. Methods: nlopt.LN_BOBYQA, nlopt.LN_SBPLX, nlopt.LN_NEWUOA is not recommended.

ftol_absFloat64

absolute tolerance criterion for profile function.

**kwargsAny

the additional keyword arguments passed to get_right_endpoint for specific method.

returns:

Returns profile function for selected parameter component. Each call of the function starts optimization.

rtype:

Function

cicobase.structures module

class cicobase.structures.EndPoint(value, profilePoints, status, direction, counter, supreme)

Bases: object

Structure storing end point for confidence interval.

Parameters:

  • value (Float64 or None # value of endpoint or nothing)

  • profilePoints (Array[ProfilePoint] # vector of profile points)

  • status (String # result of analysis)

  • direction (String # "right" or "left")

  • counter (Int # number of loss_func() calls to calculate the endpoint)

  • supreme (Float64 or None # maximal value inside profile interval)

  • "BORDER_FOUND_BY_SCAN_TOL" (status values -)

  • "BORDER_FOUND_LOSS_TOL"

:param : :param “SCAN_BOUND_REACHED”: :param “MAX_ITER_STOP”: :param “LOSS_ERROR_STOP”:

class cicobase.structures.ProfilePoint(value, loss, params, ret, counter)

Bases: object

Structure storing one point from profile function.

Parameters:

  • value (Float64 # x value of profile point)

  • loss (Float64 # y value of profile point (loss function at value))

  • params (Array[Float64] # vector of optimal values of loss_func arguments)

  • ret (String # return value from NLOpt.optimize())

  • counter (Int # number of loss_func() calls to calculate the value)

  • -5 (ret values -)

  • 5

  • 3

Module contents