Interact with your Mantle Database

​

Introduction

In your Mantle Database, data is stored as entities. Each entity in your Mantle Database has a name and a data type. Each data type has a set of required properties and optional properties. You can view all of the entities of a data type as a table in your Mantle Database. Each entity is a row in a table, and the properties are columns of the table. There a multiple data types, such as rnaseq_fastq or image_directory.

Each value of each property is one of:

• string
• integer
• double (float)
• boolean
• file

Using the Mantle SDK, you can access information stored in your Mantle Database or create new entities in your Mantle Database.

​

Interacting with a single data entity

​

Getting an entity by its unique ID

import mantlebio

mantle = mantlebio.MantleClient()

entity = mantle.dataset.get("E000001")

This returns a Python object representing the data entity.

​

Accessing an entity’s name and unique ID

If you got an entity by its unique ID and want to know its name:

import mantlebio

mantle = mantlebio.MantleClient()

entity = mantle.dataset.get("E000001")

print(entity.name)

brain_metastasis_pt_16

If you got an entity some other way (e.g. as an output of a Mantle Pipeline run) and want to know its unique ID:

print(entity.unique_id)

E000001

​

Getting entity properties

To conveniently access the values of all of an entity’s properties, you can represent the entity as a Pandas series:

import mantlebio

mantle = mantlebio.MantleClient()

entity = mantle.dataset.get("E000001")

entity_series = entity.to_series()

print(entity_series)

slide_id                                                  V10A21-107
capture_area                                                      D1
image              s3://mantle-demos-data/spatial_transcriptomics...
path_to_fastqs     s3://mantle-demos-data/spatial_transcriptomics...
image_type                                                     image
primary_tumor                                               melanoma
unique_id                                                    E000001
created_by_user                                                 user
updated_by_user                                                 user
created_at                                2024-05-20 22:51:21.479078
updated_at                                2024-05-20 22:51:21.479078
dtype: object

​

Downloading files from an entity

Files that are properties of entities are stored in Amazon S3. To use the files, you need to download them to your local working environment, whether you are in a Mantle Notebook or using a script on your own computer.

Download files from file properties using the download_s3 method, which takes as arguments the key of the property and the local path to which the file will be downloaded.

import mantlebio

mantle = mantlebio.MantleClient()

entity = mantle.dataset.get("E000001")

entity.download_s3("image", "local_image.tif")

​

Querying for a group of entities and returning a DataFrame

To get a Pandas DataFrame where datasets are represented as rows, you can query for a group of datasets and turn them into a DataFrame.

import mantlebio

mantle = mantlebio.MantleClient()

entity_list = mantle.dataset.build_query().where(
    "data_type_unique_id=rnaseq_fastq"
).execute()

This returns an iterable of entity Python objects, which can each be interacted with using the SDK. For example, you can loop through and download files from each entity into your working environment.

Additionally, you can turn this iterable into a Pandas DataFrame:

df = entity_list.to_dataframe()

​

Creating a new data entity in your Mantle Database

To create a new entity in your Mantle Database, you must provide a name and a data type, and the required properties (each data type has a set of required properties and optional properties). The properties of the entity are expressed as key-value pairs.

import mantlebio

mantle = mantlebio.MantleClient()

entity = mantle.dataset.create(
    name="4XP1 2.5Å crystal structure",
    dataset_type="custom_file",
    properties={
	   "file": {"file_upload": {"filename": "</local/path/to/4xp1.pdb>"}}
    },
    local=False,
)

To test this out yourself, download the PDB file here.

properties={
    ...
    "<file_property_key>": {"file_upload": {"filename": "<file_path>"}}
    ...
}

import mantlebio

mantle = mantlebio.MantleClient()

entity = mantle.dataset.create(
    name="<my_rnaseq_fastq>",
    dataset_type="rnaseq_fastq",
    properties={
        "sample", "<sample_name>",
	    "read1": {"file_upload": {"filename": "<local/path/to/read1.fastq.gz>"}},
        "read2": {"file_upload": {"filename": "<local/path/to/read2.fastq.gz>"}},
        "strandedness": "<strandedness>"
    },
    local=False,
)