FAQs and Troubleshooting Guide

At a Glance

	Abbreviations Key
AIFI	Allen Institute for Immunology
HISE	Human Immune System Explorer
IDE	integrated development environment
UI	user interface
VM	virtual machine

AIFI now offers IDEs designed specifically for the needs of our scientists and data analysts. These new IDEs are faster and easier to spin up and navigate. They support a workflow that promotes reproducibility, collaboration, and transparency. This document answers frequently asked questions about HISE in general and IDEs in particular. To get expert help with specific issues, file a Support ticket.

Jump to:

• Troubleshooting
• General Questions

Troubleshooting

Q: When I tried to open my IDE, an error message said Loading chunk 657 failed. What should I do?

A: First, clean your cache and cookies. Then do a hard reset (Cmd+Shift+R or Ctrl+Shift+R) and try to open your IDE again. If the error persists, use the Support button at the top of this page to report the issue.

Q: My IDE returned a provisioning-http-route-failure error. What should I do?

A: This error indicates a temporary server-side limitation in resource allocation. The Immunology Software Dev team must adjust the cloud infrastructure settings to restore access. Use the Support button at the top of this page to report the issue.

Q: I'm getting an uploadFiles error saying that the input file is not cached even though I just cached in the preceding cell.

A: This is a known issue: When you upload a result, there's a lag before the result is indexed, which makes it available in Advanced Search. Until we can eliminate that lag time, the workaround is to run hp.cache_files(), and then try your hp.upload_files() call again.

Q:  My IDE shows a startup script failure. I get a Failed to stop message when I try to stop or delete the IDE. My other IDE reaches the idle timeout error after about 30 minutes even though the limit is set to 24 hours. What's the deal?

A: This issue can occur when your home directory runs out of storage space. To resolve it, try the following fix:

1. Free up space. In your /home directory, delete or move unnecessary files until you have several gigabytes of free space available.

2. Retry. Try to start, stop, or delete the IDE again.

If the problem persists after you free up space, use the Support button at the top of this page to submit a help request.

Q: I can’t figure out how to get my Scanpy/Matplotlib plots to show up. I tried them “vanilla,” I tried adding plt.show() and matplotlib.use(`Agg`), but nothing worked.  

A: To enable inline plotting of Matplotlib graphs, add the following lines to a new cell at the beginning of your notebook. For more information, see Matplotlib's full image tutorial.

import matplotlib.pyplot as plt

% matplotlib inline

Q: My IDE shows a Pod in a Bad State error. What causes this error, and how can I fix it?

A: The Pod in a Bad State message is returned when various errors occur:

• Bug
• Missing dependency
• Incorrect configuration
• Lack of memory resources

The IDE might repeatedly try to start and then crash, devolving into a sort of Groundhog Day death loop. We usually need to fix something on our end. In the upper-right-corner of this document, click Support, and include the information requested on the form.

Q: How can I execute a shell script within a /private folder? 

A: As a workaround, you can copy the shell script to a location within /home/workspace, and then execute the script. 

General Questions

Q: What advantages do HISE IDEs offer? 

A: HISE IDEs have the following features:

