Retention Indices

PolationMethod

Supertype for all data interpolation and extrapolation methods implemented for mapping retention times to retention indices, and potentially vice versa.

See also Linear, NaturalCubicBSpline, RiMapper.

Linear() <: PolationMethod

PolationMethod type that specifies data is linearly extrapolated using the slope calculated by the applied interpolator at the nearest retention time–retention index calibration point.

See also PolationMethod, NaturalCubicBSpline, RiMapper.

PiecewiseLinear() <: PolationMethod

PolationMethod type that specifies data is interpolated using a piecewise linear approach.

See also PolationMethod, NaturalCubicBSpline, RiMapper.

NaturalCubicBSpline(; force::Bool=false) <: PolationMethod

PolationMethod type that specifies data is interpolated using a natural cubic B-spline. Application of this type will raise an error if the resulting mapping function does not produce continuously increasing values. However, by setting the force keyword argument to true, a mapping function will be returned even if it does not yield continuously increasing values. This can be useful for identifying problematic or erroneous calibration points.

See also PolationMethod, NaturalCubicBSpline, RiMapper.

Examples

julia> NaturalCubicBSpline()
NaturalCubicBSpline(false)

julia> NaturalCubicBSpline(; force=true)
NaturalCubicBSpline(true)

AbstractRiMapper

Supertype for all retention index mapper implementations. All subtypes (e.g., RiMapper) have fields to store the retention index name and metadata.

See also RiMapper, retentionindexname, metadata.

RiMapper(retentionindexname::AbstractString, 
retentiontimes::AbstractVector{<:Unitful.Time},
retentionindices::AbstractVector{<:Real};
interpolationmethod::PolationMethod=NaturalCubicBSpline(), 
extrapolationmethod::Union{Nothing, <:PolationMethod}=nothing,
metadata::Dict=Dict())

Create an RiMapper object to map retention times to retention indices using interpolation, and extrapolation by default. The optional keyword arguments interpolationmethod and extrapolationmethod allow you to explicitly specify the methods used. Currently, the available interpolators are NaturalCubicBSpline() (default) and PiecewiseLinear(). The only available extrapolator is Linear(). If extrapolationmethod is set to nothing (default), the function will raise an error for retention time values outside the calibration range. Note that both retention times and retention indices must be provided in ascending order. Additionally, the optional metadata keyword argument allows you to associate metadata with the mapper.

See also AbstractRiMapper, retentionindexname, Linear, NaturalCubicBSpline, PiecewiseLinear, retentionindices, retentiontimes, interpolationmethod, extrapolationmethod, rt2ri, metadata, retentionindex.

Examples

julia> ld = RiMapper("Kovats", (1:5)u"minute", 1000:1000:5000)
RiMapper {index name: Kovats, calibration points: 5}
retention times: 1 minute, 2 minute, 3 minute, 4 minute, 5 minute
retention indices: 1000, 2000, 3000, 4000, 5000
interpolation method: NaturalCubicBSpline(false)
extrapolation method: nothing
metadata: 0 entries

julia> retentionindex(ld, 1u"minute") ≈ 1000.0
true

julia> retentionindex(ld, 1.5u"minute") ≈ 1500.0
true

julia> retentionindex(ld, 11u"minute") ≈ 11000.0
ERROR: ArgumentError: retention time outside range for calculating retention index
[...]

julia> retentionindices(ld)
1000:1000:5000

julia> retentiontimes(ld)
(1:5) minute

julia> interpolationmethod(ld)
NaturalCubicBSpline(false)

julia> extrapolationmethod(ld) === nothing
true

julia> ld = RiMapper("Kovats", (1:5)u"minute", 1000:1000:5000, extrapolationmethod=Linear())
RiMapper {index name: Kovats, calibration points: 5}
retention times: 1 minute, 2 minute, 3 minute, 4 minute, 5 minute
retention indices: 1000, 2000, 3000, 4000, 5000
interpolation method: NaturalCubicBSpline(false)
extrapolation method: Linear()
metadata: 0 entries

julia> retentionindex(ld, 11u"minute") === 11000.000000000011
true

julia> extrapolationmethod(ld)
Linear()

julia> ld = RiMapper("Kovats", (1:5)u"s", 10:10:50, interpolationmethod=PiecewiseLinear())
RiMapper {index name: Kovats, calibration points: 5}
retention times: 1 s, 2 s, 3 s, 4 s, 5 s
retention indices: 10, 20, 30, 40, 50
interpolation method: PiecewiseLinear()
extrapolation method: nothing
metadata: 0 entries

