Penn State
i2b2
–
Penn
State
i2b2
User Guide & Frequently Asked Questions
User Guide
and
Frequently Asked Questions
Document prepared jointly by Ryan Moog from Cerner Corporation and Susan Craft from PSHMC
Center for Quality Innovation.
The authors graciously acknowledge the international i2b2 user community, including several
academic intuitions, who generously share their development tools and expertise.
V4.0
September 9, 2013
i2b2 User Guide & Frequently Asked Questions
Contents
General Information.............................................................................................................................................4
Q: What is i2b2? ...............................................................................................................................................4
Q: How is i2b2 populated? ..............................................................................................................................4
Q: How often is i2b2 updated?........................................................................................................................4
Q: What data is not in Penn State Hershey Medical Center’s i2b2? ............................................................4
Q: Can individual patients be identified? ........................................................................................................5
Q: What level(s) of access are available? .......................................................................................................5
Q: What HIPAA protections exist in the de-Identified project?.......................................................................5
Q: Do I need IRB approval to use the de-identified i2b2? .............................................................................5
Q: What if I want to find out actual patient information? ..............................................................................5
Q: What if I need additional data elements that are not in i2b2?.................................................................5
Q: What are the system requirements for the i2b2 web client? ...................................................................6
Q: How do I access the i2b2 web client? ........................................................................................................6
System Navigation (Web Client) ..........................................................................................................................7
Q: How do I navigate the i2b2 web client? .....................................................................................................7
Q: What are the icons at the top of each window in the i2b2 web client? ...................................................8
Term Search .........................................................................................................................................................9
Q: How do I search for a term? ........................................................................................................................9
Q: Is there support for using wildcards in search?.........................................................................................9
Query Building ................................................................................................................................................... 10
Q: How do I build a query? ............................................................................................................................ 10
Q: What query analyses do I have available? .............................................................................................. 11
Q: How do I distinguish between “Or” and “And”? ...................................................................................... 12
Q: How do I use the “Dates” function? ........................................................................................................ 13
Q: Do I have to use the “Dates” function? ................................................................................................... 14
Q: Can I use different dates for each group? .............................................................................................. 14
Q: How do I use the “Occurs” function?....................................................................................................... 14
Q: How do I use the “Exclude” function? ..................................................................................................... 15
Q: Can a query time out? .............................................................................................................................. 16
Q: The results indicate that there are 0 patients, but I know patients in our system should meet the
search criteria – what’s going on? ............................................................................................................... 16
Analysis Tools .................................................................................................................................................... 16
Q: What analysis tools can I use in the web client? .................................................................................... 16
Saved and Previous Queries ............................................................................................................................ 21
Q: How do I see the results of a previous query? ........................................................................................ 21
Q: How do I re-run a previous query? ........................................................................................................... 22
2
i2b2 User Guide & Frequently Asked Questions
Q: How do I save a query? ............................................................................................................................ 22
Q: How do I create a new folder in my Workplace folder? .......................................................................... 22
Q: How do I re-run a saved query? ............................................................................................................... 22
Q: Can Administrators see all queries?........................................................................................................ 23
Q: Can I use the results of a previous query in a new query? .................................................................... 23
Tips and Tricks .................................................................................................................................................. 23
Q: What should I keep in mind when building queries? ............................................................................. 23
Useful Links: ...................................................................................................................................................... 25
3
i2b2 User Guide & Frequently Asked Questions
General Information
Q: What is i2b2?
i2b2 (Informatics for Integrating Biology & the Bedside) is an informatics framework created through
NIH funding to leverage existing data for research cohort discovery. i2b2 was designed to support
cohort identification, retrospective data analysis, and hypothesis generation. Data is accessed from
the server at Cerner Corporation in Kansas City, Missouri using an internet browser. The web client
is designed with a user-friendly, drag-and-drop interface to enable users to perform data queries
without extensive training or technical expertise.
Q: How is i2b2 populated?
Cerner populates Hershey Medical Center’s i2b2 using data from Cerner’s Millennium EMR
(Connected) and the Penn State Hershey Medical Center (HMC) billing system. Leveraging a nightly
extraction process, PSHMC sends data to Cerner from both systems, where they are processed,
mapped, and formatted for i2b2. PSHMC maintains an identified and a de-identified project of i2b2.
The de-identified project uses an additional process that strips the data of all patient identifiers.
Demographics – From Connected
Diagnoses (ICD-9) – From PSHMC billing files
Laboratory (LOINC) – From Connected, but mapped at Cerner
Medication (NDC) – From Connected (includes ordered from in-patient pharmacy only)
Microbiology (Snomed) – not included
Procedures (ICD-9) – From PSHMC billing files (in-patient only)
Providers – The Ontology folder Provider is not set up to return data on the patients of an individual
Provider. (Note: this data is not always well populated in Connected).
Visit details – Inpatient, Outpatient, Emergency, Same Day Care, and Observation (from the billing
files)
Q: How often is i2b2 updated?
Hershey Medical Center’s i2b2 is updated weekly. Refreshes typically run from late Saturday
evening until early Sunday morning, during which time i2b2 will not appear to be off-line, but may
return inconsistent and unreliable results.
Q: What data is not in Penn State Hershey Medical Center’s i2b2?
The data in i2b2 reflects a subset of the data in PSHMC’s Connected electronic medical record. Data
such as vital signs, family history, images, notes and other un-coded fields are not be present in the
current i2b2 implementation. Enhancements are anticipated and will be announced as they are
implemented.
4
General Information
i2b2 User Guide & Frequently Asked Questions
Q: Can individual patients be identified?
Hershey Medical Center has access to 2 separate i2b2 projects: De-identified project and Identified
project. Access is granted by an Administrator, and most users will only have access to the deidentified project type.
Q: What level(s) of access are available?
In the de-Identified project, a user can be assigned to:
Obfuscated – Able to see only aggregated results, obscured further by being within +/- 3 of the
actual count. Additionally, a user may run a query only 3 times in a specified period to prevent
repeated querying to determine actual patient count.
Aggregated – Aggregated (not obscured) counts are available and the user is not limited to the
number of times a query is run.
Protected– All fields are available to the user. Since a list of patients (not just aggregated counts) is
available, some data on these patients can be exported using the Export XLS plug-in. Most HMC
users will be granted Protected access in the de-identified project.
In the Identified project, all available data can be seen by the user, including Medical Record
Numbers. The identified project is currently restricted to use by honest brokers.
Q: What HIPAA protections exist in the de-Identified project?
Cerner removes the 18 identifiers required by the HIPAA Privacy rule. In addition, patients over 89
years of age are aggregated into a single category of 90 years old (though ages above 90 are listed
in the Ontology) and dates are randomly shifted by 0-35 days, with weekly periodicity preserved to
maintain the relative day of the week and a simple (not rigorous) seasonality.
Q: Do I need IRB approval to use the de-identified i2b2?
No, the Hershey Medical Center IRB gave a determination that data in Cerner’s de-identified i2b2
project is not PHI. Therefore you can use the de-identified project of i2b2 once you have been
granted access without any further approvals by the IRB.
Q: What if I want to find out actual patient information?
Requests for identified data should be processed exactly as they are for other requests for data. The
i2b2 query can be used to narrow and refine a query that can then be submitted to the Data
Warehouse and Decision Support or CTSI analysts for additional details. A well-formed query that has
been performed on the de-identified project will facilitate the retrieval of identified information.
Q: What if I need additional data elements that are not in i2b2?
The Data Warehouse and Decision Support group has created a standard data set (SDS) that
includes patient assessments (e.g. vitals, smoking/alcohol use and allergies), lab and pharmacy
data, and diagnosis codes. The SDS will return data to the requester within 3 business days. This
dataset can be requested using the same report request process that is currently used to request
data from the data warehouse. To get an SDS:
1. First refine a query cohort using i2b2
5
General Information
i2b2 User Guide & Frequently Asked Questions
2. Name the query with the date and your name (right click in previous query window to
“rename”)
3. Submit a Report Request: Infonet>Departments>Technical/IT>Our Services>Request Report
a. Source: Connected EMR
b. Detail: Identify that this is an i2b2 query; include the name you gave the query.
c. If you are requesting PHI for research, include IRB number
d. Other dates: not used
e. The reports (as excel spreadsheets) will be sent to your Business Objects inbox in
Infoview (Start menu > my apps > log-in > folders (Business Objects) > Infoview).
f. Note: there may be a lot of data returned (e.g. lab results). In some cases it will be
necessary to engage PHS to assist with data review.
4. Important: The Data Warehouse group will first re-run your query in an identified environment
to determine the corresponding encounter numbers (OOS). The count (and cohort) of
patients in the SDS almost certainly will differ from the original query. That is due to the date
shifting algorithm in the de-identified i2b2. The cohort will be largely the same, but some
patients may have drifted in or out of the date shift range. If the data is for research (without
IRB approval) they will de-identify it again before sending.
Q: What are the system requirements for the i2b2 web client?
The i2b2 web client is compatible with multiple platforms (Windows & Mac) and browsers (Firefox,
Internet Explorer, Safari, and Google Chrome). While all platforms are compatible, Firefox and
Google Chrome are preferred for an optimal user experience.
Q: How do I access the i2b2 web client?
An Introductory Training session must be completed. See HMC Clinical and Translational Institute
(CTSI) web page for class times and information: http://ctsi.psu.edu/?page_id=3706
Once the account request has been processed, the i2b2 Administrator will generate an e-mail with
your username and password. The i2b2 web client can then be accessed at the following address:
https://i2b2.cernerresearch.com/webclient/#
1.
2.
3.
4.
5.
Enter your Username
Enter your password
Leave “i2b2 Host” defaulted to: Cerner Research
Click Login
If prompted with the “Choose a Project” window, select the desired Project and click “Go”.
6
i2b2 User Guide & Frequently Asked Questions
System Navigation (Web Client)
Q: How do I navigate the i2b2 web client?
After logging into the i2b2 project in the web client, you will be presented with the following screen:
The main i2b2 screen displays the following sections:
A. Navigate Terms – This allows the user the ability to navigate the entire i2b2 ontology.
B. Find Terms – This allows the user to search based on naming convention or actual code
value.
C. Workplace – The Workplace contains saved directories. Users can either save or share
previous queries here.
D. Previous Queries – This section contains most recently run queries.
E. Query Tool – The Query Tool is used to build query concepts. The Query Tool contains “group
panels”, each indicating a separate term or term group you wish to be included in your query.
F. Query Status – The Query Status contains the execution status of any query currently being
run.
G. Toolbar – The toolbar includes the following links:
i. Find Patients – Clicking this link directs the user back to the main i2b2 query tool
ii. Analysis Tools – Clicking this link directs the user to the Plugin Viewer (see page 17
for plug-in details).
iii. Message Log – The message log is intended to provide detailed information about
i2b2’s performance for troubleshooting.
iv. Help – Clicking this link accesses the basic i2b2.org Help page.
v. Logout – Clicking this link logs the user out of the system.
H. Temporal Constraint – When selected, you can set any Groups to “occur within the same
financial encounter” or to be treated independently from the other Groups (e.g. Group 1 and
7
System Navigation (Web Client)
i2b2 User Guide & Frequently Asked Questions
group 2 terms must occur within the same financial encounter, but Group 3 terms could
have happened at any time). Select Temporal Constraint to turn the function on, and then
use the field under the dates row to turn it on or off for a specific Group of terms. Note: this
functions only with the AND logic. You cannot ask for terms within a group to meet different
temporal conditions.
Q: What are the icons at the top of each window in the i2b2 web client?
In the Ontology window, display options are listed:
1. Show Hidden Terms – Displays any hidden ontology terms (no terms currently hidden)
2. Show Synonymous Terms – Displays any synonym terms (terms that share a concept code,
but have a different hierarchy) (synonyms currently disabled)
3. Enable Patient Counts – Displays a count of patients that meet the term or folder criteria.
4. Use Short Tooltips – Displays any configured short name tooltips (no short names currently
configured)
5. Show Concept Code in Tooltip – Displays complete concept code in the tooltip.
6. Disable Modifiers (no modifiers currently configured)
In the Query Tool and Previous Queries window, clicking the second icon will display options for that
specific window. Users can adjust options like the sorting format for previous queries. Clicking the
last icon will expand the window to its maximum size.
8
System Navigation (Web Client)
i2b2 User Guide & Frequently Asked Questions
Term Search
Q: How do I search for a term?
i2b2 enables users to search for terms, to supplement the use of the Ontology explorer. The “Find Terms”
window allows for searches by term name and code.
To search by term name, click the “Find Terms” navigation tab, and ensure that “Search by Names” is
selected. There are modifiers that can help to refine the search. Selecting “contains” will return the
searched text string wherever it appears in the ontology. i2b2 is very “literal”, so using “exact” will only be
successful if you also know the code that follows the term and likewise “ending with” will also search on
the coded number following the text string. Click “Find” when you have completed entering your search
criteria.
To search by code, click the “Find Terms” navigation tab, and then select the “Search by Codes” tab.
Here, you must enter a code and select a coding system (ICD-9, NDC, LOINC). Click “Find” when you have
completed entering your search criteria.
Hint:
Diagnosis and procedure IDC9 codes are easy to find by doing a Google search.
For lab tests and medications, the Ontology contains many codes for tests and medications not
performed or prescribed at Hershey Medical Center. Using the “enable patient counts” will help
guide you to terms that represent lab tests and medications populated with HMC data. It is often
useful to choose a term as high on the Ontology tree as is applicable.
Q: Is there support for using wildcards in search?
Today, the i2b2 application does not support the use of wildcard expressions (*, %, etc.) in searching.
While not exactly synonymous, it is possible to perform a “contains” search to query the ontology for all
terms that contain a substring of text.
9
Term Search
i2b2 User Guide & Frequently Asked Questions
Query Building
Q: How do I build a query?
Queries can be built using i2b2’s simple drag and drop interface. Once you have identified a term
that you wish to query for, simply click and drag the term over to Group 1 in the Query Tool.
Once a single term is entered into the group, the second group becomes enabled and is available to
be utilized. A second term can be added to the group.
Once the query has been developed, click “Run Query” at the bottom of the Query Tool.
You will then be asked to name the query and choose the analysis. By default, the query will be
named with an abbreviated version of the terms and the time the query was run. The name can be
changed by editing this text. You will also be asked which type of query you would like to run. For
more information about query result types, see Q: “What query analyses do I have available?”
Please note: only users with “Protected” data access roles will be able to generate patient set lists;
10
Query Building
i2b2 User Guide & Frequently Asked Questions
those with “Obfuscated” or “Aggregated” permissions can only generate patient counts. Click “OK”
to run the query.
The query will execute as designed. Check the Query Status window for information as the query
runs. When the query completes, you will be given the query results that meet the search criteria and
the time taken to run the query.
Note: Users with “Obfuscated” permissions will retrieve results that are obfuscated (obscured) by
returning +/- 3 records each time the query is run. These users are also limited to the number of
times they can run the same query in a predefined time period. All other data access roles will
retrieve exact query results.
Q: What query analyses do I have available?
The latest version of i2b2 makes available several analysis types:
a. Patient List - Generates a list of patients meeting the criteria.
b. Event List – Generates a list of encounters/visits meeting the criteria. Individual
patients may be counted more than once, or not at all.
c. Number of patients – Generates a simple count of patients that meet the query
criteria.
d. Gender patient breakdown – Breaks down the patient count by gender.
e. Vital Status patient breakdown – Breaks down the patient count by vital status
(Deceased: Y/N).
11
Query Building
i2b2 User Guide & Frequently Asked Questions
f. Race patient breakdown – Breaks down the patient count by patient race.
g. Age patient breakdown – Breaks down the patient count by age.
h. Timeline – Creates a data set that meets the query criteria and can be analyzed as a
patient timeline.
Q: How do I distinguish between “Or” and “And”?
Building a group of terms across the group panels naturally indicates an “And” connector. For example,
the following query indicates is for females who have had a Cesarean section and have a diagnosis of
essential hypertension.
To build an “Or” query, include the terms in the same group panel. For example, to query for females who
have had a Cesarean section or have a diagnosis of essential hypertension, build the query like this:
This query will return counts for females who have at least one or more of the criteria in Group 2.
Females who are hypertensive or have given birth via Cesarean section will meet the criteria of this query.
12
Query Building
i2b2 User Guide & Frequently Asked Questions
Q: How do I use the “Dates” function?
In i2b2, the “Dates” function can be used to further refine the query to only include terms that have been
recorded during a specific time. The “Dates” function can be used for activities data, like medications,
procedures and diagnoses, to restrict the results to a certain time period..
Note: Reference data (Demographics), is not compatible with the “Dates” function. If the “Dates”
function is used with reference data, it will retrieve “0 patient” results.
The “Date” function in i2b2 allows users to set a beginning date, an end date, or both. For example, if
you wanted to query for patients who have had an Obstetrical Procedure (ICD-9 72-75) since January 1,
2012, with no particular end date, follow these steps:
1. Once the desired term has been input into the group panel, click the “Dates” button.
2. On the Date Range pop-up, enter the dates you would like to restrict your query to. For this
example, select the check-box for “From:” to indicate you will be setting a beginning date,
and enter 01/01/2012. i2b2 displays dates in the MM/DD/YYYY format.
3. Click “OK”. The date range has now been set, and Dates will be underlined in the column for
which it was set. When the query is run, i2b2 will only return patients who have had an
Obstetrical Procedure since January 1, 2012.
13
Query Building
i2b2 User Guide & Frequently Asked Questions
Q: Do I have to use the “Dates” function?
No, the use of the “Dates” function is optional. If a query term is not date-limited, i2b2 will return all
results for that term, regardless of date.
Q: Can I use different dates for each group?
Yes. Each group has a unique “Dates” function. For example, if you build a query with a first group with
an Obstetrical Procedure term and a date limitation of 01/01/2012 – 12/31/2012, and a second group
with the Essential Hypertension term and no date limitation, i2b2 will return the number of patients who
had a diagnosis of essential hypertension recorded at some point in (in the total date range included in
i2b2) and an Obstetrical Procedure recorded in 2012.
Q: How do I use the “Occurs” function?
In i2b2, the “Occurs” function allows users to query for patients with multiple occurrences of a term. For
example, to search for a patient with more than one Obstetrical Procedure (ICD-9 72-75), follow these
steps:
1. Once the desired term has been input into the group panel, click the “Occurs > 0x” button.
2. On the Occurrences pop-up, select the number of term occurrences you require in your query.
For this example, select “1”.
3. Click OK. The occurrence limit has now been set. When the query is run, i2b2 will only
return patients who have at least two Obstetrical Procedures.
14
Query Building
i2b2 User Guide & Frequently Asked Questions
Q: How do I use the “Exclude” function?
In i2b2, the “Excludes” function allows users to exclude a group of patients from a query. For example, to
query for all patients who have had an Obstetrical Procedure except for patients with a Low cervical
cesarean section (ICD-9 74.1), follow these steps.
1. Build a query with multiple group panels. One panel should include the group you wish to
exclude from your query. For this example, the below query can be built.
2. Once the desired term of exclusion has been input into the group panel, click the “Exclude”
button.
3. The label on the group panel will change to say “none of these”. When the query is run, i2b2
will return all patients with an Obstetrical Procedure, except for patients with a Low cervical
cesarean section.
15
Query Building
i2b2 User Guide & Frequently Asked Questions
Q: Can a query time out?
Queries do not time out in i2b2. They will always run to completion, as long as the application is
connected to the database.
Most queries run in under one minute. In the event that a query is particularly large (either in scope of
terms, or scope of patients potentially returned), queries may run longer. The i2b2 web client will
eventually display a message (after ~ 5 minutes) indicating that your session has “timed out”, but the
query will continue running. Simply log back into the application and check the Previous Queries window
for your results.
In the event that a query does not ever return, please contact your i2b2 administrator.
Q: The results indicate that there are 0 patients, but I know patients in our system should
meet the search criteria – what’s going on?
There are a number of explanations for this scenario.
1. For HIPAA compliance reasons, i2b2 obfuscates results below a threshold for some roles. With
the obfuscated data protection role, the query count can be configured to prevent retrieving
results lower than a certain threshold. This may be configured if there is concern that results
lower than this threshold could result in patient re-identification.
2. It is possible that one or more patients are not properly documented in Connected.
3. If the expected information is in a note, image, registry, history or other uncoded field not
currently available in the i2b2, it will not be present.
4. If data is very current, it may not yet have been processed on the Hershey Medical Center side
(e.g. billing files), or it may not be included due to the weekly i2b2 refresh schedule.
5. Because the ICD-9 data are from billing files, it is possible that working diagnoses have been
changed or modified per HIS protocols.
6. Carefully examine your query logic. Using an AND clause with a data type (e.g. religion) which
does not have HMC data will cause the whole query to fail.
Analysis Tools
Q: What analysis tools can I use in the web client?
The web client currently has several plugins loaded to use for analysis. Click the “Analysis Tools”
menu (near the top right corner) to display the set of plugins available (lower right panel):
1. Demographics (1 Patient Set) – Simple Counts: A method for breaking down patient sets by
age, sex, race and vital status. To generate the analysis, drag a patient set from the
workplace or previous queries section onto the “Specify Data” tab.
2. Demographics (2 Patient Sets) – Simple Counts: A method for comparing two patient sets by
age, sex, race and vital status. To generate the analysis, drag patient sets from the
workplace or previous queries section onto the “Specify Data” tab.
3. Timeline: A method for displaying laterally when concepts/terms were observed in a patient
set. To generate, drag a patient set and one or more concepts onto the “Specify Data” tab.
16
Analysis Tools
i2b2 User Guide & Frequently Asked Questions
The concepts may be any of the terms used to create the underlying query, or terms that
might be relevant for the population defined by the query. If the concept is relevant for the
patient, a row will be created.
a. The concept does not have to have been included in the original query. The query
concepts simply narrow down a patient set. A user can then ask questions of that
patient set by choosing additional concepts, and plotting them on the Timeline (or
exporting them, as below)
b. When a Timeline is generated, hover over the tick mark to see the underlying code
resolve
c. A double click brings up a box that includes time stamp for the concept (e.g. admit
date/time date for an ICD9 code).
4. ExportXLS: A plug in that allows data to be exported based on a defined patient set. This
plug-in:





