Unfolder¶

class ompy.Unfolder(num_iter=200, response=None)[source]¶

Bases: object

Performs Guttormsen unfolding

The algorithm is roughly as follows:

Define matrix Rij as the response in channel i when the detector is hit by γ-rays with energy corresponding to channel j. Each response function is normalized by Σi Rij = 1. The folding is then:

f = Ru

where f is the folded spectrum and u the unfolded. If we obtain better and better trial spectra u, we can fold and compare them to the observed spectrum r.

As an initial guess, the trial function is u⁰ = r, and the subsequent being:

uⁱ = uⁱ⁻¹ + (r - fⁱ⁻¹)

until fⁱ≈r.

Note that no actions are performed on the matrices; they must already be cut into the desired size.

Variables:

num_iter (int, optional) – The number of iterations to perform. defaults to 200. The best iteration is then selected based on the score method
R (Matrix) – The response matrix
weight_fluctuation (float, optional) – A attempt to penalize fluctuations. Defaults to 1e-3
minimum_iterations (int, optional) – Minimum number of iterations. Defaults to 5.
use_compton_subtraction (bool, optional) – Set usage of Compton subtraction method. Defaults to True.
response_tab (DataFrame, optional) – If use_compton_subtraction=True a table with information (‘E’, ‘eff_tot’, …) must be provided.
FWHM_tweak_multiplier (Dict, optional) –
See compton subtraction method Necessary keys: [“fe”, “se”, “de”, “511”]. Magne’s suggestion:
```
FWHM_tweak_multiplier = {"fe": 1., "se": 1.1,
                         "de": 1.3, "511": 0.9}
```
iscores (np.ndarray, optional) – Selected iteration number in the unfolding. The unfolding and selection is performed independently for each Ex row, thus this is an array with len(raw.Ex).

Todo

Unfolding for a single spectrum (currently needs to be mocked as a
Matrix).

Unfolds the gamma-detector response of a spectrum

Parameters:

num_iter (int) – see above
reponse – see above

Attributes Summary

R

Methods Summary

`__call__`(matrix)	Wrapper for self.apply()
`apply`(raw[, response])	Run unfolding.
`chi_square`(folded)	Compute Χ² of the folded spectrum
`compton_subtraction`(unfolded)	Compton Subtraction Method in Unfolding of Guttormsen et al (NIM 1996)
`fluctuations`(counts[, sigma])	Calculates fluctuations in each Ex bin gamma spectrum S by summing the relative diff between the spectrum and a smoothed version of it.
`fold`(matrix)	Folds a matrix with the loaded response
`remove_negative`(matrix)	Wrapper for Matrix.remove_negative()
`score`(chisquare, fluctuations)	Calculates the score of each unfolding iteration for each Ex bin based on a weighting of chisquare and fluctuations.
`step`(unfolded, folded, step)	Perform a single step of Guttormsen unfolding
`update_values`()	Verify internal consistency and set default values

Attributes Documentation

R¶

Methods Documentation

__call__(matrix)[source]¶

Wrapper for self.apply()

Return type:: Matrix

apply(raw, response=None)[source]¶

Run unfolding.

Selected iteration for each Ex row can be obtained via self.iscores, see above.

Parameters:

raw (Matrix) – Raw matrix to unfold
response (Matrix, optional) – Response matrix. Defaults to the matrix provided in initialization.

Returns:

Unfolded matrix

Return type:

Matrix

Todo

Use better criteria for terminating

chi_square(folded)[source]¶

Compute Χ² of the folded spectrum

Uses the familiar Χ² = Σᵢ (fᵢ-rᵢ)²/rᵢ

Return type:: ndarray

compton_subtraction(unfolded)[source]¶

Compton Subtraction Method in Unfolding of Guttormsen et al (NIM 1996)

Parameters:: unfolded (ndarray) – unfolded spectrum
Return type:: ndarray
Returns:: unfolded spectrum, with compton subtraction applied

We follow the notation of Guttormsen et al (NIM 1996) in what follows. u0 is the unfolded spectrum from above, r is the raw spectrum, .. parsed-literal:

w = us + ud + ua
is the folding contributions from everything except Compton, i.e.
us = single escape,
ua = double escape,
ua = annihilation (511).

v = pf*u0 + w == uf + w is the estimated “raw minus Compton” spectrum c is the estimated Compton spectrum.

Note

The tweaking of the FWHM (“facFWHM” in Mama) has been delegated to the creation of the response matrix. If one wants to unfold with, say, 1/10 of the “real” FWHM, this this should be provided as input here already.
We apply smoothing to the different peak structures as described in the article. However, you may also “tweak” the FWHMs per peak for something Magne thinks is a better result.

Todo

When we unfolding with a reduced FWHM, should the compton method still work with the actual fhwm?

fluctuations(counts, sigma=50)[source]¶

Calculates fluctuations in each Ex bin gamma spectrum S by summing the relative diff between the spectrum and a smoothed version of it.

∑ | (S - ⟨S⟩) / ⟨S⟩ |

Parameters:

counts (np.ndarray) – counts of spectrum to act on (calibration from self.raw).
sigma (float, optional) – width of the gaussian for the smoothing. Defaults to 20

Returns:

column vector of fluctuations in each Ex bin

Return type:

np.ndarray

fold(matrix)[source]¶

Folds a matrix with the loaded response

Parameters:: matrix (Matrix) – Input matrix
Returns:: Folded matrix
Return type:: folded (Matrix)

remove_negative(matrix)[source]¶

Wrapper for Matrix.remove_negative()

Put in as an extra method to facilitate replacing this by eg. fill_and_remove_negatve

Parameters:: matrix (Matrix) – Input matrix

score(chisquare, fluctuations)[source]¶

Calculates the score of each unfolding iteration for each Ex bin based on a weighting of chisquare and fluctuations.

Parameters:

chisquare (np.ndarray) – chisquare between raw and unfolded
fluctuations (np.ndarray) – measure of fluctuations (to be penalized)

Return type:

ndarray

Returns:

score (the lower the better)

step(unfolded, folded, step)[source]¶

Perform a single step of Guttormsen unfolding

Performs the steps
    u = u + (r - f),      for step > 0
    f = uR

Parameters:

unfolded (np.ndarray) – unfolded spectrum of iteration step-1
folded (np.ndarray) – folded spectrum of of iteration step-1
step (np.ndarray) – Iteration number

Return type:

Tuple[ndarray, ndarray]

Returns:

Arrays with counts for the unfolded and folded matrix (unfolded, folded)

update_values()[source]¶

Verify internal consistency and set default values

Raises:: ValueError – If the raw matrix and response matrix have different calibrations.