API Reference

UnivariateFunction

An abstract type. The concrete structs that have been implemented are UndefinedFunction, PEFunction, SumOfFunctions, Piecewise_Function.

Undefined_Function <: UnivariateFunction

This function throws an error if you ever try to evaluate it. Think of it as doing the role of missing but for UnivariateFunctions

PE_Function{F<:Real,I<:Integer} <: UnivariateFunction

This function has the functional form: a exp(b(x-base)) (x-base)^d Where a,b,base are floats and d is a positive integer. These four are the members of the struct.

Sum_Of_Functions <: UnivariateFunction

This function contains a vector of UnivariateFunctions. When evaluated it adds the evaluations of these functions and returns the sum.

Piecewise_Function <: UnivariateFunction

This function contains a vector of locations in the x space and a vector of UnivariateFunctions. When evaluated it uses these vectors as a lookup. It chooses the correct UnivariateFunction and evaluates it.

evaluate(f::UnivariateFunction, r::Real)
evaluate(f::UnivariateFunction, d::Q) where Q<:Union{Date,DateTime,ZonedDateTime}
evaluate(f::UnivariateFunction, x::DatePeriod)

This evaluates the function at the requested point. If a Date, DateTime is input then it is first converted to a scalar with the years_from_global_base_date function. DatePeriods are converted with the period_length function.

derivative(f::UnivariateFunction)

This calculates the derivative of the function and returns it as a UnivariateFunction.

Inputs

• f - A UnivariateFunction.

Returns

• A UnivariateFunction.

indefinite_integral(f::UnivariateFunction)

This calculates the indefinite integral of a UnivariateFunction.

Inputs

• f - A UnivariateFunction.

Returns

• A UnivariateFunction.

evaluate_integral(f::UnivariateFunction,left::AbstractFloat, right::AbstractFloat)
evaluate_integral(f::UnivariateFunction,left::Q, right::W) where Q<:Union{Date,DateTime,ZonedDateTime} where W<:Union{Date,DateTime,ZonedDateTime}

This calculates the integral of a function from a left limit to a right limit and returns a scalar.

If a Date, DateTime is input then it is first converted to a scalar with the years_from_global_base_date function.

Inputs

• f - A UnivariateFunction.
• left - A left limit (scalar)
• right - A right limit (scalar)

Returns

• A Real.

right_integral(f::UnivariateFunction, left::Real)
right_integral(f::UnivariateFunction, left::Q) where Q<:Union{Date,DateTime,ZonedDateTime}

This calculates the integral of a function from a left limit and returns it as a UnivariateFunction. So if you were to then evaluate this integral function at a point x then you would get the integral between left and x.

If a Date, DateTime is input then it is first converted to a scalar with the years_from_global_base_date function.

Inputs

• f - A UnivariateFunction.
• left - A left limit (scalar)

Returns

• A UnivariateFunction.

left_integral(f::UnivariateFunction, right::Real)
left_integral(f::UnivariateFunction, right::Q) where Q<:Union{Date,DateTime,ZonedDateTime}

This calculates the integral of a function from a right limit and returns it as a UnivariateFunction. So if you were to then evaluate this integral function at a point x then you would get the integral between right and x.

If a Date, DateTime is input then it is first converted to a scalar with the years_from_global_base_date function.

Inputs

• f - A UnivariateFunction.
• right - A right limit (scalar)

Returns

• A UnivariateFunction.

create_quadratic_spline(x::Vector{Q},y::Vector{<:Real} ; gradients::Union{Missing,Vector{<:Real}} = missing, extrapolation::Tuple{Schumaker_ExtrapolationSchemes,Schumaker_ExtrapolationSchemes} = (Curve,Curve),
                             left_gradient::Union{Missing,Real} = missing, right_gradient::Union{Missing,Real} = missing) where Q<:Union{Date,DateTime,ZonedDateTime}
create_quadratic_spline(x::Vector{<:Real},y::Vector{<:Real} ; gradients::Union{Missing,Vector{<:Real}} = missing, extrapolation::Tuple{Schumaker_ExtrapolationSchemes,Schumaker_ExtrapolationSchemes} = (Curve,Curve),
                             left_gradient::Union{Missing,Real} = missing, right_gradient::Union{Missing,Real} = missing)
create_quadratic_spline(x::Union{Vector{D},Vector{<:DatePeriod}},y::Vector{<:Real}; gradients::Union{Missing,Vector{<:Real}} = missing, extrapolation::Tuple{Schumaker_ExtrapolationSchemes,Schumaker_ExtrapolationSchemes} = (Curve,Curve),
                             left_gradient::Union{Missing,Real} = missing, right_gradient::Union{Missing,Real} = missing) where D<:DatePeriod

