User documentation

Welcome to the Glowing Bear user documentation. If you are a new user looking for a short introduction, you can visit our quick start guide.

More detailed information can be found below.

Table of contents

Left panel

The left panel contains information about the Ontology tree, Cohorts saved in the database and their Variables.

Ontology tree

The ontology tree shows a hierarchy of data items that are available for your user. It contains concepts and studies and the number of subjects that have information for them. This tree is created when the data set is loaded into the database and the data items are not necessarily limited to existing terminologies. Each node in the tree is either a folder, or one of the node types listed below. The number of subjects that have at least one observation for a specific variable is appended to the label. The nodes in the tree can be dragged into the right panel to compose criteria that define the group of subjects. Dragging one of the nodes automatically adds a criterion to the builder for the concept and/or study that is associated with this tree node. The concept criteria can be further specified to precisely compose your queries.

More details on subject selection can be found further down.

For some nodes, additional information is available when hovering over the label. This is indicated by an ⓘ information icon.

The search box in this panel allows you to search in the tree. Nodes that match the search string will be highlighted and opened for convenient access. Note that if there are too many search results, not all nodes will be opened, but the number of total results found is displayed below the search box.

Cohorts

Cohorts you’ve created previously can be seen and restored from here. This is convenient if you frequently require information about the same (updated) group of subjects. The first cohort in the list is named currently editing. This shows the result of the user actions during data selection in the right window. When you click on a cohort name you can quickly visualise the number of subjects above the search box in this panel. If multiple cohorts are selected the number of subjects visualised is the union of the cohorts selected. However, be aware that if the cohorts contain overlapping subjects, these will be counted only one time. Next to the cohorts name there are several buttons that allow the following actions:

If you have previously downloaded a cohort, or received a file with a cohort query from a colleague, you can use the Import button to add this cohort to your list of saved cohorts. A cohort query file is specially formatted and is not meant to be created or edited by hand.

Cohort subscription for subjects and samples

Note: this feature is available to users on request.

By subscribing yourself to a saved cohort you will receive an email when there are new subjects or samples found for the specified criteria. Any time new data is loaded, Glowing Bear will check whether you have access to any of the new subjects and samples information and notify about the changes. If you expand the cohort box you will find below the cohort details, an additional button: “Show subscription records”. Clicking on this button you can check if there are any changes of the data related to the cohort saved. In particular the time and the IDs of items changed are reported

Variables

The Variable panel shows the variables selected by the users’ actions during cohort selection. When opening or refreshing the page all the subjects of the dataset will be selected by default, meaning that in this panel all the variables are shown. The variables can be displayed in two ways: Tree view and Category view. Switching between the two views you can either opt for a hierarchical visualization of the variables or a plain list, respectively. This panel is present across the different windows: cohort selection, analysis and data export. The variables shown can be dragged and dropped or selected ( in the case of the data export window) for the specific window purpose. A search box is also present, allowing to look for a specific variable either in the tree or the categorise view.

Right Panel

The right panel provides the main user functionality to interact with the database: Cohort selection, Analysis, and Data Export.

Cohort selection

Once you are familiar with Glowing Bear you would start here to select criteria to create a data set that you want to use within the application. In the Cohort Selection panel the total subject counts of the database is shown by default in Summary. It is important to know that after choosing the desired criteria and requesting updated counts with the Update cohort button, the displayed counts in the Summary line reflect that particular part of the data selection. el.

Select a group of subjects

Glowing Bear Step 1 image

You can select the group of subjects you are interested in three ways: by dragging nodes from the tree on the left, into add criteria box, typing into that box, or selecting them from a drop-down menu. Dragging tree nodes automatically adds constraints for a concept and/or study, e.g. Subjects with any value for '/Demographics/Gender'. If you choose the drop-down menu option you can select the following options:

Note: adding no criteria in add criteria box selects everyone in the database.

Extended query to custom subject dimension types

A cohort is created by selecting the variables of interest connected to a patient such as: gender, age, diagnosis, treatment, et cetera. Retrieving from the database, the information specifically contained in the so called “subject dimension type” for the patients. However, now you can choose to customize the subject dimension type to the needs and requirements of any given hospital, research institution or life science organization. Allowing the selection of a cohort, based on other subject information than patients. For example, in the box below the Summary subject counts, a drop-down menu shows the current available subject dimension options, such as: Patient, Diagnosis ID, Biosources ID, Biomaterials ID, and Images ID. This extension allows users to retrieve specific information on the selected dimensions independently from the others.

Glowing Bear dimension type

Group constraint creation

You can click on the + of the empty add criterion-box, to create a group constraint that allow you to build a more articulate and complex query. A complex query can be visualised as a series of constraints linked with and/or logic, and it can be imagined as a mathematical expression with parentheses. Those parenthesis are displayed with different range of blue vertical lines on the left side of the constraint boxes.

An example of a complex query sentence:

Give me all patients in the dataset that are female and were born between 1992 and 1997, and that have RNA or DNA biomaterials.

The translation to mathematical expression with parentheses:

