ACT i2b2 Plug-Ins 1.1 User Guide

ACT i2b2 Plug-Ins User Guide

For Version 1.1 Plugins, Document updated: February 14, 2017
Latest guides can be found at: http://community.i2b2.org/wiki/display/ACT/
 

Introduction

As part of ACT Aim 3, three i2b2 web client plugins have been developed. While Shrine allows ACT users run a query over the ACT network and receive aggregated patient count from other sites, the i2b2 plugins help the users to review actual patient data at a local site level for recruitment. The plugins facilitate finding original flagged SHRINE queries from within ACT i2b2 web-client, reviewing and selecting patients based on SHRINE queries, and finally exporting a list of i2b2 numbers of selected patients of interest for clinical trials. These plugins are tools meant to assist local ACT sites to identify patient cohorts for ACT clinical trials. Version 1.1 plugins are as follows:

1. SHRINE to i2b2 Connector
2. Patient Table Reviewer
3. Patient List Exporter

At present, the ACT i2b2 plugins support two different workflows:

1. Self-service workflow, and
2. Concierge workflow

The self-service workflow enables users to utilize SHRINE to i2b2 Connector plugin to review the original SHRINE queries, and then use Patient Set Viewer plugin to retrieve patient data.

In the concierge workflow , users will use the SHRINE to i2b2 Connector and Patient List Exporter plugins to download the local patients list for a SHRINE query. The patient list obtained then can be used by an institution’s local concierge service to retrieve further patient identifiers for review.

i2b2 users need the following roles to be able to use these plugins:

Usage guidelines

Below are some guidelines to utilize ACT i2b2 plugins

1. How to use “SHRINE to i2b2 Connector” plugin

This plugin displays all flagged queries that were executed on ACT SHRINE network, inside the ACT i2b2 web-client. Users will be able to view any of the SHRINE queries and run them locally in their local i2b2 web-client.

An ACT site is required to be connected to SHRINE network to use this plugin. User should create and flag a SHRINE query using their SHRINE web-client to proceed with the test. To create a SHRINE query, drag and drop the “Antihistamines” folder from “ACT Medications” ontology into the query tool panel of the SHRINE client.

Name it “Antihistamines Test” + [YourSite]

Example : “Antihistamines Test Partners” or “Antihistamines Test PHS” for Partners Healthcare.

Pick a query topic and run the query.

Once the query is completed, flag the query in the SHRINE client

After the SHRINE query is flagged, log into your local ACT i2b2 web-client and proceed with the following steps:

a)      Select “Analysis Tools” from the menu bar on top right of the local i2b2 web-client and click the “Shrine to i2b2 Connector” plugin. This will display all flagged SHRINE queries executed by different sites on the ACT network inside the “SHRINE to i2b2 Connector” panel. Identify the SHRINE query that you have executed.

b)      View the SHRINE query in local i2b2 web-client by clicking on associated “View & Run” button

c)      Run the SHRINE query in local i2b2 by clicking on “ Run Query“ button in the Query Tool panel, name it “Antihistamines Test [YourSite] Local” (e.g.  Antihistamines Test Partners Local). Select “Patient Set” when you run it. This way the Shrine query is converted into a local ACT i2b2 query with a patient set.

2. How to use “Patient Table Reviewer” Plugin

This plugin enables users to review individual patients by looking at their data in a table.  There is an on-screen tutorial available by clicking the Tutorial link on the top right of the Plugin window.

a)      Load the plugin “Review Table of Patients” from the “Analysis Tools” tab on the menu bar:

b)      Find the query “Antihistamines Test [YourSite] Local” in the Previous Query panel on bottom left of the query tool (e.g.  Antihistamines Test Partners Local)

c)      Drag and drop the query from Previous Query panel into the “Patient(s)” input box in the

“Create Patient Table to Review” section

d)      Make sure that the concepts from the dropped previous query have been populated below the “Concept(s)” box

e)      Drag and drop additional concepts from the Ontology (Navigate Terms panel on top left) into the “Concept(s)” input box in the “Select Patients and Concepts to view” section (Optional)

f)        Change aggregation option for any of the concepts (Optional). There are multiple aggregation options available in the plugin that are listed in Table 1.1 .  This is the way of defining the table structure for patient data.

g)      After the query is selected and the patient data table structure is defined, you can either download a complete table of data for all patients in the query for future review and selection, or can review the patients real-time and select for trials.

h)      To download patient data table, click on “Download patient table as CSV file” and then click on “Download Patient Table(CSV)” button. This brings the user to “Download Status” tab and displays the state of download on screen

User doesn’t need to be logged into i2b2 web-client for the download to finish. Once a job starts, it keeps working in the background. So, users can log back in later and use the “History” tab of the plugin to download the patient data

i)        To review patients real-time, click on the “View table of patients”. This brings patients data on the screen in the pre-defined table format

j)        To save patients for clinical trials you should select a workplace folder. To select a workplace folder, click on “Designate a Workplace folder” and then drag an existing folder from left side “Workplace” panel into the “Selected Folder” box on the right-hand side.

To create a new workplace folder, right click on an existing folder in the Workplace panel and then choose “New Folder” option. Give a name to the folder Test _[YourSite] (eg. Test_Partners)

To save any patients of interest check off the corresponding box to the left in the patient table row in “View Table of Patient” section.  Selected patients will appear in your workplace folder on the left side of the query tool. Patients can be also unselected from the table.

3. How to use “Patient List Exporter” plugin

This plugin allows users to download patient i2b2 numbers either from a workplace folder or from a previous query.

To download patients from a workplace folder:

a)      Load the plugin from “Analysis Tools” menu

b)      Explore the Workplace panel on the left and find a folder that has patients saved in it. Drag the folder to right hand side into the Patient List Exporter panel and drop into Workplace Folder(s) box.

c)      Download a csv file of the i2b2 numbers of the patients in the selected workplace folder by clicking on the “Download Patient List” button

To download patients from a previous query:

a)      Load the plugin from Analysis Tools menu

b)      Drag and drop your previous query “Antihistamines Test [YourSite] Local” from Previous Query panel on the bottom left of the web-client into the “Your Previous Query” input box of the plugin on right

c)      Click on the “Download Patient List” button to download a csv file with the i2b2 patient numbers of all patients in the patient set. Check that the patient numbers in the query patient set and the downloaded file match each other.

Table 1.1: Available Aggregates