• Faster startup
• Billing support
• GitHub integration
• Jupyter notebook UI
• Conda packages or customization
• Dedicated support from our Customer Engineering team

  Future plans include greater disk bandwidth and improved management of idle instances.

  

  ---

  Q: How can I report a problem with my IDE and get help from the Immunology Software Dev team?

  A: To request help, file a support ticket. Don't worry–the form goes to a monitored inbox, not a cosmic vacuum. A customer engineer will reply during normal business hours. Include the following information in your message (as requested on the form):

  • IDE name. Provide the name you chose for your IDE.
  • Account and project name. Include your account name (such as "Original collective longitudinal cohort study") and project name (such as "FH1 MM Treatment Analysis"). For help finding this information, see the Accounts and Projects section of Get Started with HISE.
  • Name of your scientific project. Tell us which research project you're involved with, such as "Health and Age study" or "RA study."
  • Steps to reproduce the issue. Describe the context of the crash. What were you doing when it happened? Is the problem constant or intermittent? Have you made any recent changes to the IDE?
  • Screenshots or code blocks. Include the error message, error logs, or other additional information to help your support engineer diagnose and troubleshoot the issue.

  ---

  Q: How do I create a HISE IDE?

  A: From the top navigation menu in HISE, click RESEARCH, and then choose IDEs. For detailed instructions, see Create Your First HISE IDE (Tutorial).

  

  ---

  Q: Which folders persist from session to session?

  A: See the summary table in Explore IDE Folders.

  ---

  Q: Where is the root disk?

  A: The root disk is part of the VM instance that's built when you create a HISE IDE. Because the root disk contains the operating system files, it's sometimes called the "boot disk." When you stop and restart your instance, the root disk persists.
  
  The root disk has a hierarchical folder structure that includes the read-only root directory (/). It also contains writeable paths like /var and /home. The root disk is different from the data disk, /home/jupyter, where you save your files and data. 

  By default, the size of the root disk is 10 GB. When the disk is full, an HTTP 524 error is returned. For details, see Explore IDE Folders.

  

  ---

  Q: Where is the temporary/scratch disk?

  A: The scratch space is your /temp folder. It's used to cache data in active use, process temporary files, and store intermediate computational results. For example, the folder might be used to store data after a system check or repair operation. Files in the /temp folder are persistent. For details, see Explore IDE Folders.

  

  ---

  Q: What is a Conda environment?

  A: Conda is a package manager used to bundle source code, tools, dependencies, and instructions for deploying these resources efficiently. When an IDE is created or restarted, Conda quickly spins up an environment based on the selected data modality. Conda packages are maintained in a GitHub repository to ensure reproducibility of the steps in the analysis as well as the identical development environment used to obtain a given set of results. For details, see Use HISE IDE Packages and Use the Conda Environment (Tutorial).

  ---

  Q: Why is Conda-based installation necessary?

  A: Conda creates a snapshot of the tools and resources necessary to re-create scientific or data analytic results. It captures not only the results themselves, but also the environment in which the steps were taken or computations made. The Conda environment includes the code needed to reproduce the exact version of every package and dependency in use when the researchers reached their conclusions. The original researchers or unaffiliated investigators can then attempt to reproduce those results simply by launching the same Conda environment. Conda packages are maintained in a GitHub repository to ensure reproducibility of the steps in the analysis as well as the identical development environment used to obtain a given set of results. 
  
  Using pip instead of Conda for installlation also causes conflicts in the upload_files() process. The uploaded item will not be attached to your study in the HISE Collaboration Space. 
  
  

  Note: For the HISE SDK, install with pip. To preserve reproducibility and avoid errors, use Conda to install all other scientific packages and dependencies.

  ---

  Q: Can I resize an instance?

  A: Yes.

  ---

  Q: The read_files and cache_files SDK methods both download the requested files to your IDE. So which one should I use?

  A: To promote transparency and reproducibility, call hp.read_files() to download HISE files from Advanced Search into your IDE when you create visualizations or prepare work for publication. Later you can call hp.cache_files() to find the absolute file paths to enter as parameters in the upload_files function.

  	hp.read_files()	cache_files()
  Metadata attached	Yes	No
  Content returned	Latest version of the requested files	List of cached absolute file system paths
  Retrieval method	Reads files anew each time the function is called	Reads files once and then fetches from cache

  ---

  Q: When I call hp.read_files() or hp.cache_files(), the downloaded files are saved to what location? 

  A: The files go to the /input folder (/home/workspace/input) in a nested format, as in the following example. For details, see Explore IDE Folders.
  

  ---

  Q: Are R and Python available within a single environment?

  A: Yes. To choose R and Python within a single environment, choose "Minimal modality" when you create your IDE.

  

  ---

  Q: Where can I find my projectGuid and accountGuid?

  A: To retrieve your projectGuid and accountGuid, log in to HISE and navigate to RESEARCH > Pipeline Dashboard. Use the filters to find the pipeline whose IDs you want, and click </> Full JSON.

  

  You'll see the projectGuid and accountGuid on separate lines, as shown in the following image.

  

  ---

  Q: Deleted items are accumulating in my .local/share/Trash. 

  A: This is a known minor issue. If it bothers you to have deleted items in your trash bin, you can delete the files using the rm SDK command. If you need help, we'll be happy to walk you through the process. Use the Support button to submit your request. 

  

  ---

  Related Resources

  Explore IDE Folders

  Use HISE IDEs (Tutorial)

  Manage HISE IDE Packages

  Best Practices for HISE IDE Users

  Create Your First HISE IDE (Tutorial)