Alpha 1 i2b2 User Guide

Transcription

1 Alpha 1 i2b2 User Guide About i2b2 Accessing i2b2 Data Available in i2b2 Navigating the Workbench Workbench Screen Layout Additional Workbench Features Creating and Running a Query Creating a Query Excluding Data/Date Ranges Running a Query/Types of Results Important Notes Regarding Queries Temporal Query Using the Plugin Analysis Tools Excel Export Demographic (1 Patient Set) Demographic (2 Patient Set) Timeline

2 About i2b2 The i2b2 program is an NIH funded collaborative of the National Center for Biomedical Computing based at Partners HealthCare System in Boston, MD. The i2b2 program has developed an informatics framework that enables clinical researchers to use existing clinical data for discovery research and facilitate the design of targeted therapies for individual patients with diseases having genetic origins. The final output is an open access database with de identified clinical data for the public to query. Accessing i2b2 The registry main page can be found at From here, if you click on CRC Research Portal you will be prompted to login to access i2b2 and other resources. To access i2b2 for the first time, you will need to register for the researcher portal on the alpha 1 registry website. Click Register for Portal Access and fill out the required information to register. You will receive an to authenticate your address once the completed form is submitted. After you have authenticated your , you should be able to login to i2b2 within an hour. CRC s will not gain REDCap access until their information is verified. Patients, outside researchers and other users will never be granted access to REDCap. Everytime you login to i2b2 you will be prompted to agree to the Data Usage Agreement. If you are a CRC or researcher and have already registered to access REDCap, then you will use that same login to access i2b2.

3 Data Available in i2b2 Below are the top level folders in the hierarchy of available terms that can be used in queries. There is also some additional descriptions underneath some of the bullets for clarification. Additional data from the REDCap surveys may become available in the future. Alpha 1 Genotype Biorepository Samples Available DNA Liver Biopsy Lung Biopsy Plasma RNA Serum Other Demographics Diagnostic History Liver Diseases Lung Diseases Other Diseases FEV1 Category Liver Function Lab tests that reflect liver function Lung Function Lab tests that reflect lung function (including historical visit lung function tests) Outcomes Charlson Comorbidity Index CAT Score SGRQ Score Transplant (lung and liver) and LVR (Lung Volume Reduction) Therapies Augmentation Oxygen Visit Type Baseline Follow Up (1 3) Historical Visit (Each patient can have a maximum of 5 historical visits and corresponding data entered) Vitals

4 Navigating the Workbench Workbench Screen Layout Once logged on, the i2b2 Query & Analysis Tool Workbench screen is displayed. The basic i2b2 workbench screen provides six panes for identifying, building and running queries. 1. Navigate Terms This is where you will locate search concepts using a hierarchical folder structure. 2. Find Terms In this pane, you can find search concepts using a representative word, phrase or specific code to describe the concept 3. Workplace Items in the Workplace SHARED folder are queries that are visible to other users with access to the same project. If you want to share a query with others in your group, drag the query to the SHARED folder. These queries won t be deleted. Items in the personal folder are individual queries that won t be deleted or shared with others. If you want to save a query for personal use, drag it to your personal folder. 4. Previous Queries Any query you execute will be saved in the Previous Queries section. The default name is built from the first characters for the items placed in the Group boxes. A user can overwrite the default name or rename after it s saved by right clicking. There is a limit

5 to how many items appear in the Previous Queries section. Only the most recent queries are visible in the Previous Queries section; older queries roll off. For long term saving of queries, drag them to the personal folder. You can right click and delete a previous query. You can change the Max Number of Queries to display by pressing the Set Options button and overwriting the default of Query Tool This is the main work area where you will define and refine the criteria for your query. To place query terms in this pane, drag and drop them from the navigating terms or searching terms boxes. Individual concepts or entire folders can be dragged and dropped with the exception of demographics (individual concepts must be selected when querying with demographic terms, not folder concepts). 6. Query Status The progress and results of queries can be seen in this pane. Additional Workbench Features Expanding Panes To expand the panes to a larger size, click the screen button on the top right corner of the pane. You can shrink the pane back to its normal size by clicking the same screen button again. Creating and Running a Query Creating a Query To create a query, drag and drop concept folders or individual concept into the query tool groups. Items in the same group will be treated as one or more of these are true while each group will be connected with an and with other groups.

