Use the Upload Files SDK Method (Tutorial)

	Abbreviations Key
HISE	Human Immune System Explorer			obj	object
hp	hisepy			SDK	software development kit
IDE	integrated development environment			ss	study space

At a Glance

This document explains how to upload files–such as cleaned datasets, analysis outputs, summary tables, or visualizations–to a study in the HISE Collaboration Space. Doing so lets you share your insights with others. The upload_files() method is shown in the box below.

Instructions

 Import libraries

To get started, set up your environment to interact with HISE programmatically and access all available SDK functions. For details, see Use Hise SDK Methods.

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

2. Open an IDE. For instructions, see Create Your First HISE NextGen IDE (Tutorial).

3. To import hisepy, enter the following code into a new cell in your IDE.

#Import the Python SDK to enable programmatic access to HISE functions
import hisepy as hp

 Get the study space ID

Each study in any given project is assigned a study space ID. This unique ID ensures that your uploaded files are saved to the correct study in the Collaboration Space. It's one of four parameters required in an upload_files() call. See the accompanying table for a full list of required and optional parameters. 

1. To find your study space ID, enter the following code. A list of dictionaries is returned.

# Return all available study spaces for your account
ss_output = hp.get_study_spaces()

2. To search for the study you want, enter the following line. In this example, we look up a study titled "Sample Study."

# Find the name of a particular study space
ss_name = 'Sample Study' 

for study_space in ss_output:

if study_space['name'] == ss_name:

ss_obj = study_space

# Show the matching study space dictionary
ss_obj

3. To extract the ID from the dictionary object, enter the following code.

# Extract the unique study space ID from the selected study space object
ss_id = ss_obj['id']
print(study_space)

Retrieve file IDs and download files to your IDE

To ensure that you work with the intended datasets, first identify their IDs (for example, from an advanced search), and then download them using a reader method like read_files(), read_samples(), or cache_files(). Doing so creates a local copy of the data and allows the system to track which files have been accessed in your current session.

1. Identify the files you want to use. You can list as many as you like, separated by commas (for example, ['ID1', 'ID2', 'ID3']).

# Pass in file ID(s)
files = ['4613f981-127e-4b07-a437-6f2d814eac9d']

2. To download files to your IDE, enter the following line in a new cell.

# Cache the specified files
hp.cache_files(files)

 Upload files to your study

To make your data accessible for analysis or sharing, upload your results to the study space.

1. To upload your results file, replace the file path and input file IDs as necessary. A successful upload will print out a trace id.

# Upload results file(s) to specified study space
hp.upload_files(
    files=['input/2842984779/cohorts/4613f981-127e-4b07-a437-6f2d814eac9d/hise-example.txt'],
    study_space_id=ss_id,
    title='A demo upload',
    input_file_ids=files
)

Tips and Troubleshooting

 Use batch uploads to avoid timeouts

Timeout errors typically occur when you try to upload a large number of files or a large total data volume in a single operation. The system is unable to process the data within the allotted time, resulting in a timeout. The risk of a timeout depends not only on the number of files, but also on their individual and total sizes. Divide your upload into smaller batches, with fewer files per call. Instead of consolidating all research activities into a single IDE, create separate notebooks for specific purposes, such as preprocessing, predictive modeling, and visualization. For information on space limitations, see the Q&A document. 

 Set the files and input_file_ids parameters as lists

The files and input_file_ids parameters must be set as lists even if you upload only one file. The files list should contain absolute file paths–not just filenames or relative paths. To obtain these paths, use cache_files(), which downloads the specified files and stores them locally in the cache directory, returning their locations. The input_file_ids list includes the IDs of all files used to generate the result files. This ensures traceability and reproducibility, clarifying which input files yielded the uploaded results.

 Supply either study_space_id or project

The upload_files method lets you specify certain parameters in alternative ways. To indicate where files should be uploaded, for example, you can provide either a study_space_id or a project–but not both. If you're not sure which parameter is required or how to format it, use help(hp.upload_files) to review the SDK help documentation, as shown in the following image. In addition, check the HISE documentation shown in the Related Resources section at the bottom of this page.

Related Resources

Use HISE SDK Methods

Best Practices for NextGen IDE Users

Attach a NextGen IDE to a Study (Tutorial)

Create Your First HISE NextGen IDE (Tutorial)