webclient.help.qt.html Maven / Gradle / Ivy
Untitled Document
i2b2 Query Tool View
The Query Tool view is designed to simplify the process of retrieving information from the database associated to the i2b2 Web Client.
Introduction
This section describes the layout and contents of this view.
Layout of the Query Tool View
The Query Tool view is used to define and run a "select query" that will retrieve information from the database associated to the i2b2 Web Client.
The Query Tool view can be broken down into several sections which are defined below.
Query Name
The name of a query will be assigned when it is run and will display in the Query Name field.
The only time a query name will appear prior to running the query is when you drag a previous query from either the Previous Query or Workplace views and drop it into the Query Name field.
Temporal Constraint
The Temporal Constraint is defined on the query level and depending on what is selected will set the default for the panel timing.
Panel
A panel is the section of the Query Tool view that contains information about a group of concepts. The panel can be broken down into the following sections.
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.
Selection Criteria
This area of the panel is used to define date selections and other constraints.
Panel Timing
The panel timing defines the constraint on the panel level and uses the patient's visits in determining eligibility.
Group List
This section contains the terms that will be used during the process of querying the database.
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
- The message will appear as "drop a term on here"
- The color of the box will be yellow
- Term(s) listed
- The message will appear as "one or more of these"
- The color of the box will be green
- An additional information box will appear between panels
NOTE:
Once you add an item to a panel, an additional information box will appear between the two panels containing the text "AND". This is to indicate that each panel will be joined with an AND operator when the SQL query is created.
Toolbar
The toolbar is the bottom section of the Query Tool view and contains several buttons that perform various actions.
Run Query / Cancel Query Button
On the toolbar for the Query Tool there is a single button for running and canceling a query. Depending on the circumstances defined below the label on this button and its associated action will change to one of the following: (1) Run Query or (2) Cancel Query.
Run Query Button
Clicking on the button labeled Run Query will run your query with the defined search criteria.
Cancel Query Button
Once you start running a query, the label will change to Cancel Query. Clicking on the button when it says Cancel Query will cancel the query and free up the Query Tool / Web client so that you can continue to do other things.
NOTE:
Clicking on Cancel Query in the Query Tool will only cancel the web client piece of the process. The server side will continue to run.
Clear Button
The Clear button will reset the view to the default; this includes deleting the concepts listed in the panel and removing any constraint that have been defined.
Print Query Button
The Print button will open a window with the query information in a printable format.
Query Status View
The Query Status view is located below the Query Tool view and contains information regarding the status of a query that is either running or has just finished as well as the results of a previous query.
While a query is running you will see the name of the query and how long it has been running.
Once the query has finished, the number of patients meeting the search criteria will appear in this view. You will also see the length of time it took to retrieve the requested information. This is a display only view.
NOTE:
The result types that appear will depend on what you have selected when running the query..
Options
Users can define how long to wait before a query will time out. This setting is defined in the Query Tool Options, which can be accessed by clicking on the Show Options button (
).
The default setting is 180 seconds, which means the web client will wait for a response from the server for 180 seconds. Once it reaches that time it will display a message saying the query has timed out and will continue to run in the background.
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 Query Tool view.
- 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.
- 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.
- Previous Query
A new query can be created from one that has already been run by dragging the previous query (
) from Previous Query and Workplace views.
- Patient Set
A patient set (
) can be can be used in a query by dragging the patient set from Previous Query and Workplace views . When you run the query it will use the patient set to query against.
- Encounter Set
An encounter set () can be used in a query by dragging the patient set from Previous Query and Workplace views. When you run the query it will use the encounter set to query against.
Operators
There are two operators, known as SQL Logical Operators, which are necessary when running a query that has more than one item. These operators provide a way to specify exactly what you want to retrieve. The operators are the 'AND' and 'OR' operators.
IMPORTANT:
The query tool knows which operator to use based on the panels used when defining the query. It is important to verify you are setting up your 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 fulfill both requirements.
OR Operator
The OR operator returns a record if either the first condition or the second conditions are true.
The query tool uses the OR operator when concepts are listed in different panels.
Example:
WHAT: Return only those patients who have Acute Myocardial Infarction OR Angina Pectoris.
HOW: In the query tool add both concepts Acute Myocardial Infarction and Angina Pectoris to Group 1.
RESULT: The population is broadened to include all patients who fit either one of those criteria.
Add Concepts
Concepts can be added to the Query Tool view by simply dragging the concept from one of the following views.
- Navigate Terms view
- Find Terms view
- 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
- In the Navigate Terms view, expand the folder(s) that contains the concept or grouping of concepts you want to add.
- Highlight the concept () or folder () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- 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.
NOTE:
For detailed information on how to search for terms, please see the i2b2 Find Terms help.
Add Concept From Find Terms View
- In the Find Terms view, search for the item(s) you want to add.
- Highlight the concept () or folder () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The item will now display in the panel for Group 1.
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.
Add Concept From Workplace View
- In the Workplace view, expand the folder(s) that contains the concept or grouping of concepts you want to add.
- Highlight the concept () or folder () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The item will now display in the panel for Group 1.
Add Modifiers
Modifiers can be added to the Query Tool view by simply dragging the modifier from one of the following views.
- Navigate Terms view
- Find Terms view
- 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.
Add Modifier From Navigate Terms View
- In the Navigate Terms view, expand the folder(s) that contains the modifier or grouping of grouping of modifiers you want to add.
- Highlight the modifier () or modifier folder () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The name of the concept associated to the modifier plus the modifier 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.
NOTE:
For detailed information on how to search for terms and modifiers, please see the i2b2 Find Terms help.
Add Modifier From Find Terms View
- In the Find Terms view, search for the term(s) and modifier you want to add.
- Highlight the modifier () or modifier folder () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The name of the concept associated to the modifier plus the modifier will now display in the panel for Group 1.
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.
Add Modifier From Workplace View
- In the Workplace view, expand the folder(s) that contains the modifier or grouping of modifiers you want to add.
- Highlight the modifier () or modifier folder () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The name of the concept associated to the modifier plus the modifier will now display in the panel for Group 1.
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.
- Previous Query view
- Workplace view
Within the Query Tool view, the previous query can be added to one of the following two locations.
Query Name field
The items 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.
Panel (Group)
Used within a new query (query-in-query). The information associated with the previous query can not be edited. 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.
Add Previous Query From Previous Query View (New Query)
- In the Previous Query view highlight the previous query () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the previous query into the Query Name.
- The item(s) associated with the previous query 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.
NOTE:
When you run the query it will receive a new name. This is to distinguish the first previous query from the second.
Add Previous Query From Previous Query View (Query-in-Query)
- In the Previous Query view highlight the previous query () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the previous query into the panel labeled Group 1.
- The previous query will now display in the panel for Group 1.
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.
Add Previous Query From Workplace View (New Query)
- In the Workplace view, expand the folder(s) that contains the previous query you want to add.
- Highlight the previous query () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the previous query into the Query Name.
- The item(s) associated with the previous query 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.
NOTE:
When you run the query it will receive a new name. This is to distinguish the first previous query from the second.
Add Previous Query From Workplace View (Query-in-Query)
- In the Workplace view, expand the folder(s) that contains the previous query you want to add.
- Highlight the previous query () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the previous query into the panel labeled Group 1.
- The previous query will now display in the panel for Group 1.
NOTE:
When you run the query it will receive a new name. This is to distinguish the first previous query from the second.
Add Patient Set
A patient set can be added to the Query Tool view by simply dragging the list of patients from one of the following views.
- Previous Query view
- Workplace view
How to add a patient set from each of these views is explained in the next few sections.
Previous Query View
The Previous Query view displays the queries that were run by the user.
Add Patient Set From Previous Query View
- In the Previous Query view click on the plus sign (
) next to the name of the previous query that contains the patient set.
- Click on the plus sign () next to the results folder.
- Highlight the Patient set () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The item will now display in the panel for Group 1.
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.
Add Patient Set From Workplace View
- In the Workplace view, expand the folder(s) that contains the list of patients you want to add.
- Highlight the Patient set () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The item will now display in the panel for Group 1.
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.
- Previous Query view
- Workplace view
How to add an encounter set from each of these views is explained in the next few sections.
Previous Query View
The Previous Query view displays the queries that were run by the user.
Add Encounter Set From Previous Query View
- In the Previous Query view click on the plus sign () next to the name of the previous query that contains the patient set.
- Click on the plus sign () next to the results folder.
- Highlight the Encounter set () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The item will now display in the panel for Group 1.
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.
Add Encounter Set From Workplace View
- In the Workplace view, expand the folder(s) that contains the list of patients you want to add.
- Highlight the Encounter set () by clicking on its name.
- While holding the left mouse button down, drag the item over to the Query Tool view
- Drop the item into the panel labeled Group 1.
- The item will now display in the panel for Group 1.
NOTE:
When you run the query it will receive a new name. This is to distinguish the first previous query from the second.
Add a Panel / Group
Three panels are typically displayed as part of the standard Query Tool view. Some complex queries may require the use of additional panels.
NOTE:
In order to add a panel, the previous panels must contain at least one concept.
- Click on the New Group button located on the toolbar at the bottom of the Query Tool view.
- A new panel will be added.
Navigate Multiple Panels
On the toolbar at the bottom of the view, there are additional navigational buttons that will become active when more than three panels are being used.
Begin button
will move the display to show the first panel
End button
will move the display to show the last panel in use
Previous button
will move the display back one panel
Next button
will move the display forward one panel
Delete / Remove
There are three options for removing a concept from the Query Tool view. Users can (1) reset all the groups, (2) clear all items in a panel, or (3) delete an individual item from the group.
Reset Groups
- Click on the Clear button located on the toolbar at the bottom of the Query Tool view.
- All the groups will be reset, the temporal constraint will return to the default setting, and the query name will be removed (if one exists).
WARNING:
Once you click on the clear button, all items in every group; and the constraints will be removed, therefore you need to make sure you want to delete ALL items.
Clear Items in a Panel / Group
- Click on the Delete button (
) located in the top right corner of the panel (next to the Group name).
- The group will be reset.
WARNING:
Once you click on the delete button, all items in every group; and the constraints will be removed, therefore you need to make sure you want to delete ALL items.
Delete Single Item
- Using the right mouse button, click on the name of the item to be removed.
- A list box will open.
- Select Delete from the list.
- The concept will be removed from the list.
WARNING:
Once you click on the delete, any constraints specific to that item will be removed, therefore you need to make sure you want to delete that item.
Setting Constraints
Constraints are used to narrow down the search criteria to a particular time frame, 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
Temporal
Constraint is defined on the query level and utilizes the patient encounters and / or instance number when determining eligibility.
Panel Timing
Constraint is defined on the panel level and utilizes the patient encounters and / or instance number when determining eligibility.
Date
Constraint uses a date range when determining eligibility.
Occurrence
Constraint is by the number of occurrences an item is documented.
Exclusion
Constraint will not include patients with the concepts listed in the panel.
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 panel level.
Temporal and Panel Timing Constraints
Both temporal and panel constraints are very similar in that both utilize the visit / encounter information along with the concepts defined to determine if a patient meets the search criteria.
The main difference between a temporal and a panel timing constraint is that temporal constraints are defined at the query level and panel timing constraints are defined at the panel level.
Temporal Constraint
As stated in the previous section the Temporal Constraint is defined at the query level.
Users can select one of three available options:
- Treat all groups independently
- The items (facts) can occur at any time in the patient's history.
- Selected items occur in the same financial encounter
- The items (facts) occur during the same visit (financial encounter).
- Items instance will be the same
- The items (facts) occur during the same visit (financial encounter) AND the same instance.
- Can only be selected if a modifier is listed in a panel.
NOTE:
In order to be considered the same instance, the facts have to have the same patient number, encounter number, concept, provider, start date, and instance number.
Treat All Groups Independently
- Panel timing constraint will default to Treat Independently
- Panel timing constraint can not be changed
- Items defined in the panels can occur at any time in the patients history
Example:
Patient has a medication with a dose greater than 500 mg and a medication that is taken once a day documented at any time in their history.
RESULTS: there are 47 patients who have had a medication with a dose of 500 mg and a frequency of once a day entered as a fact in the observation_fact table, where medication dose and frequency have the same patient_num.
Selected Groups Occur in the Same Financial Encounter
- Panel timing constraint will default to Occurs in Same Encounter
- The default panel timing constraint can be changed to Treat Independently
- Items defined in the panels occur during the same financial encounter (visit)
IMPORTANT:
The panel timing will override the temporal constraint setting.
Example:
Patient has a medication with a dose greater than 500 mg and a medication that is taken once a day documented during the same visit.
RESULTS: there are 41 patients who have had a medication with a dose of 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.
Items Instance Will Be the Same
- Panel timing constraint will default to Items instance will be the same
- The default panel timing constraint can be changed to Treat Independently
- Items defined in the panels occur during the same financial encounter (visit) AND the same instance
IMPORTANT:
The panel timing will override the temporal constraint setting.
Example:
Patient has a medication with a dose greater than 500 mg and a medication that is taken once a day documented during the same instance.
RESULTS: there are 36 patients who have had a medication with a dose of 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 , concept_cd, provider_id, start_date, AND instance_num.
Panel Timing Constraint
As stated in the previous section the Panel Timing Constraint is defined at the panel level and can only be changed when the temporal constraint is defined as Selected groups occur in the same financial encounter or Items instance will be the same.
Users can select one of three available options:
- Treat all groups independently
- The items (facts) can occur at any time in the patient's history.
- Selected items occur in the same financial encounter
- The items (facts) occur during the same visit (financial encounter).
- Temporal constraint has to be set to Same financial encounter in order to be available for selection.
- Items instance will be the same
- The items (facts) occur during the same visit (financial encounter) AND the same instance.
- Temporal constraint has to be set to Items instance will be the same in order to be available for selection.
NOTE:
In order to be considered the same instance, the facts have to have the same patient number, encounter number, concept, provider, start date, and instance number.
Treat Independently
The items (facts) listed in the panel can occur at any time in the patient's history.
Occurs in the Same Encounter
The items (facts) listed in the panel occur during same visit (financial encounter).
In the example shown below, the items (facts) listed in the panel for Group 1 can occur at any time in the patient's history while the items in Group 2 and 3 have to occur during the same 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 visit.
RESULTS: 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
Items Instance Will Be The Same
The items (facts) listed in the panel occur during same instance.
In the example shown below, the items (facts) listed in the panel for Group 1 can occur at any time in the patient's history while the items in Group 2 and 3 have to occur during the same instance.
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.
RESULTS: there are 3 patients who have had a medication with a dose of 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 , concept_cd, provider_id, start_date, 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.
The start date associated with the observation is what is used to determine if there is a positive hit.
Specified Date Range: From and To Dates Defined
Only data with activity within the defined date range will be used.
Example:
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 their 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.
Setting the Date Constraint (FROM / TO Date Range)
- Click on the Dates button located in the selection criteria section of the panel.
- A new window will open.
- Click the check box next to the date in the From box.
- At this point there are two methods of entering your starting date.
- Manually type it in the text box.
- Click on the drop-down arrow (
) to open the calendar view and click on the desired date.
Once you click on the desired date the calendar window will close.
- Click the check box next to the date in the To box.
- Highlight the default date or click on the drop-down arrow and enter the date you want to use as your ending date.
- Click on the OK button.
- Dates will now be underlined to indicate a date constraint has been set.
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:
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 their record any time on or after 01/01/2001 then their data will be included. If the diagnosis was entered prior to 01/01/2001 then it will not be included.
Setting the Date Constraint (FROM Date only)
- Click on the Dates button located in the selection criteria section of the panel.
- A new window will open.
- Click the check box next to the date in the From box.
- At this point there are two methods of entering your starting date.
- Manually type it in the text box.
- Click on the drop-down arrow () to open the calendar view and click on the desired date.
Once you click on the desired date the calendar window will close.
- Click on the OK button.
- Dates will now be underlined to indicate a date constraint has been set.
Specific End Date: Only the To Date is Defined
All data up until the defined end date. No start date defined.
Example:
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 their 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 (TO Date only)
- Click on the Dates button located in the selection criteria section of the panel.
- A new window will open.
- Click the check box next to the date in the To box.
- At this point there are two methods of entering your ending date.
- Manually type it in the text box.
- Click on the drop-down arrow () to open the calendar view and click on the desired date.
Once you click on the desired date the calendar window will close.
- Click on the OK button.
- Dates will now be underlined to indicate a date constraint has been set.
Occurrences Constraint
Users can define the number of times an item has to occur in order to be considered a positive "hit".
Setting the Occurrences Constraint
- Click on the Occurs > 0x button located in the selection criteria section of the panel.
- A new window will open.
- Click on the drop-down arrow to display a list of numbers.
- Select a number from the list.
- Click on the OK button.
- Occurs > 0x will now be underlined to indicate a constraint has been set and the 0 will be replaced with the selected number.
Exclude Constraint
The exclude constraint will not include patients with the item(s) listed in the panel.
- Click on the Exclude button located in the selection criteria section of the panel.
- The text in the information box will change to "none of these" and the background color will change to pink.
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, numeric, etc.).
For those items that do have values there are different types of values that may be associated with it.
NOTE:
The different types of constraints and how they work are the same regardless of whether or not it is associated with a concept or a modifier.
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.
- High
- Low
- Abnormal
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.
- Using the right mouse button, click on the item listed in the panel.
- A pop-up menu will open.
- Select Set Value from the list.
- A new window will open.
- Click on the radial dial next to By flag.
- A new field with a drop-down selection box will appear.
- Click on the drop-down arrow to change the flag or accept the default.
- Click on the OK button.
- The value constraint has been set.
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.
- Using the right mouse button, click on the item listed in the panel.
- A pop-up menu will open.
- Select Set Value from the list.
- A new window will open.
- Click on the radial dial next to By flag.
- A new field with a drop-down selection box will appear.
- Click on the drop-down arrow to change the flag or accept the default.
- Click on the OK button.
- 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.
- Test Not Performed
- Borderline
- Positive
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.
- Using the right mouse button, click on the item listed in the panel.
- A pop-up menu will open.
- Select Set Value from the list.
- A new window will open.
- Click on the radial dial next to By value.
- A new field listing the enumerated values will appear.
- Click on the name of the value you want to include.
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.
- Click on the OK button.
- The value constraint has been set.
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.
- Using the right mouse button, click on the item listed in the panel.
- A pop-up menu will open.
- Select Set Modifier Value from the list.
- A new window will open.
- Click on the radial dial next to By value.
- A new field listing the enumerated values will appear.
- Click on the name of the value you want to include.
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.
- Click on the OK button.
- The value constraint has been set.
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.
- 200
- 1.3
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.
- Using the right mouse button, click on the item listed in the panel.
- A pop-up menu will open.
- Select Set Value from the list.
- A new window will open.
- Click on the radial dial next to By value.
- Two new fields will appear; one with a drop down selection box and the other a text box.
- Click on the drop-down arrow to change the operator or accept the default.
- Enter a numerical value at the Please enter a value field.
- Click on the OK button.
- The value constraint has been set.
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.
- Using the right mouse button, click on the item listed in the panel.
- A pop-up menu will open.
- Select Set Modifier Value from the list.
- A new window will open.
- Click on the radial dial next to By value.
- Two new fields will appear; one with a drop down selection box and the other a text box.
- Click on the drop-down arrow to change the operator or accept the default.
- Enter a numerical value at the Please enter a value field.
- Click on the OK button.
- The value constraint has been set.
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.
- Using the right mouse button, click on the item listed in the panel.
- A pop-up menu will open.
- Select Set Modifier Value from the list.
- A new window will open.
- Click on the radial dial next to By value.
- Two new fields will appear; one with a drop down selection box and the other a text box.
- The Units will default to the normal units defined for the item.
- Click on the drop-down arrow to change the units.
- Click on the drop-down arrow to change the operator or accept the default.
- Enter a numerical value at the Please enter a value field.
- Click on the OK button.
- The value constraint has been set and the numerical value has been converted to the normal units.
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 the output.
Output Selection
When you run a query you need to select what type of result the server will return. There are several result types available, each of which will yield a different output.
Patient set
Provides a list of patients who met the search criteria.
Encounter set
Provides the total number of encounters that 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
Not used in the Web Client. If selected it will work the same as patient set.
The result type(s) will appear when you click on the Run Query button and they can be selected in any combination.
Patient Set
This option will return a set of patients who meet the defined criteria and will display the appropriate information in the following views.
- Query Status View
- The patient set information will appear as soon as the query has finished running.
- It will also appear in this view when you drag a previous query to the Query Name field in the Query Tool view.
- Previous Query View
- Displays the query and the results returned.
Encounter Set
This option will return a set of encounters for those patients who meet the defined criteria and will display the appropriate information in the following views.
- Query Status View
- The encounter set information will appear as soon as the query has finished running.
- It will also appear in this view when you drag a previous query to the Query Name field in the Query Tool view.
- Previous Query View
- Displays the query and the results returned.
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 views.
- Query Status View
- The patient count information will appear as soon as the query has finished running.
- It will also appear in this view when you drag a previous query to the Query Name field in the Query Tool view.
- Previous Query View
- Displays the query and the results returned.
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 views.
- Query Status View
- The information for the gender patient breakdown will appear as soon as the query has finished running.
- It will also appear in this view when you drag a previous query to the Query Name field in the Query Tool view.
- Previous Query View
- Displays the query and the results returned.
Vital Status Patient Breakdown
This option will return a breakdown by vital status for those patients who meet the defined criteria and will display the appropriate information in the following views.
- Query Status View
- The information for the vital status patient breakdown will appear as soon as the query has finished running.
- It will also appear in this view when you drag a previous query to the Query Name field in the Query Tool view.
- Previous Query View
- Displays the query and the results returned.
Race Patient Breakdown
This option will return a breakdown by race for those patients who meet the defined criteria and will display the appropriate information in the following views.
- Query Status View
- The information for the race patient breakdown will appear as soon as the query has finished running.
- It will also appear in this view when you drag a previous query to the Query Name field in the Query Tool view.
- Previous Query View
- Displays the query and the results returned.
Age Patient Breakdown
This option will return a breakdown by age for those patients who meet the defined criteria and will display the appropriate information in the following views.
- Query Status View
- The information for the age patient breakdown will appear as soon as the query has finished running.
- It will also appear in this view when you drag a previous query to the Query Name field in the Query Tool view.
- Previous Query View
- Displays the query and the results returned.
Run Query
Once the query criterion has been defined, the final steps are to click on the Run Query button, select the result type(s), and click on the OK button to run the query.
- Once you have defined the search criteria click on the Run Query button located on the toolbar at the bottom of the Query Tool view.
- A new window will open.
- A name for the query will default at the query name field.
- Either change the name of the query or accept the default.
- In the query result type section, click on the checkboxes for those result types you want to include when the query is run.
- Click on the OK button.
- The Run Query window will close and the querying process will begin.
Once you begin the process of running the query the Query Status view will display "Running Query", the name of the query, and the time that has elapsed.
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
- To cancel a query that is running, simply click on the Cancel Query button.
- Cancel will display in the Query Status view.
Saving a Query
This section describes the process of saving queries.
Previous Query
A previous query () is created automatically when a query is run from the Query Tool. The query is stored in the database and displayed in the Previous Query view.
NOTE:
Previous queries can also be seen in Workplace view if the user copied it to their workplace or shared folder in workplace view.
- Run a query.
- Go to the Previous Query view.
- The query you just ran will now appear in the list of previous queries.
NOTE:
If the previous query does not appear in the list automatically you can refresh the view to update the list. This is done by using the right mouse button and clicking anywhere in the Previous Query view.
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.
- Click on the Print Query button located on the toolbar at the bottom of the Query Tool view
- A new window will open displaying the information about the query.
- On the menu bar, click on File to display the menu options.
- Select Print from the menu.