17
Offers different formats and levels of detail.
Optionally replaces patient IDs with ascending numbers.
Optionally adds a selection of demographic patient details.
Optionally resolves numerical concept codes into their underlying meaning.
Optionally includes ontology path of concept codes.
Analysis Tools
i2b2 User Guide & Frequently Asked Questions
Exports tabulated data into a CSV or HTML/XLS file that can easily be used by SPSS and
other statistics software.

a. Click the “ExportXLS” plugin from the plugin list to display its tabs.
b. Navigate to the "Specify Data" tab. Then, drag and drop a Patient Set and one or
more concepts of interest (Ontology Terms) onto the input boxes.
c. Click the "View Results" tab to view the table of the observations.
Usage Tips:
I.
II.
III.
IV.
V.
18
There are 4 options for formatting the output:
 1 row per observation (duplicates removed, 1 column per observation
set): A new row is created for each observation. All observation details
(concept code, value, unit ...) are written into one cell. One column is
created for each concept that has been dragged onto the input box.
Note: Duplicate entries are removed! This format only
returns a list of the different observations that were found.
 1 row per observation (all, with timestamps, 1 column per observation
set): Similar to the option above, but: timestamps of the observations
are tabulated as well. Therefore, duplicates are not possible and
nothing is removed.
 1 row per observation (detailed, 1 column per observation detail): This
