Overview¶

The Subject Viewer allows you to view subject data in various layouts. This data may include procedures, medications, omics data, documents, images, survey results and more, as graphs and in tables. Its accessed by clicking anywhere within the row of a subject in the Subjects tab (as shown in the clip below). The data displayed on the Subject Viewer page will depend on the layout selected.

Subject Viewer Header¶

The blue header at the top of the page (shown above) by default includes:

• Breadcrumb path of users location in PHC: Project Name/Current Tab/Subject
• to access and update the subject's demographics
• to select your layout from the dropdown
• to edit Layout
• to access Omics Explorer

The header can be configured to include more information about the subject and data can be displayed or available in a dropdown format (to reduce clutter and save space). This information often comes from the subject's medical record but can come from other sources as long as it’s tagged appropriately to make them accessible.

Add Header Data¶

Users with the layoutAdmin ABAC access have access to and the ability to add and modify what data is displayed in the page header.

The clip below demonstrates how to add data to the header.

How to Add Header Data:

1. Click the Header Data button (if you do not see this button, try clicking on the layout icon in the header )

   

2. Add data fields to be displayed in the Header or Dropdown by clicking on the tab desired in the window that opens

3. Click the + Add Field button
4. Select the field from the dropdown
5. Edit the label (optional)
6. To switch the field to Header or Dropdown, click the Move Field to Header/Dropdown button
7. Click Apply to commit changes

Header Settings¶

The Header Settings is where users can adjust what data is seen and located within the header/header dropdown.

To Adjust Header Fields:

1. Click the Header Data button (if you do not see this button, try clicking on the layout icon in the header )

   

2. Click on either the Header tab or Dropdown tab (see image below) to adjust the fields there.

   

3. Edit Header fields (see image above):

   • Move a field up or down: Move a field up or down in the display (as shown in the image above) is done by clicking the up or down arrow beside the field.
   • Delete a Field: Clicking the "x" deletes a field.
   • Move Field to Dropdown/Header: Clicking this button will move the field you select to the other location (either dropdown or header).
   • Add a Field: Clicking + Add a Field lets you add more fields to be displayed.
4. Click Apply to save changes.

If in masked mode (icon to toggle this on and off is found on the top right of the page, above the header), identifying data (such as DOB and name) is altered to a more vague display (such as birth year and initials).

Timeline Slider¶

A timeline slider is situated at the top of the Subject Viewer page. It dictates the timeline for everything in the view. A default time range can be set and is specific to the layout you are viewing. Whenever you open any subject, it will show this default timeline you've set.

The timeline slider can be adjusted by grabbing a handle and pulling it to show the time range you are seeking. If you grab the handle and drag it all the way to the left, it will show about 30% more of the subject's timeline. This can be repeated to widen your view. The clip below shows this in action as the Cancer Outcome Dates table updates as we expand the timeline.

To the right of the timeline (also shown in clip below) are two icons to return you to common views:

• Maximize Date Range - shows everything since the subject's DOB
• Reset to Default Date Range - returns to the preset date range

You can also adjust the time range you view by zooming in on the graph. This is done by hovering your cursor on the graph, clicking the zoom tool (which is selected by default) on the graph, then click and drag the cursor to dictate the time range you wish to zoom on as shown in the clip below.

Layouts¶

A layout is a page comprised of the header section and various modules (tables/graphs) displaying subject data. Layouts can be customized to show the data your most interested in viewing. A project can have multiple layouts which users can select from the dropdown menu in the header.

You can easily add common layouts from the PHC library to your project. Or you can create a custom layout.

Add a Layout¶

How to Add the First Layout to a Project:

1. Navigate to the Manage Layouts page:

   • If this is the first layout in the project: In Subject Viewer, click Create Layout in the blue header to open the Manage Layouts page.

     

   • For adding an additional layout to a project: Click on the Layout dropdown and click Manage Layouts .

     

2. Once in the Manage Layouts page, click to open the Add a Layout page (shown below).

   

3. Select from a prebuilt layout or craft a new layout:

   • Prebuilt Layout:
     1. Click on Layout Library tab.
     2. Scroll through available layouts or use the Search Library search box.
     3. In the layout row you wish to add, click on the (far right of the row).

   • Create a New Layout (this gives you a blank layout where you can add modules):

     1. Click on Create a New Layout tab.

        

     2. Give the Layout a name and description (optional), then click Create Layout.

     3. You'll return to the Manage Layouts page where you can see your new layout. On this page you can also:

        • Select which layout is default.
        • Add another layout by clicking .

        

     4. Click Done to return to the Subject Viewer page.

Layout Edits¶

You can access the Layout Edit tools by clicking the Layout icon .

The tools available include:

• - Allow subjects to view this layout - This toggle will either let subjects view this layout when they are in the PHC or prevent them from viewing it.

