Upload a File Map to Associate Files with Samples (Tutorial)

Last updated 2026-07-14

At a Glance

Use upload_file_map() (Python) | uploadFileMap() (R) to upload several files in a single call and assign each file its own file type and inputs. This keeps file provenance accurate without forcing you to split your batch into multiple uploads to assign different metadata to each file.

In a standard upload_files() call, every file in the batch shares the same inputs and file type. With upload_file_map(), you pass a file map so that each entry can point to different input samples or input files.

How It Works

The upload_file_map() call is for uploads in which one experimental run or notebook produces several different kinds of result files, each associated with its own inputs. Instead of sending a blanket list of files that all share a single metadata block, you send a file map in which each entry has its own file type and input samples or input files.

A mixed batch is any upload like this, in which different files in the same call are linked to different inputs or file types. This often happens with multisample assays, when a single run processes several samples together but generates separate outputs that map to different input samples. It also happens when you use multiple modalities, such as RNA‑seq, flow cytometry, and imaging, in a single workflow. Each modality produces its own file types.

When to Use This Feature

Use this feature when you want to upload a mixed batch of files in one call, and each file needs its own inputs or file type for downstream search, validation, or analysis:

You’re uploading results from a multisample assay in which each output file should point to a different set of input samples or input files.
You’re uploading mixed modalities in one batch and need to tag each file with a different file type.
You want to avoid workflows in which you either split a batch into multiple uploads or lose provenance by applying a shared metadata block to all files.

NOTE

Don’t use upload_file_map() when all files in the upload share the same inputs and file type and one metadata set is sufficient. In that case, the existing upload_files() call is simpler.

Instructions

Build your file map

Create an empty list named files to hold the entries.

files = []

2. Add your first file to the list with its path, file type, and input sample metadata.

NOTE
The files corresponding to your input_sample_ids must be downloaded to your IDE before you reference them in a file map, or an error will occur.

files.append(
   {
       "file": "/data/assays/rna_seq/participant_001_run1.fastq.gz",
       "file_type": "RNA_Seq_Reads",
       "input_sample_ids": [
           "sample-001-rna-extract",
       ],
   }
)

3. Add a second file to the list, including its own file type and input sample metadata.

files.append(
   {
       "file": "/data/assays/flow_cytometry/participant_001_panel_a_stats.csv",
       "file_type": "Flow_Cytometry_Stats",
       "input_sample_ids": [
           "sample-001-viability",
           "sample-001-cd45-panel-a",
       ],
   }
)

Following is the complete example, combining the above steps:

files = []

files.append(
   {
       "file": "/data/assays/rna_seq/participant_001_run1.fastq.gz",
       "file_type": "RNA_Seq_Reads",
       "input_sample_ids": [
           "sample-001-rna-extract",
       ],
   }
)

files.append(
   {
       "file": "/data/assays/flow_cytometry/participant_001_panel_a_stats.csv",
       "file_type": "Flow_Cytometry_Stats",
       "input_sample_ids": [
           "sample-001-viability",
           "sample-001-cd45-panel-a",
       ],
   }
)

Configure upload content

To associate the upload with the right study or project, set either study_space_id or project.

# Set either
study_space_id = "f2f03ecb-5a1d-4995-8db9-56bd18a36aba"
# or
project = "multiomics-pilot"

Add a descriptive title and any input_file_ids that represent the upstream files used to generate these results.

title = "Multiomics upload: RNA-seq and flow cytometry (Project HTAPP-01)"
input_file_ids = ["9f6d7ab5-1c7b-4709-9455-3d8ffffbb6c8"]

(Optional) To control where files are stored and how the upload runs, set store, destination, and flags like do_prompt, do_conda_build_check, use_fast_mode, and noFileSet.

store = "project"
destination = "/results/uploads"
do_prompt = True
do_conda_build_check = True
use_fast_mode = False
noFileSet = False

Run the upload and review results

To start the upload, call hp.upload_file_map() with your files list and context parameters.

result = hp.upload_file_map(
   files=files,
   study_space_id="f2f03ecb-5a1d-4995-8db9-56bd18a36aba",
   title="Multiomics upload: RNA-seq and flow cytometry (Project HTAPP-01)",
   input_file_ids=input_file_ids,
   store="project",
   destination="/results/uploads",
   do_prompt=True,
   do_conda_build_check=True,
   use_fast_mode=False,
   noFileSet=False,
)

To track the upload status, click RESEARCH and select the card for your IDE. Review the status tag and upload file logs to see whether the call succeeded, failed, or is still in progress. To capture the upload IDs for logs or downstream workflows, read them from the result dictionary.
```
trace_id = result["TraceId"]
workflow_id = result["WorkflowId"]
file_ids = result["FileIds"]
process_id = result["ProcessId"]
```

Related Resources

Work with Studies (Tutorial)

Use the Upload Files SDK Method (Tutorial)

Use HISE SDK Methods and Get Help in the IDE