Use the HISE SDK to Create Visualizations (Tutorial)
 | Abbreviations Key |
| HISE | Human Immune System Explorer |
| IDE | integrated development environment |
At a Glance
When you visualize a data set that's instrumental to your research, you can share your results with other scientists and save your visualization to a template. Templates let you document your methodology, tools stack, and input data, so that others can reproduce your results.
This document explains how to create a visualization template and save it to HISE so that any other HISE user can repurpose it create their own interactive visualization.
Components
When you save a visualization in HISE, the IDE instance itself (but not the home/jupyter directory) is recorded, including the following components:
- Input data
- Code
- Resulting data being visualized
- IDE image details
- Resulting trace
By default, visualizations are saved in Draft mode. You can use this stage to review the results with your collaborators. If you're not satisfied with the visualization, you can delete it and create an improved version. When you're happy with the result, you can switch the visualization mode to Final. Note that only final visualizations can be used in publications and Data Apps.
Paths
| Type | Description | Preprocessing | Library |
| Simple visualizations | Single figures | R or Python | Plotly based–includes support in R for the ggplot library |
| Complex visualizations | Interactive figures or figures with multiple graphs | For rapid rendering, load data without preprocessing if possible. Any necessary preprocessing can be done in R or Python. | Dash based |
There are two paths to creating a saved visualization, as shown in the accompanying table.
Simple Visualizations
In the examples folder within your HISE IDE instance, the Plotly subfolders (under "Python" and under "R") contain example figures you can use as the basis of a simple visualization, supplying your own data frames. The folder also contains information on how to save visualizations to a study, either by using a UI widget to facilitate parameter value selection or by manually providing the parameter.
Complex Visualizations
In the examples folder of your HISE IDE instance, use Markdown Preview to open the ReadMe.md file, which explains the concepts and approach to complex visualizations, and guides you through the various notebooks of sample code.
Instructions
Read from the remote bucket
For a visualization template to work, the visualization must be read from a cloud storage bucket. The visualization is stored separately from the data. This decoupling enables the creation of multiple instances of a visualization, each of which pulls data from a different source.
1. Log in to HISE.
2. From the top navigation, choose COLLABORATION SPACE > IDE instances.
3. Create an IDE instance. For details, see Work with IDE Instances.
4. To parse the URL that points to the remote location of the data set and reads in its contents as a data.frame, use the init_data() function, as shown below:
parsed_url = urlparse(search)data_url = parse_qs(parsed_url.query)['data-url'][0]logger.info("reading data: %s", data_url)df = pd.read_json(data_url
Set the port number
Next, set the port number and debug flag in the main app.py function.
1. To set the port number to 8050 and set the debug flag to False, use the app.run_server() function:
if __name__ == '__main__':
logger.info("running app server")
app.run_server(host='0.0.0.0', port=8050, debug=False)
Save your template to HISE
To save your work to HISE, adjust the environment.yml config file (only if needed) and call hisepy.save_abstraction().
1. To create an environment.yml file, create and activate a conda environment, and install the application packages. For details, see Installing conda.
2. In your terminal, execute the following command:
conda env export > environment.yml
3. Create a tar file that contains your app.py script and the contents of /home/jupyter/demo-hise-api/demos/Visualization_apps/dash/configs. If you have Python packages or libraries that aren't already specified in the file, replace the .yml file with the one that already exists.
4. To save your visualization template to HISE, call hisepy.save_abstraction():
hp.save_abstraction(app_filepath='/home/jupyter/examples/Visualization_apps/dash/app.py',
title="Title",description="Description",result_file_types=["scRNA-seq-labeled"],
image='/home/jupyter/examples/Visualization_apps/dash/image.png',
data_contract_id="09a19b05-a34d-4d12-bc0b-e59a5e35be87",additional_files=[])
(Optional): Save a template that uses only sample or subject metadata
To save a template that uses only sample or subject metadata, you must set two additional parameters.
1. To execute the hisepy.save_abstraction() function, enter the following code block:
hp.save_abstraction(app_filepath='/home/jupyter/examples/Visualization_apps/dash/app.py',
title="Title", description="Description",
is_sample_metadata_app = True,
image='/home/jupyter/examples/Visualization_apps/dash/image.png',
data_contract_id="09a19b05-a34d-4d12-bc0b-e59a5e35be87",
additional_files=[])
2. To determine which string value to pass into the result_file_type parameter, use the utility function hisepy.get_result_files().This function returns a data.frame with the following columns: id, fileType, description, and isSearchable. If the incorrect string value is inserted, the function returns an error and prints a list of all possible valid values.
Plotly visualizations sometimes return a
Following is an example implementation of the above solution. Remember to update Conda as a first step.
|
Related Resources
Explore No-Code Visualizations