AIM Template Builder 2.0 User's Guide

The ATB allows you to generate a set of well-defined questions and answer choices to facilitate collecting information for a particular purpose, such as The Cancer Genome Atlas Glioblastoma (TCGA GBM) study. These questions and answers are contained in an AIM XML template file that you can import into an AIM-enabled application, such as NCI's implementation of AIM on the ClearCanvas open source workstation. Aided by the information in the XML file, users of the AIM-enabled application can then annotate medical images using a controlled vocabulary and standard template. This results in simple and constrained annotations that are reproducible and consistent. The AIM-enabled application captures answers and exports them as an AIM XML document or AIM Digital Imaging and Communications in Medicine (DICOM) Structured Reporting (SR) document. Users can then send the document to the AIM Data Service or DICOM storage Service Class Provider (SCP), respectively.

You use the ATB to design templates based on lexicons of standard and user-definable terms. You add anatomic entities, imaging observations, inferences, calculations, and markups as components to a template. Adding tags to a template helps you make them easier to find. You combine multiple templates into template groups.

You can search for shared templates and template groups using the AIM Template Service and then modify them in the ATB.

AIM templates are based on the AIM template XML schema:
Version 2, Revision 13

When you open older AIM templates created using XML schema version 1, revisions 18, 19, and 23 in ATB 2.0, ATB 2.0 automatically converts them to the latest XML schema, which is version 2, revision 13.

AIM template XML schemas are based on the AIM 3.0 model and the AIM 4.0 model. XML schema version 2 collects more information than the AIM 3.0 model can store. Any information that the XML schema version 2 collects is saved to the AIM 4.0 model.

 

Imaging reports contain both graphical drawings and medical knowledge in the form of annotations. These annotations are stored as unstructured text and separated from graphical drawings, which are typically in a proprietary format on an imaging system. Extracting this valuable medical information and combining it with drawings on another system is a time-consuming process that yields results that are cumbersome to filter and search. Also, existing vocabularies used to describe medical images contain thousands of terms. This makes it difficult for users to find these terms and then include them in their AIM annotations.

The AIM model begins to solve this problem by capturing the descriptive information of an image with user-generated graphical symbols placed on the image into a single common information source. AIM captures medical findings using standard vocabularies such as RadLex, SNOMED CT_^®, and DICOM, and user-defined terminology. Image information captured in the AIM model includes the anatomic entity and its characteristics, imaging observation and its characteristics, and inference.

An AIM template contains a collection of data collection items (questions) and possible values (answers) for each question. You create a template for each imaging study. You capture each item and value using a standardized vocabulary.

An AIM template has one or more components. Each component represents a study question that may have one or more answers. Template components can be any of the following: anatomic entity, imaging observation, inference, calculation, or geometric shape (markup).

Both anatomic entities and imaging observations are also described by their associated characteristics. Anatomic entity and imaging observation characteristics inherit the attributes of their respective component. Characteristics have annotator confidence that allows a user to enter a percentage that represents the level of user confidence in answering the question. A characteristic may also have a quantification value.

You must configure ATB so that it can find the AIM Template Service and include the appropriate user name in an AIM template. The AIM Template Service is web service that can be used to store, search, and retrieve AIM template XML documents.

1. Click the Settings button ().
   The Options window appears.
   
2. Change the caGrid Userame value to the name you used when you  registered for your caGrid account. You must have a caGrid account to publish templates to the ATS. 
3. Change the ATS URL value to the server where the AIM Template Service you will use is located. If you are not hosting your own AIM Template Service instance, the URL is http://imaging.fsm.northwestern.edu.
4. Confirm or change the Default Author. The default author's name appears in the metadata of any object you create in ATB.
5. Click Save.

Deleting a template group does not delete the templates within it.

1. Click the Template Groups tab.
2. Select the template group you want to delete by clicking it.
3. Below the left panel, click .
   A message appears asking you to confirm the deletion.
4. Click Delete.

You can edit the name, version, description, and author of a template group.

1. Click the Template Groups tab.
2. Below the left panel, click .
   The selected template group's description appears.
