BarDensr

What is it for?

This package is a collection of tools for dealing with spatial multiplexed data. Specifically, we assume the following setup.

• There are J different "barcodes" (e.g. 300 different barcodes labeling 300 RNA transcripts)
• There is a grid of M0 x M1 x M2 "voxels" (e.g. 2048 x 2048 x 150 voxels)
• There are N different "frames" (e.g. 7 imaging rounds and 4 channels = 28 frames)
• There is an unobservable M0 x M1 x M2 x J "density" giving a nonnegative value for each barcodes (j) at each voxel (m0,m1,m2), indicating where the "rolonies" are.
• There is a N x J "codebook" matrix full of nonnegative numbers, indicating how much we expect a given barcode (j) to contribute to the observations at given frame (n).
• We observe a N x M0 x M1 x M2 "imagestack" giving a nonnegative value for each frame (n) at each voxel (m0,m1,m2).
• Given the density, we assume the imagestack can be modelled by the following process: blur along the spatial dimensions, apply the codebook along the barcodes dimensions, and add noise.

What can BarDensr do?

Currently:

• Spot-calling
  • Given an imagestack, the codebook, and the point-spread function, attempt to guess the density.
  • Given a density, attempt to identify bumps (e.g. individual rolonies).
• Registration
  • Generate movies which can help identify if the imagestack has registration issues.
  • Find transformation of an imagestack so that for each frame the same voxel corresponds to the same physical location on the slices.
• Preprocessing
  • GPU-accelerated background subtraction via Lucy-Richardson
  • Generate figures which can help identify colorbleed in the imagestack (and suggest a correction)

We are working on a few additional algorithms for the following tasks. These can be found if you dig into this code, but they are not really ready for public use.

• Given an imagestack, try to guess the codebook.
• Correct vignetting artifacts in an imagestack.
• Stitch several imagestacks together from different fields of view.

• Attempt to reconstruct cell morphology from a density.

How do I use it?

Installation

pip install --upgrade git+https://github.com/jacksonloper/bardensr.git

Data structures

To use this python package, you will need to store your data with the following conventions.

• An imagestack should be a numpy array of shape N x M0 x M1 x M2. Here M0, M1, M2 refer to the spatial dimensions of the tissue. If the tissue is measured only in two-dimensions, one can set one of these values to unity (i.e. a numpy array of shape N x M0 x M1 x 1).
• A codebook should be a numpy array of dimension N x J.

Documentation of functionality

The public API (at readthedocs) and the example notebook should be enough to get started. We welcome any requests or suggestions for improved documentations; submit an issue to this github repo.

FAQ

How do I make bardensr use GPUs? How do I make it use CPUs?

The heavy lifting of this package is all performed by tensorflow. As such, if you want to insist that the lifting is run on a GPU or CPU, you can wrap function calls with tf.device. The simplest version of this pattern is as follows:

devicename = 'GPU' # <-- or 'CPU'
with tf.device(devicename):
    interesting_result=bardensr.foo(my_cool_data)

I ran out of RAM :(

Several options for dealing with memory limitations --

1. Create minitiles from your imagestack, and process each separately.
2. Use CPU (GPUs almost always have less RAM).
3. Use lower precision (e.g. convert numpy array to float16)
4. Use a bigger machine!