Skip to content

Commit 8c4a785

Browse files
apearsonnapearsonn
committed
Updated docstrings
1 parent 8b98185 commit 8c4a785

31 files changed

+1323
-203
lines changed

‎docs/src/index.md

+14
Original file line numberDiff line numberDiff line change
@@ -1 +1,15 @@
11
# LegendSpecFits.jl
2+
3+
This package provides functionality to fit probability distribution functions to histograms.
4+
5+
This package is part of the [LegendJuliaRegistry](https://github.com/legend-exp/LegendJuliaRegistry), meaning that you can download the package as follows:
6+
```julia
7+
import Pkg
8+
9+
# add the LegendJuliaRegistry
10+
Pkg.Registry.add(Pkg.RegistrySpec(url = "https://github.com/legend-exp/LegendJuliaRegistry"))
11+
12+
# add LegendSpecFits
13+
Pkg.add("LegendSpecFits")
14+
```
15+

‎src/aoe_cut.jl

+122-26
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,22 @@
11

22
"""
3-
prepare_dep_peakhist(e::Array{T}, dep::T,; relative_cut::T=0.5, n_bins_cut::Int=500) where T<:Real
3+
prepare_dep_peakhist(e::Array{T}, dep::Quantity{T},; relative_cut::T=0.5, n_bins_cut::Int=500, uncertainty::Bool=true) where T<:Real
44
55
Prepare an array of uncalibrated DEP energies for parameter extraction and calibration.
6+
7+
# Arguments
8+
* 'e': Calibrated energies
9+
* 'dep': DEP energies
10+
11+
#Keywords
12+
* 'relative_cut':
13+
* 'n_bins_cut': Number of histogram bins to cut from plot
14+
* 'uncertainty': Energy uncertainty
15+
616
# Returns
7-
- `result`: Result of the initial fit
8-
- `report`: Report of the initial fit
17+
* `result`: Result of the initial fit
18+
* `report`: Report of the initial fit
19+
920
"""
1021
function prepare_dep_peakhist(e::Array{T}, dep::Quantity{T},; relative_cut::T=0.5, n_bins_cut::Int=500, uncertainty::Bool=true) where T<:Real
1122
# get cut window around peak
@@ -26,11 +37,27 @@ export prepare_dep_peakhist
2637

2738

2839
"""
29-
get_n_after_aoe_cut(aoe_cut::T, aoe::Array{T}, e::Array{T}, peak::T, window::Array{T}, bin_width::T, result_before::NamedTuple, peakstats::NamedTuple; uncertainty=true) where T<:Real
40+
get_n_after_aoe_cut(aoe_cut::Unitful.RealOrRealQuantity, aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, peak::T, window::Vector{T}, bin_width::T, result_before::NamedTuple, peakstats::NamedTuple; uncertainty::Bool=true, fixed_position::Bool=true) where T<:Unitful.Energy{<:Real}
3041
3142
Get the number of counts after a AoE cut value `aoe_cut` for a given `peak` and `window` size while performing a peak fit with fixed position. The number of counts is determined by fitting the peak with a pseudo prior for the peak position.
43+
44+
# Arguments
45+
* 'aoe_cut': A/E cut value
46+
* 'aoe': A/E
47+
* 'e': Calibrated energies
48+
* 'peak': Data peak
49+
* 'window': histogram window size of counts used
50+
* 'bin_width': Histogram bin widths
51+
* 'result_before':
52+
* 'peakstats': Peak statistics
53+
54+
# Keywords
55+
* 'uncertainty': Data uncertainty
56+
* 'fixed_position': Position of peak
57+
3258
# Returns
33-
- `n`: Number of counts after the cut
59+
* `n`: Number of counts after the cut
60+
3461
"""
3562
function get_n_after_aoe_cut(aoe_cut::Unitful.RealOrRealQuantity, aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, peak::T, window::Vector{T}, bin_width::T, result_before::NamedTuple, peakstats::NamedTuple; uncertainty::Bool=true, fixed_position::Bool=true) where T<:Unitful.Energy{<:Real}
3663
# get energy after cut and create histogram
@@ -49,12 +76,24 @@ export get_n_after_aoe_cut
4976

5077

5178
"""
52-
get_sf_after_aoe_cut(aoe_cut::T, aoe::Array{T}, e::Array{T}, peak::T, window::Array{T}, bin_width::T, result_before::NamedTuple; uncertainty=true) where T<:Real
79+
get_sf_after_aoe_cut(aoe_cut::Unitful.RealOrRealQuantity, aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, peak::T, window::Vector{T}, bin_width::T, result_before::NamedTuple; uncertainty::Bool=true) where T<:Unitful.Energy{<:Real}
5380
5481
Get the survival fraction after a AoE cut value `aoe_cut` for a given `peak` and `window` size from a combined fit to the survived and cut histograms.
5582
83+
# Arguments
84+
* 'aoe_cut': A/E cut value
85+
* 'aoe': A/E
86+
* 'e': Calibrated energies
87+
* 'peak': Peak name
88+
* 'window': Data window in energy
89+
* 'bin_width': Histogram bin widths
90+
* 'result_before': Survival fraction before A/E cut
91+
92+
# Keywords
93+
* 'uncertainty': uncertainty of survival fraction
94+
5695
# Returns
57-
- `sf`: Survival fraction after the cut
96+
* `sf`: Survival fraction after the cut
5897
"""
5998
function get_sf_after_aoe_cut(aoe_cut::Unitful.RealOrRealQuantity, aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, peak::T, window::Vector{T}, bin_width::T, result_before::NamedTuple; uncertainty::Bool=true) where T<:Unitful.Energy{<:Real}
6099
# get energy after cut and create histogram
@@ -69,14 +108,31 @@ export get_sf_after_aoe_cut
69108

70109

71110
"""
72-
get_aoe_cut(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T},; dep::T=1592.53u"keV", window::Vector{T}=[12.0, 10.0]u"keV", dep_sf::Float64=0.9, cut_search_interval::Tuple{Quantity{<:Real}, Quantity{<:Real}}=(-25.0u"keV^-1", 0.0u"keV^-1"), rtol::Float64=0.001, bin_width_window::T=3.0u"keV", fixed_position::Bool=true, sigma_high_sided::Float64=NaN, uncertainty::Bool=true, maxiters::Int=200) where T<:Unitful.Energy{<:Real}
111+
get_aoe_cut(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T},; dep::T=1592.53u"keV", window::Vector{<:T}=[12.0, 10.0]u"keV", dep_sf::Float64=0.9, cut_search_interval::Tuple{<:Unitful.RealOrRealQuantity, <:Unitful.RealOrRealQuantity}=(-25.0*unit(first(aoe)), 1.0*unit(first(aoe))), rtol::Float64=0.001, bin_width_window::T=3.0u"keV", fixed_position::Bool=true, sigma_high_sided::Float64=NaN, uncertainty::Bool=true, maxiters::Int=200) where T<:Unitful.Energy{<:Real}
73112
74113
Get the AoE cut value for a given `dep` and `window` size while performing a peak fit with fixed position. The AoE cut value is determined by finding the cut value for which the number of counts after the cut is equal to `dep_sf` times the number of counts before the cut.
75114
The algorhithm utilizes a root search algorithm to find the cut value with a relative tolerance of `rtol`.
115+
116+
# Arguments
117+
* 'aoe': A/E
118+
* 'e': Calibrated energies
119+
120+
# Keywords
121+
* 'dep': DEP energies
122+
* 'window': Data window in energy
123+
* 'dep_sf': Surrival fraction of DEP energies
124+
* 'cut_search_interval': Data interval to search for a cut value
125+
* 'rtol': Relative tolerance
126+
* 'bin_width_window': Specified window around the peak in which the bin algorithm is applied
127+
* 'fixed_position': Fixed position of cut
128+
* 'sigma_high_sided': Fixed upper limit cut
129+
* 'uncertainty': Uncertainty
130+
* 'maxiters': Maximum iterations
131+
76132
# Returns
77-
- `cut`: AoE cut value
78-
- `n0`: Number of counts before the cut
79-
- `nsf`: Number of counts after the cut
133+
* `cut`: AoE cut value
134+
* `n0`: Number of counts before the cut
135+
* `nsf`: Number of counts after the cut
80136
"""
81137
function get_aoe_cut(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T},; dep::T=1592.53u"keV", window::Vector{<:T}=[12.0, 10.0]u"keV", dep_sf::Float64=0.9, cut_search_interval::Tuple{<:Unitful.RealOrRealQuantity, <:Unitful.RealOrRealQuantity}=(-25.0*unit(first(aoe)), 1.0*unit(first(aoe))), rtol::Float64=0.001, bin_width_window::T=3.0u"keV", fixed_position::Bool=true, sigma_high_sided::Float64=NaN, uncertainty::Bool=true, maxiters::Int=200) where T<:Unitful.Energy{<:Real}
82138
# cut window around peak
@@ -101,12 +157,27 @@ export get_aoe_cut
101157