Makes a quadratic shape-preserving interpolation spline using the SchumakerSpline.jl package. This is returned as a Piecewise_Function rather than as a Schumaker struct.

Inputs

• x - A Vector with the x coordinates
• y - A Vector with the y coordinates
• gradients - A Vector with the gradiants at each x location. This is calculated if not provided.
• extrapolation - A tuple of enum value describing how to extrapolate (on the left and right sides).
• left_gradient - The gradiant to impose on the left edge (ie the first x coordinate).
• right_gradient - The gradiant to impose on the right edge (ie the last x coordinate).

Returns

• A Piecewise_Function containing the spline.

create_quadratic_spline(schum::Schumaker)

This converts a spline represented by a SchumakerSpline.Schumaker struct into the same spline but represented by a Piecewise_Function.

Inputs

• schum - A Schumaker struct.

Returns

• A Piecewise_Function containing the spline.

create_constant_interpolation_to_right(x::Vector{Date},y::Vector{<:Real})
create_constant_interpolation_to_right(x::Vector{<:Real},y::Vector{<:Real})
create_constant_interpolation_to_right(x::Union{Vector{D},Vector{<:DatePeriod}},y::Vector{<:Real}) where D<:DatePeriod

Makes a piecewise constant interpolation function. values from the left are copied to the right.

Inputs

• x - A Vector with the x coordinates
• y - A Vector with the y coordinates

Returns

• A Piecewise_Function containing the interpolation function.

create_constant_interpolation_to_left(x::Vector{Date},y::Vector{<:Real})
create_constant_interpolation_to_left(x::Vector{<:Real},y::Vector{<:Real})
create_constant_interpolation_to_left(x::Union{Vector{D},Vector{<:DatePeriod}},y::Vector{<:Real}) where D<:DatePeriod

Makes a piecewise constant interpolation function. values from the right are copied to the left.

Inputs

• x - A Vector with the x coordinates
• y - A Vector with the y coordinates

Returns

• A Piecewise_Function containing the interpolation function.

create_linear_interpolation(x::Vector{Date},y::Vector{<:Real})
create_linear_interpolation(x::Union{Vector{D},Vector{<:DatePeriod}},y::Vector{<:Real}) where D<:DatePeriod
create_linear_interpolation(x::Vector{R},y::Vector{<:Real}) where R<:Real

Makes a piecewise linear interpolation function. This is continuous.

Inputs

• x - A Vector with the x coordinates
• y - A Vector with the y coordinates

Returns

• A Piecewise_Function containing the interpolation function.

simplify(f::Piecewise_Function, n_points::Integer, left::Real, right::Real, method::Symbol = :linear)
simplify(f::Piecewise_Function, n_points::Integer, left::Q, right::Q, method::Symbol = :linear) where Q<:Union{Date,DateTime,ZonedDateTime}

Approximates a Piecewise_Function with a simpler one by evaluating at n_points evenly spaced points over [left, right] and re-interpolating.

Inputs

• f - A Piecewise_Function to simplify.
• n_points - The number of evenly spaced sample points.
• left - The left boundary of the domain.
• right - The right boundary of the domain.
• method - The interpolation method. One of :constant_right, :constant_left, :linear, :quadratic.

Returns

• A Piecewise_Function.

UnivariateFitter

A mutable struct for iteratively fitting univariate functions with shape constraints. Each call to fit! fits new data and optionally blends with the previous fit via weight_on_new. Periodic simplification reduces the complexity of the accumulated Piecewise_Function.

Fields

• fun - The current fitted UnivariateFunction.
• method - Fitting method. One of :increasing, :decreasing, :convex, :concave, :quasiconvex, :quasiconcave, :supersmoother.
• times_through - Number of times fit! has been called.
• simplification_frequency - Simplify the function every this many calls to fit!. 0 disables simplification.
• nbins - Number of bins for the regression and for simplification.
• equally_spaced_bins - If true, bins are equally spaced in x; if false, based on observation quantiles.
• weight_on_new - Blending weight in [0,1]. 1.0 means only the new fit is used; lower values blend with the previous fit.
• left_ - Left boundary for simplification domain.
• right_ - Right boundary for simplification domain.

Constructor

UnivariateFitter(method::Symbol; nbins=10, equally_spaced_bins=true,
                 weight_on_new=1.0, simplification_frequency=0,
                 left=-Inf, right=Inf)

Creates a UnivariateFitter initialised with a zero function.

fit!(fitter::UnivariateFitter, x_new, y_new)

