decimal App Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Planning App Instructions for Use ======

===== Overview and Indications for Use =====

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.

===== User Responsibilities =====

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, accuracy, and security described herein.

===== Clinical Safety =====

It is the responsibility that the user performs end-to-end testing prior to the clinical implementation of Astroid. The user should follow accepted industry guideline (such as AAPM TG244) for the end-to-end testing. This testing should be performed by qualified personnel.

It is the responsibility of the facility to ensure that all users of the Astroid treatment planning system have had training on the Astroid product and possess the appropriate clinical education, experience, and (where applicable) licensure to develop clinical treatment plans. This includes, but is not limited to, the application training provided by Astroid staff. 

It is recommended that users follow acceptable global standards during the commissioning of the Astroid product. During the clinical set up, the following should be tested to ensure clinical safety prior to treatment:
  - Geometric relationships of the hardware machine models  
  - The dose algorithm   
  - Data access and storage  
  - Accuracy of the planning dose systems.  

==== Warning ====

It is critical that all users read these Instructions for Use and the User Guide material carefully and completely and consult the provided User Guides and other training materials to ensure proper use of the application and proper interpretation of results.

<WRAP center round important 60%>
Prior to the delivery of any plan on a patient, users are responsible for performing patient specific QA to ensure clinical acceptability of the delivered dose distribution. Since users are responsible for testing the acceptability of the delivered dose before treatment, Astroid, its staff, and representatives shall not be liable for any mis-treatments that may result from use of the system.
</WRAP>

<wrap em>Caution: Federal law restricts this device to sale by or on the order of a physician.</wrap> 

===== Intended Use =====

The Astroid Planning App is an interactive end user application that leverages the existing .decimal Astroid Dosimetry App library [FDA 510(k) K150547] 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. 

===== User Profile =====

The Astroid Planning App is a tool to develop radiotherapy treatment plans for delivery using a proton therapy system. Such plans are generally developed to meet the directives of a physician through a formal documented prescription. As such, the users of this application are expected to be supervised by an attending physician and should themselves be experienced in the physics and dosimetric characteristics of proton radiotherapy. Additionally, users are expected to have formal training in general radiotherapy techniques and best practices, proton therapy specific planning techniques, and general principles of patient safety and care. Most users will have college-level training or degrees, as well as licensure for their particular roles and responsibilities through their state, nation, or professional association. Users should also be well versed in regulations regarding protection of patient health information and have a basic understanding of standard practices regarding computer usage and security. 

===== Product Features =====

In the most common, primary 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 via Thinknode®), user interface controls, and visualization tools.  
 The Astroid Planning App software communicates with other treatment planning systems generally by sending & receiving files in various DICOM RT formats, although the extensive Application Programming Interface (API) of Thinknode® allows users to easily build their own export and import conversion applications. 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. It is this area that provides opportunity for the most likely incorrect use of the software, which would be poor or inadequate commissioning of the application (note many other cases of potential misuse have be designed out of the system by limiting allowed user interactions, providing warnings, and preventing unsafe or incompatible operations). This main misuse is mitigated by requiring that users understand that it is their responsibility to perform appropriate quality assurance measurements for every patient plan prior to treatment, which should independently confirm that the treatment plan information displayed within the Astroid Planning App adequately matches the actual, to be delivered, plan. Please note that such testing is a safety and regulatory requirement in most territories.


==== 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]]). 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.

==== Coordinates and Units of Measure ====

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 DICOM coordinate systems for display information (machine based coordinates are NOT available)
  * All linear dimensions are shown in millimeters (mm)
  * All angular dimensions are shown in degrees (deg)
  * All radiation dose quantities will be shown with their corresponding units within the application (e.g. Gy(RBE) or %)
  * All date/time values are provided in a // dd/mm/yyyy h:m:s // format using local time on a 24 hour clock
  * 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 ====

