Example usage

To use fitlistreader in a project:

import fitlistreader
from fitlistreader.fitlist import Fitlist

Basic interactions

To simply read out values which are directly stored in the fitlist file, you can interact with it just like with a standard python list object:

fl = Fitlist('../tests/gs_trans.fit')
average_energy = 0
for peak in fl:
    average_energy += peak.pos
average_energy /= len(fl)
print(f"The average of all energies in the fitlist is: {average_energy:.2f} keV")
i = 10
print(f"The {i}th peak in the Fitlist has an energy of {fl[i].pos:.1f}±{fl[i].dpos:.1f} keV")
print(f"  and a volume of {fl[i].vol:.0f}±{fl[i].dvol:.0f} Counts")

The average of all energies in the fitlist is: 5844.63 keV
The 10th peak in the Fitlist has an energy of 3311.6±0.5 keV
  and a volume of 128±12 Counts

The elements of a Fitlist are Peak objects. Their fields are directly accessible by name. The names are equivalent to the keys supplied for the CLI output, except for the background data.

Background data must be processed to get usefull values, as aspects like the Background volume is not saved in the fitlist file directly. Only parameters for their reconstruction are available, which are processed by the Fitlistreader before they are made accessible. They can be accessed as sub-fields from the bg object of a peak

print(f"The background volume under the {i}th peak is {fl[i].bg.vol:.1f}±{fl[i].bg.dvol:.1f} Counts. ")
print(f"it was fitted with the {fl[i].bg.model} background model")

The background volume under the 10th peak is 13.3±3.4 Counts. 
it was fitted with the polynomial background model

Advanced usage

The reconstructed background is dependant on marker position. This is not strictly the same method which is used by HDTV to determine background parameters, which has access to the binning, type, and especially the content of the Histogram which was fitted originally and can take these effects into account for a more acurate determination.

A way to circumvent this is by using the determined integrals directly. You can get access to the integrals by member functions of the Fitlist object:

integ = fl.get_integral_by_peakID(i)
print(f"The Background determined by HDTV originally for the {i}th peak was {integ['bg'].vol:.1f}±{integ['bg'].dvol:.1f}")

The Background determined by HDTV originally for the 10th peak was 14.0±0.7

This way of retrieving an integral returns a dict of FitIntegral objects, as a single integral in HDTV is comprised of a “Total” or ‘tot’ integral, taking into account all bins in the marker regions, a “Background” or ‘bg’ integral, only including the bin contents below the fitted Background curve, and a “subtracted” or ‘sub’ Integral, which is the difference of the two, or more visually, only includes bin contents above the background curve.

The FitIntegral object itself is similar to the Peak object, the avalible fields for these objects are

Key	Description
`pos`	Ceter position of the integral. The zeroth moment of the integral.
`dpos`	Uncertainty in the ceter position of the integral.
`vol`	Volume of the integral. The same as the first moment of the integral.
`dvol`	Uncertainty in the volume of the integral.
`width`	Width of the integral. Related to the second moment of the integral.
`dwidth`	Uncertainty in the width of the integral.
`skew`	Skewedness of the integral. Equivalent to the third moment of the integral.
`dskew`	Uncertainty in the skewedness of the integral

The third moment of an integral, or the skewedness is only determined for uncalibrated integrals by HDTV, the reason for this is not known. For calibrated integrals, skew and dskew is set to float(NaN).

The calibration of a spectrum is also saved in the fitlist file. More specifically, each Fit also stores the calibrationn with which it was created, making it possible to have several different calibrations for a single spectrum. This is rather unlikely to be used, but because of this, the calibration is a peak property:

print(f"The calibration used for the first peak is {fl[0].calibration}")

The calibration used for the first peak is

In this example, no calibration was done for the fitlist (TODO: change this)

Utilities

Currently, the only utility function for the fitlist reader is a method to determine the closest peak to a given position. This is not as trivial as one would naively assume, as peaks do not have to be ordered by position in a fitlist file. To only return peak objects is also not trivial. All in all, the method used is not complicated or particularly efficient, but it is stable:

tgt_energy = 5327 # pos, in this case equivalent to keV
sol = fl.closest(tgt_energy)
print(f"The peak closest to {tgt_energy} kev is the one at {sol[0].pos:.2f} keV with a difference of {sol[1]:.2f} keV. ")

The peak closest to 5327 kev is the one at 5372.23 keV with a difference of 45.23 keV. 