3. Change the name of the group, version, description, and authors as needed.
4. Optionally, add a tag to the group to make it easier to search for the template group in the future.
5. Click Save.
   The edited template group appears in the Groups panel.

You can create a copy of a template group to make it easier for you to customize it.

1. Click the Template Groups tab.
2. Select the template group you want to copy.
3. At the bottom of the Groups panel, click .
   A copy of the template with the name of Current Template Name copy appears in the Groups panel. You can now customize the copied template group.

When you search the AIM Template Service for a template group that you want to modify in ATB, you import it at the same time. You do not have to take a separate step to download the template group. Once you find the template group in the search results, click it to begin using it in ATB.

1. Click the Template Groups tab.
2. Below the left panel, click and then select Search Groups.
   The Template Groups Search page appears.
   

3. Narrow your search by entering information into the fields. If you do not enter any information into the fields, all template groups available in ATS appear, and it may take longer to see the results of your search. The following fields are available.

   Field	Description
   Container Name	Template group name
   Container Description	Template group description
   Container Author	Person who created the template group in the AIM-enabled application
   Disease	Disease that is the topic of the templates in the template group
   Body Part	Body part that is the topic of the templates in the template group
   Tag Name	A name associated with this template group
   Tag Value	The value associated with the tag name for this template group

4. Click Search.
   All template groups matching the search criteria you entered appear.
   
5. Click the name link for a template group.
   ATB imports the template.

You can import a template group and use or customize it in AIM Template Builder.

1. Click the Template Groups tab.
2. Below the left panel, click .
3. Click Import.
   The Open dialog box appears.
4. Search for an XML file that contains template group information in it. The AIM Template Builder only accepts template group files that have been validated by the AIM Template XML schema. This file could have been exported from the AIM Template Builder or it could have been created manually using the AIM template XML schema.

A message appears that notifies you if the file was successfully imported. A template group that is successfully imported also appears in the Template Group list. If the import was unsuccessful, a message appears that indicates the reason why.

You can export a template group you created in AIM Template Builder to use it in an AIM-enabled workstation. Template groups created in AIM Template Builder validate the AIM template schema,  AIMTemplate_v2rv13.xsd, and are in XML format.

1. Click the Template Groups tab.
2. Select the template group you want to export.
3. Below the left panel, click .
4. Click Export.
   The Save dialog box appears.
5. Select a location where you want to save the template group XML file.

You can publish a template group that you created in AIM Template Builder to the AIM Template Service so that others can find it or so that you can import it into another application.

1. Click the Template Groups tab.
2. Select a template group from the Groups panel.
3. Below the left panel, click .
4. Click Publish.
   A window opens, prompting you to log in to the AIM Template Service.
5. Enter your password or log in as a different user and then click Login. You must have a caGrid account to publish templates to the ATS.
   The steps that follow are unique to your configuration of the AIM Template Service.

Associating one or more tags with a template group makes it easier for you to find and others to discover a template group that you created. Tags are composed of a name and a value. The tag name must be a lexicon term. The tag value can be a string you enter or a lexicon term.

1. Click the Template Groups tab.
2. Select a template group.
3. Below the left panel, click .
   The selected template group's description appears.
4. Click .
5. Double-click the Name column.
   The Edit Tag Name dialog box appears.
   

   

6. Click Select Term.
   The Lexicon Search dialog box appears.
7. Select a lexicon name and then search for an existing term. For example, in the following window, the selected lexicon is SNOMED_CT and the term is Disease.
   

   

8. Click Save.
9. Assign a code or string value to the term by clicking the Value column, entering the code or string value (for example, GBM), and then clicking Enter.
10. Click Done.
    You can see the tag when you open the template group.
    

    

When you design a template, it is helpful to keep the purpose in mind. A template structures how users will enter information into an imaging application. The following table may help make the connection between the AIM Template Builder and information entered into an imaging application.

Algorithms are types of calculations that you can add to an AIM template.

1. Create a Calculation.
2. Click to add an algorithm type to the calculation type.
   A new panel appears on the right for algorithm attributes.
   

