Skip to content

Commit

Permalink
Revert function reordering (clarify changes in docstrings)
Browse files Browse the repository at this point in the history
  • Loading branch information
@halleysfifthinc
halleysfifthinc committed Jan 22, 2024
1 parent 676a0b5 commit b70804b
Show file tree
Hide file tree
Showing 3 changed files with 180 additions and 196 deletions.
85 changes: 40 additions & 45 deletions src/peakheight.jl
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
"""
peakheights!(peaks, heights;
peakheights(peaks, heights;
minheight=nothing,
maxheight=nothing
) -> (peaks, heights)
Modify and return `peaks` and `heights` by removing peaks that are less than `minheight` or greater
than `maxheight`.
Return a copy of `peaks` and `heights` where peak heights are removed if less than
`minheight` and/or greater than `maxheight`.
See also: [`peakprom`](@ref), [`peakwidths`](@ref), [`findmaxima`](@ref)
Expand All @@ -16,44 +16,35 @@ julia> x = [0,5,2,3,3,1,4,0];
julia> xpks, vals = findmaxima(x)
(indices = [2, 4, 7], heights = [5, 3, 4], data = [0, 5, 2, 3, 3, 1, 4, 0])
julia> peakheights!(xpks, vals; maxheight=4);
julia> xpks, vals
julia> peakheights(xpks, vals; maxheight=4)
([4, 7], [3, 4])
julia> peakheights(xpks, vals; minheight=4.5)
([2], [5])
```
"""
function peakheights!(
peaks::Vector{Int}, heights::AbstractVector{T};
minheight=nothing, maxheight=nothing,
function peakheights(
peaks::AbstractVector{Int}, heights::AbstractVector;
minheight=nothing, maxheight=nothing,
min=minheight, max=maxheight
) where {T}
)
if !isnothing(minheight)
Base.depwarn("Keyword `minheight` has been renamed to `min`", :peakheights!)
end
if !isnothing(maxheight)
Base.depwarn("Keyword `maxheight` has been renamed to `max`", :peakheights!)
end
length(peaks) == length(heights) || throw(DimensionMismatch("length of `peaks`, $(length(peaks)), does not match the length of `heights`, $(length(heights))"))
if !isnothing(min) || !isnothing(max)
lo = something(min, typemin(Base.nonmissingtype(T)))
up = something(max, typemax(Base.nonmissingtype(T)))
matched = findall(x -> !(lo ≤ x ≤ up), heights)
deleteat!(peaks, matched)
deleteat!(heights, matched)
end

return peaks, heights
peakheights!(copy(peaks), copy(heights); min=min, max=max)
end


"""
peakheights(peaks, heights;
peakheights!(peaks, heights;
minheight=nothing,
maxheight=nothing
) -> (peaks, heights)
Return a copy of `peaks` and `heights` where peak heights are removed if less than
`minheight` and/or greater than `maxheight`.
Modify and return `peaks` and `heights` by removing peaks that are less than `minheight` or greater
than `maxheight`.
See also: [`peakprom`](@ref), [`peakwidths`](@ref), [`findmaxima`](@ref)
Expand All @@ -64,30 +55,34 @@ julia> x = [0,5,2,3,3,1,4,0];
julia> xpks, vals = findmaxima(x)
(indices = [2, 4, 7], heights = [5, 3, 4], data = [0, 5, 2, 3, 3, 1, 4, 0])
julia> peakheights(xpks, vals; maxheight=4)
([4, 7], [3, 4])
julia> peakheights!(xpks, vals; maxheight=4);
julia> peakheights(xpks, vals; minheight=4.5)
([2], [5])
julia> xpks, vals
([4, 7], [3, 4])
```
"""
function peakheights(
peaks::AbstractVector{Int}, heights::AbstractVector;
minheight=nothing, maxheight=nothing,
function peakheights!(
peaks::Vector{Int}, heights::AbstractVector{T};
minheight=nothing, maxheight=nothing,
min=minheight, max=maxheight
)
) where {T}
if !isnothing(minheight)
Base.depwarn("Keyword `minheight` has been renamed to `min`", :peakheights!)
end
if !isnothing(maxheight)
Base.depwarn("Keyword `maxheight` has been renamed to `max`", :peakheights!)
end
peakheights!(copy(peaks), copy(heights); min=min, max=max)
end
length(peaks) == length(heights) || throw(DimensionMismatch("length of `peaks`, $(length(peaks)), does not match the length of `heights`, $(length(heights))"))
if !isnothing(min) || !isnothing(max)
lo = something(min, typemin(Base.nonmissingtype(T)))
up = something(max, typemax(Base.nonmissingtype(T)))
matched = findall(x -> !(lo ≤ x ≤ up), heights)
deleteat!(peaks, matched)
deleteat!(heights, matched)
end

