diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml index 9c793591..959ad88a 100644 --- a/.JuliaFormatter.toml +++ b/.JuliaFormatter.toml @@ -1,2 +1,3 @@ style = "sciml" -format_markdown = true \ No newline at end of file +format_markdown = true +format_docstrings = true \ No newline at end of file diff --git a/ext/DataInterpolationsRegularizationToolsExt.jl b/ext/DataInterpolationsRegularizationToolsExt.jl index 28e8c47b..47d63dbf 100644 --- a/ext/DataInterpolationsRegularizationToolsExt.jl +++ b/ext/DataInterpolationsRegularizationToolsExt.jl @@ -32,35 +32,39 @@ const LA = LinearAlgebra """ # Arguments -- `u::Vector`: dependent data. -- `t::Vector`: independent data. + + - `u::Vector`: dependent data. + - `t::Vector`: independent data. # Optional Arguments -- `t̂::Vector`: t-values to use for the smooth curve (useful when data has missing values or - is "scattered"); if not provided, then `t̂ = t`; must be monotonically - increasing. -- `wls::{Vector,Symbol}`: weights to use with the least-squares fitting term; if set to - `:midpoint`, then midpoint-rule integration weights are used for - _both_ `wls` and `wr`. -- `wr::Vector`: weights to use with the roughness term. -- `d::Int = 2`: derivative used to calculate roughness; e.g., when `d = 2`, the 2nd - derivative (i.e. the curvature) of the data is used to calculate roughness. + + - `t̂::Vector`: t-values to use for the smooth curve (useful when data has missing values or + is "scattered"); if not provided, then `t̂ = t`; must be monotonically + increasing. + - `wls::{Vector,Symbol}`: weights to use with the least-squares fitting term; if set to + `:midpoint`, then midpoint-rule integration weights are used for + _both_ `wls` and `wr`. + - `wr::Vector`: weights to use with the roughness term. + - `d::Int = 2`: derivative used to calculate roughness; e.g., when `d = 2`, the 2nd + derivative (i.e. the curvature) of the data is used to calculate roughness. # Keyword Arguments -- `λ::{Number,Tuple} = 1.0`: regularization parameter; larger values result in a smoother - curve; the provided value is used directly when `alg = :fixed`; - otherwise it is used as an initial guess for the optimization - method, or as bounds if a 2-tuple is provided (TBD) -- `alg::Symbol = :gcv_svd`: algorithm for determining an optimal value for λ; the provided λ - value is used directly if `alg = :fixed`; otherwise `alg = - [:gcv_svd, :gcv_tr, :L_curve]` is passed to the - RegularizationTools solver. -- `extrapolate::Bool` = false: flag to allow extrapolating outside the range of the time points provided. + + - `λ::{Number,Tuple} = 1.0`: regularization parameter; larger values result in a smoother + curve; the provided value is used directly when `alg = :fixed`; + otherwise it is used as an initial guess for the optimization + method, or as bounds if a 2-tuple is provided (TBD) + - `alg::Symbol = :gcv_svd`: algorithm for determining an optimal value for λ; the provided λ + value is used directly if `alg = :fixed`; otherwise `alg = [:gcv_svd, :gcv_tr, :L_curve]` is passed to the + RegularizationTools solver. + - `extrapolate::Bool` = false: flag to allow extrapolating outside the range of the time points provided. ## Example Constructors + Smoothing using all arguments + ```julia -A = RegularizationSmooth(u, t, t̂, wls, wr, d; λ=1.0, alg=:gcv_svd) +A = RegularizationSmooth(u, t, t̂, wls, wr, d; λ = 1.0, alg = :gcv_svd) ``` """ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::AbstractVector, @@ -75,8 +79,9 @@ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::Abstrac end """ Direct smoothing, no `t̂` or weights + ```julia -A = RegularizationSmooth(u, t, d; λ=1.0, alg=:gcv_svd, extrapolate=false) +A = RegularizationSmooth(u, t, d; λ = 1.0, alg = :gcv_svd, extrapolate = false) ``` """ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, d::Int = 2; @@ -103,8 +108,9 @@ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, d::Int = 2; end """ `t̂` provided, no weights + ```julia -A = RegularizationSmooth(u, t, t̂, d; λ=1.0, alg=:gcv_svd, extrapolate=false) +A = RegularizationSmooth(u, t, t̂, d; λ = 1.0, alg = :gcv_svd, extrapolate = false) ``` """ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::AbstractVector, @@ -129,8 +135,9 @@ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::Abstrac end """ `t̂` and `wls` provided + ```julia -A = RegularizationSmooth(u, t, t̂, wls, d; λ=1.0, alg=:gcv_svd, extrapolate=false) +A = RegularizationSmooth(u, t, t̂, wls, d; λ = 1.0, alg = :gcv_svd, extrapolate = false) ``` """ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::AbstractVector, @@ -156,8 +163,10 @@ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::Abstrac end """ `wls` provided, no `t̂` + ```julia -A = RegularizationSmooth(u, t, nothing, wls,d; λ=1.0, alg=:gcv_svd, extrapolate=false) +A = RegularizationSmooth( + u, t, nothing, wls, d; λ = 1.0, alg = :gcv_svd, extrapolate = false) ``` """ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::Nothing, @@ -184,8 +193,10 @@ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::Nothing end """ `wls` and `wr` provided, no `t̂` + ```julia -A = RegularizationSmooth(u, t, nothing, wls, wr, d; λ=1.0, alg=:gcv_svd, extrapolate=false) +A = RegularizationSmooth( + u, t, nothing, wls, wr, d; λ = 1.0, alg = :gcv_svd, extrapolate = false) ``` """ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::Nothing, @@ -212,8 +223,10 @@ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::Nothing end """ Keyword provided for `wls`, no `t̂` + ```julia -A = RegularizationSmooth(u, t, nothing, :midpoint, d; λ=1.0, alg=:gcv_svd, extrapolate=false) +A = RegularizationSmooth( + u, t, nothing, :midpoint, d; λ = 1.0, alg = :gcv_svd, extrapolate = false) ``` """ function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::Nothing, @@ -243,7 +256,9 @@ end # function RegularizationSmooth(u::AbstractVector, t::AbstractVector, t̂::AbstractVector, # wls::Symbol, d::Int=2; λ::Real=1.0, alg::Symbol=:gcv_svd) -""" Solve for the smoothed dependent variables and create spline interpolator """ +""" +Solve for the smoothed dependent variables and create spline interpolator +""" function _reg_smooth_solve( u::AbstractVector, t̂::AbstractVector, d::Int, M::AbstractMatrix, Wls½::AbstractMatrix, Wr½::AbstractMatrix, λ::Real, alg::Symbol, extrapolate::Bool) @@ -285,7 +300,9 @@ function _derivative_matrix(t::AbstractVector, d::Int) return D end -"""Linear interpolation mapping matrix, which maps `û` to `u`.""" +""" +Linear interpolation mapping matrix, which maps `û` to `u`. +""" function _mapping_matrix(t̂::AbstractVector, t::AbstractVector) N = length(t) N̂ = length(t̂) @@ -304,7 +321,9 @@ function _mapping_matrix(t̂::AbstractVector, t::AbstractVector) return M end -""" Common-use weighting, currently only `:midpoint` for midpoint-rule integration """ +""" +Common-use weighting, currently only `:midpoint` for midpoint-rule integration +""" function _weighting_by_kw(t::AbstractVector, d::Int, wls::Symbol) # `:midpoint` only for now, but plan to add functionality for `:relative` weighting N = length(t) diff --git a/src/interpolation_caches.jl b/src/interpolation_caches.jl index 12f5e532..bf293d7d 100644 --- a/src/interpolation_caches.jl +++ b/src/interpolation_caches.jl @@ -5,11 +5,13 @@ It is the method of interpolating between the data points using a linear polynom Extrapolation extends the last linear polynomial on each side. ## Arguments -- `u`: data points. -- `t`: time points. + + - `u`: data points. + - `t`: time points. ## Keyword Arguments -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct LinearInterpolation{uType, tType, FT, T} <: AbstractInterpolation{FT, T} u::uType @@ -32,12 +34,14 @@ It is the method of interpolating between the data points using quadratic polyno Extrapolation extends the last quadratic polynomial on each side. ## Arguments -- `u`: data points. -- `t`: time points. -- `mode`: `:Forward` or `:Backward`. If `:Forward`, two data points ahead of the point and one data point behind is taken for interpolation. If `:Backward`, two data points behind and one ahead is taken for interpolation. + + - `u`: data points. + - `t`: time points. + - `mode`: `:Forward` or `:Backward`. If `:Forward`, two data points ahead of the point and one data point behind is taken for interpolation. If `:Backward`, two data points behind and one ahead is taken for interpolation. ## Keyword Arguments -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct QuadraticInterpolation{uType, tType, FT, T} <: AbstractInterpolation{FT, T} u::uType @@ -66,12 +70,14 @@ end It is the method of interpolation using Lagrange polynomials of (k-1)th order passing through all the data points where k is the number of data points. ## Arguments -- `u`: data points. -- `t`: time points. -- `n`: order of the polynomial. Currently only (k-1)th order where k is the number of data points. + + - `u`: data points. + - `t`: time points. + - `n`: order of the polynomial. Currently only (k-1)th order where k is the number of data points. ## Keyword Arguments -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct LagrangeInterpolation{uType, tType, FT, T, bcacheType} <: AbstractInterpolation{FT, T} @@ -106,11 +112,13 @@ It is a spline interpolation built from cubic polynomials. It forms a continuous Extrapolation extends the last cubic polynomial on each side. ## Arguments -- `u`: data points. -- `t`: time points. + + - `u`: data points. + - `t`: time points. ## Keyword Arguments -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct AkimaInterpolation{uType, tType, bType, cType, dType, FT, T} <: AbstractInterpolation{FT, T} @@ -159,17 +167,19 @@ end """ ConstantInterpolation(u, t; dir = :left, extrapolate = false) -It is the method of interpolating using a constant polynomial. For any point, two adjacent data points are found on either side (left and right). The value at that point depends on `dir`. +It is the method of interpolating using a constant polynomial. For any point, two adjacent data points are found on either side (left and right). The value at that point depends on `dir`. If it is `:left`, then the value at the left point is chosen and if it is `:right`, the value at the right point is chosen. Extrapolation extends the last constant polynomial at the end points on each side. ## Arguments -- `u`: data points. -- `t`: time points. + + - `u`: data points. + - `t`: time points. ## Keyword Arguments -- `dir`: indicates which value should be used for interpolation (`:left` or `:right`). -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `dir`: indicates which value should be used for interpolation (`:left` or `:right`). + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct ConstantInterpolation{uType, tType, dirType, FT, T} <: AbstractInterpolation{FT, T} u::uType @@ -195,11 +205,13 @@ It is a spline interpolation using piecewise quadratic polynomials between each Extrapolation extends the last quadratic polynomial on each side. ## Arguments -- `u`: data points. -- `t`: time points. + + - `u`: data points. + - `t`: time points. ## Keyword Arguments -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct QuadraticSpline{uType, tType, tAType, dType, zType, FT, T} <: AbstractInterpolation{FT, T} @@ -262,11 +274,13 @@ It is a spline interpolation using piecewise cubic polynomials between each pair Extrapolation extends the last cubic polynomial on each side. ## Arguments -- `u`: data points. -- `t`: time points. + + - `u`: data points. + - `t`: time points. ## Keyword Arguments -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct CubicSpline{uType, tType, hType, zType, FT, T} <: AbstractInterpolation{FT, T} u::uType @@ -331,14 +345,16 @@ It is a curve defined by the linear combination of `n` basis functions of degree Extrapolation is a constant polynomial of the end points on each side. ## Arguments -- `u`: data points. -- `t`: time points. -- `d`: degree of the piecewise polynomial. -- `pVecType`: symbol to parameters vector, `:Uniform` for uniform spaced parameters and `:ArcLen` for parameters generated by chord length method. -- `knotVecType`: symbol to knot vector, `:Uniform` for uniform knot vector, `:Average` for average spaced knot vector. + + - `u`: data points. + - `t`: time points. + - `d`: degree of the piecewise polynomial. + - `pVecType`: symbol to parameters vector, `:Uniform` for uniform spaced parameters and `:ArcLen` for parameters generated by chord length method. + - `knotVecType`: symbol to knot vector, `:Uniform` for uniform knot vector, `:Average` for average spaced knot vector. ## Keyword Arguments -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct BSplineInterpolation{uType, tType, pType, kType, cType, FT, T} <: AbstractInterpolation{FT, T} @@ -439,20 +455,22 @@ end """ BSplineApprox(u, t, d, h, pVecType, knotVecType; extrapolate = false) -It is a regression based B-spline. The argument choices are the same as the `BSplineInterpolation`, with the additional parameter `h < length(t)` which is the number of control points to use, with smaller `h` indicating more smoothing. +It is a regression based B-spline. The argument choices are the same as the `BSplineInterpolation`, with the additional parameter `h < length(t)` which is the number of control points to use, with smaller `h` indicating more smoothing. For more information, refer http://www.cad.zju.edu.cn/home/zhx/GM/009/00-bsia.pdf. Extrapolation is a constant polynomial of the end points on each side. ## Arguments -- `u`: data points. -- `t`: time points. -- `d`: degree of the piecewise polynomial. -- `h`: number of control points to use. -- `pVecType`: symbol to parameters vector, `:Uniform` for uniform spaced parameters and `:ArcLen` for parameters generated by chord length method. -- `knotVecType`: symbol to knot vector, `:Uniform` for uniform knot vector, `:Average` for average spaced knot vector. + + - `u`: data points. + - `t`: time points. + - `d`: degree of the piecewise polynomial. + - `h`: number of control points to use. + - `pVecType`: symbol to parameters vector, `:Uniform` for uniform spaced parameters and `:ArcLen` for parameters generated by chord length method. + - `knotVecType`: symbol to knot vector, `:Uniform` for uniform knot vector, `:Average` for average spaced knot vector. ## Keyword Arguments -- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. + + - `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. """ struct BSplineApprox{uType, tType, pType, kType, cType, FT, T} <: AbstractInterpolation{FT, T} diff --git a/src/interpolation_utils.jl b/src/interpolation_utils.jl index 1693c942..28222f76 100644 --- a/src/interpolation_utils.jl +++ b/src/interpolation_utils.jl @@ -66,8 +66,8 @@ end """ bracketstrictlymontonic(v, x, guess; lt=, by=, rev=false) -Starting from an initial `guess` index, find indices `(lo, hi)` such that `v[lo] ≤ x ≤ -v[hi]` according to the specified order, assuming that `x` is actually within the range of +Starting from an initial `guess` index, find indices `(lo, hi)` such that `v[lo] ≤ x ≤ v[hi]` +according to the specified order, assuming that `x` is actually within the range of values found in `v`. If `x` is outside that range, either `lo` will be `firstindex(v)` or `hi` will be `lastindex(v)`.