emObject Guide

What is emObject?

emObject is an abstraction for multimodal spatial omics data in Python. It’s inspired by other data abstractions and data science libraries like Seurat, but purpose-built for multiplexed imaging, spatial transcriptomics, and similar assays. emObject unlocks a seamless data science workflow between the core data types in a spatial dataset: matrix-format data, images, and masks - via shared indexing and dedicated attributes to hold measurements, featurizations, and annotations on data across spatial scales.

As emObject evolves, we envision this data abstraction providing an expected and efficient format for science and engineering code and as a step towards closing the loop between code and no-code analysis on the Enable platform.

For more info about the design and motivation for emObject, see the manuscript emObject: domain specific data abstraction for spatial omics.

What’s in an emObject?

emObject has dedicated attributes for all the common attributes we encounter in analyzing spatial data. A single emObject represents data at the acquisition level - future functionality is planned to represent experiments.

Data attributes are aligned along several axes:

1. The observation axis - typically cells or visium spots
2. The variable axis - typically genes or biomarkers
3. The segment axis - unique, contiguous regions of ROI masks

Layers

Layers are an additional axis within emObjects that stack the core data attributes - data, var, obs, sobs. This allows us to hold multiple versions - or multiple data modalities - within a single object. For example, we could have a raw and normalized data layer, or a layer for CODEX and a layer for H+E data. Annotations are kept within a layer since computations derived from the images may be affected by the numeric values in data.

What gets stored where?

• Biomarker expression -> data
• Notes about biomarkers -> var
• Featurization -> obs
• Spatial info -> pos
• Assignment of cells to segments -> seg
• Annotations on segment level -> sobs
• Unstructured info, whole image annotations -> meta

Getting started

Requirements

emObject requires Python 3.8 or higher and is tested on MacOS 13.2 (Ventura) and Ubuntu 18.04 and 22.04.

Installation

To install emObject, clone this repo:

git clone https://gitlab.com/enable-medicine-public/emobject.git

and install:

sudo python setup.py install

If you use pipenv as a package manager, you can install via:

pipenv install '-e .' --dev

from within the emobject.emobject repository.

You can also install directly via PyPI:

pip install emobject

or, if you use pipenv (recommended):

pipenv install emobject

emObject API

Overview

emObject strives to maintain consistency with existing tools in the Python data science ecosystem, like Pandas and NumPy. Wherever possible, the API is shared - under the hood, many attributes of emObject rely on existing tools. When we need to introduce something new, an effort is made to design an API that feels familiar to users comfortable with the Python data science ecosystem.

Tutorial

A full demo is available on Gitlab.

import emobject.emobject as emo
import emobject.emimage as emi
from emobject import core
import pandas as pd 
import numpy as np
import matplotlib.pyplot as plt

import os

🏗️ Building an EMObject

There are several ways to construct an EMObject. We provide an API for building an EMObject directly from the Enable Database (currently for Enable internal users only) and reading EMObjects from an on-disk store.

It's also possible to directly create an EMObject from existing data you might have, but this currently requires a good understanding of EMObject's inner workings and can lead to unexpected behavior if done incorrectly. We're working to streamline this, so in the meantime it is highly recommended to use one of the above options.

💽 Loading an EMObject from Disk

We can load an existing EMObject from its on-disk Zarr representation.

E = core.load('./test/Charville_c001_v001_r001_reg001.zarr/')

🔎 Access object attributes

Most attributes are represented as Pandas DataFrames, and can be interacted with using standard Pandas API. For example, we can grab the first 10 biomarker expression entries:

E.data.head(10)

Data and attributes are indexed by the observeration axis (cells) and the variable axis (biomarkers/genes). In some cases, no axis is provided, in which case an integer axis is generated. To inspect the axes:

E.obs_ax

RangeIndex(start=0, stop=10145, step=1)

EMObject attributes are built on top of familiar libraries from the Python data science ecosystem, like NumPy and Pandas. This gives EMObject data attrbutes a familiar API. For example, we can slice through individual attributes using Pandas .loc:

E.data.loc[:,'CD45']

0        107.672997
1        100.445000
2        156.197006
3        150.371002
4        100.744003
            ...    