extrapolationmethod(mapper::RiMapper)

Return the name of the extrapolation method. If no extrapolation is applied, the function returns nothing.

See also RiMapper, interpolationmethod, retentionindex.

Example

julia> rts, ris = (1:5)u"minute", 1000:1000:5000;

julia> ld = RiMapper("Kovats", rts, ris);

julia> extrapolationmethod(ld) === nothing
true

julia> ld = RiMapper("Kovats", rts, ris, extrapolationmethod=Linear());

julia> extrapolationmethod(ld)
Linear()

interpolationmethod(mapper::RiMapper)

Return the name of the applied interpolation method.

See also RiMapper, extrapolationmethod, retentionindex.

Example

julia> ld = RiMapper("Kovats", (1:5)u"minute", 1000:1000:5000);

julia> interpolationmethod(ld)
NaturalCubicBSpline(false)

maxretentionindex(mapper::RiMapper)

Return the highest retention index used to construct the retention index mapper.

See also RiMapper, minretentionindex, retentionindices.

Example

julia> ld = RiMapper("Kovats", (1:5)u"minute", 1000:1000:5000);

julia> maxretentionindex(ld)
5000

maxretentiontime(chrom::AbstractChromatogram; timeunit::Unitful.TimeUnits, 
ustripped::Bool=false)

Return the highest retention time used to construct the retention index mapper. The optional keyword argument timeunit lets you change the unit of the returned retention time. All time units defined in the package Unitful.jl (e.g., u"s", u"minute") are supported. The optional keyword argument ustripped lets you choose whether to include the unit in the returned value.

See also RiMapper, maxretentiontime, retentiontimes.

Examples

julia> ld = RiMapper("Kovats", (1:5)u"minute", 1000:1000:5000);

julia> maxretentiontime(ld) ≈ 5u"minute"
true

julia> maxretentiontime(ld, timeunit=u"s") ≈ 300u"s"
true

julia> maxretentiontime(ld, timeunit=u"s", ustripped=true) ≈ 300
true

metadata(mapper::AbstractRiMapper)

Return the metadata.

See also AbstractRiMapper, RiMapper.

Example

julia> ld = RiMapper("Kovats", (1:5)u"minute", 1000:1000:5000, metadata=Dict(:id => 7))
RiMapper {index name: Kovats, calibration points: 5}
retention times: 1 minute, 2 minute, 3 minute, 4 minute, 5 minute
retention indices: 1000, 2000, 3000, 4000, 5000
interpolation method: NaturalCubicBSpline(false)
extrapolation method: nothing
metadata: 1 entry

julia> metadata(ld)
Dict{Any, Any} with 1 entry:
  :id => 7

minretentionindex(mapper::RiMapper)

Return the lowest retention index used to construct the retention index mapper.

See also RiMapper, maxretentionindex, retentionindices.

Example

julia> ld = RiMapper("Kovats", (1:5)u"minute", 1000:1000:5000);

julia> maxretentionindex(ld)
5000

minretentiontime(chrom::AbstractChromatogram; timeunit::Unitful.TimeUnits, 
ustripped::Bool=false)

Return the lowest retention time used to construct the retention index mapper. The optional keyword argument timeunit lets you change the unit of the returned retention time. All time units defined in the package Unitful.jl (e.g., u"s", u"minute") are supported. The optional keyword argument ustripped lets you choose whether to include the unit in the returned value.

See also RiMapper, maxretentiontime, retentiontimes.

Examples

julia> ld = RiMapper("Kovats", (1:5)u"minute", 1000:1000:5000);

julia> minretentiontime(ld) ≈ 1u"minute"
true

julia> minretentiontime(ld, timeunit=u"s") ≈ 60u"s"
true

julia> minretentiontime(ld, timeunit=u"s", ustripped=true) ≈ 60
true

retentionindex(mapper::RiMapper, retentiontime::Unitful.Time)

Return the retention index associated with a given retention time.

See also RiMapper, retentionindices, maxretentionindex, minretentionindex.

Examples

julia> rts, ris = [1.2, 2.4, 3.8, 5.0]u"minute", [1000, 2000, 3000, 4000];

julia> ld = RiMapper("Kovats", rts, ris)
RiMapper {index name: Kovats, calibration points: 4}
retention times: 1.2 minute, 2.4 minute, 3.8 minute, 5.0 minute
retention indices: 1000, 2000, 3000, 4000
interpolation method: NaturalCubicBSpline(false)
extrapolation method: nothing
metadata: 0 entries

