i2b2 Temporal Query Tool View

The Temporal Query Tool view extends the query functionalities provided by the classic Query Tool view. Users can submit temporal queries to using the Temporal Query Tool view.

i2b2 Temporal Query Tool View

The Temporal Query Tool view extends the query functionalities provided by the classic Query Tool view. Users can create and submit temporal queries to using the Temporal Query Tool view. It submits a "select query" that will retrieve information from the database associated to the i2b2 Web Client.

Introduction

The interface is organized to facilitate the temporal querying process. There are three main steps in the process: Defining a population, defining temporal relationships, and reviewing and submitting query. The interface is designed to take users through each of these three steps. The section below describes the interface for each step in detail.

Step 1: Define Population

The image below shows the starting point of the Temporal Query Tool view interface along with its annotations. Users would interact with the Group Panels to define a population they are interested in. In the next step, users would define the temporal relationships they are interested in. Finally, users would review and submit their queries in the third step. This section breaks down the interface for the 1st step.

The Patient/Encounter Dropdown Box allows users to choose whether to define the population of the query using patients or encounters. The default is Patient:

Creating a population is optional. Users can skip Step 1 to use all data in the database.

Group Panel

At the start up, the interface for Step 1 displays three groups by default. Each of the groups contains several components. In general, all areas bounded by an orange-yellow highlight are clickable.

  1. (Group Heading) The heading is a label to easily identify the collection of terms. Each heading will contain "Group" followed by a sequential number.

    Example: Group 1, Group 2, Group 3, etc.

  2. (Selection Criteria) This area of the panel is used to define date selections and other constraints.
  3. (Panel Timing) The panel timing defines the constraint on the panel level and uses the patient's visits in determining eligibility.
  4. (Group List) This section contains the terms that will be used during the process of querying the database.
  5. (Delete Group) Clicking on this button will remove the group from the query construction. Users should use it to quickly discard a group.
  6. (Information Box) The content in the information box will change depending on whether or not a term is listed in the panel / group.
    • No term(s) listed
      1. The message will appear as "drop a term on here"
      2. The color of the box will be yellow
    • Term(s) listed
      1. The message will appear as "one or more of these"
      2. The color of the box will be green
      3. An additional information box will appear between panels

New/Add Group Button

qtToolbarNewGroup

The New Group button lets users to quickly add additional Groups.

Query Drop Area

A previous query saved in Workplace view or in the Previous Query view can be dragged and dropped here to reload the query. Reloading a query will overwrite the current query information. If the previous query is a temporal query, its population and temporal relationships will all be loaded. If the previous query is a non-temporal query, only the population portion of the temporal query interface will be loaded since a non-temporal query has no temporal relationship information.

Step 2: Define Temporal Relationships

Step 2: Define Temporal Relationships is used to define temporal relationships. It allows users to create a list of Events and a list of Temporal Relationships. Users define a list of interested Events and also define Temporal Relationships to describe how the events are related temporally, e.g. Event A must occur before Event B.

The interface is therefore a bit more complicated than Step 1 presented in the earlier section. It is broken into two major parts, presented below. On the left are the Event in Query panel and the Show Population panel. The Event in Query panel lets users define a list of Events. The Show Population panel allows users see and change the population definition originally defined in Step 1. On the right is a panel allowing users to add, remove, or modify relationships among the events.

Events in Query Panel

(Event Panels at startup)

The Events in Query Panel allows users to add, remove, and edit each Event. Each Event is represented by an Event Panel. An Event consists of a list of Groups just like a population definition. Users can add, remove, and edit each of the Groups in an Event by dragging terms into a group, changing its constraints, etc. At startup, two empty Events are added, each with a Group. More Events can be added by clicking on the Add Event button.

One difference between an Event and a set of Groups in Step 1 is that the first Group in an Event is special. It cannot be removed (note the missing Remove Group button), and its Group Binding Control is missing. The Group Binding for the 1st Group of every Event is not changeable. All other Group's Group Bindings are changeable. The first group anchors all other groups in an Event. That is, the first Group determines the timing of the enclosing Event with respect to the other Events temporally in the query.

Under the list of Events is the gray background, which serves as a Query Drop Area. Users can drop previous query in the Query Drop Area to overwrite the current query. It has the same effect as the Query Drop Area in Step 1.

An Event Panel has several components.

  1. (Event ID) This area shows the Event's name and color. Clicking on this area will expand/collapse the entire Event. When an Event Panel is collapsed, all its Groups are hidden. Only a row that contains the Event ID area is shown. Click on the Event ID area to expand the Event. All Events are expanded when created. Color of an Event is assigned only when at least one term has been added to it.
  2. (Event-Wide Date Constraints) Selecting this area allows users to specify date constraints for all Groups in this Event. This serves a similar function as the supplemental Query-wide Date Constraints Control Panel in the Step 1.
  3. (Remove Event Button) Clicking this button will remove the Event, deleting all its content and removing it from view.
  4. (Group Panel) The Group Panel is the same as the ones in Step 1.
  5. (Add Group Button) Clicking on it adds a new Group to the Event.

The population in Step 1 is shown. The title changes to "Edit Population," and every component is editable just as they are in Step 1.

Temporal Relationship Definition Panel

On the right hand side of the Step 3 interface is where users can define how Events are related to one another temporally. The Temporal Relationship Definition Panel contains a list of Temporal Relationship Panels and an Add Temporal Relationship Button. These components are described in detail below.

