Skip to content

Commit

Permalink
Merged in docs/RAM-3733_interpreting_results (pull request #407)
Browse files Browse the repository at this point in the history 
RAM-3733 Add "interpreting results" sections to docs

Approved-by: Randy Taylor
  • Loading branch information
@jrkerns
jrkerns committed Jun 25, 2024
2 parents 079634f + e76df98 commit feeb061
Show file tree
Hide file tree
Showing 13 changed files with 585 additions and 13 deletions.
141 changes: 141 additions & 0 deletions docs/source/acr.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,33 @@ Continuing from above:
data_dict["ct_module"]["roi_radius_mm"]
...
Interpreting CT Results
-----------------------

The outcome from analyzing the phantom available in RadMachine or from
``results_data`` is:

* ``phantom_model``: The model of the phantom used.
* ``phantom_roll_deg``: The roll of the phantom in degrees.
* ``origin_slice``: The slice number of the "origin" slice; for ACR this is Module 1.
* ``num_images``: The number of images in the passed dataset.
* ``ct_module``: The results of the CT module with the following items:

* ``offset``: The offset of the module slice in mm from the origin slice (z-direction).
* ``roi_distance_from_center_mm``: The distance of the ROIs from the center of the phantom in mm in the image plane.
* ``roi_radius_mm``: The radius of the ROIs in mm.
* ``rois``: A dictionary of the analyzed ROIs. The key is the name of the material
and the value is the mean HU value. E.g. ``'Air': -987.1``.
* ``roi_settings``: A dictionary of the ROI settings. The keys are the material names,
each with the following items:

* ``angle``: The angle of the ROI in degrees.
* ``distance``: The distance of the ROI from the center of the phantom in mm.
* ``radius``: The radius of the ROI in mm.
* ``distance_pixels``: The distance of the ROI from the center of the phantom in pixels.
* ``radius_pixels``: The radius of the ROI in pixels.
* ``angle_corrected``: The angle of the ROI corrected for phantom roll in degrees.

MRI Algorithm
-------------

Expand Down Expand Up @@ -287,6 +314,120 @@ low-contrast visibility test.

.. math:: PSG = ghosting_{ratio} * 100

Interpreting MRI Results
------------------------

The outcome from analyzing the phantom available in RadMachine or from
``results_data`` is:

* ``phantom_model``: The model of the phantom used.
* ``phantom_roll_deg``: The roll of the phantom in degrees.
* ``origin_slice``: The slice number of the "origin" slice; for ACR this is Slice 1.
* ``num_images``: The number of images in the passed dataset.
* ``slice1``: A dictionary of data for the "Slice 1" module with the following items:

* ``offset``: The offset of the phantom in mm from the origin slice.
* ``bar_difference_mm``: The difference in bar positions in mm.
* ``slice_shift_mm``: The measured shift in slice position compared to nominal.
* ``measured_slice_thickness_mm``: The measured slice thickness in mm.
* ``row_mtf_50``: The MTF at 50% for the row-based ROIs.
* ``col_mtf_50``: The MTF at 50% for the column-based ROIs.
* ``rois``: A dictionary of the analyzed MTF ROIs. The key is the name of the
ROI; e.g. ``Row 1.1`` and the key is a dictionary of the following items:

* ``name``: The name of the ROI.
* ``value``: The mean HU value of the ROI.
* ``stdev``: The standard deviation of the ROI.

* ``roi_settings``: A dictionary of the ROI settings. The keys are the ROI names,
each with the following items:

* ``angle``: The angle of the ROI in degrees.
* ``distance``: The distance of the ROI from the center of the phantom in mm.
* ``radius``: The radius of the ROI in mm.
* ``distance_pixels``: The distance of the ROI from the center of the phantom in pixels.
* ``radius_pixels``: The radius of the ROI in pixels.
* ``angle_corrected``: The angle of the ROI corrected for phantom roll in degrees.

* ``slice11``: A dictionary of results from the analysis of "Slice 11" with the '
following items:

* ``offset``: The offset of the phantom in mm from the origin slice.
* ``bar_difference_mm``: The difference in bar positions in mm.
* ``slice_shift_mm``: The measure shift in slice position compared to nominal.
* ``rois``: A dictionary of results of the left and right bar ROIs. The key
is the name of the bar and the results are a dictionary with the following items:

* ``name``: The name of the ROI.
* ``value``: The mean HU value of the ROI.
* ``stdev``: The standard deviation of the ROI.

* ``roi_settings``: A dictionary of the ROI settings. The keys are the ROI names,
each with the following items:

* ``angle``: The angle of the ROI in degrees.
* ``distance``: The distance of the ROI from the center of the phantom in mm.
* ``radius``: The radius of the ROI in mm.
* ``distance_pixels``: The distance of the ROI from the center of the phantom in pixels.
* ``radius_pixels``: The radius of the ROI in pixels.
* ``angle_corrected``: The angle of the ROI corrected for phantom roll in degrees.

* ``uniformity_module``: A dictionary of results from the uniformity module with the following items:

* ``offset``: The offset of the phantom in mm from the origin slice.
* ``ghosting_ratio``: The ghosting ratio.
* ``piu``: The percent integral uniformity.
* ``piu_passed``: Whether the PIU passed the test.
* ``psg``: The percent signal ghosting.
* ``rois``: A dictionary of the analyzed ROIs. The key is the name of
the ROI region with the following items:

* ``name``: The name of the ROI.
* ``value``: The mean HU value of the ROI.
* ``stdev``: The standard deviation of the ROI.
* ``difference``: The difference in HU value from the nominal value.
* ``nominal_value``: The nominal HU value of the ROI.
* ``passed``: Whether the ROI passed the test.

* ``roi_settings``: A dictionary of the ROI settings. The keys are the ROI names,
each with the following items:

* ``angle``: The angle of the ROI in degrees.
* ``distance``: The distance of the ROI from the center of the phantom in mm.
* ``radius``: The radius of the ROI in mm.
* ``distance_pixels``: The distance of the ROI from the center of the phantom in pixels.
* ``radius_pixels``: The radius of the ROI in pixels.
* ``angle_corrected``: The angle of the ROI corrected for phantom roll in degrees.

* ``ghost_rois``: A dictionary of the analyzed ghosting ROIs. The key is the name of
the ROI region with the following items:

* ``name``: The name of the ROI.
* ``value``: The mean HU value of the ROI.
* ``stdev``: The standard deviation of the ROI.

* ``ghost_roi_settings``: A dictionary of the ghosting ROI settings. The keys are the ROI names,
each with the following items:

* ``angle``: The angle of the ROI in degrees.
* ``distance``: The distance of the ROI from the center of the phantom in mm.
* ``radius``: The radius of the ROI in mm.
* ``distance_pixels``: The distance of the ROI from the center of the phantom in pixels.
* ``radius_pixels``: The radius of the ROI in pixels.
* ``angle_corrected``: The angle of the ROI corrected for phantom roll in degrees.

* ``geometric_distortion_module``: A dictionary with the following items:

* ``offset``: The offset of the phantom in mm from the origin slice.
* ``profiles``: A dictionary of the profiles used to measure the geometric distortion.
The key is the name of the profile and the value is a dictionary with the following items:

* ``width_mm``: The FWHM of the profile in mm.
* ``line``: A dictionary representing the line to be plotted.

* ``distances``: A dictionary of the lines measuring the ROI size. The
key is the name of the line direction and the value is a string of the
line length.

API Documentation
-----------------
Expand Down
92 changes: 92 additions & 0 deletions docs/source/cbct.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,8 @@ you can remove or adjust its offset by subclassing and overloading the ``modules
ct = PartialCatPhan504.from_zip(...) # use like normal
.. _cbct-mtf:

Examining rMTF
^^^^^^^^^^^^^^

Expand Down Expand Up @@ -490,6 +492,96 @@ Post-Analysis
* **Test if values are within tolerance** -- For each module, the determined values are compared with the nominal values.
If the difference between the two is below the specified tolerance then the module passes.

Interpreting Results
--------------------

The results of a CatPhan analysis in RadMachine or from ``results_data`` are:

* ``catphan_model``: The model of CatPhan that was analyzed.
* ``catphan_roll_deg``: The roll of the phantom in degrees.
* ``origin_slice``: The "origin" slice number. For CatPhan, this is the center of the HU module.
* ``num_images``: The number of images in the passed dataset.
* ``ctp404``: The results of the CTP404 module (HU linearity, spacing) with the following items:

* ``offset``: The offset of the module from the origin slice in mm.
* ``low_contrast_visibility``: The low contrast visibility score.
* ``thickness_passed``: Whether the slice thickness passed.
* ``measured_slice_thickness_mm``: The measured slice thickness in mm.
* ``thickness_num_slices_combined``: The number of slices combined when measuring slice thickness.
* ``geometry_passed``: Whether the geometry test passed, using the 4 nodes.
* ``avg_line_distance_mm``: The average distance between the 4 nodes in mm.
* ``line_distances_mm``: A list of the individual distances between nodes.
* ``hu_linearity_passed``: Whether all the HU ROIs were within tolerance.
* ``hu_tolerance``: The tolerance used for the HU linearity test.
* ``hu_rois``: A dictionary of the HU ROIs and their values. The keys will be the material
name such as ``Acrylic``. The values for each ROI will be a dictionary with the following keys:

* ``name``: The name of the material.
* ``value``: The measured HU value.
* ``nominal_value``: The nominal HU value.
* ``passed``: Whether the ROI passed.
* ``stdev``: The pixel value standard deviation of the ROI.
* ``difference``: The difference between the measured and nominal values.

* ``ctp486``: The results of the CTP486 module (HU uniformity) with the following items:

* ``uniformity_index``: The uniformity index as defined in Equation 2 of `Elstrom et al <https://www.tandfonline.com/doi/pdf/10.3109/0284186X.2011.590525>`__.
* ``integral_non_uniformity``: The integral non-uniformity as defined in Equation 1 of `Elstrom et al <https://www.tandfonline.com/doi/pdf/10.3109/0284186X.2011.590525>`__.
* ``nps_avg_power``: The average power of the noise power spectrum. See :ref:`nps`.
* ``nps_max_freq``: The most populous frequency of the noise power spectrum.
* ``passed``: Whether the uniformity test passed.
* ``rois``: A dictionary of the uniformity ROIs and their values. The keys will be the region
name such as ``Top``. The values for each ROI will be a dictionary with the following keys:

* ``name``: The region the ROI was sampled from.
* ``value``: The measured HU value.
* ``nominal_value``: The nominal HU value.
* ``passed``: Whether the ROI passed.
* ``stdev``: The pixel value standard deviation of the ROI.
* ``difference``: The difference between the measured and nominal values.

* ``ctp528``: A dictionary of results for the CTP528 (spatial resolution) module with the
following items:

* ``start_angle_radians``: The angle where the circular profile started.
* ``mtf_lp_mm``: A dictionary from 10% to 90% resolution in steps of 10 of the MTF in lp/mm. E.g. ``'20': 0.748``.
To get the MTF at a specific resolution see :ref:`cbct-mtf`.
* ``roi_settings``: A dictionary of the settings used for each MTF ROI. The key names are ``region_<n>``
where ``<n>`` is the region number. The values are a dictionary with the following keys:

* ``start``: The start angle of the ROI in degrees relative to the ``start_angle_radians`` setting.
* ``end``: The end angle of the ROI in degrees relative to the ``start_angle_radians`` setting.
* ``num peaks``: The number of peaks found in the profile.
* ``num valleys``: The number of valleys found in the profile.
* ``peak spacing``: The spacing between peaks in pixels.
* ``gap size (cm)``: The size of the gap between the bars in cm.
* ``lp/mm``: The number of line **pairs** per mm.

* ``ctp515``: A dictionary of results for the CTP515 (Low contrast) module with the following items:

* ``cnr_threshold``: The contrast-to-noise ratio threshold used to determine if a low contrast ROI was "seen".
* ``num_rois_seen``: The number of ROIs that were above the threshold; ie. "seen".
* ``roi_settings``: A dictionary of the settings used for each low contrast ROI. The key names are ``n``
where ``<n>`` is the size of the ROI. The values are a dictionary with the following keys:

* ``angle``: The angle of the ROI in degrees.
* ``distance``: The distance from the phantom center in mm.
* ``radius``: The radius of the ROI in mm.
* ``distance_pixels``: The distance from the phantom center in pixels.
* ``angle_corrected``: The angle of the ROI corrected for phantom roll.
* ``radius_pixels``: The radius of the ROI in pixels.

* ``roi_results``: A dictionary of the low contrast ROIs and their values. The keys will be the size
of the ROI such as ``'9'``. The values for each ROI will be a dictionary with the following keys:

* ``contrast method``: The method used to calculate the contrast. See :ref:`contrast`.
* ``visibility``: The visibility score of the ROI.
* ``visibility threshold``: The threshold used to determine if the ROI was "seen".
* ``passed visibility``: Whether the ROI was "seen".
* ``contrast``: The contrast of the ROI.
* ``cnr``: The contrast-to-noise ratio of the ROI.
* ``signal to noise``: The signal-to-noise ratio of the ROI.

Troubleshooting
---------------

Expand Down
23 changes: 23 additions & 0 deletions docs/source/cheese.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,29 @@ Analysis
* **Measure HU values of each plug** -- Based on the nominal spacing and roll compensation (if applied),
each plug area is sampled for the median and standard deviation values.

Interpreting Results
^^^^^^^^^^^^^^^^^^^^

The outcome from analyzing the phantom available in RadMachine or from
``results_data`` is:

* ``origin_slice``: The slice index that was used for the ROI analysis.
* ``num_images``: The number of images that were in the passed dataset.
* ``phantom_roll``: The roll of the phantom in degrees.
* ``rois``: A dictionary of ROIs. The key is the ROI number and the value
of each key contains:

* ``center_x``: The x-coordinate of the center of the ROI in pixels.
* ``center_y``: The y-coordinate of the center of the ROI in pixels.
* ``diameter``: The diameter of the ROI in pixels.
* ``median``: The median HU value of the ROI.
* ``std``: The standard deviation of the HU values of the ROI.

* ``roi_<n>``: This is the same thing as an individual result from ``rois``, but the name itself has
the ROI number appended. I.e. ``rois['11'] == roi_11``. It is redundant information and is the older implementation
of providing ROI data. Some "cheese" analyses may not have this set of keys. It
is deprecated due to the variable number of ROIs that can be analyzed.

API Documentation
-----------------

Expand Down
57 changes: 57 additions & 0 deletions docs/source/field_analysis.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -731,6 +731,63 @@ notekeeping.
:ref:`analysis_definitions`). For symmetry calculations that operate around the CAX, the CAX must first be determined, which is
the center of the FWHM of the profile.