Astroid contains many displays throughout the plan creation process. Please refer to [[http://apps.dotdecimal.com/doku.php?id=planning:userguide:tutorials:all_tutorials#astroid_optimization|the Astroid Tutorials]].

==== Unauthorized Use ====

The Astroid Planning Application will contain sensitive patient information that is protected under various governmental regulations, therefore users must ensure they adequately follow all appropriate and applicable rules regarding how, where, and when their staff may access the application and its data. In order to facilitate proper usage and protections, Astroid has a robust user permissioning scheme, as well as industry standard options for configuring password requirements, as explained at the [[https://developers.thinknode.com/services/ams/settings|Thinknode Account Management Settings page]]. Since all application and data access requires user login credentials, it is important that site administrators implement a strong password policy and that all users understand the importance of maintaining secrecy of their password (i.e. passwords should never be shared among more than one user). It is these user credentials that protect the system and its data from unauthorized access and replication.  

==== Access Control ====

Astroid (Thinknode) administrators have the ability to manage user access, passwords, and "lock" data records to prevent unwanted and unintended modification. Several features have specific access rights that can be configured, including the ability to lock data records, unlock data records, and delete data. By configuring these options, administrators can lock critical data records, such as beam models, equipment information, and other machine/site level data, such that only expressly authorized users can edit these fields. All critical site records such as these should be kept "locked" at all times, and should be unlocked by only be authorized users when expliciting desiring to edit said records (and locking them again after modification is complete). In addition to the practice of locking site data records, users are expected to establish a review process whereby a minimum of two authorized individuals will review all proposed site data changes (including beam models and equipment data) prior to updating the records in Thinknode (please note that at this time, all such records are downloaded, reviewed, and updated through the Thinknode Desktop Client, which is available for download [[https://desktop.thinknode.com/|here]]).

As Astroid is a cloud based application the site administrator will be responsible for the installation of Astroid on to the appropriate workstations. Each user should have an individual log in and password to access the planning app that prevents unauthorized access. Best practices should be followed.

For further information on access management and permission settings please refer to [[https://developers.thinknode.com/services/iam|Thinknode IAM Services]]. The Thinknode services provide two important considerations regarding your clinical data, first, the permission schemes and access control, provide effective control against unintentional and malicious data manipulation and the inherent storage redundancy of the cloud resources provides exception protection against data loss.

==== Known Limitations ====

For a list of known system issues and limitations please refer to the following articles for the Planning App and Dosimetry App, respectively.

[[planning:userguide:userguide#known_application_limitations|Planning App Known Limitations]]

[[dosimetry:userguide:userguide#known_application_limitations|Dosimetry App Known Limitations]]


==== Release Management (Launcher) ====

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 the local Planning App client stays in sync with the latest release version (as set via Thinknode)
  - Provides user authentication and password management

When an application update is available via the astroid Launcher, the users will be required to install the App in the Launcher. This is accomplished by selecting the //Install// button for the specific app. Within a few minutes, the app should be downloaded and installed locally for the current user account. The user will then be able to launch the released app version from the astroid Launcher.

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 ===

In order to "push" a new Planning App version to the astroid Launcher, the dev-launcher realm must be updated to include an RKS entry for the new version of the application being released. The //client_version// record references the immutable data for the application package that contains the file system contents for the app versions (executable, dlls, etc.). The RKS hierarchy for this realm should be as follows:
  * **<client>** (e.g.: planning)
    * **<client_version>** (e.g: 1.0.0-beta1)
      * References Immutable: <code>{
  "reference": "<immutable_id>",
  "path": "planning_app.exe"
} </code>
    * **<client_version>**
  * **<client>**
    * **<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. 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 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 ===

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 ====

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. 

The following procedure shall be followed in order to safely release new versions of an application:
  - 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 ====

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)]].

===== Astroid Patient Data Model =====

The following page describes the hierarchy of data used to manage patient data records within the Astroid planning environment.

==== Hierarchy ====

  * __**Patient**__
    * __**Course**__
      * Prescriptions & Clinical Goals
      * Directive Structure List
      * __**Patient Model**__
        * Imaging Data
        * Structure Data
          * Active Variant
          * Variant List
        * __**Plans**__
          * RSP Data
          * Structures & Points
          * Calculation Grid
          * Treatment Room
          * Beams
            * Snout
            * Devices & Spot Options
            * DRRs
          * Fraction Groups
            * Target
            * Constraint
            * Targets (1 or more)
              * Constraint (1 or more)
              * Beamset (1 or more)
                * Beams (1 or more)
          * Constraints
          * Objectives
          * Optional Fluence Override
          * Dose Results

/*

Variant: 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.

*/
==== Descriptions ====

  * **__Patient__**:
    * A person receiving medical treatment. A Patient record contains basic personal information and demographics, as well as any number of treatment Courses.
    * This is where the patient name (prefix, given name, middle name, family name, suffix), medical record number (MRN#), sex (male, female, other, any) and date of birth (month, day, year) are stored. 
  * **__Course__**: 
    * A prescribed regimen to be followed to treat a specific disease occurrence for a specific period of time. A Course will contain the physician's Intent and Directive information
    * The user will label the Course of treatment and specify the physician of record. The user has the option of adding a description of the course of treatment.
    * The intent captures the physician's purpose for this Course of radiation treatment. An Intent contains information about any protocols this patient is under, as well information regarding the disease site, body system, and body part (for both templating and billing purposes). An Intent can contain any number of Directives (although it's uncommon to have more than one). The user will define the type of treatment (curative, palliative, or prophylactic), as well as the treatment site at this level. A narrative of what the physician desires to achieve as a result of the course is also saved here.
    * The directive is the physician's orders for treating this Course. A Directive contains information about the prescription and other clinical goals for the Course. 
    * A Course also contains any number of Patient Models.
  * **__Patient Model__**: 
    * A description of the patient's anatomy. Contains a single CT image set and all contour variants (targets and organs at risk) associated with these images. A Patient Models can contain any number of associated Plans.
    * **__Variant__**:
      * 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__**: 
    * 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 60%>.decimal LLC, 121 Central Park Place Sanford, FL. 32771 1-800-255-1613</WRAP>