Last modified 2025-05-19

Support

Attach a NextGen IDE to a Study (Tutorial)

Abbreviations Key
HISEHuman Immune System Explorer
IDEintegrated development environment

At a Glance

A HISE study is a workspace for collaborative research. Studies contain documents, data, visualizations, research methods, statistics, IDEs, Certificates of Reproducibility, and other project materials. This document explains how to attach a NextGen IDE to a study in HISE.

Instructions

 Upload your input files

1. Navigate to HISE, and use your organizational email address to sign in.

2. From the top navigation menu, click RESEARCH > IDE NextGen.

3. Find the card for the IDE you want to add to your study.

A. To create a new IDE, click CREATE IDE INSTANCE. Then follow the remaining instructions (Steps 6-10) in Create Your First NextGen IDE (Tutorial).

B. To open an existing IDE, click the Play icon.

C. When you're notified that the IDE is running, click the boxed arrow icon to open it.

4. On the Launcher tab of your open (new or restarted) IDE, in the Notebook section, choose Python or R.

5. To import the HISE SDK and (optional) the Pandas library, run the following code in the first cell of your notebook. 

import hisepy as hp

import pandas as pd

6. To save your input file or file set to a study, click the button.

Save files to a study

7. To find your file input IDs, follow the steps below.

A. On the Search Results page, click GET IDE SCRIPTS.

B. In the Query IDE Scripts dialog box, copy the input file IDs.

8. To download your input files to HISE, return to your open IDE notebook, and enter the following code (replacing the example file IDs with your own, of course) in a new cell. This command stores the cached files in the cloud and makes them available to your local workspace for processing.

hp.cache_files(["ead87a5d-dbd3-400b-9b2b-f54762662721", "af2e1f70-9bd5-4408-8935-3ceca7da97e0", "5874551f-58e1-4f0d-ba60-d6cd14297877"])

9. To create and save an output file, run the following code in a new cell. If you like, replace output-file.csv with a more descriptive filename.

df = pd.DataFrame()
df.to_csv("/home/workspace/output-file.csv")

10. Use the following instructions to find your study_space_id, which you'll need in Step 1.11.

A. Beginning/intermediate users. Find your study_space_id in the study URL path parameters.

i. From the top navigation menu, click COLLABORATION SPACE

ii. Click the card for the study space whose ID you want to add. 

iii. Copy the path parameter from the URL, between studies/ and /reports (the highlighted portion in the example below).

https://dev.allenimmunology.org/#/collaboration/studies/fd5959ed-b8e0-4171-a5fd-fd5250366094/reports

B. Power users. To find the study_space_id programmatically, call hp.get_study_spaces()

11. In the next cell, enter your hp.upload_files() call with the four required parameters, including the input_file_ids from Step 1.7 and the study_space_id from Step 1.10. You can copy the code at left. The image at right shows an example hp.upload_files() call.

hp.upload_files(
    files=["/home/workspace/my-test-upload-file.txt"],
    study_space_id="fd5959ed-b8e0-4171-a5fd-fd5250366094",
    title="my test upload",
    input_file_ids=[
        "ead87a5d-dbd3-400b-9b2b-f54762662721",
        "af2e1f70-9bd5-4408-8935-3ceca7da97e0",
        "5874551f-58e1-4f0d-ba60-d6cd14297877"
    ],
)

For a list of upload_files parameters, see the following table.

ParameterData typeRequired or optionalDescription
fileslistrequiredList of file paths to upload
study_space_idstringrequiredID of the upload destination (study space or workspace)
projectstringoptionalProject name or ID 
titlestringrequiredTitle or description of your choice
input_file_idslistrequiredInput file IDs associated with this upload call (to track data provenance)
input_sample_idslistoptionalInput sample IDs associated with this upload
file_typeslist optionalList of file types included in the upload
storestringoptionalName of Project Store or other backend storage location
destinationstringoptionalDestination path or folder
do_promptbooleanoptionalIndicator of whether to prompt the user for confirmation before uploading
do_conda_build_checkbooleanoptionalIndicator of whether to do a readiness check of the Conda environment before uploading

 View the IDE in your study space

1. From the top navigation menu in HISE, choose COLLABORATION SPACE. 

2. Find and click the card for the study to which you uploaded your files in Step 1.11.

3. From the side navigation menu, choose IDE Instances

4. This view shows all the notebooks that have uploaded data or visualizations to your study by calling hp.upload_files(), hp.save_dash_app(), or hp.save_visualization(). To see the output files associated with a given IDE, click Output Files.

5. If the IDE doesn't appear in your list of IDE instances, it's likely that the processes are still running. To see which processes have been completed and which are still running, follow the steps below.

A. In the HISE top navigation menu, choose RESEARCH > IDE NextGen.

B. Click the card for your IDE.

C. To drill down into the upload files workflow, click the Running tag. Your IDE will appear in the IDE Instances side navigation only after all processes have succeeded.


Related Resources

Create Your First NextGen IDE Instance (Tutorial)

Manage NextGen IDE Instances (Tutorial)

Best Practices for NextGen IDE Users