##!===============================================================================================!##
##!========================================== New API ==========================================!##
##!===============================================================================================!##
return peaks, heights
end

"""
peakheights!(pks) -> NamedTuple
Expand All @@ -97,16 +92,16 @@ end
- `min`: Filter out any peak with a height smaller than `min`.
- `max`: Filter out any peak with a height greater than `min`.
Find the heights of the peaks in `pks`, and filter out any peak
Find the heights of the peaks in `pks`, and filter out any peak
with a heights smaller than `min` or greater than `max`.
Note that because the peaks returned by `findpeaks` already have
the feature `heights` calculated, this function is mainly useful to
Note that because the peaks returned by `findpeaks` already have
the feature `heights` calculated, this function is mainly useful to
filter peaks by a minimum and/or maximum height.
If the positional argument `pks` is omitted, a function is returned such
that `peakheights!(pks)` is equivalent to `pks |> peakheights!`.
Note: This function mutates the vectors stored in the NamedTuple `pks`,
Note: This function mutates the vectors stored in the NamedTuple `pks`,
and not the named tuple itself.
See also: [`peakproms!`](@ref), [`peakwidths!`](@ref)
Expand Down Expand Up @@ -145,9 +140,9 @@ peakheights!(; kwargs...) = pks -> peakheights!(pks; kwargs...)
- `min`: Filter out any peak with a height smaller than `min`.
- `max`: Filter out any peak with a height greater than `min`.
Non-mutation version of `peakheights!`. Note that
this copies all vectors in `pks`, including the data.
This means that it is less performant. See the docstring for
Non-mutation version of `peakheights!`. Note that
this copies all vectors in `pks`, including the data.
This means that it is less performant. See the docstring for
`peakheights!` for more information.
"""
peakheights(pks::NamedTuple; kwargs...) = peakheights!(deepcopy(pks); kwargs...)
peakheights(pks::NamedTuple; kwargs...) = peakheights!(deepcopy(pks); kwargs...)
145 changes: 69 additions & 76 deletions src/peakprom.jl
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,65 @@
"""
peakproms(peaks, x;
strict=true,
minprom=nothing,
maxprom=nothing
) -> (peaks, proms)
Calculate the prominences of `peaks` in `x`, and removing peaks with prominences less than
`minprom` and/or greater than `maxprom`.
Peak prominence is the absolute height difference between the current peak and the larger of
the two adjacent smallest magnitude points between the current peak and adjacent larger
peaks or signal ends.
The prominence for a peak with a `NaN` or `missing` between the current peak and either
adjacent larger peaks will be `NaN` or `missing` if `strict == true`, or it will be
the larger of the smallest non-`NaN` or `missing` values between the current peak and
adjacent larger peaks for `strict == false`.
See also: [`findminima`](@ref), [`findmaxima`](@ref), [`peakproms!`](@ref)
# Examples
```jldoctest
julia> x = [0,5,2,3,3,1,4,0];
julia> xpks = argmaxima(x)
3-element Vector{Int64}:
2
4
7
julia> peakproms(xpks, x)
([2, 4, 7], Union{Missing, Int64}[5, 1, 3])
julia> x = [missing,5,2,3,3,1,4,0];
julia> peakproms(xpks, x)
([2, 4, 7], Union{Missing, Int64}[missing, 1, 3])
julia> peakproms(xpks, x; strict=false)
([2, 4, 7], Union{Missing, Int64}[5, 1, 3])
```
"""
function peakproms(peaks::AbstractVector{Int}, x::AbstractVector{T};
strict=true, minprom=nothing, maxprom=nothing,
min=minprom, max=maxprom
) where {T}
if !isnothing(minprom)
Base.depwarn("Keyword `minprom` has been renamed to `min`", :peakproms)
end
if !isnothing(maxprom)
Base.depwarn("Keyword `maxprom` has been renamed to `max`", :peakproms)
end
if !isnothing(min) || !isnothing(max)
_peaks = copy(peaks)
else
# peaks will not be modified
_peaks = peaks
end
return peakproms!(_peaks, x; strict=strict, min=min, max=max)
end

