Biomedical Images

Learn how you can catalog, manage, and preview biomedical images in the TileDB catalog.

TileDB models large, multi-resolution biomedical imaging with dense arrays

TileDB is an ideal solution for structuring, managing, and processing large multi-resolution biomedical imaging, using its multi-dimensional array model. Read the Structure: Biomedical Imaging section for more details on programmatically handling biomedical imaging with TileDB, and how to integrate with popular imaging tools. This section focuses mostly on TileDB’s catalog features on the UI console.

Add image

With TileDB, you can physically create and store all images in TileDB’s cloud-optimized storage format in a cloud object store like Amazon S3, which is completely under your control. You can then register the image with TileDB, so that it is added to its catalog. In other words, a TileDB image can physically exist, even if it is not part of the TileDB catalog (which offers flexibility, but it is not recommended as you may lose track of your images).

Given the above, you can add an image to the TileDB catalog in two ways:

• Create and register in one step: TileDB offers you programmatic APIs to physically create and register your images in a single step.
• Create first, register after: Alternatively, you may first physically create an image in your object store, without necessitating cataloging it with TileDB as well. At any point in time, you can register an existing images with TileDB using the UI or an API command.

Create and register in one step

Creating and registering an image in a single step programmatically is covered in section Structure: Biomedical Imaging.

From the UI, you can create and register an image as follows:

1. Select Assets from the left navigation menu.
2. Select the Add Asset button.
3. Choose Data on the emerging window.
4. Expand the Life Sciences option and select Biomedical Imaging.
5. Select Ingest biomedical imaging dataset.
6. In the new window, select the Cloud credentials (should be an ARN role) that can access the source file, and input the physical Source path and Destination path for the image.
7. Select Ingest.

The above will ingest your image into the TileDB format and register it into the TileDB catalog.

Create first, register later

Suppose you have already created a TileDB image on Amazon S3, which is covered in section Structure: Biomedical Imaging. You can register this image in two ways, either from the TileDB UI console, or programmatically.

From the UI, follow these steps:

1. Select Assets from the left navigation menu.
2. Select the Add Asset button.
3. Choose Data on the emerging window.
4. Expand the Life Sciences option and select Biomedical Imaging.
5. Select Registering biomedical imaging group.
6. In the new window, select the cloud credentials (should already exist under your account Settings) that can access the source path, select a name for the image, and optionally add a license and tags.

Programmatically, you can register an existing image with the following command:

Python

tiledb.cloud.asset.register(
    storage_uri="s3://<bucket>/<image_name>",
    namespace="<account>",  # Optional, you may register it under your username, or one of your organizations
    name="<image_name>",  # Could be different from the physical image name
    description=None,  # Optional, this will appear under Overview
    credentials_name="<credentials>",  # Required, which AWS credentials from your account can access the image.
    # You must have already added your AWS credentials in your account settings
)

A registered image will appear under Assets -> Data -> Biomedical Imaging in the TileDB catalog.

Overview

In this screen, you can find basic information about the image:

• Image name - This appears at the very top of the screen, and consists of the account name and the name you provided to the image when registering it.

• Description - If you provided a description to the image (programmatically or in Settings), it is visible here. The description is indexed and searchable in the catalog. Therefore, it’s recommended to add a meaningful description for all your assets.

• License - The type of license for the image, especially if you are making this publicly available.

• Tags - These can be used for efficient search in the catalog.

• UUID - The unique identifier for the image.

• Original URI - The location on cloud storage where the image is physically stored.

• TileDB URI - The unique resource identifier for TileDB, based on which you can call the image when coding. It comprises the namespace identifier and the UUID of the image.

• Permissions - What rights the current user has on this image. Possible values are READ and ADMIN.

• Number of assets - TileDB models the image as a TileDB group, which may contain other TileDB groups and TileDB arrays.

Referring to the image programmatically

It is important to understand how to refer to your image programmatically. You can do it in two ways:

1. Using the TileDB URI format tiledb://<account>/<image_name>. This is the most user-friendly way, but TileDB allows duplicated image names, and if you have an image with a non-unique name, this will throw an error.
2. Using the TileDB URI from the asset’s Overview tab (that is, the URI with format tiledb://<account>/<UUID>). TileDB URIs referencing the asset’s UUID are unique. Thus, this method will always work.

You can programmatically get overview information about the image with the following command:

Python

# The following will return a JSON file with various info about the image.
tiledb.cloud.asset.info("tiledb://<account>/<image_name>")

Preview

TileDB allows you to preview an image with its built-in image viewer under the Preview tab. The viewer efficiently slices an image from the cloud object storage, working very well with large, multi-resolution images, which do not need to be fetched in their entirety in your machine memory.

Contents

TileDB models images as TileDB groups, which may contain TileDB arrays and other TileDB groups. The contents of an image are visible in the Contents tab, where you can browse them and see their details.

Metadata

Images may be associated with metadata in the form of key-value pairs, which is visible in the Metadata tab.

Sharing & activity

The Sharing screen allows you to securely share your image with other TileDB users, whereas the Activity screen shows you the various accesses performed on the image by you or any other user you have shared your array with. They are both covered in detail in the Collaborate section.

Settings

In the image settings, you can modify the following:

• Description - Note that this is indexed and, thus, searchable in the TileDB catalog.
• Tags - These can be used for efficient search in the catalog.
• License - The type of license for the image, especially if you are making this publicly available.
• Make public - If you wish to share the image with all the TileDB users. This will appear in the Marketplace tab in the left navigation menu. If you make an image public, you can easily change it back to private in the same manner.
• Change cloud credentials - Credentials should be provided so that TileDB can securely access the image on the cloud store where it is physically stored.
• Rename image - Read the Rename image subsection below.
• Delete image - Read the Delete image subsection below.

You can programmatically update some image settings with the following command:

Python

tiledb.cloud.asset.update_info(
    uri="tiledb://<account>/<image_name>",
    description=None,  # Optional - A new description
    name=None,  # Optional - A new name for the image
    tags=None,  # Optional - Image tags that will be searchable in the catalog
    access_credentials_name=None,  # Optional - The cloud credentials that access the image (should already exist in your account settings)
)

To make an image public programmatically, run the following:

Python

tiledb.cloud.asset.share(
    "tiledb://<account>/<image_name>", namespace="public", permissions="read"
)

Rename image

A useful property of the TileDB catalog and the way it registers images is that you can easily rename a SOMA dataset, without physically moving it, thus avoiding the very expensive copying operations entailed in object stores when physically renaming/moving file objects. You can rename an image from the Settings tab.

You can programmatically rename an image as follows:

Python

tiledb.cloud.asset.update_info(
    "`tiledb://<account>/<previous_name>`", name="<new_name>"
)

Warning

Take caution when renaming images, as any URIs including the previous image name will no longer work.

Delete image

When deleting an image, you have two options:

• Unregister: This operation removes the image from the TileDB catalog, but it does not physically remove it from the object store. Since the image will persist on storage, you can register it again in the TileDB catalog in the future.
• Delete: This operation both unregisters and physically removes the image from storage. Note that this operation cannot be undone.

You can delete the image from the Settings tab, which will prompt you to choose among the two operations above.

You can also programmatically delete or unregister the image as follows:

Python

# Unregister an image
tiledb.cloud.asset.deregister(uri="tiledb://<account>/<image_name>")

# Delete an image
tiledb.cloud.asset.delete(uri="tiledb://<account>/<image_name>")