Title: Delete Empty Containers

Date: June 24th 2020

This notebook demonstrates how to remove empty containers with a top-down method.

Install and Import Dependencies

Flywheel API Key and Client

Get your API_KEY. More on this at in the Flywheel SDK doc here.

Instantiate the Flywheel API client

Show Flywheel logging information


Flywheel data model relies on hierarchical containers. You can read more about the flywheel containers in our documentation here.

Flywheel Project are structure into the following hierarchy:

└── Project
    └── Subject 
        └── Session
            └── Acquisition

Each of Project, Subject, Session and Acquisition are containers. Containers share common properties such as the ability to store files, metadata or analyses.

How does the top-down approach work?

Based on the Flywheel Hierarchy above, the top-down approach will start from the Subject container and traverse down through Session and Acquisition containers. This method will remove Subject, Session and Acquisition containers that have no children containers, and no files nor analyses attached to the container.


In order to run this notebook, you will need to have the right permission on the Group level to create a new Project for testing.

Initialize a few values

Now, we will be defining a few values that will be use in this notebook. The GROUP_ID is the Group ID that you will be using throughout this notebook.

Please defined below the path to file that you would like to use for testing which will be uploaded to your Flywheel instance

INFO: For tutorial purposes, we are creating a test project and uploading some DICOM files on Acquisition container. Feel free to use one of your test projects and skip the 'Create A New Test Project' section.

Create A New Test Project

Create Subject, Session and Acquisition container and upload File

Here, we will be create one Subject container and in that Subject container, we will be adding one Session and in that Session, there will be one Acquisition added. Here we will also upload the File to the Acquisition that created.

Helpful Functions

Getting Started

First, we are going to do a dry run by setting dry_run to True before actually deleting the Subjects container.

Now we can try to actually delete the empty containers

As expected, it didn't delete the Subject 01 subject container as the Acquisition contains a file.

So let's try to delete the file that we have uploaded earlier to the acquisition. If you recall, the file that is being uploaded is named as TEST_FILE_BASENAME. We will be using the delete_file method to delete the file from the Acquisition container.

INFO: You can also use delete_file method to delete file from the Session or Subject container

After deleting the file, we can try to delete the container again.

Do I have the proper permissions to delete a container in my project?

If you have a project where you would like to remove/delete empty containers, you will need to have the right permissions to delete/modify the containers on the Project level. Below are the minimum requirements.

After you have verified that you have the right permissions to delete/remove containers in the desired project, you can get the project container and call delete_empty_containers_in_project function again.