Please note that at least one Temporal Relationship Panel must be filled before users can move on to Step 3. A Temporal Relationship Panel is filled only if has a fulfilled Event in the Top Event Definition dropdown box and a fulfilled Event in the Bottom Event Definition dropdown box (see the image below). A fulfilled Event is one that has at least a fulfilled Group. A fulfilled Group is one that contains at least one term (not empty).

  1. The color indicator shows the colors of the Events that are being referenced in the Temporal Relationship. The top color (green in this example) matches the color of the Event in the Top Event Definition row and the bottom color (orange) matches the color of the Event in the Bottom Event Definition row. If an Event that has no content is referred, no color will be displayed in the Color Indicator.
  2. (Top Event Definition)This row allows users designate the first Event in this Temporal Relationship. A second event is specified in the Bottom Event Definition row. The dropdown boxes have the following choices:

    (Dropdown box options for Event Definition)

  3. (Event Ordering) This dropdown box describes how the Top Event elates to the Bottom Event.

    (Dropdown box options for Event Ordering)

  4. (Bottom Event Definition) This row allows users designate the second Event in this Temporal Relationship. It has the same dropdown box options as Top Event Definition.
  5. (Occurrence Temporal Constraint) Users can optionally describe the specified Event Ordering by a time range, creating the bolded part of, for example, "Event 1 Occurs Before Event 2 By > 5 day(s)." This additional temporal constraint can be a bounded range such as "By > 5 day(s) And < 10 day(s)." Users must first check the "By" checkbox to enable the dropdown boxes on that row. The "And" checkbox becomes enabled only when the "By" checkbox is checked. Checking the "And" checkbox enables the dropdown boxes on its row. Both the By row and the And row have the same options depicted below.

    (Options for Occurrence Temporal Constraint)

  6. (Add Temporal Relationship Button) This adds a new Temporal Relationship Panel should users require more relationship constraints among Events.

Step 3: Review and Submit Query

The last step allows users to review and modify the name of the query and selection of analyses types they want the server to return as the results of the query.

qtRunQueryWindow

Query Name Area

Upon entering Step 3, a query name is automatically generated. A "(t)" prefix indicates the query is a temporal query, differentiating it from normal queries submitted using the classic query tool. Some terms used in the query are then appended to identify this query. A timestamp is added at the end. Users may modify the query name however they wish. The name in the Query Name Area will be displayed in the Previous Query view once the query is submitted

Analysis Type Area

The area presents the different analyses types users can select as results of the query. They are exactly the same as the ones from the classic Query Tool:

Table of Result Types
Patient list Provides a set of patients who met the search criteria.
Event list Provides a set of encounters for those patients who met the search criteria.
Number of patients Provides the total number of patients who met the search criteria.
Gender patient breakdown Provides a breakdown of the patients by their gender.
Vital Status patient breakdown Provides a breakdown of the patients by their vital status.
Race patient breakdown Provides a breakdown of the patients by their race.
Age patient breakdown Provides a breakdown of the patients by their age
Timeline Provides a set of patients who met the defined criteria and automatically generates a timeline in the timeline view.

By default Number of patients and Timeline are selected.

Run Query Button

In Step 3, the Footer is different. Instead of another "Next" button, a Submit Query Button is there instead. It allows users to execute the query they have built in Step 1 and Step 2.

After pressing Submit Query, the button will become inactive to prevent inadvertent submission. A "Processing..." text will display to indicate that the query is being sent to the server for processing. The red rectangular button allows users to cancel the query submission.

queryStatusRun

When the server completes the processing, the number of patients found will be returned:

queryStatusFinish

If the query takes too long, a message will be displayed instead, in addition, the Submit Query Button will become available again. Users are advised to monitor the Previous Queries view to see when the query finishes.

NOTE:

The result types that appear will depend on what you have selected when running the query..

Popup Editors

Many of the UI elements discussed above are for display only. That is, they display the content of a Group or an Event or a Query, but they do not themselves allow editing of the values. Instead, users have to click on display components to launch an editor. The various editors are presented here.

This dialogs are all modal. That means no other actions can be performed when the dialog is launched. Users must first dismiss (typically by either selecting OK or Cancel) the dialog before other UI elements in the Web Client can be interacted with.

The dialogs can be moved by dragging the blue title area around, and they usually appear where the mouse pointer is when launched.

  1. (Date Constraint Editor) The Date Constraint Editor is launched when user clicks on a Date Constraint Control in every Group Panel, in the title area of an Event, in the Supplemental Control Panel in Step 1, and in the View Population Panel in Step 2.

    The editor starts up as the left-most figure below. Clicking on either of the orange-yellow-highlighted textboxes will launch a calendar widget for users to select the start (middle figure) or the end date (right-most figure). When finished, users should click on the OK button in the gray footer area to accept the constraints. Alternatively, clicking the Cancel button will leave the original date constraints unmodified.

    The start and end date constraints are both inclusive. That is if the start date is January 1, 1999, and the end date is December 31, 1999, the range of the constraint spans from 1/1/1999 00:00:00.000 to 12/31/1999 23:59:59.999.

    qtConstDateWindow

  2. (Group Binding Editor) The Group Binding Editor is found in every Group Panel. It lets users change the binding for that Group. The left figure depicts the initial appearance when a Group Binding Editor is launched. It consists of three rows, each represent a binding option. The last option (Bound-by-Observation) is only available as a choice if a modifier is dropped in the Group. Selecting one of the radio buttons and clicking on OK will set the new binding. Cancel will cancel the operation and leave the original binding unmodified.

  3. (Occurrence Count Constraint Editor) This editor can be launched in every Group by clicking on its Count Control area. Users can specify how many (or few) times the terms in a Group must occur. The editor itself is simple: a dropdown box specifies the type of operator and a spinner allowing for a number to be specified.

    The left figure shows the dialog at startup, and the right figure shows all the operator options.

    qtConstOccurSelectqtConstOccurWindow

  4. (Value Editor) When users drop an ontology term that can be further constrained by values into a Group, a Value Editor will automatically launch. Users can use this editor to select a way to constrain the value of the term and specify what values to constrain the term by. If a term that supports values already exists in a Group, users can right click on the term and select "Edit Value..." to launch the Value Editor for that term. Please note that some Modifiers do not support values (e.g. Circulatory Systems [Primary diagnosis]).

    qtConstValSelect(Right click on a term that supports value constraints to launch the Value Editor)

    Note that the constraint is optional. The default constraint put on these terms is "No Value," and by closing the dialog immediately, users can quickly accept the default constraint. Please note that closing the dialog does not cancel the value editing operation, it instead accepts the values that are currently set.

    If multiple terms were dropped at the same time, all terms that support value constraints in the same drop will appear in a list the left side of dialog. Users can select the terms on the list to view and edit its value constraint. Alternatively, users can use the navigation buttons "Previous", "Next" to navigate. Finally, to finish, users should select the last term on the list and click on "Finish."

    qtConstValTropI1(The Value Editor shows two terms on its list on the left. The right half shows the currently set value constraints for the selected term on list. The default is "No Value." Users can also navigate the list by using the "Next" "Previous" buttons on the bottom of the right half. When finished, click on the "Finish" button or simply close the dialog.)

    Different terms support different kinds of value constraint, some are constrained by text, some by numeric value, some by a list of pre-arranged values, and some by abnormal flags. For example, the Color term supports abnormal flags and a list of pre-arranged values. These options are shown on the right half of the dialog. By selecting the radio buttons, users can choose the kind of constraint they want. Here are the screen shots of the right half of the dialog when radio buttons other than "No Value" are chosen for the term Color.

    qtConstValTropI2qtConstValCpk2