3. Provide attributes for the algorithm type.

   Field	Description
   Description	Explanatory text about the component
   Unique Identifier	Any string that uniquely identifies this algorithm
   Algorithm Name	Algorithm name
   Algorithm Version	Algorithm version
   MathML	An optional mathML representation of the calculation

4. Click Save.

Geometric shapes, which are equivalent to markups, describe a user's region of interest on an image and are patterned after DICOM SR graphical types. Combinations of these shapes can be used to represent graphical drawings placed on images.

1. Click the Templates tab.
2. In the Templates panel, select the template to which you want to add a geometric shape.
3. In the Template Components panel, right-click the template name and select Create Geometric Shape. You can also find this option in the toolbar ().
   A new panel appears on the right and the toolbar below the Template Components panel changes to provide the option for geometric shapes.
4. In the panel on the right, provide the required information, as follows:
   
   1. Provide a Label for the calculation.
   2. Provide Explanatory Text to better describe the label.
   3. Specify the minimum and maximum number of Answer Choices that the person answering the related question may select in the template. Answer Choices inform the AIM template user how many markups the user has to create. For example, if there are two circles (min=max=2), the user should create two circles. If a multipoint is assigned with a value min=max=2, ATB interprets that this is a line (with two points, x1,y1 and x2,y2). Developers of an AIM-enabled workstation must know how to map AIM template markup to an appropriate graphical drawing tool on their workstation.
   4. Select the button that describes your display preference for the inference in the template.
   5. Select the button that describes your display preference for Annotator Confidence.
   6. Specify whether or not a comment is required.
   7. Specify one or more names in the Default Authors field to show who created the calculation. 
   8. Optionally, provide a Group Label, which can show an affiliation between this calculation and others in the same group.

   9. Select the Shape Type from the options of two-dimensional and three-dimensional shapes.
      The geometric shapes available are as follows. ATB follows the DICOM standard.

      Shape	Description
      2D Point (Arrow)	A single pixel denoted by a single (column,row) pair
      2D Circle	A circle defined by two (column,row) pairs. The first point is the central pixel. The second point is a pixel on the perimeter of the circle.
      2D Polyline (Closed Polygon)	A series of connected line segments with ordered vertices denoted by (column,row) pairs. If the first and last vertices are the same, it is a closed polygon.
      2D Ellipse	An ellipse defined by four pixel (column,row) pairs. The first two points specify the endpoints of the major axis and the second two points specify the endpoints of the minor axis of an ellipse.
      2D Multipoint (Connected Points)	Multiple pixels each denoted by a (column,row) pair
      3D Polygon (Closed Coplanar Polygon)	A series of connected line segments with ordered vertices denoted by (x,y,z) triplets, where the first and last vertices shall be the same forming a polygon; the points shall be coplanar.
      3D Polyline (Connected Line Segments)	A series of connected line segments with ordered vertices denoted by (x,y,z) triplets. The points need not be coplanar.
      3D Multipoint (Series of Points)	Multiple locations each denoted by an (x,y,z) triplet. The points need not be coplanar.
      3D Point (Arrow)	A single location denoted by a single (x,y,z) triplet.
      3D Ellipse	An ellipse defined by four (x,y,z) triplets. The first two triplets specify the endpoints of the major axis and the second two triplets specify the endpoints of the minor axis.
      3D Ellipsoid	A three-dimensional geometric surface whose plane sections are either ellipses or circles and contains three intersecting orthogonal axes, “a”, “b”, and “c”. The ellipsoid is defined by six (x,y,z) triplets, the first and second triplets specifying the endpoints of axis “a”, the third and fourth triplets specifying the endpoints of axis “b”, and the fifth and sixth triplets specifying the endpoints of axis “c”.

   10. If this is the last question in the template, select No More Questions.

   11. If this is not the last question, select the question that should follow this one from the options in the Next Question to Ask box.

5. Click Save.

Associating one or more tags with a template makes it easier for you to find and others to discover a template that you created. Tags are composed of a name and a value. The tag name must be a lexicon term. The tag value can be a string you enter or a lexicon term.

1. Click the Templates tab.
2. Select a template.
   The template components appear in the center panel.