julia> retentionindex(ld, 1.8u"minute") ≈ 1516.9172932330828
true

julia> retentionindex(ld, 1.1u"minute") ≈ 913.9194139194141
ERROR: ArgumentError: retention time outside range for calculating retention index
[...]

julia> ris = retentionindex.(ld, [2, 3]u"minute");  # broadcasting across multiple RT values

julia> ris ≈ [1683.3751044277362, 2430.719656283566]
true

retentionindex(chrom::AbstractChromatogram, retentiontime::Unitful.Time; 
info::Bool=false)

Return the retention index corresponding to a given retention time.

See also RiMapper, retentionindices, maxretentionindex, minretentionindex.

Examples

julia> rts, ris = [1.2, 2.4, 3.8, 5.0]u"minute", [1000, 2000, 3000, 4000];

julia> ld = RiMapper("Kovats", rts, ris);

julia> chrom = Chrom(Int64[1, 2, 3]u"s", Int32[12, 956, 1], rimapper=ld);

julia> retentionindex(chrom, 1.8u"minute") ≈ 1516.9172932330828
true

julia> retentionindex(chrom, 1.1u"minute") ≈ 913.9194139194141
ERROR: ArgumentError: retention time outside range for calculating retention index
[...]

julia> ris = retentionindex.(chrom, [2, 3]u"minute");  # broadcasting across multiple RT values

julia> ris ≈ [1683.3751044277362, 2430.719656283566]
true

julia> chrom = Chrom(Int64[1, 2, 3]u"s", Int32[12, 956, 1]);

julia> retentionindex(chrom, 120u"s")
ERROR: ArgumentError: no retention index mapper implemented
[...]

retentionindexname(mapper::RiMapper)

Return the retention index name.

See also AbstractRiMapper, RiMapper.

Example

julia> ld = RiMapper("Kovats", (1:10)u"minute", 1000:1000:10000);

julia> retentionindexname(ld)
"Kovats"

retentionindices(mapper::RiMapper)

Return the retention indices used to construct the retention index mapper. Note: the function returns a reference to the data structure.

See also RiMapper, maxretentionindex, minretentionindex, retentiontimes.

Example

julia> rts, ris = [1.2, 2.4, 3.8, 5.0]u"minute", [1000, 2000, 3000, 4000];

julia> ld = RiMapper("Kovats", rts, ris);

julia> retentionindices(ld)  # reference to the data structure
4-element Vector{Int64}:
 1000
 2000
 3000
 4000

julia> retentionindices(ld)[:]  # a copy of these values
4-element Vector{Int64}:
 1000
 2000
 3000
 4000

retentiontimes(mapper::RiMapper; timeunit::Unitful.TimeUnits, ustripped::Bool=false)

Return the retention times used to construct the retention index mapper. The optional keyword argument timeunit lets you change the unit of the returned retention times. All time units defined in the package Unitful.jl (e.g., u"s", u"minute") are supported. The optional keyword argument ustripped lets you choose whether to include the unit in the returned values. Note: If no time unit conversion is applied and the unit is not stripped, the function returns a reference to the data structure.

See also RiMapper, maxretentiontime, minretentiontime, retentionindices.

Example

julia> rts, ris = [1.2, 2.4, 3.8, 5.0]u"minute", [1000, 2000, 3000, 4000];

julia> ld = RiMapper("Kovats", rts, ris);

julia> retentiontimes(ld)  # reference to the data structure
4-element Vector{Quantity{Float64, 𝐓, Unitful.FreeUnits{(minute,), 𝐓, nothing}}}:
 1.2 minute
 2.4 minute
 3.8 minute
 5.0 minute

julia> retentiontimes(ld)[:]  # a copy of these values
4-element Vector{Quantity{Float64, 𝐓, Unitful.FreeUnits{(minute,), 𝐓, nothing}}}:
 1.2 minute
 2.4 minute
 3.8 minute
 5.0 minute

julia> retentiontimes(ld, timeunit=u"s")
4-element Vector{Quantity{Float64, 𝐓, Unitful.FreeUnits{(s,), 𝐓, nothing}}}:
  72.0 s
 144.0 s
 228.0 s
 300.0 s

julia> retentiontimes(ld, timeunit=u"s", ustripped=true)
4-element Vector{Float64}:
  72.0
 144.0
 228.0
 300.0