Interpreting Results
--------------------

The field analysis result is slightly different if analyzing a device array vs
a 2D image (EPID/DICOM). In both cases the following is given:

* ``protocol``: The protocol used for the analysis. See: :ref:`analysis_definitions`.
* ``protocol_results``: This is a dictionary that contains the results of the protocol calculations. The keys are the protocol names.
Generally, they are ``symmetry_horizontal``, ``symmetry_vertical``, ``flatness_horizontal``, and ``flatness_vertical``.
The values themselves are the calculated values for that specific protocol equation.
* ``centering_method``: The method used to determine the center of the field. See :ref:`centering`.
* ``normalization_method``: The method used to normalize the field. See :ref:`normalization`.
* ``interpolation_method``: The method used to interpolate the field. See :ref:`interpolation`.
* ``edge_detection_method``: The method used to detect the field edges. See :ref:`edge`.
* ``top_penumbra_mm``: The penumbra width at the top of the field.
* ``bottom_penumbra_mm``: The penumbra width at the bottom of the field.
* ``left_penumbra_mm``: The penumbra width at the left of the field.
* ``right_penumbra_mm``: The penumbra width at the right of the field.
* ``geometric_center_index_x_y``: The geometric center of the field in pixel coordinates.
* ``beam_center_index_x_y``: The beam center of the field in pixel coordinates.
* ``field_size_vertical_mm``: The vertical field size in mm.
* ``field_size_horizontal_mm``: The horizontal field size in mm.
* ``beam_center_to_top_mm``: The distance from the beam center to the top edge of the field.
* ``beam_center_to_bottom_mm``: The distance from the beam center to the bottom edge of the field.
* ``beam_center_to_left_mm``: The distance from the beam center to the left edge of the field.
* ``beam_center_to_right_mm``: The distance from the beam center to the right edge of the field.
* ``cax_to_top_mm``: The distance from the CAX to the top edge of the field.
* ``cax_to_bottom_mm``: The distance from the CAX to the bottom edge of the field.
* ``cax_to_left_mm``: The distance from the CAX to the left edge of the field.
* ``cax_to_right_mm``: The distance from the CAX to the right edge of the field.
* ``top_position_index_x_y``: The top position of the field in pixel coordinates.
* ``top_horizontal_distance_from_cax_mm``: The horizontal distance from the top position to the image center.