10140    166.009995
10141    174.339005
10142    106.834999
10143    302.000000
10144     62.540001
Name: CD45, Length: 10145, dtype: float64

Annotations about observations are stored in .obs.

E.obs.head(10)

✏️ Annotating EMObject Attributes

In our object, we didn't provide any annotations to variables, but they can be stored in .var. No attributes are created until called, so this adds no overhead until used:

E.var.head(10)

But, we could add some annotation to the biomarkers

passed_qc = np.random.randint(0, 2, size=E.var_ax.shape[0]) # some dummy values
passed_qc = passed_qc.astype(bool)

E.add_anno(
    attr='var',
    value=passed_qc, 
    name="PassedQC")

E.var.head(5)

You can do this on observations too.

random_int = np.random.randint(0, 10, size=E.n_obs)

E.add_anno(
    attr='obs',
    value=random_int,
    name='RandomIntAnno'
)

E.obs.head(10)

You could also add 2-D arrays of annotations:

multiple_annos = np.random.randint(0,100, (E.n_obs, 2))
multiple_annos

array([[92,  5],
       [21, 77],
       [94, 18],
       ...,
       [14,  4],
       [46, 64],
       [27, 51]])

multiple_annos = np.random.randint(0,100, (E.n_obs, 2))

E.add_anno(
    attr='obs',
    value=multiple_annos,
    name=['test1', 'test2']
)

E.obs.head(5)

E.obs

🤿 Working with ROI and segmentation masks

Masks are stored in .mask, but are represented as a unique EMMask object.

We see that this object has 3 masks associated with it.

E.mask.n_masks

3

If you're loading an EMObject from a previous store or the Enable database, you'll see whatever names were stored last. The segmentation mask you've requested will always be named segmentation_mask.

We're building from scratch, so EMObject has provided dummy mask names, which we can update.

E.mask.mask_names

array(['mask_0', 'mask_1', 'mask_2'], dtype='<U6')

E.mask.mask_names = np.array(['gloms', 'bloodvessels', 'artifacts'])

Masks can be selected by name with an interface similar to Pandas:

E.mask.mloc('gloms')

array([], shape=(0, 4032, 4032), dtype=int64)

To plot a mask:

E.mask.plot('gloms')

🧩 Segments

Within masks, each contiguous region is defined as a segment. For example, in the mask shown above, there are 3 segments.

To enable segment-wise annotations and analysis, we generate a mapping of observatoins to segments, in .seg, which is a n_obs x n_mask array. Non-zero elements of .seg are unique identifiers of segment. The col index of .seg matches the .mask index.

A summary of mask segments is provided in the n_seg attribute:

E.n_seg

{'gloms': 3, 'bloodvessels': 4, 'artifacts': 1}

E.seg

array([[   0, 9479,    0],
       [   0,    0,    0],
       [   0,    0,    0],
       ...,
       [   0,    0,    0],
       [   0,    0,    0],
       [   0,    0,    0]], dtype=uint16)

As with other types of data, EMObject supports annotations on segments via the add_anno and del_anno functions previously described.

Because sobs stores an annotation array per mask, we must specify the mask. A current quirk is that calls to sobs arrays in the object (e.g. to read them) must be done by index. API improvements incoming here.

seg_anno = np.random.randint(0, 100, 4)

E.add_anno(
    attr='sobs', 
    value=seg_anno,
    name='TestSegAnno',
    mask='gloms'
)

E.sobs[0]

Now delete it:

E.del_anno(
    attr='sobs',
    name='TestSegAnno',
    mask='gloms'
)

🥞 Layering

EMObject supports layers, which are intended to hold transformations on the core data within one object. For example, the same region could have the original raw data matrix, plus a normalized transformation of that data. It's also possible that derived measurments on observations or variables could be affected by the original data.

