bounds - Parameter constraints

pm

Return the tuple (~v-dv,~v+dv), where ~expr is a 'nice' number near to to the value of expr. For example::.

pmp

Return the tuple (~v-%v,~v+%v), where ~expr is a 'nice' number near to the value of expr. For example::.

pm_raw

Return the tuple [v-dv,v+dv].

pmp_raw

Return the tuple [v-%v,v+%v]

nice_range

Given a range, return an enclosing range accurate to two digits.

init_bounds

Returns a bounds object of the appropriate type given the arguments.

Bounds

Bounds abstract base class.

Unbounded

Unbounded parameter.

Bounded

Bounded range.

BoundedAbove

Semidefinite range bounded above.

BoundedBelow

Semidefinite range bounded below.

Distribution

Parameter is pulled from a distribution.

Normal

Parameter is pulled from a normal distribution.

BoundedNormal

truncated normal bounds

SoftBounded

Parameter is pulled from a stretched normal distribution.

Parameter bounds and prior probabilities.

Parameter bounds encompass several features of our optimizers.

First and most trivially they allow for bounded constraints on parameter values.

Secondly, for parameter values known to follow some distribution, the bounds encodes a penalty function as the value strays from its nominal value. Using a negative log likelihood cost function on the fit, then this value naturally contributes to the overall likelihood measure.

Predefined bounds are:

Unbounded
    range (-inf, inf)
BoundedBelow
    range (base, inf)
BoundedAbove
    range (-inf, base)
Bounded
    range (low, high)
Normal
    range (-inf, inf) with gaussian probability
BoundedNormal
    range (low, high) with gaussian probability within
SoftBounded
    range (low, high) with gaussian probability outside

New bounds can be defined following the abstract base class interface defined in Bounds, or using Distribution(rv) where rv is a scipy.stats continuous distribution.

For generating bounds given a value, we provide a few helper functions:

v +/- d:  pm(x,dx) or pm(x,-dm,+dp) or pm(x,+dp,-dm)
    return (x-dm,x+dm) limited to 2 significant digits
v +/- p%: pmp(x,p) or pmp(x,-pm,+pp) or pmp(x,+pp,-pm)
    return (x-pm*x/100, x+pp*x/100) limited to 2 sig. digits
pm_raw(x,dx) or raw_pm(x,-dm,+dp) or raw_pm(x,+dp,-dm)
    return (x-dm,x+dm)
pmp_raw(x,p) or raw_pmp(x,-pm,+pp) or raw_pmp(x,+pp,-pm)
    return (x-pm*x/100, x+pp*x/100)
nice_range(lo,hi)
    return (lo,hi) limited to 2 significant digits
class bumps.bounds.Bounded(lo, hi)[source]

Bases: Bounds

Bounded range.

[lo,hi] <-> [0,1] scale is simple linear [lo,hi] <-> (-inf,inf) scale uses exponential expansion

While technically the probability of seeing any value within the range is 1/range, for consistency with the semi-infinite ranges and for a more natural mapping between nllf and chisq, we instead set the probability to 0. This choice will not affect the fits.

get01(x)[source]

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)[source]

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

put01(v)[source]

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)[source]

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)[source]

Return a randomly generated valid value.

target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

start_value()

Return a default starting value if none given.

to_dict()
class bumps.bounds.BoundedAbove(base)[source]

Bases: Bounds

Semidefinite range bounded above.

[-inf,base] <-> [0,1] uses logarithmic compression [-inf,base] <-> (-inf,inf) is direct below base-1, 1/(base-x) above

Logarithmic compression works by converting sign*m*2^e+base to sign*(e+1023+m), yielding a value in [0,2048]. This can then be converted to a value in [0,1].

Note that the likelihood function is problematic: the true probability of seeing any particular value in the range is infinitesimal, and that is indistinguishable from values outside the range. Instead we say that P = 1 in range, and 0 outside.

get01(x)[source]

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)[source]

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

put01(v)[source]

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)[source]

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)[source]

Return a randomly generated valid value.

target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

start_value()[source]

Return a default starting value if none given.

to_dict()
class bumps.bounds.BoundedBelow(base)[source]

Bases: Bounds

Semidefinite range bounded below.

The random initial condition is assumed to be within 1 of the maximum.

[base,inf] <-> (-inf,inf) is direct above base+1, -1/(x-base) below [base,inf] <-> [0,1] uses logarithmic compression.

Logarithmic compression works by converting sign*m*2^e+base to sign*(e+1023+m), yielding a value in [0,2048]. This can then be converted to a value in [0,1].

Note that the likelihood function is problematic: the true probability of seeing any particular value in the range is infinitesimal, and that is indistinguishable from values outside the range. Instead we say that P = 1 in range, and 0 outside.

get01(x)[source]

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)[source]

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

put01(v)[source]

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)[source]

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)[source]

Return a randomly generated valid value.

target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

start_value()[source]

Return a default starting value if none given.

to_dict()
class bumps.bounds.BoundedNormal(mean=0, std=1, limits=(-inf, inf))[source]

Bases: Bounds

truncated normal bounds

get01(x)[source]

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)[source]

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

put01(v)[source]

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)[source]

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)[source]

Return a randomly generated valid value, or an array of values

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

For the truncated normal distribution, we can just use the normal residuals.

start_value()[source]

Return a default starting value if none given.

to_dict()
class bumps.bounds.Bounds[source]

Bases: object

Bounds abstract base class.

A range is used for several purposes. One is that it transforms parameters between unbounded and bounded forms depending on the needs of the optimizer.

Another is that it generates random values in the range for stochastic optimizers, and for initialization.

A third is that it returns the likelihood of seeing that particular value for optimizers which use soft constraints. Assuming the cost function that is being optimized is also a probability, then this is an easy way to incorporate information from other sorts of measurements into the model.