.. note::
This says CAX, and by this we mean the CAX of the machine, regardless of field size/position.

* ``top_vertical_distance_from_cax_mm``: The vertical distance from the top position to the image center.
* ``top_horizontal_distance_from_beam_center_mm``: The horizontal distance from the top position to the beam center.
* ``top_vertical_distance_from_beam_center_mm``: The vertical distance from the top position to the beam center.
* ``left_slope_percent_mm``: The slope of the left side of the in-field region in percent per mm.
* ``right_slope_percent_mm``: The slope of the right side of the in-field region in percent per mm.
* ``top_slope_percent_mm``: The slope of the top side of the in-field region in percent per mm.
* ``bottom_slope_percent_mm``: The slope of the bottom side of the in-field region in percent per mm.
* ``top_penumbra_percent_mm``: The penumbra width at the top of the field in percent per mm.
* ``bottom_penumbra_percent_mm``: The penumbra width at the bottom of the field in percent per mm.
* ``left_penumbra_percent_mm``: The penumbra width at the left of the field in percent per mm.
* ``right_penumbra_percent_mm``: The penumbra width at the right of the field in percent per mm.

If analyzing a 2D image (EPID/DICOM) the following is also given.
The ROI in this case is where the finite profile areas overlap. E.g.
if ``vert_width`` and ``horiz_width`` are 0.1, there is a central 10% of the field that is used for the following ROI:

* ``central_roi_mean``: The mean pixel value of the central region of interest.
* ``central_roi_std``: The standard deviation of the pixel values of the central region of interest.
* ``central_roi_max``: The maximum pixel value of the central region of interest.
* ``central_roi_min``: The minimum pixel value of the central region of interest.

API Documentation
-----------------

Expand Down
Loading

0 comments on commit feeb061

Please sign in to comment.