3. In the Template Components panel, right-click the template name.
4. From the menu that appears, select .
   A new tag appears in the Template Components panel.
   
5. Provide the tag name and value.
   
   • To provide the tag name, click Select Term in the Lexicon Term (Tag Name) panel in the top right. A tag must contain at least three characters.
   • To provide the tag value, enter your own or select a term from the lexicon. To enter your own value, click Use String Value and then enter a value in the String Value box.
6. Click Save.

A key concept in understanding answer choices in AIM Template Builder is the difference between pre-coordinated and post-coordinated terms.

When users of your AIM template answer template questions, you can offer a list of standardized terms from a lexicon for their answers. These terms are called answer choices in ATB 2.0 but were called allowed terms in ATB 1.1. You can associate answer choices with Anatomic Entity, Imaging Observation, and Inference components, and Anatomic Entity and Imaging Observation characteristics.

Once you create an answer choice, you can add more answer choices under it hierarchically. This allows you to create new concepts, also called post-coordinated terms, from existing answer choices.

1. Right-click the component or characteristic and select Add Answer Choices or click in the toolbar.
   The Lexicon Search dialog box appears.
2. Select an answer choice from a lexicon you have created as follows.
   
   1. From the list on the far left of the page, select at least one lexicon where you believe the term you are searching for is located. Click and hold the Shift or Ctrl key to select multiple lexicons.
   2. In the list to the right, enter the term you want to search for. Options include the following:
      
      • Click Whole word if you are entering the whole word and want to restrict your search to it.
      • Enter only part of the term, such as "Tum" for "Tumor".
      • Do not enter any terms to retrieve all terms in the selected lexicon(s).
   3. Click . All lexicon entries matching your search criteria appear in the search results.
   4. Select a term from the search results.
   5. Click .
      

      The answer choice appears in the Answer Choices list in the right panel, as shown below. Relevant steps in the selection of this answer choice are highlighted in red.
      
      

      Slide panel borders

      Adjust your view of the information in multiple panels by clicking and dragging the border between them.

   6. Click Save.
      The answer choice appears in the Template Components panel under the component or characteristic you originally selected.

You can modify an answer choice by choosing a different lexicon term for it, changing its metadata, making it the default answer, or making its selection indicate that the template user has reached the last question.

1. Select an answer choice belonging to a template component.
   The metadata associated with that answer choice appears in the right panel.
2. Below that metadata, click Select Term.
   The Lexicon Search dialog box appears. The term you selected appears in the Lexicon Term panel on the right.
3. From the list on the far left of the page, select at least one lexicon where you believe the term you are searching for is located. Click and hold the Shift or Ctrl key to select multiple lexicons.
4. In the list to the right, enter the term you want to search for. Options include the following:
   
   • Click Whole word if you are entering the whole word and want to restrict your search to it.
   • Enter only part of the term, such as "Tum" for "Tumor".
   • Do not enter any terms to retrieve all terms in the selected lexicon(s).
5. Click . All lexicon entries matching your search criteria appear in the search results.
6. Select a term in the search results.
   The selected term replaces your original term in the Lexicon Term panel.
7. Click OK.
   The Templates tab appears with the lexicon term in the right panel.
   

8. Click the Default Answer checkbox if you want this answer choice to be the default answer. If you choose this, the answer choice is preceded by a blue icon in the Template Components tree, as follows:

   The number of default answers must be equal or greater than the minimum number of answer choices you specified when you added this characteristic to the template component.

9. Select the No More Questions checkbox if you want the selection of this answer choice to indicate that this is the last question in the template.
10. In the Next Question to Ask section, highlight the next question that the template should ask the user. This selection is not available if you have identified this as the last question in the template.
11. Click Save.

When an answer choice must be specific, you can add valid terms to the answer choice so that the template forces the user to specify one of those terms.

1. In the Template Components panel, right-click an answer choice and select Add Valid Terms or select  in the toolbar.
   The Lexicon Search page appears.