"""
peakproms!(peaks, x;
strict=true,
Expand All @@ -12,7 +74,7 @@ prominences.
See also: [`peakproms`](@ref), [`findminima`](@ref), [`findmaxima`](@ref)
"""
function peakproms!(peaks::AbstractVector{Int}, x::AbstractVector{T};
strict=true, minprom=nothing, maxprom=nothing,
strict=true, minprom=nothing, maxprom=nothing,
min=minprom, max=maxprom
) where {T}
if !isnothing(minprom)
Expand Down Expand Up @@ -132,75 +194,6 @@ function peakproms!(peaks::AbstractVector{Int}, x::AbstractVector{T};
return peaks, proms
end

"""
peakproms(peaks, x;
strict=true,
minprom=nothing,
maxprom=nothing
) -> (peaks, proms)
Calculate the prominences of `peaks` in `x`, and removing peaks with prominences less than
`minprom` and/or greater than `maxprom`.
Peak prominence is the absolute height difference between the current peak and the larger of
the two adjacent smallest magnitude points between the current peak and adjacent larger
peaks or signal ends.
The prominence for a peak with a `NaN` or `missing` between the current peak and either
adjacent larger peaks will be `NaN` or `missing` if `strict == true`, or it will be
the larger of the smallest non-`NaN` or `missing` values between the current peak and
adjacent larger peaks for `strict == false`.
See also: [`findminima`](@ref), [`findmaxima`](@ref), [`peakproms!`](@ref)
# Examples
```jldoctest
julia> x = [0,5,2,3,3,1,4,0];
julia> xpks = argmaxima(x)
3-element Vector{Int64}:
2
4
7
julia> peakproms(xpks, x)
([2, 4, 7], Union{Missing, Int64}[5, 1, 3])
julia> x = [missing,5,2,3,3,1,4,0];
julia> peakproms(xpks, x)
([2, 4, 7], Union{Missing, Int64}[missing, 1, 3])
julia> peakproms(xpks, x; strict=false)
([2, 4, 7], Union{Missing, Int64}[5, 1, 3])
```
"""
function peakproms(peaks::AbstractVector{Int}, x::AbstractVector{T};
strict=true, minprom=nothing, maxprom=nothing,
min=minprom, max=maxprom
) where {T}
if !isnothing(minprom)
Base.depwarn("Keyword `minprom` has been renamed to `min`", :peakproms)
end
if !isnothing(maxprom)
Base.depwarn("Keyword `maxprom` has been renamed to `max`", :peakproms)
end
if !isnothing(min) || !isnothing(max)
_peaks = copy(peaks)
else
# peaks will not be modified
_peaks = peaks
end
return peakproms!(_peaks, x; strict=strict, min=min, max=max)
end


##!===============================================================================================!##
##!========================================== New API ==========================================!##
##!===============================================================================================!##



"""
peakproms!(pks) -> NamedTuple
peakproms!() -> Function
Expand All @@ -210,14 +203,14 @@ end
- `max`: Filter out any peak with a height greater than `min`.
- `strict`: How to handle `NaN` and `missing` values. See documentation for more details. Default to `true`.
Find the prominences of the peaks in `pks`, and filter out any peak
Find the prominences of the peaks in `pks`, and filter out any peak
with a prominence smaller than `min` or greater than `max`.
The prominences are returned in the field `:proms` of the returned named tuple.
If the positional argument `pks` is omitted, a function is returned such
that `peakproms!(pks)` is equivalent to `pks |> peakproms!`.
Note: This function mutates the vectors stored in the NamedTuple `pks`,
Note: This function mutates the vectors stored in the NamedTuple `pks`,
and not the named tuple itself.
See also: [`peakwidths!`](@ref), [`peakheights!`](@ref)
Expand Down Expand Up @@ -262,9 +255,9 @@ peakproms!(; kwargs...) = pks -> peakproms!(pks; kwargs...)
- `max`: Filter out any peak with a height greater than `min`.
- `strict`: How to handle `NaN` and `missing` values. See documentation for more details. Default to `true`.
Non-mutation version of `peakproms!`. Note that
this copies all vectors in `pks`, including the data.
This means that it is less performant. See the docstring for
Non-mutation version of `peakproms!`. Note that
this copies all vectors in `pks`, including the data.
This means that it is less performant. See the docstring for
`peakproms!` for more information.
"""
peakproms(pks::NamedTuple; kwargs...) = peakproms!(deepcopy(pks); kwargs...)
peakproms(pks::NamedTuple; kwargs...) = peakproms!(deepcopy(pks); kwargs...)
Loading

0 comments on commit b70804b

Please sign in to comment.