Fit the UnivariateFitter to new data x_new, y_new. The fitted function is blended with the previous fit according to fitter.weight_on_new. If simplification_frequency > 0 and the current iteration is a multiple, the function is simplified via resampling.

create_ols_approximation(y::Vector{<:Real}, x::Vector{<:Real}, base_x::Real = 0.0, degree::Integer = 1, intercept::Bool = true)
create_ols_approximation(y::Vector{<:Real}, x::Vector{Q}, base_x::Union{Date,DateTime} = global_base_date, degree::Integer = 1, intercept::Bool = true) where Q<:Union{Date,DateTime,ZonedDateTime}

An approximation function calculated via OLS.

Inputs

• y - A Vector with the y coordinates
• x - A Vector with the x coordinates
• base_x - A real that offsets the x. So a coordinate with x value of 2.0 will be converted to 1.8 if base_x is 0.2.
• degree - What the highest power of x should be. So if this is 3 then the equation will have x, x^2, x^3 as predictors.
• intercept - Should there be an x intercept.

Returns

• A Sum_Of_Functions containing the approximation function.

create_chebyshev_approximation(func::Function, nodes::Integer, degree::Integer, left::Real, right::Real)

An function that will approximate another function via Chebyshev polynomials.

Inputs

• func - A function that you want to approximation
• nodes - The number of approximation nodes
• degree - The degree of the Chebyshev polynomials.
• left - The left limit of the approximation
• right - The right limit of the approximation.

Returns

• A Sum_Of_Functions containing the approximation function.

supersmoother(x::Vector{R}, y::Vector{R}; 
              spans::Vector{R} = [0.05, 0.2, 0.5],
              bass::R = 0.0) where R<:Real

Friedman's SuperSmoother (1984) - a local linear regression with adaptive bandwidth.

Returns a Piecewise_Function (linear interpolation of smoothed values).

Arguments

• x: Independent variable values
• y: Dependent variable values
• spans: Candidate spans to consider (fraction of data points). Default [0.05, 0.2, 0.5]
• bass: Bass enhancement (0-10). Higher values favor smoother fits. Default 0.0

Example

f = supersmoother(x, y)
f(2.5)  # evaluate at new point
derivative(f)  # get derivative function

isotonic_regression(x, y; increasing=true)

Fit an isotonic (monotonic step function) regression using the Pool Adjacent Violators (PAV) algorithm.

Arguments

• x: Independent variable values
• y: Dependent variable values
• increasing: If true, fit monotonically increasing function; if false, decreasing. Default true

Returns a Piecewise_Function representing the isotonic fit.

Example

x = collect(1.0:10.0)
y = x .+ randn(10)
fit = isotonic_regression(x, y; increasing=true)
fit(5.5)  # evaluate at new point

monotonic_regression(x, y; nbins=10, equally_spaced_bins=true, increasing=true)

Fit a piecewise linear monotonic regression using nonnegative least squares.

This method divides the x-domain into bins and fits a piecewise linear function with nonnegative slopes (for increasing) or nonpositive slopes (for decreasing).

Arguments

• x: Independent variable values
• y: Dependent variable values
• nbins: Number of bins for the piecewise linear fit. Default 10
• equally_spaced_bins: If true, bins are equally spaced in x; if false, based on observation quantiles. Default true
• increasing: If true, fit monotonically increasing function; if false, decreasing. Default true

Returns a Piecewise_Function representing the monotonic fit.

Example

x = collect(range(0, 5, length=100))
y = sqrt.(x) .+ 0.1 .* randn(100)
fit = monotonic_regression(x, y; nbins=15, increasing=true)
fit(2.5)  # evaluate at new point
derivative(fit)  # get derivative function

unimodal_regression(x, y; nbins=10, equally_spaced_bins=true, convex=false, quasi=true)

Fit a unimodal regression function to the data.

Arguments

• x: Independent variable values
• y: Dependent variable values
• nbins: Number of bins for piecewise linear fit
• equally_spaced_bins: If true, bins are equally spaced; if false, based on observation quantiles
• convex: If false, fits concave/quasiconcave (single maximum); if true, fits convex/quasiconvex (single minimum)
• quasi: If true, only enforces unimodality (slopes change sign once); if false, also enforces curvature

Shape constraints:

• convex=false, quasi=true: Quasiconcave - slopes go from + to - (single peak)
• convex=true, quasi=true: Quasiconvex - slopes go from - to + (single trough)
• convex=false, quasi=false: Concave - slopes monotonically decrease
• convex=true, quasi=false: Convex - slopes monotonically increase

Returns a Piecewise_Function.