2. Select a valid term from a lexicon you have created as follows.
   
   1. From the list on the far left of the page, select at least one lexicon where you believe the term you are searching for is located. Click and hold the Shift or Ctrl key to select multiple lexicons.
   2. In the list to the right, enter the term you want to search for. Options include the following:
      Click Whole word if you are entering the whole word and want to restrict your search to it.
      Enter only part of the term, such as "Tum" for "Tumor".
      Do not enter any terms to retrieve all terms in the selected lexicon(s).
   3. Click . All lexicon entries matching your search criteria appear in the search results.
   4. Select a term in the search results.

   5. Click .
      The valid term appears in the Answer Choices list in the right panel, as shown below. Relevant steps in the selection of this valid term are highlighted in red.
      

      Slide panel borders

      Adjust your view of the information in multiple panels by clicking and dragging the border between them.

   6. Click Save.
      The valid term appears in the Template Components panel under the answer choice you originally selected.

3. Repeat this procedure until you have added all of the valid terms for the answer choice. You can also add valid terms to other valid terms.

When you add an anatomic entity or imaging observation component to your template, you may add one or more characteristics to it. When you import a template into an imaging application, each template component becomes a heading and characteristics describe the component. For example, the component could be "Lesion" with the characteristics of "Enhancement Quality", "Proportion Enhancing", "Proportion nCET", and "Proportion Necrosis".

Anatomic entity characteristics and imaging observation characteristics can be quantifiable or non-quantifiable. A quantifiable value can be scale, quantile (such as quartile, percentile, or n-tile), numerical like a decimal number in a UCUM (Unified Code for Units of Measurement) unit, and interval. Examples of non-quantifiable characteristics are present, absent, and not applicable.

1. Add a template component of the Anatomic Entity or Imaging Observation.
2. Right-click the component and select Create Anatomic Entity Characteristic () or Create Imaging Observation Characteristic ().

3. Specify information describing the characteristic, as follows.

   Field	Description
   Label	Required field. Double-click this field to add a label. A label becomes a heading in the image annotation form that users complete once the template is imported into an imaging application. For example, "Lesion".
   Explanatory Text	Description of the component; for example, "Select the type of lesion".
   Answer Choices	Required field. The minimum and maximum number of times the users may select this term when they annotate an image. The number of answer choices you add must be greater than or equal to the maximum number you specify here.
   Should Display	Required field. Select this box to display this component in the template. In certain situations, information in a component is known and will not be changed. If you choose not to display a question (a characteristic) in a template, you must specify a default answer if the minimum number of answer choices is one or greater.
   Annotator Confidence	Required field. Display or hide this value. Annotator confidence is a percentage that represents the level of user confidence in answering the question.
   Require Comment	Select Yes or No to indicate whether users must provide a comment when answering this question.
   Authors	Describes the AIM Template Builder user who created this component.
   Group Label	Describes any text that you want to associate with one or more template components and thereby group them together for display purposes.

4. Click Save.
5. Add an answer choice to the characteristic.
6. Create a characteristic quantification.

AIM templates include a set of questions and one or more answer choices for each question.

1. Add a template component.
2. Right-click the template component and select Create Question. You can also find this option in the toolbar ().
   A new panel appears on the right and the toolbar below the Template Components panel changes to provide options for question, which are to add or delete a question ().
   

3. Provide information about the question.

   Field	Description
   Code Meaning	The lexicon term you want to use in the question
   Code Value	The value of the lexicon term
   Schema Designator	The organization that created the schema
   Schema Version	The version of the schema you are using

   In this version of ATB, a question is defined as a concept code. This means that you will have to select a concept code from a list of existing lexicons from your local ATB. If you don’t have a concept code defined, which you probably don’t have in your local ATB, you will have to create your private lexicon that consists of your set of questions.
   
   Refer to the Questions and instructions lexicon for example questions to consider.

   Example

   You may want to create the following question: Where is a tumor located?
   
   You may define the question as follows.

   1. Create a lexicon called My private questions.
      
      1. Select the Lexicon tab.
      2. Click to add a new lexicon.
      3. Enter the metadata as follows:
         Name: My Private Lexicon
         Schema Designator: MPL
         Schema Version: 1.0
         Description: My private lexicon
         Authors: NCI
      4. Click Save.
   2. Click to add a new term.
   3. Enter the metadata as follows:
      Code Meaning: Where is the tumor?
      Description: Identify where the tumor is on the image or images.
      Code Value: MPL-0001
   4. Click Save. You can now use this question concept code.
