This guide explains how to use caBIG® Annotation and Image Markup (AIM) to build templates that are compatible with the AIM information model. The intended audience for this guide is a biomedical researcher familiar with the AIM information model.
To Print the Guide
You can send this page to a printer or export it to PDF and HTML.
Â
Getting Started with the ATB
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.
Why Use the AIM Model?
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.
What is in an AIM Template?
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.
Configuring ATB for Publishing
- Click the Settings button ().
The Options window appears. - 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.
- 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.
- Confirm or change the Default Author. The default author's name appears in the metadata of any object you create in ATB.
- Click Save.
Working with Template Groups
A template group is a container that holds individual templates.
Adding a Template Group
- Click the Template Groups tab.
- Below the left panel, click .
The Group Members panel at the bottom of the application expands to include a new template group panel. - Enter the name of the new group, its version number and description, and your name in the boxes provided. You can edit this information later if needed.
- Click Save.
The new template group appears in the Groups panel on the left side of the application.
Deleting a Template Group
- Click the Template Groups tab.
- Select the template group you want to delete by clicking it.
- Below the left panel, click .
A message appears asking you to confirm the deletion. - Click Delete.
Editing a Template Group
- Click the Template Groups tab.
- Below the left panel, click .
The selected template group's description appears. - Change the name of the group, version, description, and authors as needed.
- Optionally, add a tag to the group to make it easier to search for the template group in the future.
- Click Save.
The edited template group appears in the Groups panel.
Copying a Template Group
- Click the Template Groups tab.
- Select the template group you want to copy.
- 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.
Searching for a Template Group
- Click the Template Groups tab.
- Below the left panel, click and then select Search Groups.
The Template Groups Search page appears.
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 - Click Search.
All template groups matching the search criteria you entered appear.
- Click the name link for a template group.
ATB imports the template.
Importing a Template Group
- Click the Template Groups tab.
- Below the left panel, click .
- Click Import.
The Open dialog box appears. - 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.
No need to import template groups downloaded from the AIM Template Service
After you search for a template group in the AIM Template Service, you can open it and begin using it. It has already been imported to the AIM Template Builder. The import feature described in this procedure supports the importing of template files that are in XML format.
Exporting a Template Group
- Click the Template Groups tab.
- Select the template group you want to export.
- Below the left panel, click .
- Click Export.
The Save dialog box appears. - Select a location where you want to save the template group XML file.
Publishing a Template Group
- Click the Template Groups tab.
- Select a template group from the Groups panel.
- Below the left panel, click .
- Click Publish.
A window opens, prompting you to log in to the AIM Template Service. - 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.
Adding a Tag to a Template Group
- Click the Template Groups tab.
- Select a template group.
- Below the left panel, click .
The selected template group's description appears. - Click .
- Double-click the Name column.
The Edit Tag Name dialog box appears. - Click Select Term.
The Lexicon Search dialog box appears. - 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.
- Click Save.
- 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.
- Click Done.
You can see the tag when you open the template group.
Deleting a Tag from a Template Group
- Click .
- Select the tag you want to delete.
- Click .
Working with Templates
AIM Template Builder Concept | Annotation Concept |
---|---|
Component | Item being annotated; for example, Tumor Location. A component can be anatomic entity, imaging observation, inference, calculation, and markup or geometric shape. |
Characteristic | Descriptive element of that item; for example, Site of Tumor Center. Only anatomic entity and imaging observation can have characteristics associated with them. |
Allowed Term | Represents a possible answer choice. It is used to describe the descriptive element of a component or characteristic. For example, Frontal Lobe is an answer choice for anatomic entity. |
Creating a Template
- Click the Templates tab.
- Below the left panel, click .
The new template window appears.
- Enter a name, description, and version for the template. The UID is also a required field but the AIM Template Builder supplies it automatically. Optionally, select values for Modality and Preceding Annotation.
- Click Save.
The new template appears in the Templates panel. You may see warnings depicted by yellow triangles in the template. For example, if you have not yet assigned the required metadata, you are notified that it is missing. The Description section below the Template Components panel shows the list of warnings. Click to locate the problem location and fix it.
- Add a tag (also called a code) to the template. Tags can either be string values or lexicon terms. A template must have a code assigned to it. The assigned code describes the purpose of the template.
- Add one or more components to the template. Components can be anatomic entity, imaging observation, inference, calculation, and markup or geometric shape.
- Add one or more characteristics to each template component you add, as applicable (Inference and Calculation components do not have associated characteristics).
Specify the allowed termsfor each characteristic (for Anatomic Entity and Image Observation components) or component (for Inference and Calculation components).
Expanding and collapsing
Above the Template Components panel, click the plus or minus buttons () to expand or collapse the template components, respectively. When you expand a template component, you see all of its characteristics. In the template component tree, double-click a component or characteristic to expose additional detail about its metadata.
Adding a Template Component
- Click the Templates tab.
- In the Templates panel, select the template to which you want to add a component.
- In the Template Components panel, right-click the template name and select Create Template Component. 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 template components.
Specify the attributes of the template component, as described in the following table.
Field
Description
Label
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".
Cardinality
The minimum and maximum number of times the template will allow users to select this term when they annotate an image. Click Unlimited if users are not limited in how many times they may select this term.
Should Display
Select this box to display this component in the template.
Authors
The AIM Template Builder user who created this component
Group Label
Any text that you want to associate with one or more template components and thereby group them together
- Click Save.
Right-click the new template component to add the AIM elements of question, anatomic entity, imaging observation, inference, calculation, geometric shape, and allowed terms.
Click Move Up or Move Down to change the order in which template components appear in the template.
Creating a Question
- Add a template component.
- 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 ().
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.
Example
You may want to create the following question:
Where is a tumor located?
You may define the question as follows.- Create a lexicon called
My private questions
.- Select the Lexicon tab.
- Click to add a new lexicon.
- Enter the metadata as follows:
Name:My Private Lexicon
Schema Designator:MPL
Schema Version:1.0
Description:My private lexicon
Authors:NCI
- Click Save.
- Click to add a new term.
- 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
- Click Save. You can now use this question concept code.
- Create a lexicon called
- Click Save.
- Add valid terms to the question. Valid terms are lexicon entries that you want to reference in a question in the template.
Creating an Anatomic Entity
- Click the Templates tab.
- In the Templates panel, select the template to which you want to add an anatomic entity.
- In the Template Components panel, right-click the template name and select Create Anatomic Entity. 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 anatomic entities. - In the panel on the right, provide the required information, as follows:
- Provide a Label for the anatomic entity. For example, "Where is the tumor located?"
- Provide Explanatory Text to better describe the label.
- Specify the minimum and maximum number of Answer Choices that the person answering the related question may select in the template.
- Select the button that describes your display preference for the anatomic entity in the template.
- Select the button that describes your display preference for Annotator Confidence.
- Specify whether or not a comment is required.
- Specify one or more names in the Default Authors field to show who created the entity.
- Optionally, provide a Group Label, which can show an affiliation between this entity and others in the same group.
- Click Save.
- Add one or more characteristics to the anatomic entity.
For example, to describe a screen that is ruptured, the AIM template captures an anatomic entity of spleen and an anatomic entity characteristic of ruptured.
Creating an Imaging Observation
- Click the Templates tab.
- In the Templates panel, select the template to which you want to add an imaging observation.
- In the Template Components panel, right-click the template name and select Create Imaging Observation. 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 imaging observations, which are to add or delete an imaging observation (). - In the panel on the right, select Annotator Confidence, if that attribute applies to the imaging observation.
- Click Save.
- Add one or more characteristics to the imaging observation.
For example, to describe an image showing a cystic mass, the AIM template captures an imaging observation of mass and an imaging observation characteristic of cystic.
Creating an Inference
- Click the Templates tab.
- In the Templates panel, select the template to which you want to add an inference.
- In the Template Components panel, right-click the template name and select Create Inference. 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 inferences, which are to add or delete an inference (). - In the panel on the right, select Annotator Confidence, if that attribute applies to the inference.
- Click Save.
- Add one or more questions to the inference.
Creating a Calculation
- Click the Templates tab.
- In the Templates panel, select the template to which you want to add a calculation.
- In the Template Components panel, right-click the template name and select Create Calculation. You can also find this option in the toolbar ().
The toolbar below the Template Components panel changes to provide options for calculations, which are to add or delete a calculation (). - Right-click the calculation and select Create Calculation Type. You can also find this option in the toolbar ().
The toolbar below the Template Components panel changes to provide options for calculation types, which are to Add Valid Terms, Create Algorithm Type, and Delete Calculation Type ().
Creating an Algorithm Type
- Create a Calculation.
- Click to add an algorithm type to the calculation type.
A new panel appears on the right for algorithm attributes.
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
- Click Save.
Creating a Geometric Shape
- Click the Templates tab.
- In the Templates panel, select the template to which you want to add a geometric shape.
- 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, which is to delete a geometric shape (). - In the panel on the right, select the shape type. Options include Point, Circle, Polyline, Ellipse, and MultiPoint.
Click Save.
The geometric shapes available are as follows.Shape
Description
Point
A single pixel denoted by a single (column,row) pair
Multipoint
Multiple pixels each denoted by an (column,row) pair
Polyline
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.
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.
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.
Adding Allowed Terms
Once you create an allowed term, you can add more allowed terms under it hierarchically. This allows you to create new concepts from existing allowed terms.
- Click .
The Lexicon Search dialog box appears. - Select an allowed term from a lexicon you have created.
- From the list in the center of the page, select at least one lexicon where you believe the term you are searching for is located.
- From the list that is furthest to the left on the page, enter the term you want to search for. You can also enter only part of the term, such as "Tum" for "Tumor".
- Click . All lexicon entries containing the word you entered appear in the search results.
- Select a term in the search results.
- Click .
The allowed term appears in the Allowed Terms list in the right panel. Click OK.
Showing and hiding panels
Adjust your view of the information in multiple panels by clicking and dragging the border between them.
- Click OK.
Modifying Allowed Terms
- Select an allowed term belonging to a template component.
The metadata associated with that term appears in the right panel. - 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. - From the list in the center of the page, select at least one lexicon.
- From the list that is furthest to the left on the page, enter the term you want to search for. You can also enter only part of the term, such as "Tum" for "Tumor".
- Click . All lexicon entries containing the word you entered appear in the search results.
- Select a term in the search results.
The selected term replaces your original term in the Lexicon Term panel. - Click OK.
The Templates tab appears. - Click Save.
Adding a Characteristic to a Template Component
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 are present, absent, and not applicable.
- Add a template component of the Anatomic Entity or Imaging Observation AIM class.
- Right-click the component and select Create Anatomic Entity Characteristic () or Create Imaging Observation Characteristic ().
Specify information describing the characteristic, as follows.
Field
Description
Label
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".
Cardinality
The minimum and maximum number of times the users may select this term when they annotate an image. Click Unlimited if users are not limited in how many times they may select this term.
Should Display
Select this box to display this component in the template. In certain situations, information in a component is known and will not be changed.
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.
- Click Save.
- Add an allowed term to the characteristic.
- Create a characteristic quantification.
Creating a Characteristic Quantification
- Add a template component of the Imaging Observation or Anatomic Entity type.
- Add a characteristic to a template component of the Imaging Observation or Anatomic Entity type.
- Add an allowed term to the characteristic.
- Right-click the allowed term and select Create Characteristic Quantification ().
- In the panel on the right, enter a name for the characteristic and select Annotator Confidence, if that attribute applies to the template component.
- Click Save.
Create a characteristic quantification type. The options include Non Quantifiable, Scale, Numerical, Quantile, and Interval. Except for the Non Quantifiable type, which can always be added, you cannot create more than one type for a single allowed term.
Note
Delete any quantification from an allowed term by right-clicking it and selecting .
Creating a Non Quantifiable
- Add a characteristic to the component.
- Add an allowed term.
- Right-click the allowed term and select Create Non Quantifiable ().
- Search for the lexicon term you want to use to describe the non quantifiable.
- Click Select Term.
The Lexicon Search dialog box appears. - From the list in the center of the page, select at least one lexicon where you believe the term you are searching for is located.
- From the list that is furthest to the left on the page, enter the term you want to search for. You can also enter only part of the term, such as "Non" for "None", and then select RadLex from the lexicon list.
- Click .
All lexicon entries containing the word you entered appear in the search results. - Select a term in the search results.
- Click OK.
The metadata for the lexicon term you selected populates the Code Meaning, Code Value, Schema Designator, and Schema Version fields.
- Click Select Term.
- Click Save.
Creating a Scale
- Add a characteristic to the component.
- Add an allowed term.
- Right-click the allowed term and select Create Scale ().
- Add a description of the scale and additional comment, if needed.
- Click Save.
- Right-click the scale and select Create Ordinal Level ().
- Provide a value for the ordinal level by typing in a number or using the arrow keys to reach the desired number.
- Optionally, describe the ordinal level.
- Click Save.
- Return to step 3 to create additional ordinal levels.
Creating a Numerical
- Add a characteristic to the component.
- Add an allowed term.
- Right-click the allowed term and select Create Numerical ().
- Provide a value and UCUM string for the numerical (required).
- Select an operator from the list (optional).
- Click Save.
Creating a Quantile
- Add a characteristic to the component.
- Add an allowed term.
- Right-click the allowed term and select Create Quantile ().
- Enter a value into the Bins field.
For example, if your range is 100, you could create 5 bins containing 20 units each. Your Bin number would be 5 in this case. - Click Save.
Creating an Interval
- Add a characteristic to the component.
- Add an allowed term.
- Right-click the allowed term and select Create Interval ().
- Specify Min Value, Max Value, Min Operator, Max Operator, and UCUM Value for an interval.
- Click Save.
- Return to step 3 to create additional intervals.
Adding Tags to a Template
- Click the Templates tab.
- Select a template.
The template components appear in the center panel. - In the Template Components panel, right-click the template name.
- From the menu that appears, select .
A new tag appears in the Template Components panel.
- 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.
- Click Save.
Searching for a Template in the AIM Template Service
- Click the Template tab.
- Below the left panel, click and then select Search Templates.
The Template Search page appears.
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
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
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
- Click Search.
All templates matching the search criteria you entered appear.
Importing a Template from the AIM Template Service
- Search for a template in ATS.
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".
Editing a Template
- Click the Templates tab.
- Select the template you want to edit. The template information appears in the right panel.
- Edit any of the information about the template that you want to change.
- Click Save.
Copying a Template
- Click the Template tab.
- Select the template you want to copy.
- 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.
Deleting a Template
- Click the Templates tab.
- Select the template you want to delete by clicking it.
- Below the left panel, click .
A message appears prompting you to confirm the deletion. - Click Delete.
The template is no longer in the Templates panel.
Adding a Template to a Template Group
This procedure assumes that you have already created both templates and template groups.
- Click the Template Groups tab.
- Select the template group that you want to populate with one or more templates.
- 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.
- Below the Group Memberships panel, click .
The templates appear in the Group Members panel.
Removing a Template from a Template Group
- If you are not already on the Template Groups tab, click it to select it.
- In the Group Memberships panel on the right side of the screen, click the box next to the template you want to remove from the template group.
- Click .
The page refreshes and the Group Members panel no longer shows the template in the template group.
Building a 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.
Creating a Lexicon
- Click the Lexicons tab.
- In the toolbar at the bottom of the page, select .
A panel for information about the new lexicon appears.
- Enter information about the lexicon. Lexicon name and Scheme Designator are required. Schema Version and Description are optional. You can change the Authors from what appears by default, which is the user who is currently logged in.
- Click Save. The lexicon appears in the Lexicon panel.
Deleting a Lexicon
- Click the Lexicons tab.
- Select the lexicon you want to delete by clicking it.
- At the bottom of the Lexicon panel, click .
A confirmation message appears. - Click Delete. The lexicon is no longer in the Lexicon panel.
Creating a Lexicon Entry
- Click the Lexicons tab.
- Select the lexicon that you want to contain your new lexicon entry.
- Right-click the lexicon and select Create Lexicon Entry, or click in the toolbar.
A panel for the new lexicon entry appears.
Complete the fields to describe the lexicon entry.
An explanation of the purpose of each field is shown in the table below.Field
Description
Code Meaning
The name of the term you want to use as the lexicon entry
Description
A description of the term
Code Value
The value assigned by the coding scheme designator
- Click Save.
Deleting a Lexicon Entry
- Click the Lexicons tab.
- Select the lexicon that contains the term you want to delete.
- Click the term you want to delete to select it.
- Click .
A confirmation message appears. - Click Delete. The lexicon entry no longer appears in the Lexicon Terms panel.
Searching for a Term
- Click the Lexicons tab.
- At the bottom of the Lexicon Terms panel, click .
The Lexicon Search window appears.
- In the list in the top middle 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.
- In the list at top left of the page, enter the term you want to search for. Click Whole word if you are entering the whole word and want to restrict your search to it. You can also enter only part of the term, such as "Tum" for "Tumor".
- Click .
All lexicon entries containing the word you entered appear in the search results. - Select a term from the search results.
- Click OK.