How to access returned data on UKB-RAP

This article explains how researchers can request access to returned datasets listed in the Showcase Returned Datasets Catalogue and how to make approved returns available within their UK Biobank Research Analysis Platform (UKB-RAP) project. 

Access involves two main steps:

1. Request access to a returned dataset on Showcase

2. Retrieve the approved returned dataset into your UKB-RAP project using the Return Fetcher App

Note: Only users with the PI, Lead Collaborator, or delegate role on the project can access the Data tab in AMS and proceed to Showcase to request access.

1. Request access to a returned dataset on Showcase

Requests for access to returned datasets are submitted via Showcase, which must be accessed from the relevant project in AMS. Requests must be submitted from the individual returned dataset page on Showcase. The Showcase Returned Datasets Catalogue provides a list of available returned datasets.

How to access Showcase from AMS

• Log in to AMS.
• Select Projects from the left-hand menu.
• Select View/Update on the relevant project.
• Open the Data tab.
• Select Go to Showcase.

On Showcase, the Returned Datasets Catalogue can be accessed via Catalogues → Returns.

How to request access

• Select Request access on the return's <return_id> page.
• Once submitted, the request will be processed (typically within one day).
• If approved, access will be enabled for your project. You will need to refresh the returned dataset page on Showcase to see the updated status.
  • Note: In some cases, the message may remain as "Access request is being processed" even after access has been granted. If more than 24 hours have passed since your submitting your request, you can proceed to run the returns app on the UKB-RAP. The job will succeed if access has been approved, regardless of the message displayed on Showcase. 
• If the returned dataset is in a higher access tier than your project, the request option will not be available.

2. Retrieve the returned dataset on the UKB-RAP

Once access has been approved on Showcase, you can retrieve the dataset into your UKB-RAP project using the ukb-data-return-fetcher app. This can be run through the UKB-RAP GUI or from the command line.

Running the returns app from the command line

Example command-line usage:

dx run ukb-data-return-fetcher -ireturn_id=<return_id> -iverbose=true --priority high

App Inputs

• return_id (required): The return ID from the Showcase Returned Datasets Catalogue (e.g., 12345)
• verbose (optional): Set to true for detailed logging (default: false)

Example optional command-line flags:

• --priority high or (default): controls job scheduling priority
• --watch: streams job logs to the terminal
• --yes: skips the confirmation prompt
• --instance-type: selects a specific compute instance

Running the returns app from the UKB-RAP GUI

The app can also be run using the UKB-RAP GUI. To do this:

• Open your UKB-RAP project.
• Go to the Tools tab
• Select Tools Library
• Select UKB - Data Return Fetcher
• Hit Run and select a project and output location
• Enter the return_id input
• Review settings and launch the job

Runtime considerations

The runtime depends primarily on the size of the returned dataset:

• Small datasets: typically a few minutes
• Large datasets: up to an hour or more

We recommend checking:

• The dataset size on Showcase
• The UK Biobank rate card for appropriate instance selection

Outputs

When the job completes successfully, the app creates a timestamped folder in your UKB-RAP project:

data_return/YYYYMMDD_HHMMSS/

This folder contains:

• A zip file of the returned dataset
• A bridging file (.txt) mapping: 
  • Your project-specific encoded participant IDs (first column)
  • Returned dataset encoded IDs (second column)

If access to the specified return has not been approved on Showcase, the app job will fail, and no data will be added to your project space.

Note

UK Biobank does not perform full scientific validation of returned datasets or code. Researchers accessing returned data are responsible for assessing its suitability for their own research.