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.
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)
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)
get FRED influence matrix image to a sum SimpleITK image object.
Notes
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
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.
get FRED influence matrix image to a sum SimpleITK image object.
Notes
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
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.
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)