Unfolder

class ompy.Unfolder(num_iter=33, 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 33. 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 0.2

  • minimum_iterations (int, optional) – Minimum number of iterations. Defaults to 3.

  • window_size (float or int?, optional) – window_size for fill negatives on output. Defaults to 10.

  • 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

rtype

Matrix

Methods Summary

__call__(matrix)

Wrapper for self.apply()

apply(raw[, response])

Run unfolding.

chi_square_red(folded)

Compute reduced Χ² 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 by summing the absolute diff between the spectrum and a smoothed version of it.

fold(matrix)

Folds a matrix with the loaded response

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
Return type

Matrix

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_red(folded)[source]

Compute reduced Χ² 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=20)[source]

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

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)

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.

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_red(folded)[source]

Compute reduced Χ² 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=20)[source]

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

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)

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.