6 In the below example, the query will return patients that have either an ALT OR AST lab test result AND a Bilirubin lab test result. Excluding Groups and Date Ranges To exclude certain groups of terms from being included in the query results click the exclude button on the top right corner of a group. To query data for a certain date range: 1. Click dates in the top left corner of a group 2. Change the dates to the range you would like to query on 3. Make sure to click on the checkboxes next to each date and click ok **Note For the entire query to represent a specific date range, the dates must be changed for each group

7 Editing a Query 1. To delete a term or folder from a group, right click on the icon to the left of the term and select Delete 2. To delete a whole group, click on the X on the upper right hand corner of the Group box. 3. To create a new Group, which will appear to the right of the existing Groups, click New Group. 4. To clear all search information that is currently in the Groups of the Query Tool pane, click Clear.

8 Running a Query When running a query there are four result type choices. More than one result type can be selected for each query and all of the results will be stored in subfolders in the previous query pane. 1. Patient Set a. Selects all of the patients that fit the query terms 2. Encounter Set a. Selects all of the encounters that fit the query terms 3. Number of Patients a. Produces the number of patients that fit the query terms 4. Timeline a. Starts the timeline plugin (more information on this plugin can be found in the plugin tool section of this document) with the query terms Results of the query will be shown in the query status pane below the query tool pane. Important Notes Regarding Queries 1. Demographics The age field searches for the patient s age today (at the time of the search) as opposed to the age at the time of the clinical encounter 2. If a query is taking a long time to run, it may time out. The default time allocated to a query is 180 seconds, or 3 minutes. To increase the amount of time that i2b2 will allow your query to run, you can change the option in the Query Tool panel. 3. To optimize the search time of a query, choose the most restrictive criteria as your first Group and move to increasingly broad categories as you move to the right.

9 Performing a Temporal Query The steps below serve as a reminder of the steps needed to set up a Temporal Query. Full instructions with pictures are available in the i2b2 User Guide available by pressing the Help button in the upper right section of the screen. 1. Change the Temporal Constraint from Treat all groups independently to Define sequence of events 2. A second entry appears with a drop down displaying the default selection of Population in which events occu r. Select your base set of patients. (If you don t provide a filter here, the entire patient population is used.) 3. Press the drop down arrow next to Population in which events occur and select Event 1. Define your Event Change drop down from Event 1 to Event 2. (optional step and you can add events if you need more than two) 5. Change drop down from Event # to Define order of events. A new set of columns appear allowing you to define the rules related to the events. 6. Press the Run Query button. 7. Temporal queries have a (t) in front of the name in the Previous Queries panel.

10 Using Plugin Tools Please be aware that screenshots from this section are not representative of Alpha1 i2b2 but the same steps can be taken to use the plugins. Note: When running a query, select the patient set option in the Run Query pop up box to produce a patient set necessary to use plugins. Access the plugins page by clicking Analysis Tools in the top right hand corner of the screen. Select desired plugin from the Plugins field at the bottom of the screen. The Tabs: Select the Specify Data tab to provide input. To locate your patient set(s), expand your query folder under Previous Queries in the lower left hand corner, expand the results folder, and drag the patient set into the appropriate box. If you do not have a patient set, see the Note above. Drag and drop one or more concepts (ontology terms) from the Navigate Terms field into the concepts input box, when applicable. Select the View Results tab to see results. Select the Plugin Help tab for more detailed information about the plugin. ExportXLS This plugin creates a table of user selected concepts as they are observed on a user selected set of de identified patients, with the option to download the resulting table as a file. For more information, see Instructions for Use: 1. Follow the instructions under the Specify Data tab. Drag and drop a patient set and one or more concepts into the input boxes. Note: It is important to specify a subset of the patient set to use if your query contains thousands of patients and/or lots of concepts. This can overwhelm the server (i2b2 hive) and cause it to fail, resulting in no result returned. The 'Number of Patients contains all patients by default. If you would like to split up a group of 1000 patients, you may first specify 500 with Starting Patient 1, then 500 more starting with 501, for example. Specify a Query Subgroup Size, generally 20 to 50, to break a patient set into smaller subgroups to be run individually before being recombined. For more information, click the Help button next to the input boxes.