BaseLayer contains all of the core tabular data attributes of EMObject: data, obs, var. EMObject wraps multiple BaseLayers into LayeredData, which allows for indexing along a layer axis. You don't really need to know how this works because you can interact as if it's all one object. If you only dream of one layer, all of the above still works (we've been using LayeredData the whole time).

To illustrate, we'll define a trivial transformation on our data:

normed_data = (E.data-E.data.mean())/E.data.std()

Now, we can add this data to a new BaseLayer called 'z-normed'.

from emobject.emlayer import BaseLayer

normed_layer = BaseLayer(data=normed_data, 
                         name = 'z-normed')

We can add this BaseLayer to our EMObject.

E.add(normed_layer)

To see the layers associated with your EMObject:

E.layers

['raw', 'z-normed']

By default, our original data is stored in the raw layer. We can see that we've now added a layer z-normed.

We can specify which layer we want to work inside of:

E.set_layer('z-normed')

Let's take a look at the data in the layer. It should match our transformed data above.

E.data

We haven't defined any variable annotations on this layer, so we shouldn't see any if we check:

E.var.head(5)

We revert back to the original annotations provided at object construction time, here we should just see ANNOTATION_LABEL, but nothing else that we've added in the previous steps.

E.obs

We can still add annotations as described above:

random_int = np.random.randint(30, 70, size=E.n_obs)

E.add_anno(
    attr='obs',
    value=random_int,
    name='RandomIntAnno - Layer'
)

E.obs.head(10)

You can change layers using .set_layer. Passing no args will return you to the starting layer.

E.set_layer()

…and we're back to our raw data annotations

E.obs.head(10)

🍕 Slicing

EMObject also supports slicing, using a Pandas-like notation. Slicing an object returns an in-memory view of the current layer, with data attributes subsetted to your specifications.

obs_subset = np.arange(0, E.n_obs, 32) # get every 32nd cell in the object
var_subset = np.array(['DAPI', 'CD45', 'aSMA']) # our favorite markers 

E_subset = E.loc(obs_subset=obs_subset, 
                 var_subset=var_subset) 

We should see that our object attributes have been subsetted:

E_subset.data

E_subset.obs 

E_subset.pos

We can also slice through on the basis of cells or masks:

glom_data = E.loc(mask='gloms')
glom_data.data.head()

segment_data = E.loc(seg_subset=9479)
segment_data.obs

You can also use slicing notation on the EMObject directly to access layers:

E['z-normed'].data.head(10)

🔬 Accessing images

EMObject represents images as an in-memory or on-disk Zarr hierarchy using the EMImage class. You can access the image directly, plot channels, and use for downstream analysis.

See what channels are in this image:

E.img.channels

array(['ACE2', 'C1QC', 'C3a', 'C3aR', 'C3d', 'C4d', 'C5aR', 'C9',
       'CD107a', 'CD11b', 'CD11c', 'CD141', 'CD183', 'CD196', 'CD21',
       'CD227', 'CD25', 'CD31', 'CD35', 'CD38', 'CD45', 'CD46', 'CD55',
       'CD68', 'Clusterin', 'CollagenIV', 'DAPI', 'EpCAM', 'FoxP3',
       'GranzymeB', 'ICOS', 'MASP2', 'Nestin', 'PD1', 'Perlecan',
       'RORgammaT', 'SC5b9', 'SPP1', 'TFAM', 'VWF', 'aSMA', 'bCatenin1'],
      dtype=object)

Plot an image channel:

E.img.plot_channel('DAPI')

E.img.img 

<zarr.core.Array (42, 4032, 4032) uint16>

💾 Saving EMObjects to disk

EMObjects can be saved to disk as a Zarr store.

core.save(E, out_dir='./savetest')

We can also verify that this object is what we think we saved:

E2 = core.load('./savetest/DemoKidney.zarr/')
E2.summary

EMObject Version 0.4.0
EMObject: 
Layers: 2
     Layer 1: raw
     Layer 2: z-normed
obs: 10145
var: 42
masks: 3

Issues and Contributions

emObject is very young 🐣! If you encounter a bug or missing/desired functionality, or just have some feedback, please submit a Gitlab issue. Contributions are also welcome 👩🏻‍💻!

"""
.. image:: ../docs/img/emObject_logo.png
.. include:: ../docs/docs.md
"""

Sub-modules

emobject.core

emobject.emexperiment

emobject.emimage

emobject.emlayer

emobject.emobject

emobject.empublicaccess

emobject.emroitools

emobject.errors

emobject.tests

emobject.utils

emobject.version