Xarray extension that uses xarray to lazy read 2D Tiff files.
Project description
TiffSlide-Xarray
A simple integration library between tiffslide and xarray.
Installation
Install from pypi:
pip install tiffslide-xarray
Usage
This library hooks into xarray's extension system as a backend engine. So it can be used even without importing.
from xarray import open_dataset
slide_level0 = open_dataset("input.svs")
The library automatically recoginizes "tiff" and "svs" files. If required, the "engine" keyword can force usage:
slide_level0 = open_dataset("input.another_extension", engine="tiffslide")
Tifflside uses the fsspec and tifffiles packages to open files. Options to these libraries can be passed using the "storage_options" and "tifffile_options" keyword arguments.
slide_level0 = open_dataset("s3://input.svs", storage_options={"s3": ... })
By default, the level 0 of the the file is read. Other levels can be read by using the "level" keyword.
slide_level1 = open_dataset("input.svs", level=1)
Negative levels are allowed to allow indexing from end of the level array.
slide_level_last = open_dataset("input.svs", level=-1)
Opening All Levels
To open all the levels in the slide, use the "open_all" to return a datatree of the slide.
from tiffslide_xarray import open_all_levels
slide = open_all_levels(input.svs)
The returned datatree places level0 at the root group, and places subsequent levels at the f"level{n}" group.
Data and MetaData Model
The data for each slide is accessible at "image,"
slide_level0.image
slide_level0["image]
Coordinates for the x, y and c dimensions are added, in units of "pixels" in the level 0 slide. This makes the cordinates between different levels directly compariable. The library assumes there are three channels, in the order of (r, g, b).
>>> slide_level0.x
[0, 1, 2...]
>>> slide_level0.y
[0, 1, 2...]
>>> slide_level0.c
['r', 'g', 'b']
All the metadata from the slide is stored in the dataset attributes. The source file name is added to the metadata of both the 'image' array and the dataset. If found in the metadata, the microns per pixel (mpp) is stored in the attributes of the 'x' and 'y' coordinates.
Lazy Loading
Slides are lazy loaded which makes the initial open very quick, and loading of small regions is quick (but not cached). Loading of large regions can be slow. To manage this, be sure to call "load" on datasets to bring them into memory if they will be accessed multiple times.
For example, this code will execute two costly reads:
roi = slide_level1.sel(x=slice(10000, 40000), x=slice(5000, 20000)) # select a large ROI
roi2 = 2.0 * roi # first read
roi2 = 3.0 * roi # second read
Calling "load" on "roi" or "slide_level1" solves this problem.
roi = slide_level1.sel(x=slice(10000, 40000), x=slice(5000, 20000)) # select a large ROI
roi = roi.load() # load the ROI into memory for subsequent processing.
roi2 = 2.0 * roi # no read
roi2 = 3.0 * roi # no read
Requesting Feedback
This project currently in alpha to obtain feedback on the API. Please submit issues or API feature/modification requests to: https://github.com/swamidasslab/tiffslide-xarray.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for tiffslide_xarray-0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b2cfee7ffe5bb37fa3ecb24217d70b29788f215553af1c13b28446b89ee288cb |
|
MD5 | 8f69dbc4af0f9ae5be92e77903fecf09 |
|
BLAKE2b-256 | 6cd880f0e43c12f1946bb703edf6999daefca8fbf3acd2aaad185fae6cd7ba32 |