get01(x)[source]

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)[source]

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

put01(v)[source]

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)[source]

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)[source]

Return a randomly generated valid value.

target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

start_value()[source]

Return a default starting value if none given.

to_dict()[source]
class bumps.bounds.Distribution(dist)[source]

Bases: Bounds

Parameter is pulled from a distribution.

dist must implement the distribution interface from scipy.stats. In particular, it should define methods rvs, nnlf, cdf and ppf and attributes args and dist.name.

get01(x)[source]

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)[source]

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

put01(v)[source]

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)[source]

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)[source]

Return a randomly generated valid value.

target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

start_value()

Return a default starting value if none given.

to_dict()[source]
class bumps.bounds.Normal(mean=0, std=1)[source]

Bases: Distribution

Parameter is pulled from a normal distribution.

If you have measured a parameter value with some uncertainty (e.g., the film thickness is 35+/-5 according to TEM), then you can use this measurement to restrict the values given to the search, and to penalize choices of this fitting parameter which are different from this value.

mean is the expected value of the parameter and std is the 1-sigma standard deviation.

get01(x)

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

put01(v)

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)

Return a randomly generated valid value.

target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

start_value()

Return a default starting value if none given.

to_dict()
class bumps.bounds.SoftBounded(lo, hi, std=None)[source]

Bases: Bounds

Parameter is pulled from a stretched normal distribution.

This is like a rectangular distribution, but with gaussian tails.

The intent of this distribution is for soft constraints on the values. As such, the random generator will return values like the rectangular distribution, but the likelihood will return finite values based on the distance from the from the bounds rather than returning infinity.

Note that for bounds constrained optimizers which force the value into the range [0,1] for each parameter we don’t need to use soft constraints, and this acts just like the rectangular distribution.

get01(x)[source]

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)[source]

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

put01(v)[source]

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)[source]

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)[source]

Return a randomly generated valid value.

target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

start_value()

Return a default starting value if none given.

to_dict()
class bumps.bounds.Unbounded[source]

Bases: Bounds

Unbounded parameter.

The random initial condition is assumed to be between 0 and 1

The probability is uniformly 1/inf everywhere, which means the negative log likelihood of P is inf everywhere. A value inf will interfere with optimization routines, and so we instead choose P == 1 everywhere.

get01(x)[source]

Convert value into [0,1] for optimizers which are bounds constrained.

This can also be used as a scale bar to show approximately how close to the end of the range the value is.

getfull(x)[source]

Convert value into (-inf,inf) for optimizers which are unconstrained.

limits = (-inf, inf)
nllf(value)[source]

Return the negative log likelihood of seeing this value, with likelihood scaled so that the maximum probability is one.

For uniform bounds, this either returns zero or inf. For bounds based on a probability distribution, this returns values between zero and inf. The scaling is necessary so that indefinite and semi-definite ranges return a sensible value. The scaling does not affect the likelihood maximization process, though the resulting likelihood is not easily interpreted.

put01(v)[source]

Convert [0,1] into value for optimizers which are bounds constrained.

putfull(v)[source]

Convert (-inf,inf) into value for optimizers which are unconstrained.

random(n=1, target=1.0)[source]

Return a randomly generated valid value.

target gives some scale independence to the random number generator, allowing the initial value of the parameter to influence the randomly generated value. Otherwise fits without bounds have too large a space to search through.

residual(value)[source]

Return the parameter ‘residual’ in a way that is consistent with residuals in the normal distribution. The primary purpose is to graphically display exceptional values in a way that is familiar to the user. For fitting, the scaled likelihood should be used.

To do this, we will match the cumulative density function value with that for N(0,1) and find the corresponding percent point function from the N(0,1) distribution. In this way, for example, a value to the right of 2.275% of the distribution would correspond to a residual of -2, or 2 standard deviations below the mean.

For uniform distributions, with all values equally probable, we use a value of +/-4 for values outside the range, and 0 for values inside the range.

start_value()

Return a default starting value if none given.

to_dict()
bumps.bounds.init_bounds(v)[source]

Returns a bounds object of the appropriate type given the arguments.

This is a helper factory to simplify the user interface to parameter objects.

bumps.bounds.nice_range(bounds)[source]

Given a range, return an enclosing range accurate to two digits.

bumps.bounds.pm(v, plus, minus=None, limits=None)[source]

Return the tuple (~v-dv,~v+dv), where ~expr is a ‘nice’ number near to to the value of expr. For example:

>>> r = pm(0.78421, 0.0023145)
>>> print("%g - %g"%r)
0.7818 - 0.7866

If called as pm(value, +dp, -dm) or pm(value, -dm, +dp), return (~v-dm, ~v+dp).

bumps.bounds.pm_raw(v, plus, minus=None)[source]

Return the tuple [v-dv,v+dv].

If called as pm_raw(value, +dp, -dm) or pm_raw(value, -dm, +dp), return (v-dm, v+dp).

bumps.bounds.pmp(v, plus, minus=None, limits=None)[source]

Return the tuple (~v-%v,~v+%v), where ~expr is a ‘nice’ number near to the value of expr. For example:

>>> r = pmp(0.78421, 10)
>>> print("%g - %g"%r)
0.7 - 0.87
>>> r = pmp(0.78421, 0.1)
>>> print("%g - %g"%r)
0.7834 - 0.785

If called as pmp(value, +pp, -pm) or pmp(value, -pm, +pp), return (~v-pm%v, ~v+pp%v).

bumps.bounds.pmp_raw(v, plus, minus=None)[source]

Return the tuple [v-%v,v+%v]

If called as pmp_raw(value, +pp, -pm) or pmp_raw(value, -pm, +pp), return (v-pm%v, v+pp%v).