6 Manage queries, gene sets and jobs in My Workspace

In this chapter you will learn how to:

What can I do in My Workspace?
Manage queries
Manage cohort lists
Manage gene sets
Administrate user groups
Schedule and monitor genomic data export jobs
Switch between Patient and Subject context

Note:

If you encounter issues resulting in Internet Explorer 11 incompatibility, see the Oracle® Healthcare Translational Research Installation Guide for upgrade instructions.

What can I do in My Workspace?

Figure 6-1 OHTR landing page and your workspace

The My Workspace page is the landing page for OHTR. Depending on the license purchased, you may have access to most or all of the sections on this web page. With a standalone OHTR license, you can only view the Cohort Queries and Cohort Lists details.

Besides managing queries, cohort lists, gene sets, user groups, and jobs, in here you can also get a constant overview of your work in the product. Your workspace features lists of your most recent items, shortcuts, queries and cohort lists.

To understand what you can see in every list, check the details below.

My recent items

This lists the most recent saved cohort query, cohort list, and gene set, which provides the quickest access to your recent work.

My queries

This lists the most recent saved patient cohort queries, sorted by the last updated date. Clicking the selected query will load it in the Cohort Query window.

Queries or lists shared with me

This lists all queries and lists that are shared with you. Clicking the selected query will load it in the Cohort Query window. Clicking the selected list will load it in the Cohort Viewer/Cohort List window.

My cohort lists

This lists the most recently saved cohort lists sorted by the last updated date. Clicking the selected list will load it in the Cohort Viewer/Cohort List window.

Queries or lists shared with all

This lists all public queries and lists. Clicking the selected query will load it in the Cohort Query window. Clicking the selected list will load it in the Cohort Viewer/Cohort List window.

My gene sets

The My Gene Sets section lists the most recently updated gene sets. Clicking the selected gene sets will load it in the Manage Gene Sets/Manage window.

Manage queries

What can I do here? In the Manage Queries tab, you can:

Search through saved queries.
View a list of queries, either created by or shared with you.
Modify queries.
Set or modify restrictions to available queries.

For information on modifying criteria for queries, inclusions and exclusions, see Chapter 2, "Modify criteria for queries using the Cohort Query".

Search for queries

On the Home page, click the Manage Queries tab.
In the Search My Queries section, select a condition and criteria for your search.
Example 6-1 Select the conditions and enter the criteria to search for queries
```
Query contains "cohort"
Privacy equals "shared"
Creation Date "On or Before" 21.05.2016
Last Update equals 23.07.2016 
 
```
Click Search.

To clear the search and enter new criteria, click Reset.

To view a query, select it from the table and click Load.

Modify queries

To change a query's name or description:

Select it from the My Queries list.
Click Edit and modify as needed.
Click Submit.

To change the privacy status of a query:

Select it from the My Queries list.
Change the access:
- Click Private to prevent anyone else from seeing or using the query.
- Click Shared with All to allow anyone to use the query.
- Click Shared to share a private query with a user or a group of users.
  
  If you chose Shared, follow the steps below.
  1. Click Add.
  2. Select a condition and enter part of a user name or a group name.
  3. Click Search.
  4. Select the user name or user group you want to include and click Add.
  5. Click Done.
  To share the query with multiple user groups, repeat the steps above before clicking Done.

Manage cohort lists

What can I do here? In the Manage Cohort Lists tab you can:

Search through available saved cohort lists.
View a list of cohorts, either created by or shared with you.
Modify cohort lists.
Set or modify restrictions to available queries.

Search and view your cohort lists

You can only search for cohort lists that you have access to.

On the Home page, click the Manage Cohort Lists tab.
In the Search my Cohort Lists section, select the conditions and enter the criteria to search for your saved cohort list.
Example 6-2 How to enter criteria to search for your saved cohort list
```
List Name equals "cohort" 
Privacy equals Private
Creation Date "On or Before" 21.05.2016Last Update equals 23.07.2016  
```
Click Search.

To clear the search and enter new search criteria, click Reset.