• - Raw Edit: Here you can view and copy the JSON code of the current layout. This is helpful if you want to copy a complex layout you created in one project and place a copy of it in another project.

  1. Click the Raw Edit .
  2. Click the Copy to Clipboard button at the bottom of the screen with the JSON code.
  3. Click the "X" in the top right corner of the JSON code screen to leave that screen.
  4. Click to a different layout or a layout in a different project.
  5. Click the Raw Edit in this current layout.
  6. Select all the code on the screen(to delete existing layout) or add the copied layout to an existing layout by clicking the screen in the location you want to add the new layout.
  7. Paste the code onto the page using Ctrl+V (Windows) or Cmd+V (Mac).
  8. Click Save at the bottom of the screen.
  9. It will take you to the Layout Dashboard and will apply any data in the current project that applies to the newly added layout modules.

• - Clear - This clears your entire subject viewer dashboard.

• - Save Changes - This saves any changes you've made to the existing layout.
• - Cancel - This cancels anything you've added since your last save and takes you out of the Edit Layout menu.

Modules¶

Modules are the graphs and tables that make up a layout. The two types of modules are tables and graphs. Data in tables is similar to the data displayed in a graph, the one difference is that tables can be configured to not respect the date range; instead, they show all records regardless of the date recorded. Tables are configured to display the most recent records.

THe PHC has some common modules available in a library for easy adding to your project. Or users can create a custom module.

Add a Module to a Layout¶