102158

103159
"""
104-
get_peaks_surrival_fractions(aoe::Array{T}, e::Array{T}, peaks::Array{T}, peak_names::Array{Symbol}, windows::Array{T}, aoe_cut::T,; uncertainty=true) where T<:Real
160+
get_peaks_surrival_fractions(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, peaks::Vector{<:T}, peak_names::Vector{Symbol}, windows::Vector{<:Tuple{T, T}}, aoe_cut::Unitful.RealOrRealQuantity,; uncertainty::Bool=true, bin_width_window::T=2.0u"keV", low_e_tail::Bool=true, sigma_high_sided::Unitful.RealOrRealQuantity=NaN) where T<:Unitful.Energy{<:Real}
105161
106162
Get the surrival fraction of a peak after a AoE cut value `aoe_cut` for a given `peak` and `window` size while performing a peak fit with fixed position.
163+
164+
# Arguments
165+
* 'aoe': A/E
166+
* 'e': Calibrated energies
167+
* 'peaks': Data range of several peaks
168+
* 'peak_names': Name of the peak
169+
* 'windows': Energy data window
170+
* 'aoe_cut': A/E cut value
171+
172+
# Keywords
173+
* 'Uncertainty':
174+
* 'bin_width_window': Specified window around the peak where the binning algorithm is applied to
175+
* 'low_e_tail': Low energy tail
176+
* 'sigma_high_sided': Fixed upper limit cut
177+
107178
# Return
108-
- `result`: Dict of results for each peak
109-
- `report`: Dict of reports for each peak
179+
* `result`: Dict of results for each peak
180+
* `report`: Dict of reports for each peak
110181
"""
111182
function get_peaks_surrival_fractions(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, peaks::Vector{<:T}, peak_names::Vector{Symbol}, windows::Vector{<:Tuple{T, T}}, aoe_cut::Unitful.RealOrRealQuantity,; uncertainty::Bool=true, bin_width_window::T=2.0u"keV", low_e_tail::Bool=true, sigma_high_sided::Unitful.RealOrRealQuantity=NaN) where T<:Unitful.Energy{<:Real}
112183
@assert length(peaks) == length(peak_names) == length(windows) "Length of peaks, peak_names and windows must be equal"
@@ -136,16 +207,30 @@ get_peaks_surrival_fractions(aoe, e, peaks, peak_names, left_window_sizes::Vecto
136207

137208

138209
"""
139-
get_peak_surrival_fraction(aoe::Array{T}, e::Array{T}, peak::T, window::Array{T}, aoe_cut::T,; uncertainty::Bool=true, low_e_tail::Bool=true) where T<:Real
210+
get_peak_surrival_fraction(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, peak::T, window::Vector{T}, aoe_cut::Unitful.RealOrRealQuantity,; uncertainty::Bool=true, lq_mode::Bool=false, low_e_tail::Bool=true, bin_width_window::T=2.0u"keV", sigma_high_sided::Unitful.RealOrRealQuantity=NaN) where T<:Unitful.Energy{<:Real}
140211
141212
Get the surrival fraction of a peak after a AoE cut value `aoe_cut` for a given `peak` and `window` size while performing a peak fit with fixed position.
142213
214+
# Arguments
215+
* 'aoe': A/E
216+
* 'e': Calibrated energies
217+
* 'peak': Peak name
218+
* 'window': Data window in energy
219+
* 'aoe_cut': A/E cut value
220+
221+
# Keywords
222+
* 'Uncertainty': Uncertainty
223+
* 'lq_mode': Inverts the cut logic
224+
* 'low_e_tail': Low energy tail
225+
* 'bin_width_window': Specified window around the peak to apply the binning algorithm
226+
* 'sigma_high_sided': Fixed upper limit cut
227+
143228
# Returns
144-
- `peak`: Peak position
145-
- `n_before`: Number of counts before the cut
146-
- `n_after`: Number of counts after the cut
147-
- `sf`: Surrival fraction
148-
- `err`: Uncertainties
229+
* `peak`: Peak position
230+
* `n_before`: Number of counts before the cut
231+
* `n_after`: Number of counts after the cut
232+
* `sf`: Surrival fraction
233+
* `err`: Uncertainties
149234
"""
150235
function get_peak_surrival_fraction(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, peak::T, window::Vector{T}, aoe_cut::Unitful.RealOrRealQuantity,; uncertainty::Bool=true, lq_mode::Bool=false, low_e_tail::Bool=true, bin_width_window::T=2.0u"keV", sigma_high_sided::Unitful.RealOrRealQuantity=NaN) where T<:Unitful.Energy{<:Real}
151236
# estimate bin width
@@ -204,16 +289,27 @@ export get_peak_surrival_fraction
204289

205290

206291
"""
207-
get_continuum_surrival_fraction(aoe:::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, center::T, window::T, aoe_cut::Unitful.RealOrRealQuantity,; sigma_high_sided::Unitful.RealOrRealQuantity=NaN) where T<:Unitful.Energy{<:Real}
292+
get_continuum_surrival_fraction(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, center::T, window::T, aoe_cut::Unitful.RealOrRealQuantity,; lq_mode::Bool=false, sigma_high_sided::Unitful.RealOrRealQuantity=NaN) where T<:Unitful.Energy{<:Real}
208293
209294
Get the surrival fraction of a continuum after a AoE cut value `aoe_cut` for a given `center` and `window` size.
210295
296+
# Arguments
297+
* 'aoe': A/E
298+
* 'e': Calibrated energies
299+
* 'center': Center of the fit
300+
* 'window': Data window in energy
301+
* 'aoe_cut': A/E cut value
302+
303+
# Keywords
304+
* 'lq_mode': Inverted cut logic
305+
* 'sigma_high_sided': Fixed upper limit cut
306+
211307
# Returns
212-
- `center`: Center of the continuum
213-
- `window`: Window size
214-
- `n_before`: Number of counts before the cut
215-
- `n_after`: Number of counts after the cut
216-
- `sf`: Surrival fraction
308+
* `window`: Window size
309+
* `n_before`: Number of counts before the cut
310+
* `n_after`: Number of counts after the cut
311+
* `sf`: Surrival fraction
312+
217313
"""
218314
function get_continuum_surrival_fraction(aoe::Vector{<:Unitful.RealOrRealQuantity}, e::Vector{<:T}, center::T, window::T, aoe_cut::Unitful.RealOrRealQuantity,; lq_mode::Bool=false, sigma_high_sided::Unitful.RealOrRealQuantity=NaN) where T<:Unitful.Energy{<:Real}
219315
# get number of events in window before cut

‎src/aoe_fit_calibration.jl

+19-8
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,28 @@
11
@. f_aoe_sigma(x, p) = sqrt(p[1]^2 + p[2]^2/x^2)
22
f_aoe_mu(x, p) = p[1] .+ p[2].*x
33
"""
4-
fit_aoe_corrections(e::Array{<:Unitful.Energy{<:Real}}, μ::Array{<:Real}, σ::Array{<:Real})
4+
fit_aoe_corrections(e::Array{<:Unitful.Energy{<:Real}}, μ::Array{<:Real}, σ::Array{<:Real}; aoe_expression::Union{String,Symbol}="a / e", e_expression::Union{String,Symbol}="e")
55
66
Fit the corrections for the AoE value of the detector.
7+
8+
# Arguments
9+
* 'e': Calibrated energies
10+
* 'μ': Mean values
11+
* 'σ': Sigma values
12+
13+
# Keywords
14+
* 'aoe_expression': A/E expression
15+
* 'e_expression': Calibrated energy expression
16+
717
# Returns
8-
- `e`: Energy values
9-
- `μ`: Mean values
10-
- `σ`: Sigma values
11-
- `μ_scs`: Fit result for the mean values
12-
- `f_μ_scs`: Fit function for the mean values
13-
- `σ_scs`: Fit result for the sigma values
14-
- `f_σ_scs`: Fit function for the sigma values
18+
* `e`: Energy values
19+
* `μ`: Mean values
20+
* `σ`: Sigma values
21+
* `μ_scs`: Fit result for the mean values
22+
* `f_μ_scs`: Fit function for the mean values
23+
* `σ_scs`: Fit result for the sigma values
24+
* `f_σ_scs`: Fit function for the sigma values
25+
1526
"""
1627
function fit_aoe_corrections(e::Array{<:Unitful.Energy{<:Real}}, μ::Array{<:Real}, σ::Array{<:Real}; aoe_expression::Union{String,Symbol}="a / e", e_expression::Union{String,Symbol}="e")
1728
# fit compton band mus with linear function

‎src/aoe_pseudo_prior.jl

+37
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1+
"""
2+
get_aoe_standard_pseudo_prior(h::Histogram, ps::NamedTuple, fit_func::Symbol; fixed_position::Bool=false)
3+
4+
Gets the A/E of a histogram using a standard pseudo prior. **
5+
6+
TO DO: add description of function and returns
7+
8+
# Arguments
9+
* 'h': Histogram data
10+
* 'ps': Peak statistics
11+
* 'fit_func': Fit function
12+
13+
# Keywords
14+
* 'fixed_position':
15+
16+
# Returns
17+
* 'pprior_base': Base pseudo prior
18+
"""
19+
120
function get_aoe_standard_pseudo_prior(h::Histogram, ps::NamedTuple, fit_func::Symbol; fixed_position::Bool=false)
221
pprior_base = NamedTupleDist(
322
μ = ifelse(fixed_position, ConstValueDist(ps.peak_pos), Normal(ps.peak_pos, 0.5*ps.peak_sigma)),
@@ -13,6 +32,24 @@ function get_aoe_standard_pseudo_prior(h::Histogram, ps::NamedTuple, fit_func::S
1332
end
1433
end
1534

35+
"""
36+
get_aoe_pseudo_prior(h::Histogram, ps::NamedTuple, fit_func::Symbol; pseudo_prior::NamedTupleDist=NamedTupleDist(empty = true), kwargs...)
37+
38+
Gets the A/E of a histogram using a pseudo prior.
39+
# Arguments
40+
* 'h': Histogram data
41+
* 'ps': Peak statistics
42+
* 'fit_func': Histogram fit function
43+
44+
# Keywords
45+
* 'pseudo_prior': Initial guess for parameters of histogram
46+
47+
# Returns
48+
* 'pseudo_prior': Initial guess for parameters of histogram
49+
50+
51+
"""
52+
1653
function get_aoe_pseudo_prior(h::Histogram, ps::NamedTuple, fit_func::Symbol; pseudo_prior::NamedTupleDist=NamedTupleDist(empty = true), kwargs...)
1754
standard_pseudo_prior = get_aoe_standard_pseudo_prior(h, ps, fit_func; kwargs...)
1855
# use standard priors in case of no overwrites given

‎src/aoefit.jl

+30-3
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,15 @@
44
generate_aoe_compton_bands(aoe::Vector{<:Real}, e::Vector{<:T}, compton_bands::Vector{<:T}, compton_window::T) where T<:Unitful.Energy{<:Real}
55
66
Generate histograms for the A/E Compton bands and estimate peak parameters.
7-
The compton bands are cutted out of the A/E spectrum and then binned using the Freedman-Diaconis Rule. For better performance
7+
The compton bands are cut out of the A/E spectrum and then binned using the Freedman-Diaconis Rule. For better performance
88
the binning is only done in the area around the peak. The peak parameters are estimated using the `estimate_single_peak_stats_psd` function.
99
10+
# Arguments
11+
* 'aoe': A/E
12+
* 'e': Calibrated energies
13+
* 'compton_bands': Compton band
14+
* 'compton_window': Data window with Compton Scattering events
15+
1016
# Returns
1117
* `peakhists`: Array of histograms for each compton band
1218
* `peakstats`: StructArray of peak parameters for each compton band
@@ -109,13 +115,22 @@ export generate_aoe_compton_bands
109115

110116

111117
"""
112-
fit_aoe_compton(peakhists::Array, peakstats::StructArray, compton_bands::Array{T}) where T<:Real
118+
fit_aoe_compton(peakhists::Vector{<:Histogram}, peakstats::StructArray, compton_bands::Array{T},; uncertainty::Bool=false) where T<:Unitful.Energy{<:Real}
113119
114120
Fit the A/E Compton bands using the `f_aoe_compton` function consisting of a gaussian SSE peak and a step like background for MSE events.
115121
122+
# Arguments
123+
* 'peakhists': Data range of the histogram peaks
124+
* 'peakstats': Peak statistics
125+
* 'compton_bands': Array of Compton bands
126+
127+
# Keywords
128+
* 'uncertainty': Fit uncertainty
129+
116130
# Returns
117131
* `result`: Dict of NamedTuples of the fit results containing values and errors for each compton band
118132
* `report`: Dict of NamedTuples of the fit report which can be plotted for each compton band
133+
119134
"""
120135
function fit_aoe_compton(peakhists::Vector{<:Histogram}, peakstats::StructArray, compton_bands::Array{T},; uncertainty::Bool=false) where T<:Unitful.Energy{<:Real}
121136

@@ -152,13 +167,25 @@ export fit_aoe_compton
152167

153168

154169
"""
155-
fit_single_aoe_compton(h::Histogram, ps::NamedTuple{(:peak_pos, :peak_fwhm, :peak_sigma, :peak_counts, :mean_background, :μ, :σ), NTuple{7, T}}; uncertainty::Bool=true) where T<:Real
170+
fit_single_aoe_compton(h::Histogram, ps::NamedTuple; uncertainty::Bool=true, pseudo_prior::NamedTupleDist=NamedTupleDist(empty = true), fit_func::Symbol=:f_fit, background_center::Union{Real,Nothing} = ps.peak_pos, fixed_position::Bool=false)
156171
157172
Perform a fit of the peakshape to the data in `h` using the initial values in `ps` while using the `f_aoe_compton` function consisting of a gaussian SSE peak and a step like background for MSE events.
158173
174+
# Arguments
175+
* 'h': Histogram data
176+
* 'ps': peak statistics
177+
178+
# Keywords
179+
* 'uncertainty': Fit uncertainty
180+
* 'pseudo_prior': Initial guess for histogram parameters
181+
* 'fit_func': Fit function name
182+
* 'background_center': Center of background fit curve
183+
* 'fixed_position':
184+
159185
# Returns
160186
* `result`: NamedTuple of the fit results containing values and errors
161187
* `report`: NamedTuple of the fit report which can be plotted
188+
162189
"""
163190
function fit_single_aoe_compton(h::Histogram, ps::NamedTuple; uncertainty::Bool=true, pseudo_prior::NamedTupleDist=NamedTupleDist(empty = true), fit_func::Symbol=:f_fit, background_center::Union{Real,Nothing} = ps.peak_pos, fixed_position::Bool=false)
164191
# create pseudo priors

0 commit comments

Comments
 (0)