To view a cohort list, select it from the My Cohort Lists and click Load.

Modify cohort lists

You can modify your cohort lists in multiple ways, from editing their names to changing their privacy status.

To change a cohort list's name and description:

Select it from the My Cohort Lists section.
Click Edit.
Click Submit.

To change the privacy status of a cohort list:

Select it from the My Cohort Lists.
Change the access:

Click Private to prevent anyone else from accessing the list.
Click Shared with All to allow everyone to access the list.
Click Shared to share a private list.

If you chose Shared, follow the steps below.
1. Click Add.
2. Select a condition and enter part of a user name or a group name.
3. Click Search.
4. Select the user name or user group you want to include and click Add.
5. Click Done.
To share the cohort list with multiple users or user groups, repeat the steps above before clicking Done.

Manage gene sets

What are gene sets and what can I do in here? Gene set refers to groups or lists of genes. This set can consist of a couple of genes or hundreds of genes. This allows you to group genes into convenient collections for reuse. You can group a few genes for quick search retrieval or for use in a cohort query. In this tab, you can create, edit, and manage gene sets.

A few things to keep in mind about gene sets in OHTR:

There are no restrictions on genes that can be included in a gene set. You can mix genes from multiple species or assembly versions.
The same gene can be part of many different gene sets.
Gene sets are private and cannot be shared among users.
Gene set names are not case-sensitive.
When genes are compared using the Contains or Starts With option, the limit is 512 characters.

Create a new gene set

Along the top, click Manage Gene Sets and go to the Create New or Edit section.
Specify the genes you want to include in the gene set. This can be done in three ways:
- Type in Gene Names - Search for genes using their Ensembl or HUGO names. You can enter multiple gene names separated by space, comma or semicolon.
- Add from existing gene set - Search for genes based on an existing gene set.
- Upload from a file - Select a text file (CSV, TSV, TXT) from your computer where the genes are delimited by comma, space or tab. Click Choose File to browse for the file.
Note:
The file size limit is less than 5MB when genes are matched using Equals.
Select a value for Species.
Select an Assembly Version.
Click Submit. The matching genes appear in the Available Genes pane.
Use the arrow ( ) to move available genes to the Final Gene Set panel.

Use the double arrow ( ) to move all available genes to the Final Gene Set panel.

To remove genes from the Final Gene Set panel, use the Remove or Remove All buttons.
In the Save Gene Set section, enter the name and description of the gene set.
Click Submit.

Edit a gene set

To edit a gene set:

Along the top, click the Manage Gene Sets tab, and go to the Create New or Edit section.
Search for the gene set you want to edit using the Add from existing Gene Set option.
Select a value for Species.
Select an Assembly Version.
Click Submit. The gene set appears in the Available Genes pane.
Use the arrow( ) to move available genes to the Final Gene Set panel.

Use the double arrow ( ) to move all available genes to the Final Gene Set panel.

To remove genes, use the Remove or Remove All buttons.
Click Submit.

Note:

When you search genes using the Contains or Starts With option, the limit is 512 characters

Manage a gene set

To manage a gene set:

Click the Manage Gene Sets tab and go to the Manage section.
Enter the gene set you want to modify.
Click Submit.

To print the data, click Print on the top right.

To export the data in an.xls file, click Export.

To remove a gene set, click Delete Gene Set at the bottom.

Note:

When you delete a gene set, its record is still available in the database but it can only be restored by a system administrator.

Administrate user groups

Administrating user groups can be done directly from the OHTR UI.

To simplify sharing, create user groups and assign users to them. Instead of sharing queries or lists with each user individually, set up a list of users to share multiple items to multiple users at the same time.

Note:

Only the user that is the owner of a list can modify its members. However, any user can share any given lists with other groups and see members in other lists.

Create a user group

Navigate to Manage User Groups, User groups.
Click Create.
In the Create User Group window, enter a name and description.
Click Submit.

Assign users to a group

Immediately after you create a group