1. On the Subject Viewer page, be sure the layout you wish to customize is selected in the layout dropdown (if it isn't, select it).
2. Click the icon beside the layout name to enter the layout editing.
3. Add a module by clicking the within the purple circle at the bottom right of the page.

4. On the Add a Module page that opens select between:

   • Existing Modules

     1. Click on Library tab.
     2. Scroll through available modules or use the Search Library search box.
     3. In the module row you wish to add, click on the (far right of the row).
     4. Continue adding modules or if you are done, click the in the top right-hand corner of the page.

     

   • Build Your Own Module - Current modules available are shown in the image below. Once you click on a module, it will add it to your Subject Viewer and you will be in edit mode, where you can set the parameters for the data displayed in your module (parameters vary based on module).

     

Module Tools¶

Each module in Subject Viewer has two tools available at the top of the module:

• Collapse module or Expand module.
• Opens the module in full screen.

To access more Module tools:

Click the icon in the header to enter Layout Edit. Now each module has the following tools in the top right corner of the module:

• Copy to current layout or copy to a different layout (if this is selected the current layout will be saved).
• Open module in a full screen window (once open, click the "x" to exit the view).
• Edit the module settings (options available vary based on module):
  1. Go to the module you wish to edit and click the Edit Module icon in the top right corner of the module.
  2. Adjust the module settings in the window that opens.
  3. Click Apply to build your chart in the layout.
  4. When you are satisfied with your chart, click the save changes icon in the blue header to save your changes.
• Collapse module or Expand module:
  1. Each table/graph can be collapsed by clicking the icon in the top right corner of the table/graph or expanded .
  2. Click the save changes icon in the blue header to save your changes. This will now be the view by default, however, users can still expand and collapse each table/graph in Subject Viewer.
• Delete module:
  1. Click the in the top right corner of the module you want to remove.
  2. Click save changes icon in the blue header to save your changes.

Move and Resize Modules¶

Each module can be relocated or resized within the layout with ease using a handle or grip.

Move a Module¶

Each module has a series of dots at the top that act as a handle.

1. Be sure you are in Layout Edit, by clicking the Edit Layout icon in the blue header.
2. Click and hold the handle to drag and drop your module anywhere in your layout.
3. Click save changes icon in the blue header to save your changes.

Resize a Module¶

Each module has a resizing handle (a triangle of dots) in the bottom right corner, allowing you to adjust the size of your module.

1. Be sure you are in Layout Edit, by clicking the Edit Layout icon in the blue header.
2. Click and hold the resizing handle as you stretch or shrink the module to the desired size.
3. Click save changes icon in the blue header to save your changes.

Graphs¶

Graphs are a type of module that allow you to visualize subject data. PHC uses Plotly for graphing data in the PHC.

The data displayed is influenced by the timeline slider at the top of the Subject Viewer page. You also can zoom in on a set of data points by hovering your cursor on the graph to access the Mode Bar tools Plotly graphs have to offer, then selecting the Zoom tool, and clicking and dragging to capture the points you wish to zoom in on.

Graphs can be configured to show all procedures, observations, and other events or show some selection of them.

Reading the Graph¶

Graphs have a legend to the right of them, defining what each colored trace or marker represents. These can be toggled on or off by clicking on the trace in the legend (if the layout is saved by clicking the in the header, it will save the graph trace configuration as default). Trace colors and color palettes can be specified; but a color cannot be explicitly tied to a data series. Marker shapes for data points can also be specified.

How to Change Trace Color or Data Point Marker:

1. Be sure you are in Layout Edit, by clicking the in the blue header.
2. Click on the module settings icon . Under Trace Style, click on the color picker to adjust the trace color and marker color (see image below).

3. Select a marker shape from the Marker Shape dropdown (see image below).

   

You can also adjust the smoothing of the graph line in the module settings as shown below.

Single events (such as a single dose of medication or a single procedure) are noted on the graph with a single data point. Hovering your cursor on a data point displays more information for that data entry.

Non-quantitative data, such as a diagnosis or medication, is graphed with no y-axis (see top graph in the image below). Events that occur over time (such as a medication taken for a few weeks) will appear as a range.

Quantitative data, such as weight or creatinine, has a y-axis (see bottom graph in the image below).

A graph can contain both non-quantitative and quantitative data types. In the clip below, the non-quantitative data (cancer medication) is displayed as ranges but we can enable shading (colored column) for easier viewing of how medication may correlate to various blood levels.

To enable graph shading:

1. Enter Layout Edit (click in the header)
2. On the module you wish to add the shading, click the edit icon
3. For the data you wish to add shading, click the beside that data name
4. Check the Enable Visual Shading checkbox
5. Click Apply in the top of the module settings

Stacked or Layered Graphs¶

Layered Graphs (see image below) are where different data traces share the same graph, intersecting and overlapping with each other.

Data traces set as swimlanes (shown in image above) are always displayed at the top of both layered and stacked types of graphs.

Stacked graphs (see image below) are where different data traces share the same graph but have their own space along the y-axis, not intersecting or overlapping with other traces.

In a stacked graph, Graph tools only work on the trace you are using the tool on, other traces are not impacted.

Trace Reference Range¶

The trace reference range (represented as two red dotted lines shown in the temperature trace in the image above) is a trace level setting and marks the upper and lower limits of normal for that trace. If these values are provided, clicking the checkbox for "Graph with Reference Values?" will configure it to display upper and lower limits of normal (as shown in the image below).

This range can be configured within the layout, allowing the user to dictate what those values are, or the range can come from the FHIR resources (if they are there).

Reference ranges may disappear upon zooming in on the graph.

If the value exceeds the normal range, the data marker shape will be changed to display an arrow up or an arrow down.

Graph Tools¶

Each Graph has two tools at the top right of the module:

• Full Screen - opens the graph as a full screen
• Collapse - collapses the graph from view

Plotly graphs in the PHC have a mode bar of tools to improve the ease of viewing the displayed data (shown below).

Mode bar graph tools include:

1. Download plot as a PNG
2. Zoom - Zooming can be performed vertically and horizontally. If graphs are stacked, only the one you zoomed in will change. When graphs are layered, all will zoom in. Double clicking within the part you zoomed will reset the vertical
3. Pan - lets you grab and drag the plot to change the date range seen
4. Zoom in - lets you zoom in
5. Zoom out - lets you zoom out
6. Autoscale - reverts after scaling
7. Reset axes - lets up zoom to include your Axes Range, if this has been set. If it has not been set it zooms to a setting that shows all the viewable data.
8. Toggle spike lines – when you hover, this drops a dotted line to the x and y axis to see where it lands
9. Show closest data on hover – shows the one data point you are closest to
10. Compare data on hover – shows all data points when you hover, if you toggle that off you’ll see the single data point that you are closest to

Tables¶

Tables are another kind of module available to add to a layout. They are a different way to view the same data represented in a graph. By default, tables follow the timeline slider limits. However, you can configure the table to ignore the data range and display all data recorded.

Table names can be customized. You can also specify which columns are displayed in a table.

Tables have infinite scrolling to autoload more records.

A fuzzy search box allows you to type part of a word and will show the data on the table that closely matches what was typed.

Data for each column can be sorted by clicking on the title of the column.

Tables cannot be downloaded.

At the top of the module you can see the number of results returned.

Genetic Variants Table¶

The Genetic Variant Table shows the summary view of the subject’s genetic test results. Default filters set in Omics Explorer for a specific kind of variant (such as somatic expression) are shown here. If the subject had multiple genetic tests done, they would be displayed in this table. Also, the Germline Whole Genome Sequence table within this combines whatever variant types are configured for it (copy number, short, and others will all be listed here).

The Genetic Variant Table is interactive:

• Navigate to the NCBI webpage for that gene by clicking the gene hyperlink within the table.
• Navigate to the Genome Browser by clicking the hyperlink under the position column.
• Navigate to the Variant Detail page by:
  • Clicking anywhere on a row
  • Hovering on a row till a purple button with the appears to the right, then clicking that
• Navigate to the Integrative Genome Viewer by scrolling to the far right column and clicking the IGV icon . If a BAM file is associated with it, you’ll see the data displayed here.

Diagnostic Reports and Images Layout: The Diagnostic Reports table links to a view of the report document by clicking the icon.

Clicking the … beside the link will popup a Request a Download button. Clicking this will change the external link icon to a download link icon which you can click to download the file.

Radiology Images table Clicking on the icon in this table opens the associated image file. If the file is too large, you can click the hyperlink to open it directly in the DICOM Viewer where you can view the static or dynamic radiologic image.

Composite Table¶

The medication module is a composite table, showing you the data both in graphic and table form, all within the same module (as shown below).