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.getInmFREDInfo(fileName: PathLike | str, displayInfo: bool = False) → DataFrame

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

Raises:

TypeError – If the file is not a proper FRED influence matrix file.
FileNotFoundError – If the file cannot be found.
NotImplementedError – If the version of the influence matrix file is not supported.

See also

getInmFREDBaseImg: get base image defined in FRED influence matrix.
getInmFREDSparse: get sparse matrices of point values from an influence matrix produced by FRED Monte Carlo.

fredtools.getInmFREDBaseImg(fileName: PathLike | str, dtype: DTypeLike = <class 'float'>, displayInfo: bool = False) → Image

Get base image defined in FRED influence matrix.

The function reads the header of 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

Raises:

TypeError – If the file is not a proper FRED influence matrix file.
FileNotFoundError – If the file cannot be found.
NotImplementedError – If the version of the influence matrix file is not supported.

See also

getInmFREDInfo: get information from an influence matrix produced by FRED Monte Carlo.
getInmFREDSparse: get sparse matrices of point values from an influence matrix produced by FRED Monte Carlo.

fredtools.getInmFREDSparse(fileName: PathLike | str, points: Iterable[Iterable[int | float | number]], interpreter: str = 'numpy', displayInfo: bool = False) → Sequence[csr_matrix]

Get sparse matrices of point values from an influence matrix produced by FRED Monte Carlo.

The function reads an influence matrix file produced by the FRED Monte Carlo and returns a list of sparse matrices of point values for each component at the requested points.

Parameters:

fileName (path) – Path to FRED influence matrix file to read.
points (array_like) – An N-element iterable of 3 elements iterables with physical points.
interpreter ({'numpy', 'cupy'}, optional) – The interpreter to be used for calculations. Use ‘numpy’ for CPU or ‘cupy’ for GPU implementation. (def. ‘numpy’)
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

List of sparse matrices of point values for each component.

Return type:

list[scipy.sparse.csr_matrix] or list[cupy.sparse.csr_matrix]

Raises:

TypeError – If the file is not a proper FRED influence matrix file, or if points is not an N-element iterable of 3-element iterables.
FileNotFoundError – If the file cannot be found.
ValueError – If the interpreter is not supported.
NotImplementedError – If the version of the influence matrix file is not supported.

See also

getInmFREDInfo: get information from an influence matrix produced by FRED Monte Carlo.
getInmFREDBaseImg: get base image defined in FRED influence matrix.

fredtools.inmSumVec(inmSparse: csr_matrix, weights: Iterable[int | float | number], displayInfo: bool = False) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

Sum up the influence matrix to a vector.

The function sums up the influence matrix for a given set of pencil beams and their weights. The influence matrix must be a sparse matrix. The function returns a summed influence matrix as an array. The sparse matrix can be given as an instance of a scipy.sparse.csr_matrix or cupy.sparse.csr_matrix object. In case of the cupy.sparse.csr_matrix object, the multiplication and summing will be performed on GPU.

Parameters:

inmSparse (scipy.sparse.csr_matrix or cupy.sparse.csr_matrix) – Sparse matrix of the influence matrix.
weights (array_like) – Array of weights for each pencil beam.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Summed influence matrix. A cupy array is returned when inmSparse is a cupy sparse matrix, and a numpy array otherwise.

Return type:

numpy.ndarray or cupy.ndarray

Raises:

ValueError – If inmSparse is not a sparse matrix, or if the number of weights is not equal to the number of pencil beams in the influence matrix.

See also

inmSumImg: sum up the influence matrix and create an image.

fredtools.inmSumImg(inmSparse: csr_matrix, weights: Iterable[int | float | number], imgBase: Image, displayInfo: bool = False) → Image

Sum up the influence matrix and create an image.

The function sums up the influence matrix for a given set of pencil beams and their weights. The influence matrix must be a sparse matrix and the number of its columns must be equal to the total number of voxels of imgBase, i.e. the product of the imgBase size in each direction. The function returns a summed influence image defined as an instance of a SimpleITK object that inherits the frame of reference of imgBase. If the summed influence vector is a cupy array (i.e. inmSparse is a cupy sparse matrix), it is converted to a numpy array before the image is built. The function is useful for calculating the sum of the influence matrix for a set of pencil beams.

Parameters:

inmSparse (scipy.sparse.csr_matrix or cupy.sparse.csr_matrix) – Sparse matrix of the influence matrix.
weights (array_like) – Array of weights for each pencil beam.
imgBase (SimpleITK.Image) – Base image for the influence matrix.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Summed influence image with the frame of reference of imgBase.

Return type:

SimpleITK.Image

Raises:

ValueError – If inmSparse is not a sparse matrix, if the number of weights is not equal to the number of pencil beams in the influence matrix, or if the number of columns of inmSparse is not equal to the total number of voxels of imgBase.

See also

inmSumVec: sum up the influence matrix to a vector.