decimal App Documentation

User Tools

Site Tools

Trace:
planning:instructions_for_use:instructions_for_use

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

planning:instructions_for_use:instructions_for_use [2017/08/11 21:16] – [Release Version Compatibility] dpatenaudeplanning:instructions_for_use:instructions_for_use [2021/07/29 18:23] (current) – external edit 127.0.0.1
Line 3: Line 3:
 ===== Overview and Indications for Use ===== ===== Overview and Indications for Use =====
  
-The Astroid Planning App is an interactive end user application that leverages the existing .decimal Astroid Dosimetry App [FDA 510(k) K150547] library of functions (accessed through the Thinknode® cloud services framework) for device creation, dose calculation, optimization, and many other purposes, for the intended use and primary purpose of enabling radiotherapy professionals to efficiently design and analyze proton radiotherapy treatment plans. Typical indications for use are for the treatment of persons with cancer, over a wide range of potential disease locations. In the most common use case of the software, users will import patient data from existing imaging and contouring software programs, manage physician prescription and intent information, develop a proton treatment plan, and analyze the plan to determine how well it meets the physician’s goals. Since the critical treatment planning functions and calculations are handled outside this software application, by a software of known quality and pedigree, the primary and most frequently used functions of this software are the record keeping service (for patient data storage), user interface controls, and visualization tools.+The Astroid Planning App is an interactive end user application for proton treatment planning for the intended use and primary purpose of enabling radiotherapy professionals to efficiently design and analyze proton radiotherapy treatment plans. This Astroid Planning App leverages the existing .decimal Astroid Dosimetry App [FDA 510(k) K150547], which is a library of treatment planning functions accessed through the Thinknode® cloud services framework, for device creation, dose calculation, optimization, and all other dosimetry and processing calculations. Since the Astroid Dosimetry App is responsible for performing the calculations, the scope of this Astroid Planning App is to be the interface for end users to input treatment planning data and review the results. Typical indications for use of this application are for the treatment of persons with cancer, over a wide range of potential disease locations. In the most common use case of the software, users will import patient data from existing imaging and contouring software programs, manage physician prescription and intent information, develop a proton treatment plan, and analyze the plan to determine how well it meets the physician’s goals. Since the critical treatment planning functions and calculations are handled outside this software application, by a software of known quality and pedigree, the primary and most frequently used functions of this software are the record keeping service (for patient data storage), user interface controls, and visualization tools.
  
 Furthermore, since the accuracy of information computed and displayed by an application such as this is very important to the proper treatment of patients, it is critical that users have the appropriate educational and clinical experience backgrounds to adequately understand and use the product. Additionally, since each radiotherapy treatment machine produces a unique beam of radiation, there is much responsibility on the end users to adequately commission and test this software over the full range of expected treatment conditions before the system is utilized for patient treatment. Furthermore, since the accuracy of information computed and displayed by an application such as this is very important to the proper treatment of patients, it is critical that users have the appropriate educational and clinical experience backgrounds to adequately understand and use the product. Additionally, since each radiotherapy treatment machine produces a unique beam of radiation, there is much responsibility on the end users to adequately commission and test this software over the full range of expected treatment conditions before the system is utilized for patient treatment.
Line 11: Line 11:
 It is the user's responsibility to commission and test the dose accuracy prior to patient treatment. This general liability on the end users should be understood and communicated to all users and a representative with signatory authority from each facility using Astroid must sign a //User Agreement// stating their understanding and acceptance of this responsibility. It is the user's responsibility to commission and test the dose accuracy prior to patient treatment. This general liability on the end users should be understood and communicated to all users and a representative with signatory authority from each facility using Astroid must sign a //User Agreement// stating their understanding and acceptance of this responsibility.
  
-Additionally, a site administrator with signatory authority will be required to sign an //End User License Agreement// on behalf of the facility indicating understanding of the responsibilities for quality and accuracy described herein.+Additionally, a site administrator with signatory authority will be required to sign an //End User License Agreement// on behalf of the facility indicating understanding of the responsibilities for quality, accuracy, and security described herein.
  
 ===== Clinical Safety ===== ===== Clinical Safety =====