is the most detailed option. A new row is created for each observation
and all observation details (concept code, value, unit ...) are written to
dedicated columns.
 1 row per patient, 1 column per observation set: A new row is created
for each patient. One column is created for each concept that has been
dragged onto the input box. All observations of a patient are then
written into one cell (with respect to the concept column).
Resolving concept/modifier codes provides additional detail on the underlying code
(e.g. Alcohol Withdrawal, rather than simply ICD9 291.81), but takes a little more
processing time.
The default export CSV file encloses all data cells in quotation marks ("). This is
necessary to export special characters like line breaks within a cell. However, some
statistics software may get confused with the quotation marks. In this case, check
the 'Exclude CSV Cell Delimiter (") Where Possible' box on the "Settings" tab to permit
the writing of quotation marks. Cells with special characters will still be enclosed in
quotation marks. However it will now be less work to remove them manually than if it
had to be done for every cell.
If a query would return very large result sets, the server automatically pages the
result. This causes a considerable delay that sometimes will fail or hang, due to
timeouts. If you encounter this problem, the query can be paged manually by setting
the 'Query Page Size' value on the "Settings" tab. This is still slower than an 'at-once'
query, but faster than automatic paging and it avoids server overload. The necessary
value cannot be predicted in general and strongly depends on the number of
observations returned, but 20 - 50 is a good idea for beginning. Higher values result
in faster processing but higher risk of server overload.
If results seem to be returning extremely slowly, it may have to do with how the data
is being pulled from the tables. Modify the Settings in the ExportXLS plugin to a page
Analysis Tools
i2b2 User Guide & Frequently Asked Questions
size of 50, which will divide the data into chunks and allows the system to pull back
the data in sequential pieces rather than all at once (see screen shot next page).
VI.
19
Not all fields will be available in the HMC de-identified i2b2 database. The first
screen capture below illustrates what data fields are retrievable from the HMC
database, and the second one illustrates results returned with these criteria
checked:
Analysis Tools
i2b2 User Guide & Frequently Asked Questions
Details of Export:
Format Used: - 1 row per observation (detailed, 1 column per observation) (Choice-3).
Note: Each row corresponds to an order.
Patient
1
Timestamp Timestamp
Observation
Observation
Observation
ID
Start
End
Set
Concept Code
Concept
Denotation
1220222
2013-02-07
00:07:00
2013-02-08
17:35:00
Alcohol
withdrawal
(291.81)
ICD9:291.81
Alcohol
withdrawal
(291.81)
2012-07-19
2012-07-19
16:44:00
16:44:00
2012-07-19
15:22:00
2012-07-19
15:22:00
Observation Observation Observation
Value
Unit
2
TB
Diazepam,
2
1220222
23 1220222
Diazepam, 5
Benzodiazepines NDC:51079028521
mg tablet
(51079028521)
Sodium
(LP15099-2)
LOINC:2951-2
Sodium SerPlsCnc (2951-2)
143
Patient ID- i2B2 de-identified patient identification number.
Timestamp Start (i) ICD9 (Diagnoses & Procedures):– Admit Date & Time for all visit types for a single encounter
(ii) NDC (Medications):- Order Start Date & Time
(iii) LOINC (Labs):- Specimen Collect Date & Time
Timestamp End (i) ICD9 (Diagnoses & Procedures):- Inpatient, ED, SDS – Discharge Date & Time
20
Analysis Tools
Modifier
i2b2 User Guide & Frequently Asked Questions
Outpatient – same as Admit Date & Time
(ii) NDC (Medications):- Order Stop Date and Time (note: this is the duration of the order, as recorded
in the EMR. It may or may not reflect the actual duration of medication administration)
(iii) LOINC (Labs):- Same as specimen Collect Date & Time
Observation Set - The concepts (ontology terms) selected for the data export. (These may be parent folders).
Observation Concept Code - The specific, relevant code. (This will always be a child).
Observation Concept Denotation - Pertinent details (e.g. drug name, formulation and strength) about the
concept code.
Observation Value (i) ICD9 (Diagnoses & Procedures) – No Value given
(ii) NDC (Medications) – Number of “dispenses” of the drug per order to be given with each
administration (in the example above, the order was for 2 tablets of Diazepam).
(iii) LOINC (Labs) – Lab result
Observation Unit (i) ICD9 (Diagnoses & Procedures):– None
(ii) NDC (Medications):- Type of formulation administered (e.g. Cap (Capsule), TB (Tablet), VL (Vial),
Syringe, Bag).
(iii) LOINC (Labs):- None
Observation Modifier - N/A
5. The Project Request plug-in is currently inactive.
Saved and Previous Queries
Q: How do I see the results of a previous query?
i2b2 automatically saves the results of previous queries. The Previous Queries window maintains a list of
queries run recently, and displays them by Query Name given at the time of the initial run. To view the
results of a previous query, simply expand the Query Name folder, which will reveal the results folder.
Expand the results folder, which will reveal the query results (i.e. Patient Count, Patient Set, etc.) that was
generated.
To view the count results of a previous query, drag the Query to the “Query Name” box in the Query Tool.
The Query Tool will populate with the results.
21
Saved and Previous Queries
i2b2 User Guide & Frequently Asked Questions
Q: How do I re-run a previous query?
A previously run query can be dragged from the Previous Query window to the Query name box in either
the workbench or the web client. The Query Tool will populate with the group panels that were originally
selected. Click “Run Query”.
Note: Previous queries can be refined once a user drags the query into the Query Tool.
Q: How do I save a query?
While i2b2 saves previous queries for future reference, older queries eventually are removed from the
list. To permanently save the query for your future reference, drag the Query Name folder into the
Workplace window onto your Username folder.
Q: How do I create a new folder in my Workplace folder?
Create a new folder by right-clicking on the Username Workplace folder and then click “New Folder”.
Q: How do I re-run a saved query?
To re-run a saved query, drag the Query folder from the Workplace window back to the Query Tool. The
Query Tool will populate with the group panels that were originally selected. Click “Run Query”.
Note: Saved queries can be refined once a user drags the query into the Query Tool.
22
Saved and Previous Queries
i2b2 User Guide & Frequently Asked Questions
Q: Can Administrators see all queries?
Yes. Users with the i2b2 Administrator role can see all queries.
Q: Can I use the results of a previous query in a new query?
Yes. i2b2 features the ability to “query-in-query”. To perform this function, simply drag a previouslyexecuted query into one of the group panels. This essentially re-creates all of the query elements that
were created to generate that query within that group, and allows you to build new elements of the query
in the group panels.
Example: A previous query for women diagnosed with high blood pressure in November 2012 results in
1135 patients. You may further query this cohort to identify women between the ages of 18 and 44 by
dragging the previously-run query into a group and, then dragging the age criteria in a different group.
This allows you to drill further into previously-identified cohorts.
i2b2 Tips
Tips and Tricks
Q: What should I keep in mind when building queries?
1. There may be multiple queries to help address the same research question. To truly
visualize the whole picture of a potential cohort, individually query for all possible associated
medications, procedures, and diagnoses of the cohort.
2. Remember the inherent logic of cohort querying:
a. Queries return counts of patients who met the specified criteria.
b. Queries can be created across or within groups. An AND statement (across groups)
answers the question: Where there occurrences of all the specified concepts?
Therefore a query on Inpatients AND Outpatient will return only patients who have
been BOTH an Inpatient and an Outpatient at some point. An OR query (within
groups) will return patients who met any (but not necessarily all) of the criteria.
c. Setting the dates function will return data occurring in the same time frame, but that
does not necessarily mean there is a temporal relationship. To get data from the
same encounter, select Occurs in the Same Financial Encounter.
3. Don’t use the “Dates” or “Occurs > 0x” controls for person (reference) information.
Person/demographic information like gender and race are not associated with specific dates.
i2b2 will yield 0 results if group panels with person-specific information are date-limited.
4. Most queries finish in under a minute. To calculate the patient counts for parent concepts
like “Obstetrical Procedures”, i2b2 will calculate all underlying terms. These queries tend to
take a little longer. If a query seems to run indefinitely, log out and then right back in. Often
the query has finished behind the scenes, and the answer is in the previous queries window.
NOTE: The previous queries window does not list the count, only that the query is finished.
Drag the query back into the query tool pane, and the result will populate the query status
pane. If the query does not resolve, contact your i2b2 administrator.
23
i2b2 User Guide & Frequently Asked Questions
5. i2b2 Ontology Expansion and Searching. Navigating the i2b2 Ontology, whether expanding
the ontology explorer, or searching for ontology terms, should only take a few seconds. Some
term searches will take longer than others, but if you experience consistently long loading
times, contact your i2b2 administrator. Often logging out and then right back in will show the
query has finished behind the scenes, and the answer is in the previous queries window.
NOTE: The previous queries window does not list the count, only that the query is finished.
Drag the query back into the query tool pane, and the result will populate the query status
pane.
6. Use the search qualifiers in the Find Terms section of the Ontology to narrow the number of
returned fields.
7. Order does matter in how quickly a query completes. Start with the most restrictive concept
in Group 1, and proceed outward in successive groups with broader concepts. The i2b2 logic
will start with Group 1, and then review each subsequent concept against the patients that
met Group 1 criterion, and so forth. Therefore, queries built from most to least restrictive
(e.g. group 1 = diagnosis; group 2 = sex; group 3 = visit type) will typically return results
faster than queries built the other way.
8. A “patient set” is a group of patients meeting the defined query, but then stripped of all
qualifiers. In other words, when you define a patient set, you have created a group of
patients meeting your specified criteria, but now the “patient set” includes just that group of
patients. The underlying concepts you used to create the patient set are not going to be
exported unless you place them in the “place concept here” field. You can ask new questions
about those patients using Timeline or ExportXLS and adding concepts to be displayed.
24
i2b2 User Guide & Frequently Asked Questions
Useful Links:
1) General i2b2 community user information https://community.i2b2.org/wiki/dashboard.action
2) The PSH CTSI web site i2b2 section http://ctsi.psu.edu/?page_id=3706
25
Useful Links: