Skip to main content

A toolkit for performing TG-142 QA-related tasks on a linear accelerator

Project description

https://s3.amazonaws.com/pylinac/Pylinac+Full.png Join the chat at https://gitter.im/jrkerns/pylinac Latest Version https://anaconda.org/jrkerns/pylinac/badges/installer/conda.svg MIT Travis CI Code Coverage Code issues Documentation Status

Pylinac provides TG-142 quality assurance (QA) tools to Python programmers as well as non-programmers in the field of therapy medical physics. The package comes in two flavors: source-level and web app. The source-level allows programmers and those familiar with Python to create custom tests with pylinac while the web app is for those who don’t want or don’t know how to program.

Pylinac contains high-level modules for automatically analyzing images and data generated by linear accelerators. Most scripts can be utilized with <10 lines of code.

The library also contains lower-level hackable modules & tools for creating your own radiation therapy algorithms.

Documentation

To get started, install the package, run the demos, view the API docs, and learn the module design, visit the Full Documentation on Read The Docs.

Installation

Pylinac should be installed via conda if available. First, add the proper channel, then install the package:

$ conda config --add channels jrkerns
$ conda install pylinac

You may also install via pip, although you must have C compilers to build the dependencies :

$ pip install pylinac

See the Installation page for further details.

Tools

