ProteinPaint Portals - stjude/proteinpaint GitHub Wiki

ProteinPaint portals are primarily designed to visualize cohort-based genomic and clinical data. Samples are annotated by dictionary and other term types. A portal user may easily render these annotation data into interactive charts and plots, and dynamically filter, group, and partition cohort data to detect, analyze, and evaluate relevant patterns.

How Portals Work

Portals are available from curated datasets and a flexible dataset configuration file. The configuration file defines the structure and content of the portal, including the About section, available plots, and predefined visualizations. It enables dynamic control over the interface without requiring any custom code. Users navigate globally via the top navigation bar (detailed below), while engaging interactively with each plot on a granular level. Although the configuration governs the overall behavior of the portal, each plot remains individually configurable, enabling tailored user experiences within a unified framework.

Please use this link to see an example of a ProteinPaint portal with our test data.

How to Launch

Portals rea designed to launch from embedded websites via runproteinpaint(), uploading mass session files, or using URL parameters.

Websites

Like all ProteinPaint tools, the portal can be embedded into websites. Most portals are embedded into either the St. Jude Cloud Visualization Community, external sites, or bespoke webpages.

These are the publicly available portals:

• St.Jude Survivorship Portal

Mass Sessions

Mass sessions store the mass JSON object generated by runproteinpaint(). Use this link to see an example. See how to save and open a mass session in the Session button description below.

URLs

There are two ways to launch the portal from a URL: using a url parameters or opening a shared mass session. Please refer to the instructions in our URL parameter wiki page for descriptions of each parameter. See the detailed description of the Session button below.

Navigation Tabs

Users access different features of the portal through the top navigation tabs. By default, four main tabs are available described in the sections below.

Active tabs are highlighted. Except for the About tab, selecting a tab displays its associated actions below. Clicking the tab again hides the actions but leaves any open plots visible.

Note: Tab names and availability are configurable and may differ from the default set. Refer to the portal user guide for more information.

About

The About tab displays details about the dataset. This may include cohort selection, default visualizations, and metadata. Information about the server and data release is always shown at the bottom.

Charts

Use the Charts tab to open new plots via the “Plot” button displayed below.

The image above shows available plot types, as defined in the dataset file. For descriptions of each, see the Plots section in the right-hand sidebar.

The tab updates to reflect the number of currently open plots. Once opened, plots remain visible unless the About tab is selected, which temporarily hides them.

Groups

Create and compare custom groups using the Groups tab. The tab displays the number of groups created.

To create a group, click the Add group button and select terms from the menu. Combine terms with AND or OR. Edit, negate, or remove a term by clicking the blue term button.

Groups are named automatically (e.g., "New group", "New group 1"). Click the name to edit it. The color picker assigns a color for each group in the plots. Note: Changing the color after plots created does not update the color in open plots, only new plots.

Filter

The Filter tab shows the number of active filter objects and the resulting sample count.

Filters use the same menu as groups. Once applied, filters affect all open plots.

Portal Interactive Features

Users can access global portal actions from the controls located to the right of the main tabs.

Search

Typing in the search bar displays matching dictionary terms. Selecting a term opens the summary plot, with the default bar chart plot shown.

Undo/Redo

The global undo/redo buttons next to the search input allow users to step backward or forward through recent actions, including plot creation and removal, as well as changes to groups or filters. The history is limited to the five most recent user actions.

Session Button

Users can save snapshots of their configured plots, filters, and custom groups as mass sessions, eliminating the need to recreate them manually. The Session button provides options to save, share, open, and manage mass sessions.

Save

To save a session, enter a name in the input field and choose one of the following options:

• Browser: Saves the mass session locally in the browser’s storage. The file name will appear in the list under the Open menu option.
• File: Downloads the session as a .txt file using the name entered by the user.

Share

Users can open a shared session via a direct link or copy the link to share with others. Each shared session generates a unique URL containing a mass-session-id parameter, as documented here. Shared sessions remain accessible for a limited time, with the expiration period displayed in the toolbar. By default, mass sessions are retained for 30 days.

Open

To open a downloaded session, click the Choose file link and select the saved file. If the file is saved to the browser, click the hyperlink with the appropriate file name.

Delete

The delete option is available for sessions saved locally in the browser. To delete, check the box next to the session and click Delete selected sessions.

Delete Icon

Click on the trash can to delete all plots.