11 2. Navigate to the "Output Options" tab to select the output format and options. For more detailed descriptions, see the Plugin Help tab. Resolve Concept/Modifier Codes outputs the denotations of concept codes. For example, male gender will be displayed in the table as Male [DEM SEX:m] instead of DEM SEX:m. Include Ontology Path of Concepts outputs the ontology path to the concept code. For example, a male gender concept code in Demo displays as [\\i2b2_demo\i2b2\demographics\gender\male\dem SEX:m] instead of [DEM SEX:m]. Note: Checking 'Resolve Concept/Modifier Codes' and/or Include Ontology Path of Concepts will require massive database querying and can therefore cause a very long running time or crash. Select these options only when you are no longer varying your query and are ready to export your dataset. Note: The default export CSV file encloses all data cells in quotation marks ("), which can confuse some statistics software. Check the 'Exclude CSV Cell Delimiter (") Where Possible' box to resolve this. Cells with special characters will still be enclosed in quotation marks and will have to be removed manually. 3. Finally, select the "View Results" tab. The button will download a comma separated values file named 'i2b2 export_patient observations_[timestamp].csv' onto your desktop. The button will download an HTML encoded file named 'i2b2 export_patient observations_[timestamp].html.xls' that can be directly opened in Excel. If you wish to open it in a web browser, simply remove the '.xls' suffix. Example Result Table

12 Demographics (1 Patient Set) Simple Counts This plugin displays demographic information about a patient set across several different categories, including age, sex, race, language, religion, and vital status(vital status only covers patients who died at the hospital at any given time). Sample output: Instructions for Use: 1. Follow the instructions under the Specify Data tab. Drag and drop a small* patient set into the input box. * A patient set of 1000 ran in under 1 second with no issues. 2. Select the "View Results" tab to retrieve demographic details, including a patient count and the values, number of patients, and histogram representation for each demographic category. Demographics (2 Patient Sets) Simple Counts This plugin provides the same output as the Demographics 1 plugin above, but in the form of a comparison between two patient sets. Patient Set 1 is always shown in pink while patient set 2 is shown in green.

13 Sample output: Instructions for Use: 1. Follow the instructions under the Specify Data tab. Drag and drop two small patient sets into the input box. 2. Select the "View Results" tab to retrieve demographic details, including a patient count and the values, number of patients, and histogram representation for each demographic category. A description on how to read the results is provided. Timeline This plugin displays patient data on a graphical timeline, creating a visual representation of when selected concepts are observed within a given patient set. Instructions for Use: 1. Follow the instructions under the Specify Data tab. Drag and drop a small patient set and one or more concepts into the input boxes. Each instance of the concepts will be shown on the timeline for each patient in the patient set. 2. Select the "View Results" tab to create the timeline. The first ten patients are shown by default. Adjust which patients are shown using the arrows in the top left corner or the start and size boxes, specifying how many patients to display starting with which patient number.

14 Displaying many patients at once will take longer than scrolling through several pages of patients. The time scale at the top of the timeline indicates the start and end range of data being shown. Use the zoom and pan buttons at the top right to change the visible date range. Click on a mark on the timeline to bring up the Observation Details for that specific event, including the event ID, patient ID, concept ID, observer ID, start date, and time value character. Timeline Output Example