Influence Matrix Analyse

A collection of useful functions for reading and manipulating with influence matrices produced by a Monte Carlo. The influence matrix is usually a 3D image describing the influence (dose, LET or other) for each pencil beam, therefore it can be treated as a 4D image with geometrical X, Y, Z and pencil beam dimensions. Such matrices can occupy a lot of memory, therefore most of the functions implemented here are equipped with memory occupancy checking.

Note

The binary influence matrix file format had changed from the FRED 3.70.99 version. The function has been aligned with this format but will not work with the previous format. Use FREDtools v. 0.7.6 to read the old binary influence matrix file format or contact the FREDtools developers.

fredtools.getInmFREDSumImage(fileName, inmInfo=None, threshold=None, dtype=<class 'float'>, displayInfo=False)

Read the FRED influence matrix to sum up the SimpleITK image object.

The function reads an influence matrix file produced by the FRED Monte Carlo to an instance of a SimpleITK image object by summing the requested pencil beams with weights if requested. By default, all the pencil beams saved to the Inm influence matrix are read with the unitary weights for all pencil beams. Still, the user can ask for selected pencil beams providing influence matrix info pandas DataFrame, which must include at least columns ‘PBID’ and ‘FID’, and can include column ‘weight’, which will be used for weight calculation.

Parameters:

• fileName (path) – Path to FRED influence matrix file to read.

• inmInfo (pandas.DataFrame, optional) – A pandas DataFrame with at least columns ‘PBID’ and ‘FID’. (def. None)

• threshold (scalar, array_like or None, optional) – The threshold for which the values are filtered, defined as the fraction of maximum value for each bencim beam. It can be a scalar for a single component influence matrix or an iterable of the same size as the number of components. (def. None)

• dtype (data-type, optional) – The desired data-type for the output image, e.g., numpy.uint32 or float32. (def. numpy.float64)

• displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An object of a SimpleITK image.

Return type:

SimpleITK Image

See also

getInmFREDBaseImg

get base image defined in FRED influence matrix.

getInmFREDInfo

get information from an influence matrix produced by FRED Monte Carlo.

getInmFREDPoint

get a vector of interpolated values in a point from an influence matrix produced by FRED Monte Carlo.

getInmFREDVectorImage

get a vector image from an influence matrix produced by FRED Monte Carlo.

fredtools.getInmFREDPoint(fileName, point, inmInfo=None, dtype=<class 'float'>, interpolation='linear', raiseMemError=True, displayInfo=False)

Get vector of interpolated values in a point from FRED influence matrix.

The function reads an influence matrix file produced by the FRED Monte Carlo and interpolates the signal value for a given point or list of points. By default, the interpolated values for all the pencil beams saved to the Inm influence matrix will be calculated with the unitary weights for all pencil beams. Still, the user can ask for selected pencil beams providing influence matrix info pandas DataFrame, which must include at least columns ‘PBID’ and ‘FID’, and can include column ‘weight’, which will be used for weight calculation.

Parameters:

• fileName (path) – Path to FRED influence matrix file to read.

• point (Nx3 array_like) – 3-element iterable or an N-element iterable of 3-element iterables.

• inmInfo (pandas.DataFrame, optional) – A pandas DataFrame with at least columns ‘PBID’ and ‘FID’. (def. None)

• dtype (data-type, optional) – The desired data-type for the output image, e.g., numpy.uint32 or float32. (def. numpy.float64)

• interpolation ({'linear', 'nearest', 'cubic'}, optional) – Determine the interpolation method. (def. ‘linear’)

• raiseMemError (bool, optional) – Raise an error if the expected size of the calculated array is larger than the available RAM space. (def. True)

• displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A numpy array of shape CxPxN where C is the component number, P is the number of pencil beam, and N is the number of point.

Return type:

CxPxN numpy array

See also

getInmFREDBaseImg

get base image defined in FRED influence matrix.

getInmFREDInfo

get information from an influence matrix produced by FRED Monte Carlo.

getInmFREDVectorImage

get a vector image from an influence matrix produced by FRED Monte Carlo.

getInmFREDSumImage

get FRED influence matrix image to a sum SimpleITK image object.

Notes

1. The function exploits the scipy RegularGridInterpolator [1] to interpolate the point value.

2. The function calculates the values in a given point or list of points for each pencil beam and each component saved in the Inm influence matrix. In particular, it can be used to get the values for each pencil beam for each voxel by supplying the position of the center of each voxel (interpolation “nearest” can be set to speed up the calculations). The user should be aware of the memory usage in such cases.

3. Some vectors (when calculating for multiple points) are often filled with zero for each component. This means that no pencil beam saved in the influence matrix delivered a signal to those voxels. Filtering the function’s output for such cases and recording the zero-signal voxels is recommended.

References

[1]

https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.RegularGridInterpolator.html

Examples

The output array is a 3-dimensional array showing the signal for each component, each pencil beam, and each point. The following examples help with understanding the order of dimensions:

>> out[0, :, :] - get signals for all pencil beams at each point for component 0. It is useful for single-component scorers like dose or Edep.

>> out[1, :, 2] - get signals from all pencil beams for component 1 and point 2.

>> out[0, 2, 5] - get signal from the component 0, pencil beam 2 at point 5.

>> out[0, :, 2].sum()/out[1,:,2].sum() - calculate the ratio of the signals’ sum from all pencil beams of component 0 to component 1. In particular, this might be the LETd value at point 2, where the numerator is saved to component 0 and the denominator to component 1.

fredtools.getInmFREDPointSparse(fileName, point, dtype='float64', inmInfo=None, displayInfo=False)

Get a sparse array with values in a point from FRED influence matrix.

The function reads an influence matrix file produced by the FRED Monte Carlo to a list of row-based list of lists sparse arrays, defined as instances of a scipy.sparse.lil_array objects. The list length equals the number of components in the influence matrix file, i.e. each component is read to a separate sparse array. By default, all the pencil beams saved to the Inm influence matrix will be read with the unitary weights for all pencil beams. Still, the user can ask for selected pencil beams providing influence matrix info pandas DataFrame, which must include at least columns ‘PBID’ and ‘FID’, and can include column ‘weight’, which will be used for weight calculation.

Parameters:

• fileName (path) – Path to FRED influence matrix file to read.

• point (Nx3 array_like) – 3-element iterable or an N-element iterable of 3-element iterables describing the points in the physical coordinates. The points do not have to be defined in the voxel centers. However, they will be converted internally to pixel coordinates.

• inmInfo (pandas.DataFrame, optional) – A pandas DataFrame with at least columns ‘PBID’ and ‘FID’. (def. None)

• dtype (data-type, optional) – The desired data-type for the output sparse array, e.g., numpy.uint32 or float32. (def. ‘float64’)

• displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A list of scipy sparse arrays in row-based list of lists format, describing the influence from each pencil beam to a given voxel. The number of rows in each sparse array will equal the number of pencil beams saved in the Inm influence matrix file, and the number of columns will equal the number of points requested.

Return type:

list of scipy.sparse.lil_array

See also

getInmFREDBaseImg

get base image defined in FRED influence matrix.

getInmFREDInfo

get information from an influence matrix produced by FRED Monte Carlo.

getInmFREDVectorImage

get a vector image from an influence matrix produced by FRED Monte Carlo.

getInmFREDSumImage

get FRED influence matrix image to a sum SimpleITK image object.

Notes

1. The function exploits the scipy.sparse [2] package.

2. The function does not check the memory occupancy of the sparse arrays, as this depends strictly on the number of requested points. The user is advised to use it carefully as it can quickly fill all the machine’s memory when a large influence matrix is loaded.

References

[2]

https://docs.scipy.org/doc/scipy/reference/sparse.html

Examples

The output is a list of 2D sparse arrays. The following examples help with understanding the order of slicing:

>> out[0] - get a sparse matrix of the first component. It is helpful for single-component scorers like dose or Edep.

>> out[1][:,[2]] - get signals from all pencil beams for component 1 and point 2.

>> out[5][[7],:] - get signals from the pencil beam no 7 for component 5 in all points.

>> out[0][[2], [5]] - get signal from the component 0, pencil beam 2 at point 5.

fredtools.getInmFREDInfo(fileName, displayInfo=False)

Read basic information from FRED influence matrix.

The function reads an influence matrix file produced by the FRED Monte Carlo and gets the basic information about the pencil beams and fields saved.

Parameters:

• fileName (path) – Path to FRED influence matrix file to read.

• displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Pandas DataFrame with pencil beams and field numbers.

Return type:

DataFrame

See also

getInmFREDBaseImg

get base image defined in FRED influence matrix.

getInmFREDPoint

get a vector of interpolated values in a point from an influence matrix produced by FRED Monte Carlo.

getInmFREDVectorImage

get a vector image from an influence matrix produced by FRED Monte Carlo.

getInmFREDSumImage

get FRED influence matrix image to a sum SimpleITK image object.

fredtools.getInmFREDBaseImg(fileName, dtype=<class 'float'>, displayInfo=False)

Get base image defined in FRED influence matrix.

The function reads an influence matrix file produced by the FRED Monte Carlo and builds the basic image of a given type, defined as an instance of a SimpleITK image object, with the frame of reference defined in the influence matrix.

Parameters:

• fileName (path) – Path to FRED influence matrix file to read.

• dtype (data-type, optional) – The desired data-type for the output image, e.g., numpy.uint32 or float32. (def. numpy.float64)

• displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An object of a SimpleITK image.

Return type:

SimpleITK Image

See also

getInmFREDInfo

get information from an influence matrix produced by FRED Monte Carlo.

getInmFREDPoint

get a vector of interpolated values in a point from an influence matrix produced by FRED Monte Carlo.

getInmFREDVectorImage

get a vector image from an influence matrix produced by FRED Monte Carlo.

getInmFREDSumImage

get FRED influence matrix image to a sum SimpleITK image object.