getpiecewiselines( intervals_y_st::Vector{T},
    intervals_y_fin::Vector{T},
    domain_proportion::T;
    lb::T = -one(T),
    ub::T = one(T))

Returns (in order):

• info::Piecewise2DLineType{T}
• scale::T

Computes the parameters (contained in info) of a piecewise-linear function. intervals_y_st and intervals_y_fin specify the starting and finishing y coordinates of line segments in the piecewise-linear function. The boundary points of the specified interval are automatically accounted for if they are not in intervals_y_st and intervals_y_fin.

Input constraints:

• 0 < domain_proportion < 1.
• intervals_y_st[k] < intervals_y_fin[k] for any valid index k of intervals_y_st and intervals_y_fin. See checkzstfin() for a function that checks this condition.

Example use of info and scale.

f = xx->evalpiecewise2Dlinearfunc(xx, info, scale)
finv = yy->evalinversepiecewise2Dlinearfunc(yy, info, scale)

f is an anonymous function that takes a value from the interval [lb, ub] to a value in [lb, ub]. It mathematically implements the piecewise-linear function created by getpiecewiselines(). finv is an anonymous function that implements the mathematic inverse of f.

Example

julia> intervals_y_st = [-0.82; 0.59];

julia> intervals_y_fin = [0.044; 0.97];

julia> lb = -2.0;

julia> ub = 1.0;

julia> domain_proportion = 0.9;

julia> info, scale = getpiecewiselines(intervals_y_st, intervals_y_fin, domain_proportion; lb = lb, ub = ub)
(Piecewise2DLineType{Float64}([-1.0, -0.8992027334851938, 0.03841784529294124, 0.08505793640911433, 0.4974373576309793, 0.5], [-1.0, -0.41, 0.022, 0.295, 0.485, 0.5], [5.853333333333337, 0.46074074074074073, 5.853333333333337, 0.4607407407407408, 5.853333333333337], [4.853333333333337, 0.004299333502067071, -0.20287245444801622, 0.2558103433729858, -2.4266666666666685], [0.9376205787781351, 0.41237942122186494], [0.432, 0.19]), 2.0)

julia> _, _, boundary_pts = getboundarypts(intervals_y_st, intervals_y_fin, lb, ub, info, scale);

julia> boundary_pts
6-element Vector{Tuple{Float64, Float64}}:
 (-2.0, -2.0)
 (-1.7984054669703875, -0.82)
 (0.07683569058588248, 0.044)
 (0.17011587281822874, 0.59)
 (0.9948747152619589, 0.97)
 (1.0, 1.0)

See /examples/piecewise_linear.jl for the full example.

checkzstfin(intervals_y_st::Vector{T}, intervals_y_fin::Vector{T}) where T <: Real

Returns true if intervals_y_st and intervals_y_fin are valid inputs as intervals_y_st and intervals_y_fin for getpiecewiselines().

evalpiecewise2Dlinearfunc(x::T, A::Piecewise2DLineType{T}, scale::T)::T where T <: Real

Evaluates the piecewise-linear function with parameters contained in A and scale at input x.

Obtain info and scale from getpiecewiselines().

evalinversepiecewise2Dlinearfunc(y::T, A::Piecewise2DLineType{T}, scale::T)::T where T <: Real

Evaluates the inverse of the piecewise-linear function f at input y, where f has parameters that are contained in A and scale.

Obtain info and scale from getpiecewiselines().

infos, zs, p_range = createendopiewiselines1(p_lb::T,
        p_ub::T,
        range_proportion::T;
        N_itp_samples::Int = 10,
        domain_proportion::T = 0.9) where T <: Real

Get the parameters for a set of N_itp_samples two-segment piecewise-linear functions. One of the segments is referred to as the focus interval. The inputs range_proportion and range_proportion specifies the properties of the focus interval/line segment for each constructed piecewise-linear function in the returned set.

The focus intervals of each function is recorded in p_range. They are evenly spaced between p_lb + range_proportion/2 and p_ub - range_proportion/2.

Inputs:

• p_lb::T: lower bound for the domain and range for each function.
• p_ub::T: upper bound for the domain and range for each function. Constraint: -one(T) <= p_lb < p_ub <= one(T).
• range_proportion::T: The proportion of the range for each function's focus interval. Takes a value between 0 and 1.
• N_itp_samples::Int: The number of functions to fit,
• domain_proportion::T: The proportion of the domain for each function's focus interval. Takes a value between 0 and 1.

Outputs

• infos::Piecewise2DLineType{T}: an internal datatype for use with evalpiecewise2Dlinearfunc() to evaluate the generated piecewise-linear functions.

For example, the following creates an anonymous function for the m-th piecewise-linear function:

info = infos[m]
f = xx->evalpiecewise2Dlinearfunc(xx, info)
f_evals = f.(LinRange(p_lb, p_ub, 200))

Note the usual scale input to evalpiecewise2Dlinearfunc() is not required for the piecewise-linear functions returned by createendopiewiselines1().

• zs::Vector{Vector{T}}: For a given index m in zs,

first(zs[m]) is the range coordinate of the start of the focus interval for the m-th piecewise-linear function. last(zs[m]) is the range coordinate of the end of the focus interval for the m-th piecewise-linear function.

Do the following to the get boundary points of the piecewise-linear function.

