Bragg Peak Analysis

A class for a Bragg peak analysis, implemented in the fredtools.BraggPeak subpackage.

class fredtools.braggPeak(pos: Iterable[int | float | number], vec: Iterable[int | float | number], accuracy: int | float | number = 0.01, offset: int | float | number = 0, bortCut: Annotated[int | float | number, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=0), Le(le=1)])] = 0.6, **kwargs)

Class for Bragg curve analysis.

This class is holding methods for a Bragg peak (BP) analysis and properties of the analysis results. The analysis of a Bragg curve is made based on two methods: a simple interpolation with a given method (linear, nearest or spline) and/or a fit of the Bortfeld equation taken from [Bortfeld1997] (eq. 27). For each method, it is possible to obtain such parameters as a range of the BP at a given percent of the maximum of the distal fall-off, the value of the signal (for instance dose) at a given depth, distal fall-off and width of the BP at a given percent of the maximum.

Parameters:

• pos (iterable) – Vector of positions of the Bragg curve points.

• vec (iterable) – Vector of values (signal) of the Bragg curve points.

• accuracy (float, optional) – Accuracy of the spline and Bortfeld profiles interpolations. (def. 0.01)

• offset (float, optional) – Distance offset of the Bragg curve points. (def. 0)

• bortCut (float, optional) – The range of the data that the Bortfeld fit will be performed on. It is defined as the range of the BP in the proximal region at the fraction of the maximum of the spline interpolation. The Bortfeld fit will be performed for the input data in the distal of this range. (def. 0.6)

• **kwargs (keyword arguments, optional) –

  Additional keyword arguments:

  interpolation{‘spline’, ‘linear’, ‘nearest’}

  Interpolation method. (def. ‘spline’)

  splineOrderint

  Order of spline interpolation. Must be in range 0-5. (def. 3)

Raises:

• TypeError – If pos or vec is not iterable, not one-dimensional, or they are not of the same length.

• ValueError – If the interpolation method is not ‘linear’, ‘nearest’ or ‘spline’, or the spline order is not in range 0-5.

Examples

See example jupyter notebook at [BPTutorial]

References

[Bortfeld1997]

Bortfeld, T. An analytical approximation of the Bragg curve for therapeutic proton beams. Med. Phys. 24, 2024 (1997).

[BPTutorial]

Jupyter notebook of Bragg Peak Analysis Tutorial

property accuracy: int | float | number

Accuracy of the spline and Bortfeld profiles interpolations.

Raises:

ValueError – If the value assigned is not a positive scalar.

Type:

float

property bortCut: int | float | number

The range of the data to perform Bortfeld fit on.

Raises:

ValueError – If the value assigned is not a scalar in range 0-1.

Type:

float

property bortfeldFit: ModelResult

Result from the Model of the Bortfeld fit.

Type:

lmfit.model.ModelResult

property bortfeldFitParam: dict

Physical parameters calculated from the Bortfeld fit.

Type:

dict

property bp: list[ndarray[tuple[Any, ...], dtype[_ScalarT]]]

Original Bragg curve loaded by pos and vec.

Type:

list of arrays

property bpBort: list[ndarray[tuple[Any, ...], dtype[_ScalarT]]]

List of arrays describing pos and vec of the Bortfeld fit profile.

Raises:

ValueError – If the Bortfeld fit result does not provide the ‘depth’ keyword data.

Type:

list of arrays

property bpInterp: list[ndarray[tuple[Any, ...], dtype[_ScalarT]]]

List of arrays describing pos and vec of the interpolated profile.

Type:

list of arrays

property displayInfo: None

Display information about the Bragg peak analysis.

getDBort(range: int | float | number) → int | float | number

Get the signal value at a given range/depth based on Bortfeld fit.

The function calculates the signal value (for instance dose) at a given range (for instance depth) using the Bortfeld fit.

Parameters:

range (float) – Range/depth at which the signal value will be calculated.

Returns:

Signal value at a given range.

Return type:

float

Examples

Get the maximum value of the Bortfeld fit.

>>> braggPeak.getDBort(range=braggPeak.getRBort(dose=1))

getDFOBort(doseUp: int | float | number, doseLow: int | float | number, doseFraction: bool = True) → int | float | number

Calculate the width of the distal fall-off of the BP at a given signal level based on Bortfeld fit.

The function calculates the width of the distal fall-off of the BP at the absolute or relative signal values using the Bortfeld fit. The relative value is calculated to the maximum value of the Bortfeld fit.

Parameters:

• doseUp (float) – Absolute or relative upper signal level.

• doseLow (float) – Absolute or relative lower signal level.

• doseFraction (bool, optional) – Determine if the signal level is relative (True) to the maximum or absolute (False). (def. True)

Returns:

Width of the distal fall-off at signal level.

Return type:

float

Raises:

ValueError – If doseUp is lower than doseLow.

Examples

Get width of the distal fall-off between 80 and 20 percent of the maximum value of the Bortfeld fit.

>>> braggPeak.getDFOBort(doseUp=0.8, doseLow=0.2)

This is equivalent to the code.

>>> braggPeak.getRBort(dose=0.2, side='D') - braggPeak.getRBort(dose=0.8, side='D')

getDFOInterp(doseUp: int | float | number, doseLow: int | float | number, doseFraction: bool = True) → int | float | number

Calculate the width of the distal fall-off of the BP at a given signal level based on profile interpolation.

The function calculates the width of the distal fall-off of the BP at the absolute or relative signal values using the profile interpolation defined with interpolation and splineOrder. The relative value is calculated to the maximum value of the profile interpolation.

Parameters:

• doseUp (float) – Absolute or relative upper signal level.

• doseLow (float) – Absolute or relative lower signal level.