cv_monotonic_regression(x, y; nbins=10, equally_spaced_bins=true, nfolds=10, seed=nothing)

Fit monotonic regression, automatically selecting increasing vs decreasing based on k-fold cross-validation error.

Returns a CVRegressionResult containing:

• fitted: The fitted function (using full dataset)
• selected_shape: Either :increasing or :decreasing
• cv_errors: Dict mapping each shape to its CV error
• nfolds: Number of folds used

cv_unimodal_regression(x, y; nbins=10, equally_spaced_bins=true, nfolds=10, seed=nothing)

Fit unimodal regression, automatically selecting among:

• :quasiconcave (convex=false, quasi=true)
• :quasiconvex (convex=true, quasi=true)
• :concave (convex=false, quasi=false)
• :convex (convex=true, quasi=false)

based on k-fold cross-validation error.

Returns a CVRegressionResult containing:

• fitted: The fitted function (using full dataset)
• selected_shape: One of the four shape symbols
• cv_errors: Dict mapping each shape to its CV error
• nfolds: Number of folds used

cv_shape_regression(x, y; shapes=:all, nbins=10, equally_spaced_bins=true, nfolds=10, seed=nothing)

Fit regression with automatic shape selection via cross-validation.

shapes can be:

• :monotonic - choose between increasing/decreasing
• :unimodal - choose between quasiconcave/quasiconvex/concave/convex
• :all - choose from all 6 shapes
• A vector of symbols, e.g. [:increasing, :quasiconcave, :convex]

Available shapes: :increasing, :decreasing, :quasiconcave, :quasiconvex, :concave, :convex

Returns a CVRegressionResult with the fitted function and selection metadata.

CVRegressionResult{F<:UnivariateFunction}

Result type for cross-validated regression model selection.

Fields

• fitted::F: The fitted UnivariateFunction (typically a Piecewise_Function)
• selected_shape::Symbol: The shape that was selected (e.g., :increasing, :quasiconcave)
• cv_errors::Dict{Symbol, Float64}: Cross-validation errors for each candidate shape
• nfolds::Int: Number of folds used in cross-validation

The result is callable - you can use it directly as a function:

result = cv_shape_regression(x, y)
result(2.5)  # equivalent to result.fitted(2.5)

change_base_of_PE_Function(f::PE_Function, new_base::Real)

This changes the base of a PE_Function. So if the base was 2 then it can be converted to 3 with an additional constant term.

Inputs

• f - A PE_Function.
• new_base - The new base.

Returns

• A PE_Function or a Sum_Of_Functions.

trim_piecewise_function(func::Piecewise_Function, left_limit::Real, right_limit::Real)

This trims the end of a piecewise function. So if there is a piecewise function with support between -10,10 then you can trim it to only have support between -5 and 5. Then if it is evaluated outside -5 to 5 it will be undefined.

Inputs

• func - A Piecewise_Function.
• left_limit - The left limit.
• right_limit - The right limit.

Returns

• A Piecewise_Function.

convert_to_linearly_rescale_inputs(f::UnivariateFunction, alpha::Real, beta::Real)

Creates a new function g such that g(alpha * x + beta) = f(x), or equivalently g(y) = f((y - beta) / alpha). This remaps the domain of f so that the input range [x_lo, x_hi] maps to [alpha * x_lo + beta, alpha * x_hi + beta].

Inputs

• f - A UnivariateFunction.
• alpha - The slope of the domain rescaling.
• beta - The offset of the domain rescaling.

Returns

• A UnivariateFunction of the type that you input to the function.

get_chebyshevs_up_to(N::Integer, first_kind::Bool = true)

Get the first N chebyshev polynomials returned as a vector of UnivariateFunctions. The first 20 polynomials of each are precompiled into the binaries for speed. If you need more than that they will be calculated at runtime.

These can be from either the first kind or second kind polynomial sequence.

Inputs

• N - How many chebyshev polynomials do you want.
• first_kind - A Bool. If true you get first kind polynomials. If false you get second kind.

Returns

• A Vector of UnivariateFunctions for each polynomial.

_kfold_indices(n::Int, nfolds::Int; seed::Union{Int,Nothing}=nothing)

Generate random fold assignments for k-fold CV. Returns a vector of length n with values 1:nfolds.

_cv_error(x, y, fold_indices, fit_func; kwargs...)

Compute total cross-validation SSE for a given fitting function.

_local_linear_smooth(x::Vector{R}, y::Vector{R}, span::R) where R<:Real

Compute local linear regression smoothed values for all points. span is the fraction of data points to use in each local fit (0 < span ≤ 1).