Line 51: Line 51:
 ==== System Availability and Data Integrity ==== ==== System Availability and Data Integrity ====
  
-As with any cloud based application there is always concern with system availability and uptime. Astroid makes use of caching at various system levels to improve performance and mitigate some of these concerns, however, this can never provide 100% assurance and reliability. Since customer has unique needs, specific business agreements will be entered into with each customer as appropriate to detail the reliability guarantees and assurances. Data integrity is generally a less variable concern, as Astroid's cloud storage providers strong guarantee the highest commercially available data redundancy and integrity limits (approaching 99.999999% per year). Data is transferred to and from the cloud services using secure transfer protocols, that guarantee error-free of transfer using common industry standard techniques (for more details please see the [[https://developers.thinknode.com/guides/ipc|Thinknode IPC article]]).+As with any cloud based application there is always concern with system availability and uptime. Astroid makes use of caching at various system levels to improve performance and mitigate some of these concerns, however, this can never provide 100% assurance and reliability. Since customer has unique needs, specific business agreements will be entered into with each customer as appropriate to detail the reliability guarantees and assurances. Data integrity is generally a less variable concern, as Astroid's cloud storage providers strong guarantee the highest commercially available data redundancy and integrity limits (approaching 99.999999% per year). Data is transferred to and from the cloud services using secure transfer protocols, that guarantee error-free of transfer using common industry standard techniques (for more details please see the [[https://developers.thinknode.com/guides/ipc|Thinknode IPC article]]). While Astroid has been designed with security in mind, users should understand that it is still their responsibility to ensure the system is accessed and controlled properly. Following international standards for IT risk management, such as IEC 80001-1, is therefore highly recommended.
  
 Since data integrity is such a critical feature for application such as this, the Astroid Planning App automatically saves both the state of the application and the working record data on a timer (triggering every minute or less) as well as on exit of any create or edit event in the application. Additionally, each "save" event creates a new entry in the record's history log in Thinknode, which provides a log file for editing of all records and a ensures that patient records are saved securely on an independent medium so they are not lost in the event of a local system failure or crash. Since data integrity is such a critical feature for application such as this, the Astroid Planning App automatically saves both the state of the application and the working record data on a timer (triggering every minute or less) as well as on exit of any create or edit event in the application. Additionally, each "save" event creates a new entry in the record's history log in Thinknode, which provides a log file for editing of all records and a ensures that patient records are saved securely on an independent medium so they are not lost in the event of a local system failure or crash.
Line 59: Line 59:
 The following is a list of several important items that users should understand in regards to the information displays in the Astroid Planning Application: The following is a list of several important items that users should understand in regards to the information displays in the Astroid Planning Application:
  
-  * The Astroid Planning exclusively uses IEC 61217 coordinate systems for display information (machine based coordinates are NOT available)+  * The Astroid Planning exclusively uses DICOM coordinate systems for display information (machine based coordinates are NOT available)
   * All linear dimensions are shown in millimeters (mm)   * All linear dimensions are shown in millimeters (mm)
   * All angular dimensions are shown in degrees (deg)   * All angular dimensions are shown in degrees (deg)
Line 66: Line 66:
   * All date and time notifications in Astroid should match current Windows OS date and time, including proper use of daylight savings time where appropriate (note: Astroid will display in 24 hour format, while Windows may display in am/pm depending on local settings)   * All date and time notifications in Astroid should match current Windows OS date and time, including proper use of daylight savings time where appropriate (note: Astroid will display in 24 hour format, while Windows may display in am/pm depending on local settings)
  
 +==== Data Validation and Limits ====
 +
 +Users are responsible for inputting a lot of data into the Astroid Planning App to develop clinical treatment plans. In the course of entering such data, there are opportunities for users to enter incorrect information. Although users are responsible for checking for such errors before clinical treatment, Astroid does provide some assistance in ensuring data limitations are met by a plan. Machine energy (range) limits, gantry angles, patient support (couch) angles, snout extensions, as well as shifter and aperture sizes and availability are all explicitly limited to user configured levels within the Astroid Planning App controls. Additionally, certain incompatible settings, such as zero thickness rinds and overlapping structure min/max constraints are also explicitly prevented within the Astroid user interface. Despite these many data validation checks, some entries, such as min/max spot MU's are not validated within the Astroid user interface and users should include appropriate checks and warnings in their custom treatment plan reports to ensure such concerns are brought to the attention of all responsible parties before patient treatment begins. Such warnings should include a statement such as this (or similar): "CAUTION: SOME DATA ELEMENTS USED WERE OUTSIDE NORMAL RANGE".
 ==== Data Displays and Interpretation ==== ==== Data Displays and Interpretation ====
  
Line 95: Line 98:
 The astroid Planning App is installed and launched from the astroid Launcher. The Launcher program provides the following functionality in regards to the Planning App: The astroid Planning App is installed and launched from the astroid Launcher. The Launcher program provides the following functionality in regards to the Planning App:
   - Ensures that all users at a site are using the same version of the application   - Ensures that all users at a site are using the same version of the application
-  - Ensures that the local Planning App client stays in sync with the latest release version+  - Ensures that the local Planning App client stays in sync with the latest release version (as set via Thinknode)
   - Provides user authentication and password management   - Provides user authentication and password management
  
Line 101: Line 104:
  
 By using the astroid Launcher, users can log in to multiple realms with each realm using a different app version. This allows for scenarios of using non-clinical or research application versions from the same user account or workstation without the overhead of managing multiple installations. By logging into a realm, the user is required to use the installed client version for that realm. By using the astroid Launcher, users can log in to multiple realms with each realm using a different app version. This allows for scenarios of using non-clinical or research application versions from the same user account or workstation without the overhead of managing multiple installations. By logging into a realm, the user is required to use the installed client version for that realm.
 +
 +Details regarding the specific requirements for computers on which the Launcher and Planning App client applications will be installed can be found on the [[planning:userguide:systemrequirements|System Requirements]] page.
 === Releasing a new App Version === === Releasing a new App Version ===
  
Line 114: Line 119:
     * **<client_version>**     * **<client_version>**
  
-For the launcher to register that an application should be installed for a realm, the //client// app with the //client_version// matching the dev-launcher RKS records should be installed into that realm. +For the launcher to register that an application should be installed for a realm, the //client// app with the //client_version// matching the dev-launcher RKS records should be installed into that realm. Please note that since the Launcher uses the //dev-launcher// realm for storing its records, all users of the Launcher will need permissions to read from this realm. Also, permissions to install/change app versions in Thinknode can be limited using Thinknode policies. Specifically, the //iam:realms:installVersions// permission is used to control this accessibility.
  
-For Example: from the above RKS hierarchy example, the application client named //planning// with client version //1.0.0-beta1// should be installed in the intended realm. When a user logs into the realm in the astroid Launcher, they will have the ability to automatically install and launch that application.+For Example: from the above RKS hierarchy example, the application client named //planning// with client version //1.0.0-beta1// should be installed in the intended clinical realm where users would need to access this version. When a user logs into the astroid Launcher and selects the clinical realm, they will have the ability to automatically install and launch that application version.
  
 === Release Notes === === Release Notes ===
  
 For the release notes for each version of the Planning Application, please refer to the [[https://dotdecimal.freshdesk.com/support/discussions/forums/9000203024|.decimal Freshdesk Forum]]. For the release notes for each version of the Planning Application, please refer to the [[https://dotdecimal.freshdesk.com/support/discussions/forums/9000203024|.decimal Freshdesk Forum]].
 +
 +=== DICOM Receiver ===
 +
 +Your site may have been provided with a DICOM receiver accessory package along with the astroid Planning App. This package may also require updating when installing new versions of the Planning App. The Planning App release notes will describe the necessity for such changes between versions and will also provide download links for obtaining the latest DICOM package software files. The DICOM receiver application includes a configuration file (receiver_config.json) that controls several important parameters for the DICOM receiver:
 +  * local_ae_title: <public name for this dicom receiver>
 +  * local_port: <local network communication port for this ae title>
 +  * timeout: <max time allowed between files to consider them as a batch>
 +  * storage_root_path: <local directory where DICOM files will be saved before upload begins>
 +  * thinknode:
 +    * user_token: <user access token from the DICOM upload account for your site>
 +    * api_url: <full thinknode url for your site account>
 +    * apps: <list of apps to get contexts for, must include: dosimetry, planning, and dicom>
 +  * realm_name: <realm to which the DICOM data should be uploaded>
 +  * account_name: <thinknode account name for your site>
  
 ==== Release Version Compatibility ==== ==== Release Version Compatibility ====
 +
 +The astroid Planning App is tested for version compatibility by .decimal prior to release to customers. However, it is still important for each site to independently test and verify the data integrity of each version prior to release at the site. Specifically, .decimal will test the version compatibility by:
 +  * Adding manual and automatic data upgrades, as appropriate, for changes in the data model. When applicable, these changes are required to be sensible to the clinical environment and will be documented in the release notes.
 +  * Performing a Thinknode [[https://developers.thinknode.com/services/apm/apps|GET /apm/apps/:account/:app/branches/:branch/statistics]] route comparing the current clinical version against the new version. This route will expose any missing data upgrades between the two app versions.
 +  * Test the final dose calculations of matching patients between the two app versions to ensure the final doses exactly match (unless the dosimetry app has been otherwise indicated as changed).
  
 Prior to releasing a new app version into a realm, it is imperative to ensure that the data is compatible between the existing version installed in the realm and the new version that is intended to be installed.  Prior to releasing a new app version into a realm, it is imperative to ensure that the data is compatible between the existing version installed in the realm and the new version that is intended to be installed. 
  
-The following procedure shall be followed in order to safely release new versions of an application. +The following procedure shall be followed in order to safely release new versions of an application: 
-FIXME+  - For the realm being upgraded [[planning:instructions_for_use:instructions_for_use#realm_data_duplication_or_backup|copy the bucket data]] to a new test bucket so the new version can be tested prior to being released. 
 +  - Install the release candidate app version into a test realm that is using the copied bucket. 
 +  - Review the release notes for the new version and ensure you understand the changes. 
 +    - Check the release notes to determine if accessory applications may be impacted by the changes (e.g. DICOM receivers, report scripts) and complete any necessary steps to update or configure these items to work with the new test realm. 
 +  - Login to the launcher and select the new test realm. Ensure the new app version is able to be installed and launched. 
 +  - Open existing patients in the test realm. You should ensure each of the following for the existing patients and plans in the test realm: 
 +    - The patients and plans all open without errors. 
 +    - The final optimized dose result is the same as the previous version. Note: because a new version is released, the optimizer may rerun. But the result should be the same (Thinknode Immutable IDs may be used to confirm the exact matching of results). 
 +    - Perform any testing deemed appropriate in regards to the changes outlined in the release notes and required by regulatory guidelines for treatment planning system upgrades. 
 +  - Once the release candidate has been thoroughly tested and is ready for release, notify all users at your site of the pending release and set an appropriate date and time for the release (it is generally good practice to stop all active clinical use during the upgrade so choose a time outside of normal clinical operating hours). At the designated date/time  [[planning:instructions_for_use:instructions_for_use#realm_data_duplication_or_backup|back up the bucket data]] in the clinical realm (data may have changed since the previous copy was made, so do not skip this step). **Keeping the latest backup of data is important as it provides the ability to roll back to a working clinical state should the release process fail.** 
 +  - Using the Thinknode Client: 
 +    - Navigate to the Admin -> Realms page. 
 +    - Uninstall the existing astroid app versions and install the new app versions. 
 +    - Login to the launcher and select the clinical realm. Ensure the new app version is able to be installed and launched. 
 +    - Open a patient plan and ensure it loads without error. 
 +    - Perform any other transfer testing necessary to ensure safe clinical release.
 ==== Realm Data Duplication or Backup ==== ==== Realm Data Duplication or Backup ====
  
-Data from within in a realm can be duplicated or backed up by manually copying the realm's bucket. This will produce a new bucket that is an exact replica of the original bucket and its data. This process allows for data backup, release testing, or data manipulation without adversely impacting the original bucket and data.+Data from within in a realm can be duplicated or backed up by manually copying the realm's bucket. This will produce a new bucket that is an exact replica of the original bucket and its data. This process allows for data backup, release testing, or data manipulation without adversely impacting the original bucket and data. To restore to a copied bucket, simply change the bucket to which the desired realm is currently associated via the Thinknode-Client.
  
 If your user has the required thinknode permissions to read and manage buckets then you can backup data by running the[[https://developers.thinknode.com/services/iam/buckets|copy buckets route (POST /iam/buckets/:bucket)]]. If your user has the required thinknode permissions to read and manage buckets then you can backup data by running the[[https://developers.thinknode.com/services/iam/buckets|copy buckets route (POST /iam/buckets/:bucket)]].
Line 138: Line 177:
 The following page describes the hierarchy of data used to manage patient data records within the Astroid planning environment. The following page describes the hierarchy of data used to manage patient data records within the Astroid planning environment.
  
-===== Hierarchy =====+==== Hierarchy ====
  
   * __**Patient**__   * __**Patient**__
Line 167: Line 206:
           * Constraints           * Constraints
           * Objectives           * Objectives
 +          * Optional Fluence Override
           * Dose Results           * Dose Results
  
Line 174: Line 214:
  
 */ */
-===== Descriptions =====+==== Descriptions ====
  
   * **__Patient__**:   * **__Patient__**:
Line 190: Line 230:
       * A specific model of a target, OAR, or other structure. A physician may provide an initial target contour and a treatment plan generated using this information. The physician may later (using the same CT image set) provide a revised target contour. Rather than import this revision as a new structure or override the original, you may specify this new contour as a variant of the original. Each contour may have only a single "active" variant and the plan will automatically update based on the selection of the active variant. However, in some cases it is not desirable to update the plan, so the user may also choose to lock the plan and simply recompute DVH and other volume based statistics based on the new active variant geometry. In either case, variants can be used to streamline workflows and prevent accidental misuse of out-dated contours.       * A specific model of a target, OAR, or other structure. A physician may provide an initial target contour and a treatment plan generated using this information. The physician may later (using the same CT image set) provide a revised target contour. Rather than import this revision as a new structure or override the original, you may specify this new contour as a variant of the original. Each contour may have only a single "active" variant and the plan will automatically update based on the selection of the active variant. However, in some cases it is not desirable to update the plan, so the user may also choose to lock the plan and simply recompute DVH and other volume based statistics based on the new active variant geometry. In either case, variants can be used to streamline workflows and prevent accidental misuse of out-dated contours.
   * **__Plan__**:    * **__Plan__**: 
-    * A detailed model of a proton therapy treatment. Most aspects of the patient planning information are stored here (e.g. Beams, Fraction Groups, Optimization Information, and Dose Results). A Plan will specify the portion of the Prescription it should meet and physicians will publish (approve) a Plan to indicate it is ready to proceed to QA and (if successful) on to actual patient treatment. __There should be only one "published" Plan per Prescription__.+    * A detailed model of a proton therapy treatment. Most aspects of the patient planning information are stored here (e.g. Beams, Fraction Groups, Optimization Information, and Dose Results). A Plan will specify the portion of the Prescription it should meet and physicians will publish (approve) a Plan to indicate it is ready to proceed to QA and (if successful) on to actual patient treatment. __There should be only one "published" Plan per Prescription__. Plans may optionally contain a fluence override vector that will be used in place of the actual optimized fluence results from the plan (note there are no UI tools to add such overrides and they must be added via user controlled scripts).
  
 +==== Structures in the Data Model ====
  
----- +There are multiple levels that various structures can live at. Each level and structure type will effect how the structure will relate to the plan. Refer to the [[planning:userguide:tutorials:all_tutorials#structure_data_model|Structure Data Model Guide]] for more details.
-<WRAP center 10%>//USR-###//</WRAP>+
  
-<WRAP center 50%>.decimal LLC, 121 Central Park Place, Sanford, FL. 32771</WRAP>+ 
 +---- 
 +<WRAP center 60%>.decimal LLC, 121 Central Park Place Sanford, FL. 32771 1-800-255-1613</WRAP>
  
    
planning/instructions_for_use/instructions_for_use.1502486187.txt.gz · Last modified: 2021/07/29 18:22 (external edit)