Penn State i2b2 User Guide and Frequently Asked Questions

splashburgerInternet και Εφαρμογές Web

22 Οκτ 2013 (πριν από 3 χρόνια και 11 μήνες)

700 εμφανίσεις














































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 de
velopment tools and expertise.



V4.
0 September 9
, 2013

Penn State i2b2


User Guide & Frequently Asked Questions


Penn State i2b2

User Guide

and


Frequently Asked Questions




2




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 we
b 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

................................
................................
................................
............................

20

Q: How do I see the results of a previous query?

................................
................................
........................

20

Q: How do I re
-
run a previous query?

................................
................................
................................
...........

21




3




i2b2 User Guide & Frequently Asked Questions

Q: How do I save a query?

................................
................................
................................
............................

21

Q: How do I create a new folder in my Workplace folder?

................................
................................
..........

21

Q: How do I re
-
run a saved query?

................................
................................
................................
...............

21

Q: Can Administrators see all queries?

................................
................................
................................
........

22

Q: Can I use the results of a previous query in a new query?

................................
................................
....

22

Tips and Tricks

................................
................................
................................
................................
..................

22

Q: What shou
ld I keep in mind when building queries?

................................
................................
.............

22

Useful Links:

................................
................................
................................
................................
......................

24








4

General Information



i2b2 User Guide & Frequently Asked Questions

General Information

Q:
What is
i2b2
?

i2b2 (
I
nformatics for
I
ntegrating
B
iology & the
B
edside) 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
-
frie
ndly, 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
pro
ject

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
in
consistent and
un
reliable results.

Q: What data is not in
Penn State He
rshey 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, note
s and other un
-
coded fields are

not be present in
the
current
i2b2

implementat
ion
.

Enhancements are anticipated and will be announced as they are
implemented.







5

Gener
al Information



i2b2 User Guide & Frequently Asked Questions


Q: Can individual patients be identified?

Hershey Medical Center

has access to 2 separate i2b2
project
s
: De
-
identified project
and Identified
project. Access is granted
by an Administrator, and most users will only have access to the de
-
identified project type.


Q: What level(s) of access are available?

In the
de
-
I
dentified project,

a user can be assigned to:

Obfuscated


Able to see only aggregated results, obscured furt
her 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
R
ecord
Numbers. The identified project is currently restricted to use by
honest broke
rs.


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

a
nd 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 ne
ed additional data elements

that are not in i2b2?

The Data Warehouse and Decision S
upport group has created a standard data set
(SDS)
that
includes

patient assess
ments (e.g. vitals, smoking/
alcohol use a
nd 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




6




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:
T
he Data War
ehouse group will f
irst re
-
run your

query in an identified
environment
to determine the corresponding encounter numbers (OOS)
. T
he 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 th
e 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 requi
rements

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 Train
ing session must be completed. S
ee HMC Clinical
and T
ranslational Institute
(CTSI) we
b 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 i2
b2 web client can

then

be accessed at the following address:

https://i2b2.cernerresearch.com/webclient/#

1.

Enter your Username

2.

Enter your password

3.

Leave “i2b2 Host” defaulted to: Cerner Research

4.

Cl
ick Login

5.

If prompted with the “Choose a Project” window, select the desired Project and click “Go”.








7

System Navigation (Web Client)



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 Q
uery 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 follo
wing 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 Gr
oups to “occur within the same
financial encounter” or to be treated independently from the other Groups (e.g. Group 1 and



8

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 Con
straint 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 ter
ms (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 o
ptions fo
r that
specific window. U
sers can adjust options like the sorting format for previous queries.

Clicking the
last icon will expand the window to its maximum size.











9

Term Search



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 likewi
se “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, t
he Ontol
ogy 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 u
se 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.





10

Query Building



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.








Yo
u 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;



11

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 th
e
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 late
st 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)
.




12

Query Bu
ilding



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 hyper
tension.


To build a
n

“Or”

query
, include the terms in the same group panel. For example, to query for females w
ho
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.







13

Query Building



i2b2 User Guide & Frequently Asked Questions

Q
:

How do I
use the “Dates” function?

In i2b2,
the “Dates” fu
nction 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 use
d for activities data, like

medicati
ons,
procedures and diagnoses

and to restrict the Visit Type (e.g. Inpatient) to a c
ertain time period.
.


Note:

R
eference 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 beg
inning 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 g
roup 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 a
n

Obstetrical Procedure since J
anuary 1, 2012.









14

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 gr
oup?

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 da
te 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
O
bstetrical
P
rocedure 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 quer
y is run, i2b2 will only
return patients
who have
at least two

Obstetrical Procedure
s
.







15

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 pati
ents 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 th
is 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.






16

Analysis Tools



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 cr
iteria


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

Connect
ed.

3.

If t
he 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 quer
y 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. T
o 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.




17

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 p
lug in that allows data to be exported based on a defined patient set. This
plug
-
in:



Offers different formats and levels of detail.



Optionally replaces patient IDs with ascending numbers.



Optionally adds a selection of demographic patient details.



Optional
ly resolves numerical concept codes into their underlying meaning
.



Optionally includes ontology path of concept codes.




18

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
c
oncepts
of interest
(Ontology Term
s)

onto the input boxes.

c.

C
lick the "View Results" tab to view
the table of the observations.


Usage Tips:

I.

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 observatio
n (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).

II.

Resolving concept/modifier codes

provides
additional detail on the underlying code
(e.g. Alcohol Withdr
awal, rather than simply ICD9 291.81), but takes a little more

processing time
.

III.

The default export CSV file encloses all data cells in quotation marks ("). This is
necessary to export special ch
aracters 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.

IV.

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.

V.

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



19

Analysis Tools



i2b2 User Guide & Frequently Asked Questions

size of 50, which will divide the d
ata 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.

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:






20

Saved and Previous Queries



i2b2 User Guide & Frequently Asked Questions




5.

Project Request 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 pr
evious 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 previous
ly 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?

Whi
le 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
-
click
ing

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 f
rom the Work
place 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




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 previously
-
execut
ed 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 fo
r 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 i
n a different group.
This allows you to drill further into previously
-
identified cohorts.

i2b2 Tips


Tips and Tricks

Q:
W
hat should I keep in mind w
hen 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)
an
swers 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 nece
ssarily 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 gen
der 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 “Obstetrica
l 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 i2
b2 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.
Dra
g 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 for
th. 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 qu
ery, 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

Useful Links:



i2b2 User Guide & Frequently Asked Questions

Useful Links:


1)

General i2b2 c
ommunity user information
https://community.i2b2.org/wiki/dashboard.action

2)

The PSH CTSI web site i2b2 section
http://ctsi.psu.edu/?page_id=37
06