Creating a Query

This section describes the process of adding items to the query tool, "AND" / "OR" operators and setting constraints.

Draggable Items

In order to create your query, you will need to define what information will be retrieved from the databases. Selected items from other i2b2 Web Client views can be dragged and dropped (copied) into the Temporal Query Tool view.

  1. Concepts

    Concepts () can be defined as terms, results, providers, etc. They can be added as a group (folder ()) or individually by dragging the item(s) from Navigate Terms, Find Terms, and Workplace views.

  2. Modifiers

    Modifiers () are associated with a concept or group of concepts. They can be added as a group (modifier folder ()) or individually by dragging the item(s) from Navigate Terms, Find Terms, and Workplace views.

  3. Previous Query

    A new query can be created from one that has already been run by dragging the previous query ( or) from Previous Query and Workplace views.

  4. Patient List

    A patient list () can be used in a query by dragging the item(s) from Previous Query and Workplace views.

  5. Individual Patient

    A patient () or several patients can be used in a query by dragging them from Previous Query view and Workplace views.

  6. Event List

    An event list () can be used in a query by dragging the item(s) from Previous Query and Workplace views.

  7. Query Definition

    A new query can be created from one that has already been run by dragging the query definition () from the Workplace view.

  8. Group Template

    Users can define a group of concepts that they frequently run and save them in their workplace view. This grouping of concepts is referred to as a group template ().

    A new query can be created using the group template by dragging the template from Workplace view to the Group Header.

Operators

There are two operators, known as SQL Logical Operators, which are necessary when running a query that has more than one term. These operators provide a way to specify exactly what users want to retrieve. The operators are the 'AND' and 'OR' operators.

The query tool knows which operator to use based on the panels used when defining the query. It is important to verify the users are setting up their query correctly as each operator will return different results.

AND Operator

The AND operator returns a record if both the first condition and the second conditions are true.

The query tool uses the AND operator when concepts are listed in different panels.

Example:

WHAT: Return only those patients who have Acute Myocardial Infarction AND Angina Pectoris.

HOW: In the query tool add the concept Acute Myocardial Infarction to Group 1 and then add the concept Angina Pectoris to Group 2 .

RESULT: The population is limited by requiring the patients to have both Acute myocardial infarction and Angina pectoris..

OR Operator

The OR operator returns a record if either the first condition or the second conditions is true.

The query tool uses the OR operator when concepts are listed in the same panel.

Example:

WHAT: Return any patients who have Acute Myocardial Infarction or Angina Pectoris associated to them.

HOW: In the query tool you add both concepts, Acute Myocardial Infarction and Angina Pectoris, to Group 1.

RESULT: The population is limited to include all patients who fit either one of those criteria.

In short, terms within a Group are ORed together, while different Groups are ANDed together.

Add Concepts

Concepts can be added to the Query Tool view by simply dragging the concept from one of the following views.

1.  Navigate Terms view

2.  Find Terms view

3.  Workplace view

How to add a concept from each of these views is explained in the next few sections.

Navigate Terms View

The Navigate Terms view contains a hierarchical display of all the items that can be used to search the database.

Note: How the items are grouped and displayed is dependent on how the database is setup.

Add Concept From Navigate Terms View

1.      In the Navigate Terms view, expand the folder(s) that contain the concept or grouping of concepts that you want to add.

2.       Highlight the concept () or folder () by clicking on its name.

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the item into the panel labeled Group 1.

5.       The item will now display in the panel for Group 1.

Find Terms View

The Find Terms view provides a way to search for a particular concept and modifier.

ftView

Add Concept From Find Terms View

1.       In the Find Terms view, search for the item(s) you want to add.

2.       Highlight the concept () or folder () by clicking on its name.

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the item into the panel labeled Group 1.

qtDragFolderCardioAgents

5.       The item will now display in the panel for Group 1.

qtDropFolderCardio

Workplace

Information in the Workplace is related to the most common concepts, modifiers, and queries that an individual uses and in essence becomes their personal workplace.

wpView

Add Concept From Workplace View

1.       In the Workplace view, expand the folder(s) that contain the concept or grouping of concepts you want to add.

2.       Highlight the concept () or folder () by clicking on its name.

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the item into the panel labeled Group 1.

qtDragFolderCardioAgents

5.       The item will now display in the panel for Group 1.

qtDragFolderCardioAgents

Add Modifiers

Modifiers can be added to the Query Tool view by simply dragging the modifier from one of the following views.

1.  Navigate Terms view

2.  Find Terms view

3.  Workplace view

How to add a modifier from each of these views is explained in the next few sections.

Navigate Terms View

The Navigate Terms view contains a hierarchical display of all the items that can be used to search the database.

Note: How the items are grouped and displayed is dependent on how the database is setup.

ntView

Add modifier From Navigate Terms View

1.       In the Navigate Terms view, expand the folder(s) that contains the modifier or grouping of modifiers that you want to add.

2.       Highlight the modifier () or modifier folder () by clicking on its name.

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the item into the panel labeled Group 1.

qtDragFolderCardioAgents

5.       The item will now display in the panel for Group 1.

qtDropFolderCardio

Find Terms View

The Find Terms view provides a way to search for a particular concept and modifier.

ftView

Note: For detailed information on how to search for terms and modifiers, please see the i2b2 Find Terms View chapter.

Add Modifier From Find Terms View

1.       In the Find Terms view, search for the modifier(s) you want to add.

2.       Highlight the modifier () or modifier folder () by clicking on its name.

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the item into the panel labeled Group 1.

qtDragModPrincDx

5.       The item will now display in the panel for Group 1.

qtDropFolderCardio

Workplace

Information in the Workplace is related to the most common concepts, modifiers, and queries that an individual uses and in essence becomes their personal workplace.

wpView

Add Modifier From Workplace View

1.       In the Workplace view, expand the folder(s) that contain the modifier or grouping of modifiers you want to add.

2.       Highlight the modifier () or modifier folder () by clicking on its name.

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the item into the panel labeled Group 1.

qtDragModPrincDx

5.        The item will now display in the panel for Group 1.

qtDropModPrincDx

Add Previous Query

A previous query can be used to run a new query or as an item within a query (query-in-query). To add a previous query to the Query Tool view simply drag the query name from one of the following views.

1.  Previous Query view

2.  Workplace view

Within the Query Tool view, the previous query can be added to one of the following two locations.

Query Name field The item(s) and constraints from the original query will be used to create a new query. This information can be edited to make a new query or can be used as is to run the query again.

Please note that the tool does not currently support dropping of a previous query of a previous query or a previous query of a temporal query.
Panel (Group) Used within a new query (query-in-query). Add additional search criteria (items) to be used in the new query.

How to add a previous query from each of the views listed above is explained in the next few sections.

Previous Query View

The Previous Query view displays the queries that were run by the user.

pqView

Add Previous Query From Previous Query View (New Query)

1.       In the Previous Query view highlight the previous query () by clicking on its name

2.       While holding the left mouse button down, drag the item over to the Temporal Query Tool View.

3.       Drop the previous query into the Query Drop Area in either Step 1 or Step 2.

4.       The terms, Groups, Events, and Temporal Relationships defined in that previous query will be reconstituted in the current interface. If the previous query is a non-temporal query, then only the Population portion of the UI will be reconstituted. If the previous query is a temporal query, then both the Population portion and the temporal relationship portion of the UI will be reconstituted.

Add Previous Query From Previous Query View (Query-In-Query)

1.       In the Previous Query view highlight the previous query () by clicking on its name

2.       While holding the left mouse button down, drag the item over to the Query Tool View.

3.       Drop the previous query into the panel labeled Group 1.

4.       The previous query will now display in the panel for Group 1.

qtDragPqToPanel

Workplace View

Information in the workplace is related to the most common concepts, modifiers, and queries that an individual uses and in essence becomes their personal workplace.

wpView

Add Previous Query From workplace View (New Query)

1.       In the Workplace view, expand the folder(s) that contains the previous query you want to add.

2.       Highlight the previous query () by clicking on its name

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the previous query into the Query Drop Area in either Step 1 or Step 2.

5.       The terms, Groups, Events, and Temporal Relationships defined in that previous query will be reconstituted in the current interface. If the previous query is a non-temporal query, then only the Population portion of the UI will be reconstituted. If the previous query is a temporal query, then both the Population portion and the temporal relationship portion of the UI will be reconstituted.

Add Previous Query From Previous Query View (Query-In-Query)

1.       In the Workplace view, expand the folder(s) that contains the previous query you want to add.

2.       Highlight the previous query () by clicking on its name

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the previous query into the panel labeled Group 1.

5.       The previous query will now display in the panel for Group 1.

qtDropPqPanel

Add Patient List

A patient list can be added to the Query Tool view by simply dragging the list of patients from one of the following views.

1.  Previous Query view

2.  Workplace view

How to add a patient list from each of the views is explained in the next few sections.

Previous Query View

The Previous Query view displays the queries that were run by the user.

pqView

Add Patient List From Previous Query View

6.       In the Previous Query view click on the plus sign () next to the name of the previous query that contains the patient set.

7.       Click on the plus sign () next to the results folder.

8.       Highlight the patient list () by clicking on its name

9.       While holding the left mouse button down, drag the item over to the Query Tool View.

10.   Drop the patient set into the panel labeled Group 1.

qtDragPtSet

11.   The patient set will now display in the panel for Group 1.

qtDropPtSet

Workplace View

Information in the workplace is related to the most common concepts, modifiers, and queries that an individual uses and in essence becomes their personal workplace.

wpView

Add Patient List From Workplace View

12.   In the Workplace view find the patient list you want to add.

13.   Highlight the patient list () by clicking on its name

14.   While holding the left mouse button down, drag the item over to the Query Tool View.

15.   Drop the patient set into the panel labeled Group 1.

16.   The patient set will now display in the panel for Group 1.

qtDropPtSet

Add Encounter Set

An encounter set can be added to the Query Tool view by simply dragging the encounter set from one of the following views.

1.  Previous Query view

2.  Workplace view

How to add an event list from each of the views is explained in the next few sections.

Previous Query View

The Previous Query view displays the queries that were run by the user.

pqView

Add Event List From Previous Query View

1.       In the Previous Query view click on the plus sign () next to the name of the previous query that contains the encounter set.

2.       Click on the plus sign () next to the results folder.

3.       Highlight the encounter set () by clicking on its name

4.       While holding the left mouse button down, drag the item over to the Query Tool View.

5.       Drop the encounter set into the Group 1.

6.       The encounter set will now display in the panel for Group 1.

qtDropEncSet

Workplace View

Information in the workplace is related to the most common concepts, modifiers, and queries that an individual uses and in essence becomes their personal workplace.

wpView

Add Event List From Workplace View

1.       In the Workplace view find the encounter set you want to add.

2.       Highlight the encounter set () by clicking on its name

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the encounter set into Group 1.

5.       The encounter set will now display in the panel for Group 1.

qtDropEncSet

Add Query Definition

A query definition can be added to the query tool view by simply dragging the query name from the workplace view.

Add Query Definition From Workplace View

1.       In the Workplace view, find the query definition you want to add.

wpView

2.       Highlight the query definition () by clicking on its name

3.       While holding the left mouse button down, drag the item over to the Query Tool View.

4.       Drop the query definition into the Query Drop Area in Step 1 or Step 2.

5.       The item(s) associated with the query definition will display in the appropriate group(s), the name of the query will appear at Query Name, and any constraints that were defined when the original query was run will now default with the new query.

Add a Group Panel

Three Group Panels are displayed in Step 1 by default. In step 2, only one Group Panel is available per Event. Some complex queries may require the use of additional panels. Users may use the "Add Group" button to add more Groups.

1.       Click on the Add Group button.

qtToolbarNewGroup

(Add Group button in Step 1)

2.       A new panel is added with each click (two clicks are performed here to create a total of three Group Panels).

qtPanelAdd

In Step 2, there is an "Add Group" button for each Event, and an additional one to add Group to the population. These "Add Group" button work exactly the same as the one described above.

(Step 2 "Add Group" button)

Delete/Remove

Users can remove a Group from a query (or Event in the temporal query UI) or a term in a Group.

Remove Groups

1.       Click on the Remove Group button () located to the right top of every Group.

2.       The Group and all its content will be removed

Delete a Single Item

1.       Right click on the item in the group that you want to remove.

deleteItem

2.       Select Delete Item from the list.

3.       The item will be removed from the Group Panel

Setting Constraints

Constraints are used to narrow down the search criteria to a particular time from, number of occurrences or a specific value or range of values. In i2b2, there are several types of constraints that can be defined in the Query Tool view.

Constraint Type Description
Group Binding (Panel Timing) Constraint is defined on the Group and utilizes the patient encounters and / or instance number when determining eligibility. There are three binding choices. The most general one is bound-by-patient, followed by bound-by-encounter, and finally, the strictest one is bound-by-observation.
Date Constraint uses a date range when determining eligibility.
Occurrence Constraint is by the number of occurrences an item is documented.
Value Constraint is by the value associated to a concept or modifier. Not all items have values.

Note: In the client, the value constraints are currently the only ones that directly correspond to a single concept. All others are defined on the query or Group level.

Group Binding Constraints

Group binding constraints utilize the encounter/observation information along with the items defined to determine if a patient meets the search criteria.

Note that this is previously known as Panel Timing in the classic Query Tool. In the classic Query Tool, users can also specify Query Timing. In the Temporal Query Tool, Query Timing is automatically set by the choice of Group Bindings. That is, the strictest Group Binding dictates what the Query Timing is:

-          if there is a Group that is "bound-by-observation," then the query timing will be "bound-by-observation" (or in the classical terminology, "same instance.")

-          If there is a Group that is bound-by-encounter," but no Groups "bound-by-observation," then the query timing will be "bound-by-encounter," (or classically, "same encounter.")

-          Otherwise the query timing is "bound-by-patient" ("treat independently.")

Group Binding

Group Binding sets the binding for each Group. Possible values are Bound-by-Patient, Bound-by-Encounter, and Bound-by-Observation. These constraints tell the query processor that these Groups describe the same patient, encounters or observation.

In step 1, the default binding for each Group changes depending on whether users are defining a Patient Population or an Encounter Population. If Patient Population is used, then Bound-by-Patient is the default, and it is unchangeable. If Encounter Population is used, then Bound-by-Encounter is the default. However, in this case, users can change each Group's binding to Bound-by-Patient if they so desire or to Bound-by-Observation if a modifier term is used in that Group.

Users can select one of three available options:

1.       (Bound-by-Patient) The items (facts) can occur at any time in the patient's history.

2.       (Bound-by-Encounter) The items (facts) occur during the same encounter (e.g. visit to hospital).

3.       (Bound-by-Observation) The items (facts) occur during the same observation.

The values are hierarchical: a Group that is bound-by-observation is also bound-by-encounter and bound-by-patient. A group that is bound-by-encounter is also bound-by-patient. Every group is bound-by-patient.

The Group Binding for a Group can be set by launching the Group Binding Editor, by clicking on the highlighted area in a Group:

The Group Binding Editor consists of 3 rows, each representing a possible Group Binding value. Selecting one will set the value.

Users can also set the Group binding for all Groups using the Group Binding Control Panel in the Supplemental Control Panel in Step 1.

Bound-by-Patient

The items (facts) can occur at any time in the patient's history.

Bound-by-Encounter

The items (facts) occur during the same encounter (e.g. visit to hospital).

Example:

Patient has a diagnosis of Acute MI documented at any time in their history and they have a medication with a dose greater than 500 mg and a medication that is taken once a day documented during the same encounter.

qtTimingExample4

RESULTS: In our database, there are 4 patients who have had a medication with a dose greater than 500 mg and a frequency of once a day entered as a fact in the observation_fact table, where the medication dose and frequency have the same encounter_num AND the diagnosis of acute MI, the medication dose and frequency all have the same patient_num.

Bound-by-Observation

The items (facts) listed in the panel occur during the same observation of a visit.

Example:

Patient has a diagnosis of Acute MI documented at any time in their history and they have a medication with a dose greater than 500 mg and a medication that is taken once a day documented during the same instance.

qtTimingExample5

RESULTS: In our database, there are 3 patients who have had a medication with a dose greater than 500 mg and a frequency of once a day entered as a fact in the observation_fact table, where the medication dose and frequency have the same encounter_num AND instance_num AND the diagnosis of acute MI, the medication dose and frequency all have the same patient_num.

Date Constraint

Users can define a date range to be used when querying the database. This date range can be in any one of the following combinations. Note that all start and end dates are inclusive.

SPECIFIED DATE RANGE: FROM AND TO DATES DEFINED

Only data with activity within the defined date range will be used.

Example:

qtConstDateSelect

Concept: Acute Myocardial Infarction

From date: 01/01/2001

To date: 12/31/2005

In this example, if a patient has a diagnosis of Acute Myocardial Infarction (MI) entered on the record from 01/01/2001 to 12/31/2005 then their data will be included. If the patient does have an MI diagnosis but it was entered prior to 01/01/2001 or after 12/31/2005 then their information will not be included.

SPECIFIC START DATE: ONLY THE FROM DATE IS DEFINED

Data from the defined start date to the latest date available. No end date defined.

Example:

qtConstDateFrom

Concept: Acute Myocardial Infarction

From date: 01/01/2001

To date:

In this example, if a patient has a diagnosis of Acute Myocardial Infarction (MI) entered on the record any time on or after 01/01/2001 will be included. If the diagnosis was entered prior to 01/01/2001 then the data will not be included.

SPECIFIC END DATE: ONLY THE TO DATE IS DEFINED

All data up until the defined end date. No start date defined.

Example:

qtConstDateTo

Concept: Acute Myocardial Infarction

From date:

To date: 12/31/2005

In this example, if a patient has a diagnosis of Acute Myocardial Infarction (MI) entered on the record prior to and including 12/31/2005 then their data will be included. If the diagnosis was entered after 12/31/2005 then it will not be included.

SETTING THE DATE CONSTRAINT

  1. Click on the Dates button located in the selection criteria section of the panel.

    2. qtConstDateSelect

  2. A new window will open.

    3. qtConstDateWindow

  3. Click the check box next to the date in the From box.
  4. At this point there are two methods of entering your starting date.
    1. Manually type it in the text box.
    2. Click on the drop-down arrow (dropDownArrow) to open the calendar view and click on the desired date.

      3. qtConstDateCal1

      Once you click on the desired date the calendar window will close.

      qtConstDateFrom

  5. Click the check box next to the date in the To box.
  6. Highlight the default date or click on the drop-down arrow and enter the date you want to use as your ending date.

    7. qtConstDateFromTo

  7. Click on the OK button.
  8. Dates will now be underlined to indicate a date constraint has been set.

    9. qtConstDateSet

Occurrences Constraint

Users can define a number of times an item has to occur in order to be considered a positive "hit". Please note that the Occurrence Constraint and Exclusion from the classic query tool have been rolled into the same constraint. Here is an example of conversions from the classical query tool occurrence and exclude specification to the new occurrence constraint specification:

1.       (Exclude 1) (exclude anyone who has one or more occurrence of the desired terms) -> Edit the occurrence to (=0).

2.       (Exclude 2) (Exclude anyone who has two or more occurrences of the desired terms) -> Edit the occurrence to (<2).

3.       (1) (Only take those who have one or more occurrences of the desired terms) -> Edit the occurrence to (>0). (This is the default)

4.       (2) (Only take those who have two or more occurrences of the desired terms) -> Edit the occurrence to (>2).

Setting the Occurrences Constraint

1.       Click on the Occurrence Count Control located in the top part of a Group Panel.

qtConstOccurSelect

2.       The Occurrence Count Editor will open.

qtConstOccurWindow

3.       Use the dropbox to select the desired operator and the spinner to choose the desired number. The dropbox has the following options:

qtConstOccurSelection

4.       Click on the OK button to accept.

5.       Occurrence Count Control will update to the new constraint (4 examples provided below):

qtConstOccurSet

Different operator/number combinations will have different background. The default (>0) is white with gray text. If the operator is > and the number is greater than 0, then it will be green. If the operator is < or =, then the background will be pink. Please note that choosing the equal (=) operator restricts the number to zero (0) - you cannot choose equals x (=x), where x is any non-zero number.

Value Constraint

Value constraints can be associated with concept and modifiers but not all of them will have values. For instance, the diagnosis of Acute Myocardial Infarction does not have a value but the tests used to make the diagnosis do have values (high/ low flags, or numeric values, etc.).

Flag Value

Flags are defined in the source system when the value is entered. The following are some examples that can be found in the i2b2 Demo database.

Setting the Value Constraint (Flag) for a Concept

NOTE:

The value constraint window will open automatically when you drop a concept into a panel in the Query Tool view. This will only happen if the concept is set up in the database with XML metadata. The first three steps can be used if you did not add a value constraint when you added the item or if you wish to edit an existing item.

  1. Using the right mouse button, click on the item listed in the panel.
  2. A pop-up menu will open.
  3. Select Set Value from the list.

    4. qtConstValSelect

  4. A new window will open.

    5. qtConstValTropI1

  5. Click on the radial dial next to By flag.
  6. A new field with a drop-down selection box will appear.

    7. qtConstValTropI2

  7. Click on the drop-down arrow to change the flag or accept the default.
  8. Click on the OK button.
  9. The value constraint has been set.

    10. qtConstValTropI3

Setting the Value Constraint (Flag) for a Modifier

NOTE:

The modifier value constraint window will open automatically when you drop a modifier into a panel in the Query Tool view. This will only happen if the modifier is set up in the database with XML metadata. The first three steps can be used if you did not add a value constraint when you added the item or if you wish to edit an existing item.

  1. Using the right mouse button, click on the item listed in the panel.
  2. A pop-up menu will open.
  3. Select Set Value from the list.

    4. qtConstValSelectMod

  4. A new window will open.
  5. Click on the radial dial next to By flag.
  6. A new field with a drop-down selection box will appear.
  7. Click on the drop-down arrow to change the flag or accept the default.
  8. Click on the OK button.
  9. The value constraint has been set.

Text Value

The text value is defined in the source system when the value is entered. The following are some examples that can be found in the i2b2 Demo database.

Setting the Value Constraint (Text) for a Concept

NOTE:

The value constraint window will open automatically when you drop a concept into a panel in the Query Tool view. This will only happen if the concept is set up in the database with XML metadata. The first three steps can be used if you did not add a value constraint when you added the item or if you wish to edit an existing item.

  1. Using the right mouse button, click on the item listed in the panel.
  2. A pop-up menu will open.
  3. Select Set Value from the list.

    4. qtConstValSelect

  4. A new window will open.

    5. qtConstValCkmb1

  5. Click on the radial dial next to By value.
  6. A new field listing the enumerated values will appear.
  7. Click on the name of the value you want to include.

    8. qtConstValCkmb2

    TIP:

    To select more than one you can hold down the <Ctrl> key while clicking on each name. On the Macintosh you can hold down the command key instead of the <Ctrl> key.

  8. Click on the OK button.
  9. The value constraint has been set.

    10. qtConstValCkmb3

Setting the Value Constraint (Text) for a Modifier

NOTE:

The modifier value constraint window will open automatically when you drop a modifier into a panel in the Query Tool view. This will only happen if the modifier is set up in the database with XML metadata. The first three steps can be used if you did not add a value constraint when you added the item or if you wish to edit an existing item.

  1. Using the right mouse button, click on the item listed in the panel.
  2. A pop-up menu will open.
  3. Select Set Modifier Value from the list.

    4. qtConstValSelectMod

  4. A new window will open.

    5. qtConstValTrimoxFreq1

  5. Click on the radial dial next to By value.
  6. A new field listing the enumerated values will appear.
  7. Click on the name of the value you want to include.

    8. qtConstValTrimoxFreq2

    TIP:

    To select more than one you can hold down the <Ctrl> key while clicking on each name. On the Macintosh you can hold down the command key instead of the <Ctrl> key.

  8. Click on the OK button.
  9. The value constraint has been set.

    10. qtConstValTrimox3

Numeric Value

The numeric value is defined in the source system when the result is entered. The following are some example formats that can be found in the i2b2 Demo database.

Unlike flag and text values, numeric values use operators, such as greater than or less than when setting the constraints. The following is a listing of operators currently in use.

Operator Description / Use
Less Than (<) Any value less than the number entered.
Less Than or Equal To (<=) Any value less than or equal to the number entered (inclusive).
Equal To (=) An exact match to the number entered.
Between Any value in the range of numbers entered.
Greater Than (>) Any value greater than the number entered.
Greater Than or Equal To (>=) Any value greater than or equal to the number entered (inclusive).

Setting the Value Constraint (Numeric) for a Concept

NOTE:

The value constraint window will open automatically when you drop a concept into a panel in the Query Tool view. This will only happen if the concept is set up in the database with XML metadata. The first three steps can be used if you did not add a value constraint when you added the item or if you wish to edit an existing item.

  1. Using the right mouse button, click on the item listed in the panel.
  2. A pop-up menu will open.
  3. Select Set Value from the list.

    4. qtConstValSelect

  4. A new window will open.

    5. qtConstValCpk1

  5. Click on the radial dial next to By value.
  6. Two new fields will appear; one with a drop down selection box and the other a text box.

    7. qtConstValCpk2

  7. Click on the drop-down arrow to change the operator or accept the default.

    8. qtConstValOperator

  8. Enter a numerical value at the Please enter a value field.

    9. qtConstValEnter

  9. Click on the OK button.
  10. The value constraint has been set.

    11. qtConstValCpk3

Setting the Value Constraint (Numeric) for a Modifier

NOTE:

The modifier value constraint window will open automatically when you drop a modifier into a panel in the Query Tool view. This will only happen if the modifier is set up in the database with XML metadata. The first three steps can be used if you did not add a value constraint when you added the item or if you wish to edit an existing item.

  1. Using the right mouse button, click on the item listed in the panel.
  2. A pop-up menu will open.
  3. Select Set Modifier Value from the list.

    4. qtConstValSelectMod

  4. A new window will open.

    5. qtConstValTrimoxDose1

  5. Click on the radial dial next to By value.
  6. Two new fields will appear; one with a drop down selection box and the other a text box.

    7. qtConstValTrimoxDose2

  7. Click on the drop-down arrow to change the operator or accept the default.

    8. qtConstValOperator

  8. Enter a numerical value at the Please enter a value field.

    9. qtConstValEnter

  9. Click on the OK button.
  10. The value constraint has been set.

    11. qtConstValTrimoxDose3

Using Units In Value Constraints

Units in regards to i2b2 are the standard units of measurement associated with a value. For instance, a medication may have "mg" listed as the unit for the dose, while a HGB lab test may have "gm/dL".

The units are defined in the source system and although it is recommended that all numerical facts are stored in normalized units it is recognized that this is not always feasible. Therefore, the Web Client has the ability to convert the units when running a query.

In order for this feature to work a parameter called CRC_ENABLE_UNITCD_CONVERSION must be defined for the project. If this is not defined you need to contact your system administrator.

Defining the Units When Running a Query

NOTE:

The modifier value constraint window will open automatically when you drop a modifier into a panel in the Query Tool view. This will only happen if the modifier is set up in the database with XML metadata. The first three steps can be used if you did not add a value constraint when you added the item or if you wish to edit an existing item.

  1. Using the right mouse button, click on the item listed in the panel.
  2. A pop-up menu will open.
  3. Select Set Modifier Value from the list.

    4. qtConstValSelectMod

  4. A new window will open.

    5. qtConstValUnits1

  5. Click on the radial dial next to By value.
  6. Two new fields will appear; one with a drop down selection box and the other a text box.

    7. qtConstValUnits2

  7. The Units will default to the normal units defined for the item.
  8. Click on the drop-down arrow to change the units.

    9. qtConstValUnitsList

  9. Click on the drop-down arrow to change the operator or accept the default.

    10. qtConstValOperator

  10. Enter a numerical value at the Please enter a value field.

    11. qtConstValEnter

  11. Click on the OK button.
  12. The value constraint has been set and the numerical value has been converted to the normal units.

    13. qtConstValUnits3

In the above scenario, the normal units are "mg". When setting up the value constraint the units were changed to "gm" and the numerical value was set to 5. Upon saving the value constraint, the Web Client converted 5 gm to 5000 mg. When the query is run it will look at those facts that have both 5 gm and 5000 mg defined in the observation_fact table.

NOTE:

The unit conversion information is specific to the term and is defined in the i2b2 metadata table.

Running a Query

This section describes the process of running a query and getting results.

Analysis Types

Before users submit their query to the server, they must select the analysis types they want from the Analysis Type Area in Step 3. There are several result types available, each of which will yield a different output.

qtRunQueryWindow

Patient list Provides a set of patients who met the search criteria.
Event list Provides a set of encounters for those patients who met the search criteria.
Number of patients Provides the total number of patients who met the search criteria.
Gender patient breakdown Provides a breakdown of the patients by their gender.
Vital Status patient breakdown Provides a breakdown of the patients by their vital status.
Race patient breakdown Provides a breakdown of the patients by their race.
Age patient breakdown Provides a breakdown of the patients by their age
Timeline Provides a set of patients who met the defined criteria and automatically generates a timeline in the timeline view.

By default Number of patients and Timeline are selected.

Patient List

This option will return a list of patients who met the defined criteria and will add the query and patient list to the previous query view.

pqPtSet

Event List

This option will return a set of encounters for those patients who meet the defined criteria and will add the query and patient list to the previous query view.

pqEncSet

Number of Patients

This option will return a total count for those patients who meet the defined criteria and will display the appropriate information in the following two views.

Previous Query View - displays the query and the results returned.

pqPtCount

Note: The number is displayed in the tool tip, which can be seen by hovering over Number of Patients.

Gender Patient Breakdown

This option will return a breakdown by gender for those patients who meet the defined criteria and will display the appropriate information in the following two views.

Previous Query View - displays the query and the results returned.

pqGender

Vital Status Patient Breakdown

This option will return a breakdown by vital status for those patients who met the defined criteria and will display the appropriate information in the following two views.

Previous Query View - displays the query and the results returned.

pqVitalStatus

Race Patient Breakdown

This option will return a breakdown by race for those patients who met the defined criteria and will display the appropriate information in the following two views.

Previous Query View - displays the query and the results returned.

pqRace

Age Patient Breakdown

This option will return a breakdown by age for those patients who met the defined criteria and will display the appropriate information in the following two views.

Previous Query View - displays the query and the results returned.

pqAge

Timeline

This option will return a list of patients who met the defined criteria and will display the appropriate information in the following two views. The current implementation of Temporal QueryTool does not automatically launch the Timeline visualization. Instead, users will need to drag the previous query (or the patient set) and drop it into Timeline's configuration panel.

1.       Timeline View - displays the patients and associated concepts in the format of a timeline.

2.       Previous Query View - displays the query and the results returned.

Running a Query

Once the query has been created and the Analysis types selected, the final step to retrieve your information is to run the query. This is done by clicking on the Submit Query in the query tool.

qtToolbarRunQuery

Once you begin the process of running the query the button become inactive, and a processing indicator will appear:

qtQueryStatusRunMI

When the query process concludes, the results will be shown:

queryStatusFinish

If the query takes longer than the Web Client expects, the query will be queued up on the server side and will be finished at a later time. An entry is created in the Previous Query view immediately and users are to check the entry periodically to see when the query completes. The following message will also be displayed at the Footer. The Submit Query button will become active so users can submit another query.

Cancel a Query

To cancel a query you simply click on the Cancel Query button.

NOTE:

Keep in mind "Cancel Query" and the associated action will only appear when the query is still in the process of running

  1. To cancel a query that is running, simply click on the Cancel Query button.

    qtToolbarCancelQuery

  2. Cancel will display in the Query Status view.

    qtQueryStatusCancel

Saving a Query

A previous query () is created automatically when the query is run from the Temporal Query Tool. The query is stored and displayed in the Previous Query View. Temporal Query Tool does not currently support saving query definitions.

Note: Previous queries can also be seen in Workplace View if the user copied it to their workplace or shared folder in workplace view.

1.       Run a query.

2.       Go to the Previous Query View.

3.       The query you just ran will now appear in the list of previous queries.

pqView

Printing a Query

Users are able to print out the query information if they wish to have a hard copy of the search criteria defined for a query.

When printing a query you can either print the information for a current query or you can drag a previous query to the query tool view and print the information associated with that query.

The following steps outline the process of printing a query once you have the appropriate query in the Query Tool.

  1. Click on the Print Query button located on the toolbar at the bottom of the Query Tool view

    qtToolbarPrintQuery

  2. A new window will open displaying the information about the query.

    qtPrintWindow

  3. On the menu bar, click on File to display the menu options.
  4. Select Print from the menu.