Navigate to Manage User Groups, Group has members.
Click Add.
In the Add Users window, enter the user names or search for them.
Select the names you want to add.
Click Add.
Click Done.

Search for a group you created earlier

Navigate to Manage User Groups, Search User Groups.
Enter the details of the group you want to find.
Click Search.
Navigate to Manage User Groups, Group has members.
Click Add.
Enter the user name you want to add and select them.
Click Add.
Click Done.

Remove users from a group

Navigate to Manage User Groups, Search User Groups.
Enter the details of the group you want to find.
Click Search. The user group and its details are displayed.
Navigate to Manage User Groups, Group has members.
Select the user you want to remove.
Click Remove.

Manage user groups

You can edit, duplicate or delete a user group using the buttons at the top of the User Groups section.

Go to Manage User Groups, Search User Groups.
Enter the details of the group you want to find.
Click Search.
Follow one of these steps:
- Click Edit to change the name and description of the user group.
- Click Duplicate to create a copy of a user group.
Click Submit.

Schedule and monitor genomic data export jobs

Currently, jobs are scheduled only for Genomic Data Export. To schedule a job, navigate to the Genomic Data Export screen in the Cohort Viewer tab.

Note:

Any job executed prior to applying OHTR 3.1 will have its status changed back to 'Scheduled'.

Select the patient IDs source from one of these options:
- active query
- library query
- list
- ad-hoc
- Omics query
Select the DNA reference version.
Select the location for the gene:
- Ad-hoc List
- Pathway
- Gene Set
Select one of the following file formats to export:
- Mutation-VCF
- Copy Number Variation-SEG
- Microarray Expression-RES
- Microarray Expression Dual Channel-GCT
Select the Schedule export option.
Click Submit.

To view job information and progress, go to the Home page, and click the Jobs tab, along the top. All the jobs created by the OHTR UI are displayed. All users who created jobs can see job lists.

Manage jobs

To search for a job:

On the Home page, along the top, click Jobs.
Scroll down, after the table, and either enter part of the job's name or click the search icon ( ).
In the Search User Job window, select the appropriate conditions and enter part of a User Job Run ID or a User Job Name.
Click Search.
Select the job you want to include in the list.
Click Submit.

To run that job, on the Jobs tab, click Submit again.

To view details of a particular job:

On the Jobs tab, in the first table column, click a job's name to get to the details of the job.

To return to the Jobs tab, click the Jobs breadcrumb link.

Figure 6-2 Location of the Jobs link

To get back to the initial list of jobs, click Reset.

View job inputs

To view details on the parameters provided when scheduling a job, in the Details page, click the Inputs button on the left.
To load the job details in the Genomic Data Export page, click the Load input parameter values into Genomic Data Export page link.

Note:
You can only load these input parameters, when the job context matches the application's context.

View and download job outputs

This section shows the result files of a job. The following files are generated:

Error log file contains the log file of the application if any exception or error occurred while running the job.
User log file contains the log file, which shows the error occurred while generating the export files.
Administrator log file is for the DB administrator.

To download any of these files, click the file link under the Files column.

You can download error and user log files, but cannot download the admin log file.

Note:

When you try to export a file that does not have any patients or subjects linked to the specimen, an empty file is generated in Schedule mode.

Switch between Patient and Subject context

OHTR can be run in either Patient or Study Subject context. In Patient context, all queries are directed at patient tables in the Cohort Data Model (CDM) schema, while in the Subject context, all queries are routed to the subject tables in the Cohort Data Model (CDM).

To change context, click either one of the buttons ( ), in the upper-right corner of the screen. By default, the context is set to Patient.
The new context is available until the next time you change it.
Switching context clears the data loaded in the Cohort Viewer tabs, but not the criteria of an active query in the Cohort Query screen. Only applicable criteria for the selected context is displayed.
Example 6-3
```
Encounter criteria is not supported in the Subject context and will be disabled. When you switch back to the Patient context, it is enabled again.
 
```
For a subject or a patient to be considered deleted and not visible for selection, a given subject or patient's delete flag in CDM should be set to Y.