Give me all Patients = [(female) AND (born between 1992 and 1997)] AND [(RNA) OR (DNA) biomaterials

The visualization of the complex query in the user interface of the cohort selection panel:

Glowing Bear complex query

Observation level versus subject level constraints

The Glowing Bear query builder is flexible in the different constraint composition types it supports. In order to fully understand the query that is composed, you should know that every observation is not simply a field in a flat text file where the row indicates the subject and the column variable. Each observation has in fact a number of dimensions that provide additional context to this particular value. The most common dimensions are: patient, concept, study, trial visit, and start date. In the query builder it is both possible to create criteria that will apply to a single observation, and to a subject. For example, Subjects with the value 'Male' for the '/Demographics/Gender' only makes sense if both Male and /Demographics/Gender apply to the same observation. On the other hand, if we are looking for males with an elevated heart rate, you want to look for subjects for which the database has at least two observations, (1) one that says they are male, and (2) one that indicates they have an elevated heart rate. Glowing Bear clearly distinguishes the two. Any criteria within a single query box apply to the observation level and anything that combines the query boxes applies to the subject level.

Inclusion/Exclusion icon

Glowing Bear icon incl

Glowing Bear icon excl

In Glowing Bear you can specify if you want to exclude a criteria, switching the included/excluded icon on the right side of the constraint box. Moreover, it is not possible to select anyone you do not have any information on.

Analysis

Glowing Bear Analysis image

The Analysis tab now presents you a cross table functionality. You can drag any categorical variables from the Current data selection panel into the vertical and horizontal drop zone to create a cross table with subject counts.

Creating the cross table with any other node type is currently not supported.

Data Export

Select variable of interest

Glowing Bear variable_selection image

The Data Export tab allows you to select and visualize in a data table the data that you want to export. You can select the variables of interest by checking the boxes of the variables views in the Left panel. At this point you can choose either to first visualise and adjust the variables in the data table or export directly the data.

Import criteria in the Variable panel

Note: the Import criteria button can currently only be used in specific cases and is not meant for general use.

Data table

Glowing Bear datatable image

The internal data model for Glowing Bear is not suitable for representation in rows and columns based systems like Excel, without first specifying how to reduce the dimensionality of the longitudinal properties of the data. This step not only allows you to specify the format of the selected data, but you can also directly view it. You can use the data table by first retrieving all dimensions that apply to your selected data, by pressing the Update button. These dimensions will all be shown in the dimension director. The two lists determine whether dimensions will show in the horizontal or vertical axis of the table. You can move dimensions between the two list and change the order based on what your preferred view on the data is. In this simple example we have all applicable dimensions in the vertical axis on the left and on the right we have the concept dimension in the horizontal axis. After making changes to the dimension director, you need to press Update to retrieve your updated view on the data. This view will also be stored alongside your current data selection so that the export you make is of the same shape.

Note: dimensions other than the standard dimensions cannot be moved to the vertical axis currently.

New and recents exports

Glowing Bear export image

The Export tab allows you to specify a name. This name has to be unique across the entire application not just for your user account. After choosing a name and pressing Create export, Glowing Bear will create a downloadable .zip file with all the data selected during data selection.

Included in the export is the main data file, called data.tsv and an additional file for each dimension that applies to this particular data set. The main data file is shaped in the way you have configured the data table, otherwise the default representation is used. The additional files contain the information known about each dimension element in your data set.

Finally, it is now possible to select subjects groups both under the Cohort Selection tab and under the Data Export tab, using the saved cohorts panel on the left side. This creates a more streamlined workflow for experienced users, as they can skip the first page and don’t need to switch tabs when selecting and exporting subjects cohorts.

Glossary

Common terms explained:

Friends of Glowing Bear

transmart components overview

In a typical deployment you use KeyCloak to manage user accounts and access rights to both Glowing Bear and tranSMART. The image above quickly details the role of these three components.

KeyCloak configuration

This documentation will explain for an admin how to create a user, define roles needed to grant access, assign roles to grant access, set password policies and look at the event logs.

Note: The official KeyCloak documentation is available here and for a server admin here.

Studies and user access

In tranSMART all data is associated with a study and all user access permissions are associated with a specific study. A user can be assigned one of two study access levels to a private study:

Alternatively, it is possible for a study to be added to the database as a public study, this means anyone with access to tranSMART has measurement access to its data.

A user with the role ROLE_ADMIN is able to access studies as if they were public. This user is also able to perform administrative requests necessary after data loading or after the server application restarts.

Assigning users to study roles

This is for KeyCloak administrators only!

Creating a study role

In order to give users access to studies in tranSMART, you should first create the role according to the convention that tranSMART requires. A role name should combine the study identifier and access level, separated by the pipe | symbol, ie. <STUDY_ID>|<ACCESS_LEVEL>.

To add a role go to Clients under the Configure option in the menu.

KeyCloak Clients

Next click on the client to which the role should be added, in this case the transmart-client. In the client configuration window go to the Roles tab near the top of the screen. Click Add Role at the top right of the table displayed on screen.

KeyCloak Roles

Define the role name according to the convention mentioned above. Here we define the measurement access level role for the GSE8581 study by creating the role GSE8581|MEASUREMENTS. The description is not used outside of the KeyCloak interface and can be left empty.

KeyCloak Role add

The new role is now added to the list of possible roles that can be assigned to users.

Note: these roles can be programmatically created by the Python client.

Add role to user

To add a user to a role go to Users in the left panel, then select the users you want to give permission and open the Role Mappings tab. In the section Client Roles select transmart-client and give this user the assigned role.

KeyCloak Role assign

Python client for programmatic access

Because Glowing Bear connects to tranSMART exclusively via a publicly available API, it is also possible to import data directly into your analytical environment.

A Python client for the API can be found here. Check also the API tutorial with Python and Jupyter notebook.