_local_linear_loo_residuals(x::Vector{R}, y::Vector{R}, span::R) where R<:Real

Compute leave-one-out residuals for local linear regression at given span. Returns |yᵢ - ŷ₋ᵢ| for each point (prediction without using point i).

_smooth_values(x::Vector{R}, v::Vector{R}, span::R) where R<:Real

Smooth a vector v using local mean with given span. Used to smooth the span selection.

_supersmoother_values(x::Vector{R}, y::Vector{R}; 
                      spans::Vector{R} = [0.05, 0.2, 0.5],
                      bass::R = 0.0) where R<:Real

Core SuperSmoother algorithm. Returns smoothed y values.

• spans: The three candidate spans to try (fraction of data)
• bass: Bass enhancement parameter (0-10). Higher values produce smoother results.

seconds_between(a::Union{ZonedDateTime,DateTime,Date}, b::Union{ZonedDateTime,DateTime,Date})

The number of seconds between two dates. This is the delta between two unixtimes.

Inputs

• a - The end date
• b - The start date.

Returns

• A Real.

days_between(a, b)

The number of days between two dates. Computed as seconds_between(a, b) / 86400.

Inputs

• a - The end date (ZonedDateTime, DateTime, or Date)
• b - The start date (ZonedDateTime, DateTime, or Date)

Returns

• A Real representing the number of days (can be fractional).

Example

days_between(Date(2020, 1, 11), Date(2020, 1, 1))  # 10.0
days_between(DateTime(2020, 1, 1, 12, 0, 0), DateTime(2020, 1, 1, 0, 0, 0))  # 0.5

years_between(a, b)

The number of years between two dates. Computed as seconds_between(a, b) / (365.25 * 86400).

Inputs

• a - The end date (ZonedDateTime, DateTime, or Date)
• b - The start date (ZonedDateTime, DateTime, or Date)

Returns

• A Real representing the number of years (can be fractional).

Example

years_between(Date(2021, 1, 1), Date(2020, 1, 1))  # approximately 1.0
years_between(Date(2020, 7, 1), Date(2020, 1, 1))  # approximately 0.5

period_length(period::Dates.DatePeriod)

Converts a DatePeriod to a float representing years, measured from global_base_date. So effectively the years_between method is calculated with start and end dates being those at the start and end of the period. This is slightly complicated because a period like Month(3) might have slightly different numbers of total days depending on when in the year it is, so the period is always measured starting from global_base_date.

Inputs

• period - A Dates.DatePeriod.

Returns

• A Real representing the period length in years.

years_from_global_base_date(a)

The number of years between a date and the global base date (1970-01-01 00:00:00 UTC).

This is used internally to convert dates to floats for use in PE_Function bases.

Inputs

• a - A ZonedDateTime, DateTime, or Date

Returns

• A Real representing the number of years since 1970-01-01.

Example

years_from_global_base_date(Date(1970, 1, 1))  # 0.0
years_from_global_base_date(Date(2020, 1, 1))  # approximately 50.0

zdt2unix(d)

Convert a ZonedDateTime, DateTime, or Date to Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).

Inputs

• d - A ZonedDateTime, DateTime, Date, or missing

Returns

• An Int representing seconds since Unix epoch, or missing if input is missing.

Example

zdt2unix(Date(2020, 1, 1))  # 1577836800
zdt2unix(DateTime(2020, 1, 1, 12, 0, 0))  # 1577880000

unix2zdt(seconds_since_1970, tzz=tz"UTC")

Convert Unix timestamp (seconds since 1970-01-01 00:00:00 UTC) to a ZonedDateTime.

Inputs

• seconds_since_1970 - Unix timestamp as Integer, Real, or missing
• tzz - Timezone (default: UTC)

Returns

• A ZonedDateTime, or missing if input is missing.

Example

unix2zdt(1577836800)  # 2020-01-01T00:00:00+00:00
unix2zdt(0, tz"America/New_York")  # 1969-12-31T19:00:00-05:00

unix2dt(seconds_since_1970)

Convert Unix timestamp (seconds since 1970-01-01 00:00:00 UTC) to a DateTime.

Inputs

• seconds_since_1970 - Unix timestamp as Integer, Real, or missing

Returns

• A DateTime, or missing if input is missing.

Example

unix2dt(1577836800)  # 2020-01-01T00:00:00

unix2d(seconds_since_1970)

Convert Unix timestamp (seconds since 1970-01-01 00:00:00 UTC) to a Date.

Inputs

• seconds_since_1970 - Unix timestamp as Integer, Real, or missing

Returns

• A Date, or missing if input is missing.

Example

unix2d(1577836800)  # 2020-01-01