Below are the high-level tools currently available:

  • Continuous & One-Time Directory Analysis -

    True, one-time “set it and forget it” service that analyzes any file that enters the folder. Files with keywords and certain file types are analyzed automatically. You can also specify “source” folders to pull new files from (e.g. a Varian shared drive holding Trajectory logs or QA images).

    • Easy: Use filenames to specify analysis types - Just rename the file to contain a keyword (which are customizable) and move it to the directory!

    • Easier: Use a classifier to identify images - The epitome of lazy! Certain analyses don’t even need to have a keyword if you choose to use the automatic classifier. E.g. a picket fence and starshot image can be differentiated and analyzed according to their own modules, with no extra work!

    After installation, run the watcher script via the command line:

    $ pylinac watch "dir/to/watch"  # start watching!

    or via Python

    from pylinac import watch, process
    
    watch("dir/to/watch")  # will run forever
    process("dir/to/watch")  # will run once and then return

    And that’s it! No code to write; no fuss, no muss. Analysis settings are customizable and includes optional email service upon analysis.

  • TG-51 Absolute Dose Calibration - Input the raw data and pylinac can calculate either individual values (kQ, PDDx, Pion, etc) or use the provided classes to input all measurement data and have it calculate all factors and dose values automatically.

    Example script:

    from pylinac import tg51
    
    tg51_6x = tg51.TG51Photon(temp=TEMP, press=PRESS, model=CHAMBER,
                              n_dw=ND_w, p_elec=P_ELEC,
                              measured_pdd=66.4, lead_foil=None,
                              clinical_pdd=66.5, energy=ENERGY,
                              volt_high=-300, volt_low=-150,
                              m_raw=(25.65, 25.66, 25.65),
                              m_opp=(25.64, 25.65, 25.65),
                              m_low=(25.64, 25.63, 25.63),
                              mu=MU, tissue_correction=1.0)
    
    # Done!
    print(tg51_6x.dose_mu_dmax)
    
    # examine other parameters
    tg51_6x.pddx
    tg51_6x.kq
    tg51_6x.p_ion
    
    # change readings if you adjust output
    tg51_6x.m_raw = (25.44, 25.44, 25.43)
    # print new dose value
    print(tg51_6x.dose_mu_dmax)
  • Planar Phantom Analysis (Leeds TOR, StandardImaging QC-3) -

    The planar imaging module analyzes 2D phantoms. Currently only the LeedsTOR kV phantom and Standard Imaging QC-3 MV phantom are supported, but more phantoms are in the works!

    Features:

    • Automatic phantom localization - Set up your phantom any way you like; automatic positioning, angle, and inversion correction mean you can set up how you like, nor will setup variations give you headache.

    • High and low contrast determination - Analyze both low and high contrast ROIs. Set thresholds as you see fit.

    Example script:

    from pylinac import LeedsTOR, StandardImagingQC3
    
    leeds = LeedsTOR("my_leeds.dcm")
    leeds.analyze()
    leeds.plot_analyzed_image()
    
    qc3 = StandardImagingQC3("my_pipspro.dcm")
    qc3.analyze()
    qc3.plot_analyzed_image()
  • Winston-Lutz Analysis -

    The Winston-Lutz module analyzes EPID images taken of a small radiation field and BB to determine the 2D distance from BB to field CAX. Additionally, the isocenter size of the gantry, collimator, and couch can all be determined without the BB being at isocenter. Analysis is based on Winkler et al and Du et al.

    Features:

    • Automatic field & BB positioning - When an image or directory is loaded, the field CAX and the BB are automatically found, along with the vector and scalar distance between them.

    • Isocenter size determination - Using backprojections of the EPID images, the 3D gantry isocenter size and position can be determined independent of the BB position. Additionally, the 2D planar isocenter size of the collimator and couch can also be determined.

    • Image plotting - WL images can be plotted separately or together, each of which shows the field CAX, BB and scalar distance from BB to CAX.

    • Gantry sag - The sag of the gantry is also quantified and can be plotted.

    Example script:

    from pylinac import WinstonLutz
    
    wl = WinstonLutz("wl/image/directory")  # images are analyzed upon loading
    wl.plot_summary()
    print(wl.results())
  • Starshot Analysis -

    The Starshot module analyses a starshot image made of radiation spokes, whether gantry, collimator, MLC or couch. It is based on ideas from Depuydt et al and Gonzalez et al.

    Features:

    • Analyze scanned film images, single EPID images, or a set of EPID images - Any image that you can load in can be analyzed, including 1 or a set of EPID DICOM images and films that have been digitally scanned.

    • Any image size - Have machines with different EPIDs? Scanned your film at different resolutions? No problem.

    • Dose/OD can be inverted - Whether your device/image views dose as an increase in value or a decrease, pylinac will detect it and invert if necessary.

    • Automatic noise detection & correction - Sometimes there’s dirt on the scanned film; sometimes there’s a dead pixel on the EPID. Pylinac will detect these spurious noise signals and can avoid or account for them.

    • Accurate, FWHM star line detection - Pylinac uses not simply the maximum value to find the center of a star line, but analyzes the entire star profile to determine the center of the FWHM, ensuring small noise or maximum value bias is avoided.

    • Adaptive searching - If you passed pylinac a set of parameters and a good result wasn’t found, pylinac can recover and do an adaptive search by adjusting parameters to find a “reasonable” wobble.

    Example script:

    from pylinac import Starshot
    
    star = Starshot("mystarshot.tif")
    star.analyze(radius=0.75, tolerance=1.0, fwhm=True)
    print(star.return_results())  # prints out wobble information
    star.plot_analyzed_image()  # shows a matplotlib figure
  • VMAT QA -

    The VMAT module consists of the class VMAT, which is capable of loading an EPID DICOM Open field image and MLC field image and analyzing the images according to the Varian RapidArc QA tests and procedures, specifically the Dose-Rate & Gantry-Speed (DRGS) and MLC speed (MLCS) tests.

    Features:

    • Do both tests - Pylinac can handle either DRGS or DRMLC tests.

    • Adjust for offsets - Older VMAT patterns were off-center. Easily account for the offset by passing it in.

    • Automatic identification using file names - If your file names are clear, the image type and test type don’t even have to be specified; just load and analyze.

    Example script:

    from pylinac import VMAT
    
    vmat = VMAT(images=["DRGSopen.dcm", "DRGSdmlc.dcm"], delivery_types=["open", "dmlc"])
    vmat.analyze(test='drgs', tolerance=1.5)
    print(vmat.return_results())  # prints out ROI information
    vmat.plot_analyzed_image()  # shows a matplotlib figure
  • CT & CBCT QA -

    The CBCT module automatically analyzes DICOM images of a CatPhan 504, 503, or 600 acquired when doing CT or CBCT quality assurance. It can load a folder or zip file that the images are in and automatically correct for phantom setup in 6 axes. It can analyze the HU regions and image scaling (CTP404), the high-contrast line pairs (CTP528) to calculate the modulation transfer function (MTF), and the HU uniformity (CTP486) on the corresponding slice.

    Features:

    • Automatic phantom registration - Your phantom can be tilted, rotated, or translated–pylinac will register the phantom.

    • Automatic testing of all major modules - Major modules are automatically registered and analyzed.

    • Any scan protocol - Scan your CatPhan with any protocol; or even scan it in a regular CT scanner. Any field size or field extent is allowed.

    Example script:

    from pylinac import CatPhan504, CatPhan503, CatPhan600
    
    # for this example, we'll use the CatPhan504
    cbct = CatPhan504("my/cbct_image_folder")
    cbct.analyze(hu_tolerance=40, scaling_tolerance=1, thickness_tolerance=0.2, low_contrast_threshold=1)
    print(cbct.return_results())
    cbct.plot_analyzed_image()
  • Log Analysis -

    The log analyzer module reads and parses Varian linear accelerator machine logs, both Dynalogs and Trajectory logs. The module also calculates actual and expected fluences as well as performing gamma evaluations. Data is structured to be easily accessible and easily plottable.

    Unlike most other modules of pylinac, the log analyzer module has no end goal. Data is parsed from the logs, but what is done with that info, and which info is analyzed is up to the user.

    Features:

    • Analyze Dynalogs or Trajectory logs - Either platform is supported. Tlog versions 2.1 and 3.0 supported.

    • Save Trajectory log data to CSV - The Trajectory log binary data format does not allow for easy export of data. Pylinac lets you do that so you can use Excel or other software that you use with Dynalogs.

    • Plot or analyze any axis - Every data axis can be plotted: the actual, expected, and even the difference.

    • View actual or expected fluences & calculate gamma - View fluences and gamma maps for any log.

    • Anonymization - Anonymize your logs so you can share them with others.

    Example script:

    from pylinac import load_log
    
    tlog = load_log("tlog.bin")
    # after loading, explore any Axis of the Varian structure
    tlog.axis_data.gantry.plot_actual()  # plot the gantry position throughout treatment
    tlog.fluence.gamma.calc_map(doseTA=1, distTA=1, threshold=10, resolution=0.1)
    tlog.fluence.gamma.plot_map()  # show the gamma map as a matplotlib figure
    
    dlog = load_log("dynalog.dlg")
    ...
  • Picket Fence MLC Analysis -

    The picket fence module is meant for analyzing EPID images where a “picket fence” MLC pattern has been made. Physicists regularly check MLC positioning through this test. This test can be done using film and one can “eyeball” it, but this is the 21st century and we have numerous ways of quantifying such data. This module attains to be one of them. It will load in an EPID dicom image and determine the MLC peaks, error of each MLC pair to the picket, and give a few visual indicators for passing/warning/failing.

    Features:

    • Analyze either HD or regular MLCs - Just pass a flag and tell pylinac whether it’s HD or not.

    • Easy-to-read pass/warn/fail overlay - Analysis gives you easy-to-read tools for determining the status of an MLC pair.

    • Any Source-to-Image distance - Whatever your clinic uses as the SID for picket fence, pylinac can account for it.

    • Account for panel translation - Have an off-CAX setup? No problem. Translate your EPID and pylinac knows.

    • Account for panel sag - If your EPID sags at certain angles, just tell pylinac and the results will be shifted.

    Example script:

    from pylinac import PicketFence
    
    pf = PicketFence("mypf.dcm")
    pf.analyze(tolerance=0.5, action_tolerance=0.25)
    print(pf.return_results())
    pf.plot_analyzed_image()
  • Flatness/Symmetry Analysis -

    Analysis of Flatness & Symmetry of film or EPID images. Multiple equation definitions, in/cross plane.

Discussion

Have questions? Ask them on the pylinac discussion forum.

Contributing

Contributions to pylinac can be many. The most useful things a non-programmer can contribute are images to analyze and bug reports. If you have VMAT images, starshot images, machine log files, CBCT DICOM files, or anything else you want analyzed, upload them privately here.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pylinac-1.9.0.zip (144.4 kB view hashes)

Uploaded Source

Built Distribution

pylinac-1.9.0-py3-none-any.whl (195.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page