Dij influence matrix Analyse

A collection of useful functions for reading and manipulating with Dij influence matrices produced by a Monte Carlo. The Dij 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.

fredtools.getDijFREDVectorImage(dijFileName, FNo=None, PBNo=None, returnOrder=False, raiseMemError=True, displayInfo=False)

Read FRED Dij image to SimpleITK vector image object.

The function reads a Dij (influence matrix) file produced by the FRED Monte Carlo to an instance of a SimpleITK vector image object. The default type of the SimpleITK vector image object is “float32”. Each element of the vectors in voxels is a single pencil beam signal. By default, all the pencil beams saved to the Dij influence matrix are read, but the user can ask for selected pencil beams (the field will be read automatically) or for all pencil beams for a given field or list of fields. See the Notes for more details. The order of the vectors is the order of the pencil beam’s signal saved in the Dij matrix and can alter from the one requested by the user. It is recommended to get the true order by returnOrder=True option, to return it. The size of the SimpleITK vector image object in the memory can be significant, therefore memory checking is implemented, and it is recommended to use it.

Parameters:

  • dijFileName (path) – Path to FRED Dij file to read.

  • FNo (scalar or array_like, optional) – The number of field IDs. (def. None)

  • PBNo (scalar or array_like, optional) – The number of pencil beams IDs. (def. None)

  • returnOrder (bool, optional) – If True, the true order of the pencil beams and field IDs will be returned, along with the SimpleITK vector image. (def. False)

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

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

Returns:

An object of a SimpleITK vector image, or SimpleITK Vector Image along with the pandas DataFtame describing the order of the pencil beams and fields.

Return type:

SimpleITK Vector Image (optionally with pandas DataFrame)

See also

getDijFREDInfo

get information from a Dij influence matrix produced by FRED Monte Carlo.

getDijFREDPoint

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

getDijFREDSumImage

get FRED Dij image to a sum SimpleITK image object.

Notes

It is possible to request various combinations of pencil beams and fields. For instance:

  • FNo=None, PBNo=2: will get just the pencil beam no 2 and the field ID will be calculated automatically,

  • FNo=None, PBNo=[20,30,40]: will get just the pencil beams no 20, 30 and 40 and the field ID will be calculated automatically,

  • FNo=1, PBNo=None: will get all the pencil beams from field 1,

  • FNo=[3,1], PBNo=None: will get all the pencil beams from fields 1 and 3.

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

fredtools.getDijFREDSumImage(dijFileName, FNo=None, PBNo=None, weight=None, displayInfo=False)

Read FRED Dij image to sum SimpleITK image object.

The function reads a Dij (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 Dij influence matrix are read with the unitary weights for all pencil beams, but the user can ask for selected pencil beams (the field will be read automatically) or for all pencil beams for a given field or list of fields. The weights can be provided as a single value for all pencil beams, for each pencil beam separately or constant for each field. See the Notes for more details.

Parameters:

  • dijFileName (path) – Path to FRED Dij file to read.

  • FNo (scalar or array_like, optional) – The number of field IDs. (def. None)

  • PBNo (scalar or array_like, optional) – The number of pencil beams IDs. (def. None)

  • weight (scalar or array_like, optional) – The weights of pencil beams. (def. None)

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

Returns:

Object of a SimpleITK image.

Return type:

SimpleITK Image

See also

getDijFREDInfo

get information from a Dij influence matrix produced by FRED Monte Carlo.

getDijFREDPoint

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

getDijFREDVectorImage

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

Notes

It is possible to request various combinations of pencil beams, fields and weights. For instance:

  • FNo=None, PBNo=2, weight=None: will get just the pencil beam no 2 with unitary weight and the field ID will be calculated automatically,

  • FNo=None, PBNo=[20,30,40], weight=None: will get just the pencil beams no 20, 30 and 40 with unitary weights and the field IDs will be calculated automatically,

  • FNo=None, PBNo=[20,30,40], weight=[100,200,300]: will get just the pencil beams no 20, 30 and 40 with weights 100, 200 and 300, respectively and the field IDs will be calculated automatically,

  • FNo=1, PBNo=None, weight=1E9: will get all the pencil beams from field 1 and all the pencil beams will be weighted by 1E9,

  • FNo=[3,1], PBNo=None, weight=[1E9, 1E5]: will get all the pencil beams from fields 1 and 3 and the pencil beams will be weighted by 1E9 and 1E5 for the respective fields,

  • FNo=None, PBNo=None, weight=[1E9, 2E9, …, 3E9]: will get all the pencil beams saved in the Dij influence matrix and each pencil beam will be weighted by a separate number (the length of weight must be the same as the number of the pencil beams in the Dij influence matrix).

The last example is the most common. The Dij influence matrix is usually calculated for a single primary for each pencil beam. In such a case, the weights represent the number of particles to be delivered, calculated from a treatment plan. It has been tested that the 3D dose distribution is consistent concerning the field-of-reference and values with the dose distribution calculated directly by FRED Monte Carlo.

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

fredtools.getDijFREDPoint(dijFileName, point, interpolation='linear', raiseMemError=True, displayInfo=False)

Get vector of interpolated values in a point from FRED Dij.

The function reads a Dij (influence matrix) file produced by the FRED Monte Carlo and interpolates the signal value for a given point or list of points for each single pencil beam.

Parameters:

  • dijFileName (path) – Path to FRED Dij file to read.

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

  • 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 NxP where N is the number of points and P is the number of pencil beams.

Return type:

NxP numpy array

See also

getDijFREDInfo

get information from a Dij influence matrix produced by FRED Monte Carlo.

getDijFREDVectorImage

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

getDijFREDSumImage

get FRED Dij 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 saved in the Dij 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. It is often that some of the vectors (when calculating for multiple points) are all filled with zero. It means that no pencil beam, saved in the Dij influence matrix delivered the dose to that voxels. It is recommended filtering the output of the function for such cases and recording the zero-signal voxels.

References

Notes

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

fredtools.getDijFREDInfo(dijFileName, displayInfo=False)

Read basic information from FRED Dij

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

Parameters:

  • dijFileName (path) – Path to FRED Dij 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

getDijFREDPoint

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

getDijFREDVectorImage

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

getDijFREDSumImage

get FRED Dij image to a sum SimpleITK image object.

Notes

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