• doseFraction (bool, optional) – Determine if the signal level is relative (True) to the maximum or absolute (False). (def. True)

Returns:

Width of the distal fall-off at signal level.

Return type:

float

Raises:

ValueError – If doseUp is lower than doseLow.

Examples

Get width of the distal fall-off between 80 and 20 percent of the maximum value of the interpolation.

>>> braggPeak.getDFOInterp(doseUp=0.8, doseLow=0.2)

This is equivalent to the code.

>>> braggPeak.getRInterp(dose=0.2, side='D') - braggPeak.getRInterp(dose=0.8, side='D')

getDInterp(range: int | float | number) → int | float | number

Get signal value at given range/depth based on profile interpolation.

The function calculates the signal value (for instance dose) at a given range (for instance depth) using the profile interpolation defined with interpolation and splineOrder.

Parameters:

range (float) – Range/depth at which the signal value will be calculated.

Returns:

Signal value at a given range.

Return type:

float

Examples

Get the maximum value of the interpolation method.

>>> braggPeak.getDInterp(range=braggPeak.getRInterp(dose=1))

getRBort(dose: int | float | number, side: Literal['proximal', 'P', 'distal', 'D'] = 'distal', doseFraction: bool = True) → int | float | number

Calculate the range/depth at a given signal level based on Bortfeld fit.

The function calculates the range (depth) at the distal or proximal part, at the absolute or relative signal value using the Bortfeld fit. The relative value is calculated to the maximum value of the Bortfeld fit.

Parameters:

• dose (float) – Absolute or relative signal level.

• side ({'proximal'|'P', 'distal'|'D'}, optional) – Determine the side, proximal or distal to the maximum range, of the BP to calculate the range. (def. ‘distal’)

• doseFraction (bool, optional) – Determine if the signal level is relative (True) to the maximum or absolute (False). (def. True)

Returns:

Range at signal level.

Return type:

float

Raises:

ValueError – If the side parameter cannot be recognised.

Examples

Get a range at 80 percent of the maximum value of the Bortfeld fit at the distal fall-off of the BP.

>>> braggPeak.getRBort(dose=0.8)

Get a range at 50 percent of the maximum value of the Bortfeld fit in the proximal region.

>>> braggPeak.getRBort(dose=0.5, side='P')

getRInterp(dose: int | float | number, side: Literal['proximal', 'P', 'distal', 'D'] = 'distal', doseFraction: bool = True) → int | float | number

Calculate the range/depth at a given signal level based on profile interpolation.

The function calculates range (depth) at the distal or proximal part, at the absolute or relative signal value using the profile interpolation defined with interpolation and splineOrder. The relative value is calculated to the maximum value of the profile interpolation.

Parameters:

• dose (float) – Absolute or relative signal level.

• side ({'proximal'|'P', 'distal'|'D'}, optional) – Determine the side, proximal or distal to the maximum range, of the BP to calculate the range. (def. ‘distal’)

• doseFraction (bool, optional) – Determine if the signal level is relative (True) to the maximum or absolute (False). (def. True)

Returns:

Range at signal level.

Return type:

float

Raises:

ValueError – If the side parameter cannot be recognised.

Examples

Get range at 80 percent of the maximum value of the interpolation at the distal fall-off of the BP.

>>> braggPeak.getRInterp(dose=0.8)

Get range at 50 percent of the maximum value of the interpolation in the proximal region.

>>> braggPeak.getRInterp(dose=0.5, side='P')

getWBort(dose: int | float | number, doseFraction: bool = True) → int | float | number

Calculate the width of the BP at a given signal level based on Bortfeld fit.

The function calculates the width of the BP at the absolute or relative signal value using the Bortfeld fit. The relative value is calculated to the maximum value of the Bortfeld fit.

Parameters:

• dose (float) – Absolute or relative signal level.

• doseFraction (bool, optional) – Determine if the signal level is relative (True) to the maximum or absolute (False). (def. True)

Returns:

Width at signal level.

Return type:

float

Examples

Get width at 50 percent of the maximum value of the Bortfeld fit.

>>> braggPeak.getWBort(dose=0.5)

This is equivalent to the code.

>>> braggPeak.getRBort(dose=0.5, side='D') - braggPeak.getRBort(dose=0.5, side='P')

getWInterp(dose: int | float | number, doseFraction: bool = True) → int | float | number

Calculate the width of the BP at a given signal level based on profile interpolation.

The function calculates the width of the BP at the absolute or relative signal value using the profile interpolation defined with interpolation and splineOrder. The relative value is calculated to the maximum value of the profile interpolation.

Parameters:

• dose (float) – Absolute or relative signal level.

• doseFraction (bool, optional) – Determine if the signal level is relative (True) to the maximum or absolute (False). (def. True)

Returns:

Width at signal level.

Return type:

float

Examples

Get width at 50 percent of the maximum value of the interpolation.

>>> braggPeak.getWInterp(dose=0.5)

This is equivalent to the code.

>>> braggPeak.getRInterp(dose=0.5, side='D') - braggPeak.getRInterp(dose=0.5, side='P')

property interpolation: str

Interpolation method. Available are ‘linear’, ‘nearest’ or ‘spline’.

Raises:

ValueError – If the value assigned is not ‘linear’, ‘nearest’ or ‘spline’.

Type:

str

property offset: int | float | number

Distance offset of the Bragg curve points.

Raises:

ValueError – If the value assigned is not a scalar.

Type:

float

property plot: None

Simple plot of the Bragg peak and analysis methods.

property splineOrder: int

Order of the spline interpolation. Must be in range 0-5.

Raises:

ValueError – If the value assigned is not an integer in range 0-5.

Type:

int