intervals_y_st = [first(zs[m]);]
intervals_y_fin = [last(zs[m]);]
start_pts, fin_pts, boundary_pts = IntervalMonoFuncs.getboundarypts(intervals_y_st, intervals_y_fin, lb, ub, infos[m], 1.0)

• p_range::LinRange{T,Int}: p_range[m] is the range coordinate of the center of the focus interval for the m-th function.

See /examples/fit_logistic-logit.jl in the package repository and the repository document website for other examples.

getlogisticprobitparameters(infos::Vector{Piecewise2DLineType{T}},
    runoptimfunc::Function;
    N_fit_positions::Int = 15,
    a_lb::T = 0.1,
    a_ub::T = 0.6,
    b_lb::T = -5.0,
    b_ub::T = 5.0,
    a_initial = (a_ub-a_lb)/2,
    b_initial = (b_ub-b_lb)/2) where T <: Real

Given a set of single-focus interval region piecewise-linear functions' parameters (collectively contained in info), fit the a and b parameters of the logistic-probit function (see evalcompositelogisticprobit) for each piecewise-linear function.

Inputs

• infos: obtained from createendopiewiselines1().

• runoptimfunc: This function runs an optimization routine that the user must supply.

IntervalMonoFuncs.jl does not currently ship with any optimization routines, nor does it use third party optimization routines as dependencies. This is done so that the user can have more flexibility to choose the optimization package and tuning parameters.

runoptimfunc should be in the following form:

runoptimfunc = (pp0, ff, dff, pp_lb, pp_ub)->runoptimroutine(pp0, ff, dff, pp_lb, pp_ub, other_args...)

where runoptimroutine() is the user-supplied routine for invoking their box-constrained numerical minimization code of choice. The other optimization package-specific tuning parameters can go where other_args... is. runoptimfunc() should return a Vector{T} that contains the solution to the numerical minimization of ff.

The pp0::Vector{T} input slot is the optimization variable initial guess slot. the ff::Function slot is for the cost function, It should be such that ff(pp0) is the cost associated with the initial guess. the dff::Function slot is for the gradient of the cost function, It should be such that dff(pp0 is the gradient of the cost function evaluated at the initial guess, but one can assign it any function (such as the identity xx->xx) if they are not using a gradient-based optimization algorithm in their runoptimfunc(). the pp_lb::Vector{T} slot is for the lower bounds of the optimization variable, the pp_ub::Vector{T} slot is for the upper bounds of the variable.

runoptimfunc() must return a 1D array of type Vector{T}, where T = eltype(pp0).

There are examples on how to create a valid runoptimfunc on the repository documentation website and in /examples/fit_logistic-logit.jl.

Optional inputs:

• Nfitpositions: The number of fit positions used in the optimization.
• a_lb: lower bound used for optimizing a
• a_ub: lower bound used for optimizing a
• b_lb: lower bound used for optimizing b
• b_ub: lower bound used for optimizing b
• a_initial: initial guess for a
• b_initial: initial guess for b

Outputs (in order):

• costfuncs::Vector{Function}: the costfunction used to optimize each logistic-probit function against its corresponding piecewise-linear function.
• minxs::Vector{Vector{T}}: 1-D array of solution arrays.

first(minxs[m]) is the optimized a variable for the m-th logistic-probit function. last(minxs[m]) is the optimized b variable for the m-th logistic-probit function.

Usage for minxs: The following creates a vector of functions, each implements a fitted logistic-probit function.

qs = collect( tt->IntervalMonoFuncs.evalcompositelogisticprobit(tt, first(minxs[i]), last(minxs[i])) for i in eachindex(minxs) )

evalcompositelogisticprobit(x::T, a::T, b::T)::T where T <: Real

evaluates the map from (0,1) to (0,1). returns 1/(1 + exp(-a*(log(x/(1-x))-b)))

Some numerical stability issues when the magnitudes of a or b is larger than 2 when T = Float64. See /examples/logistic-probit.jl for an example of stability test in the root package directory.

evalcompositelogisticprobit(x_inp::T, a::T, b::T, lb::T, ub::T)::T where T <: Real

Applies the following:

• Transforms y from [lb,ub] to (0,1).
• evaluates the map, 1/(1 + exp(-a*(log(x/(1-x))-b))), which transforms a value from (0,1) to (0,1).
• transforms the evaluated map value from (0,1) to [lb,ub], and returns the result.

Some numerical stability issues when the magnitudes of a or b is larger than 2 when T = Float64. See /examples/logistic-probit.jl for an example of stability test in the root package directory.

evalinversecompositelogisticprobit(y::T, a::T, b::T)::T where T <: Real

evaluates the map from (0,1) to (0,1). return exp(b)/(exp(b) + (-1 + 1/y)^(1/a))

Some numerical stability issues when the magnitudes of a or b is larger than 2 when T = Float64. See /examples/logistic-probit.jl for an example of stability test in the root package directory.

evalinversecompositelogisticprobit(y::T, a::T, b::T)::T where T <: Real

Applies the following:

• Transforms y from [lb,ub] to (0,1).
• evaluates the map, exp(b)/(exp(b) + (-1 + 1/y)^(1/a)), which transforms a value from (0,1) to (0,1).
• transforms the evaluated map value from (0,1) to [lb,ub], and returns the result.

Some numerical stability issues when the magnitudes of a or b is larger than 2 when T = Float64. See /examples/logistic-probit.jl for an example of stability test in the root package directory.