4. Click Save.
5. Add answer choices to the question. Answer choices are lexicon entries that you want to reference in a question in the template.

When you create a template, you add questions and answer choices that are usually presented sequentially. However, you may want certain answer choices to trigger a different question than the next one in the template. You can specify the next question to ask for each answer choice.

1. Select the Templates tab.
2. Select an answer choice belonging to a template component.
   
3. In the Next Question to Ask section on the right, select the next question to ask from the list of template questions. This does not need to be a sequential question. Note that in the example above, the answer choice belongs to the Tumor Location component and Side of Tumor Center characteristic. The next question in the template is Lesion ("Select the type of lesion") but the selected next question to ask is Eloquent Brain ("Select Eloquent Brain involvement feature").
4. Click Save.

You can search the AIM Template Service for a template that you can customize in ATB. Once you find the template you want to use in the search results, you can import it. ATB 2.0 automatically converts older ATB templates to the latest schema version upon import.

1. Click the Templates tab.
2. Below the left panel, click and then select Search Templates.
   The Template Search page appears.
   

3. Narrow your search by entering information into the fields. If you do not enter any information into the fields, all template groups available in the AIM Template Service appear, and it may take longer to see the results of your search. The following fields are available.

   Field	Description
   Template Name	Template name
   Template Code Desc	Template code description
   Template Description	Template description
   Template Author	Person who created the template in the AIM-enabled application
   Modality	Any of the various types of equipment or probes used to acquire images of the body, such as radiography, ultrasound and magnetic resonance imaging
   Disease	Disease that is the topic of the templates in the template group
   Body Part	Body part that is the topic of the templates in the template group
   Tag Name	A name associated with this template
   Tag Value	The value associated with the tag name for this template

4. Click Search.
   All templates matching the search criteria you entered appear.
   

Once you find a template after searching the ATS, you can simply click it to import it to ATB.

1. Search for a template in ATS.

2. Click the Name link of the template you want to import.
   The template you imported appears in the Templates panel as "Copy of Original Template Name".

You can create a copy of a template to make it easier for you to customize it.

1. Click the Template tab.
2. Select the template you want to copy.
3. At the bottom of the Templates panel, click .
   A copy of the template with the name of Current Template Name copy appears in the Templates panel. You can now customize the copied template.

You can combine any number of templates in a template group. You may want to do this, for example, to make it easier for you to reference your data during a certain time in a longitudinal study.

This procedure assumes that you have already created both templates and template groups.

1. Click the Template Groups tab.
2. Select the template group that you want to populate with one or more templates.
3. In the Group Memberships panel on the right side of the screen, click the boxes next to the templates you want to add to the selected template group.
   
4. Below the Group Memberships panel, click .
   The templates appear in the Group Members panel.
   

A lexicon organizes the vocabulary that may appear in an AIM template. When you build a template, you can select terms from a lexicon that users of the template will be able to select as answers to template questions. For example, if an AIM template imported into an appropriate application prompts the user to specify the location of a lesion's geographic center, the template could restrict answers to certain allowed terms from the lexicon.

You must first create a lexicon, then add lexicon entries to it. Those lexicon entries become the allowed terms that you add to a template.

The ATB contains preselected terms from RadLex, caDSR (cancer Data Standards Registry and Repository) designed for a particular imaging study such as LIDC (Lung Image Database Consortium), and VASARI (Visually Accessible Rembrandt Images) vocabularies.

You can create a lexicon file that you can import into ATB 2.0. The lexicon file must contain terminology extracted from a standard lexicon such as RadLex, SONMED® CT, DICOM, or a user-defined lexicon.

1. Create a CSV file with a tab separator. When creating a new line, press Enter.
2. Make the first line the file header, with subsequent lines containing the actual data you are importing.
3. Structure the header in the following way:

An explanation of the header columns follows.