Miscellaneous

A collection of useful miscellaneous functions with no category.

fredtools.mergePDF(PDFFileNames, mergedPDFFileName, removeSource=False, displayInfo=False)

Merge multiple PDF files to a single PDF.

The function merges multiple PDF files given as a list of path strings to a single PDF.

Parameters:

PDFFileNames (list of strings) – List of path strings to PDF files to be merged.
mergedPDFFileName (string) – Path string where the merged PDF will be saved.
removeSource (bool, optional) – Determine if the source PDF files should be removed after the merge. (def. False)
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Absolute path string where the merged PDF will be saved.

Return type:

mergedPDFFileName

fredtools.getLineFromFile(pattern, fileName, kind='all', startLine=1, removeEoL=True, comment='#')

Read the line and line number from an ASCI file.

The function searches an ASCI file for lines matching a pattern and returns the line or lines number and the line strings. The pattern follows the Python regular expression [7].

Parameters:

pattern (string) – A string describing the regular expression. It is recommended the string be a row string, starting with r’…’.
fileName (string) – Path String to ASCI file.
kind ({'all', 'first', 'last'}, optional) – Determine which line is to be returned: the first only, the last, or all the lines. (def. ‘all’)
startLine (int, optional) – The line number to start the search (def. 1)
removeEoL (bool, optional) – Determine if the end-of-line should be removed from each returned line. (def. True)
comment (strung, optional) – If not None or an empty string, then no lines starting with this string (leading white spaces are removed) will be returned. (def. ‘#’)

Returns:

If kind=’all’: a tuple of two tuples where the first is the matched line numbers and the second is the line strings. If kind=’first’ or kind=’last’: a tuple with the first or last reached line number and the line string.

Return type:

line index, line string

References

fredtools.getGIcmap(maxGI, N=256)

Get colormap for Gamma Index images.

The function creates a colormap for Gamma Index (GI) images, that can be used by matplotlib.pyplot.imshow function for displaying 2D images. The colormap is created from 0 to the maxGI value, whereas from 0 to 1 (GI test passed) the color changes from dark blue to white, and from 1 to maxGI it changes from light red to red.

Parameters:

maxGI (scalar) – The maximum value of the colormap.
N (scalar, optional) – Number of segments of the colormap. (def. 256)

Returns:

An instance of matplotlib.colors.LinearSegmentedColormap object.

Return type:

colormap

See also

calcGammaIndex: calculate the Gamma Index for two images.

Examples

It is assumed that the img is an image describing a slice of Gamma Index (GI) values calculated up to maximum value 3. To plot the GI map with the GI colormap:

>>> plt.imshow(ft.arr(img), cmap=getGIcmap(maxGI=3))

fredtools.getHistogram(dataX, dataY=None, bins=None, kind='mean', returnBinCenters=True)

Get histogram or differential histogram.

The function creates a histogram data from a given dataX iterable in the defined bins. It is possible to generate a differential histogram where the values of the histogram (usually Y-axis on a plot) are a given quantity, instead of frequency of dataX values occurrance.

Parameters:

dataX (1D array_like) – 1D array-like iterable with the data to calculate histogram. For instance, it can be: a single-column pandas DataFrame, pandas Series, 1D numpy array, 1D list, 1D tuple etc.
dataY (1D array_like, optional) – 1D array-like iterable with the data to calculate differential histogram. It must be of the same size as dataX. For instance, it can be: a single-column pandas DataFrame, pandas Series, 1D numpy array, 1D list, 1D tuple etc. (def. None)
bins (1D array_like, optional) – 1D array-like iterable with the bins’ edges to calculate histogram. If none, then the bins will be generated automatically between the minimum and maximum value of dataX in 100 steps linearly. (def. None)
kind ({'mean', 'sum', 'std', 'median', 'min', 'max', 'mean-std', 'mean+std'}, optional) – Determine the dataY quantity evaluation for a differential histogram. It can be: mean, standard deviation, median, minimum, maximum, sum value or mean +/- standard deviation. (def. ‘mean’)
returnBinCenters (bool, optional) – Determine if the first element of the returned list is going to be the bin centers (True) or bin edges (False). (def. True)

Returns:

A two-element tuple of 1D numpy ndarrays, where the first element is a list of bin centres (or edges) and the second is a list of histogram values.

Return type:

List of two ndarrays

fredtools.pdfLandau(x, mpv, xi, amp=1)

Landau probability density function (PDF).

The function generates a Landau probability density with a given most probable value (mpv), width (described with xi) and amplitude at mpv. It was adapted from 3 which was implemented based on the ROOT implementation. See [1] and [2] for more details.

Parameters:

x (scalar or array_like) – Point (or points) where to calculate the PDF.
mpv (scalar) – Position of the most probable value (MPV) of the Landau distribution.
xi (float) – Parameter ‘xi’ of the Landau distribution, it is a measure of its width.
amp (scalar, optional) – Amplitude of the PDF at MPV. (def. 1)

Returns:

Single value or array of values of the Landau PDF.

Return type:

scalar or numpy array

See also

fitLandau: fit Landau distribution to data.

References

fredtools.pdfLandauGauss(x, mpv, xi, sigma=0, amp=1)

Probability density function (PDF) of Landau convoluted with a Gaussian.

The function generates a Landau convoluted with a Gaussian probability density with a given most probable value of the convoluted function (mpv), the width of Landau (described with xi), the standard deviation of Gaussian and amplitude at mpv. It was adapted from [3] which was implemented based on the ROOT implementation. See [4] for more details.

Parameters:

x (scalar or array_like) – Point (or points) where to calculate the PDF.
mpv (scalar) – Position of the most probable value (MPV) of the convoluted distribution.
xi (float) – Parameter ‘xi’ of the Landau distribution, it is a measure of its width.
sigma (scalar, optional) – Standard deviation of the Gaussian distribution. (def. 0)
amp (scalar, optional) – Amplitude of the PDF at MPV. (def. 1)

Returns:

Single value or array of values of the Landau convoluted with Gaussian PDF.

Return type:

scalar or numpy array

See also

fitLandauGauss: fit Landau distribution convoluted with a Gaussian to data.

Notes

The ‘mpv’ parameter does not describe the MPV of the landau distribution but the MPV, i.e. the position of the maximum value, of the whole Landau-gauss convoluted PDF.

References

fredtools.pdfVavilov(x, mpv, kappa, beta, scaling, amp=1)

Probability density function (PDF) of Vavilov.

The function generates a Vavilov probability density with a given most probable value function (mpv), amplitude (amp), as well as kappa, beta and scaling parameters. It uses the implementation of pyamtrack library [5] that adopts the ROOT implementation [6]. The implemented PDF is not a true Vavilov distribution and the scaling parameter is not included in the original ROOT implementation. Therefore, the parameters kappa and beta might not describe the real kappa and beta parameters of the ROOT Vavilov. Nevertheless, the PDF can be used for fitting the distribution to the measurement data and to retrieve the MPV but the user must be aware that, for instance, the energy calculated based on the beta parameter might be wrong.

Parameters:

x (scalar or array_like) – Point (or points) where to calculate the PDF.
mpv (scalar) – Position of the most probable value (MPV) of the distribution.
kappa (float) – Parameter ‘kappa’ of the Vavilov distribution.
beta (float) – Parameter ‘beta’ of the Vavilov distribution.
scaling (float) – Scaling factor of the distribution.
amp (scalar, optional) – Amplitude of the PDF at MPV. (def. 1)

Returns:

Single value or array of values of the Vavilov PDF.

Return type:

scalar or numpy array

See also

fitVavilov: fit Vavilov distribution to data.

References

fredtools.fitLandau(x, y, fixAmplitude=False)

Fit Landau distribution.

The function fits Landau distribution to the data given as x and y values, using the least square algorithm.

Parameters:

x (array_like) – X values.
y (array_like) – Y values.
fixAmplitude (bool, optional) – determine if the amp parameter of the PDF should be used in the fitting.

Returns:

Model results of the LMFit package.

Return type:

lmfit.model.ModelResult

See also

fitLandauGauss: fit Landau distribution convoluted with a Gaussian to data.
fitVavilov: fit Vavilov distribution to data.

fredtools.fitLandauGauss(x, y, fixAmplitude=False)

Fit Landau convoluted with Gaussian distribution.

The function fits Landau convoluted with Gaussian distribution to the data given as x and y values, using the least square algorithm.

Parameters:

x (array_like) – X values.
y (array_like) – Y values.
fixAmplitude (bool, optional) – determine if the amp parameter of the PDF should be used in the fitting.

Returns:

Model results of the LMFit package.

Return type:

lmfit.model.ModelResult

See also

fitLandau: fit Landau distribution to data.
fitVavilov: fit Vavilov distribution to data.

fredtools.fitVavilov(x, y, beta0=0.5, kappa0=0.3, scaling0=-1, fixAmplitude=False)

Fit Vavilov distribution.

The function fits the Vavilov distribution to the data given as x and y values, using the least square algorithm. The fitting routine is sensitive to the initial values of kappa, beta and scaling. Therefore, the results should be always validated and different initial values of the parameters can be used if needed.

Parameters:

x (array_like) – X values.
y (array_like) – Y values.
fixAmplitude (bool, optional) – determine if the amp parameter of the PDF should be used in the fitting.
beta0 (scalar, optional) – Initial value of beta parameter. (def. 0.5)
kappa0 (scalar, optional) – Initial value of kappa parameter. (def. 0.3)
scaling0 (scalar, optional) – Initial value of scaling parameter. If it is less than 0 then it is calculated based on the standard deviation of the distribution. (def. -1)

Returns:

Model results of the LMFit package.

Return type:

lmfit.model.ModelResult

See also

fitLandau: fit Landau distribution to data.
fitLandauGauss: fit Landau distribution convoluted with a Gaussian to data.

fredtools.sigma2fwhm(sigma)

Convert sigma to FWHM.

The function recalculates the sigma parameter of a Gaussian distribution to full width at half maximum (FWHM).

Parameters:: sigma (scalar) – Sigma value.
Returns:: FWHM value.
Return type:: scalar

See also

fwhm2sigma: convert FWHM to sigma.

fredtools.fwhm2sigma(fwhm)

Convert FWHM to sigma.

The function recalculates full width at half maximum (FWHM) of a Gaussian distribution to sigma.

Parameters:: fwhm (scalar) – FWHM value.
Returns:: Sigma value.
Return type:: scalar

See also

sigma2fwhm: convert sigma to FWHM.

fredtools.getCPUNo(CPUNo='auto') → int | None

Get a number of CPU cores.

The function returns the number of CPU cores. Usually, it is used in functions utilizing multiprocessing.

Parameters:: CPUNo ({'auto', 'one'} or integer, optional) – A string of ‘auto’ or “one” for all the available CPU cores or a single one, respectively, or a positive integer showing the number of CPU cores. (def. ‘auto’)
Returns:: Number of CPU cores.
Return type:: integer