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.
Raw data
{
"_id": null,
"home_page": "https://github.com/swamidasslab/tiffslide-xarray",
"name": "tiffslide-xarray",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "tiffslide,xarray",
"author": "S. Joshua Swamidass",
"author_email": "swamidass@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bc/ed/478da2fe2420986bee5f49b69f0fa60ad7df1519851b31706612f21c40c9/tiffslide_xarray-0.1a0.tar.gz",
"platform": null,
"description": "TiffSlide-Xarray\n----------------\n\nA simple integration library between tiffslide and xarray.\n\nInstallation\n============\n\nInstall from pypi:\n\n```\npip install tiffslide-xarray\n```\n\nUsage\n=====\n\nThis library hooks into xarray's extension system as a backend engine. So\nit can be used even without importing.\n\n>>> from xarray import open_dataset\n>>> \n>>> slide_level0 = open_dataset(\"input.svs\")\n\nThe library automatically recoginizes \"tiff\" and \"svs\" files. If required,\nthe \"engine\" keyword can force usage:\n\n>>> slide_level0 = open_dataset(\"input.another_extension\", engine=\"tiffslide\")\n\nTifflside uses the fsspec and tifffiles packages to open files. Options to these\nlibraries can be passed using the \"storage_options\" and \"tifffile_options\" keyword\narguments.\n\n>>> slide_level0 = open_dataset(\"s3://input.svs\", storage_options={\"s3\": ... })\n\nBy default, the level 0 of the the file is read. Other levels can be read by using\nthe \"level\" keyword.\n\n>>> slide_level1 = open_dataset(\"input.svs\", level=1)\n\nNegative levels are allowed to allow indexing from end of the level array.\n\n>>> slide_level_last = open_dataset(\"input.svs\", level=-1)\n\nOpening All Levels\n==================\n\nTo open all the levels in the slide, use the \"open_all\" to return a datatree of the \nslide.\n\n> from tiffslide_xarray import open_all_levels\n>\n> slide = open_all_levels(input.svs)\n\nThe returned datatree places level0 at the root group, and places subsequent\nlevels at the f\"level{n}\" group. \n\n\nData and MetaData Model\n=======================\n\nThe data for each slide is accessible at \"image,\"\n\n>>> slide_level0.image\n>>> slide_level0[\"image]\n\nCoordinates for the x, y and c dimensions are added, in units of \"pixels\" in the level 0\nslide. This makes the cordinates between different levels directly compariable. The library\nassumes there are three channels, in the order of (r, g, b). \n\n>>> slide_level0.x\n[0, 1, 2...]\n>>> slide_level0.y\n[0, 1, 2...]\n>>> slide_level0.c\n['r', 'g', 'b']\n\nAll the metadata from the slide is stored in the dataset attributes. The source file name is\nadded to the metadata of both the 'image' array and the dataset. If found in the metadata, the microns \nper pixel (mpp) is stored in the attributes of the 'x' and 'y' coordinates.\n\nLazy Loading\n============\n\nSlides are lazy loaded which makes the initial open very quick, and\nloading of small regions is quick (but not cached). Loading of large regions can be slow. \nTo manage this, be sure to call \"load\" on datasets to bring them into memory\nif they will be accessed multiple times.\n\nFor example, this code will execute two costly reads:\n\n> roi = slide_level1.sel(x=slice(10000, 40000), x=slice(5000, 20000)) # select a large ROI\n>\n> roi2 = 2.0 * roi # first read\n> roi2 = 3.0 * roi # second read\n\nCalling \"load\" on \"roi\" or \"slide_level1\" solves this problem.\n\n> roi = slide_level1.sel(x=slice(10000, 40000), x=slice(5000, 20000)) # select a large ROI\n>\n> roi = roi.load() # load the ROI into memory for subsequent processing.\n> roi2 = 2.0 * roi # no read\n> roi2 = 3.0 * roi # no read\n\nRequesting Feedback\n===================\n\nThis project currently in alpha to obtain feedback on the API. Please\nsubmit issues or API feature/modification requests to: https://github.com/swamidasslab/tiffslide-xarray.\n",
"bugtrack_url": null,
"license": "",
"summary": "Xarray extension that uses xarray to lazy read 2D Tiff files.",
"version": "0.1a0",
"project_urls": {
"Homepage": "https://github.com/swamidasslab/tiffslide-xarray",
"Repository": "https://github.com/swamidasslab/tiffslide-xarray"
},
"split_keywords": [
"tiffslide",
"xarray"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a63e71c2b9ef124b8ff2976287b54897b109312cca4d9331e7346fc0c2f9d49a",
"md5": "8c22af55ee866bf72b9023335cad34a3",
"sha256": "3976a8da44bd7beac6caaffc87cffa6f9773510f3c23a8007d73827a7eb43cb2"
},
"downloads": -1,
"filename": "tiffslide_xarray-0.1a0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c22af55ee866bf72b9023335cad34a3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 6163,
"upload_time": "2023-10-21T17:59:06",
"upload_time_iso_8601": "2023-10-21T17:59:06.514424Z",
"url": "https://files.pythonhosted.org/packages/a6/3e/71c2b9ef124b8ff2976287b54897b109312cca4d9331e7346fc0c2f9d49a/tiffslide_xarray-0.1a0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bced478da2fe2420986bee5f49b69f0fa60ad7df1519851b31706612f21c40c9",
"md5": "36907e8c718ef72c852237d2dea9bc19",
"sha256": "223603321e39c9e2590a99370620053a0de802697eb1fc544856dbca12fb8acc"
},
"downloads": -1,
"filename": "tiffslide_xarray-0.1a0.tar.gz",
"has_sig": false,
"md5_digest": "36907e8c718ef72c852237d2dea9bc19",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 5467,
"upload_time": "2023-10-21T17:59:08",
"upload_time_iso_8601": "2023-10-21T17:59:08.219012Z",
"url": "https://files.pythonhosted.org/packages/bc/ed/478da2fe2420986bee5f49b69f0fa60ad7df1519851b31706612f21c40c9/tiffslide_xarray-0.1a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-21 17:59:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "swamidasslab",
"github_project": "tiffslide-xarray",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tiffslide-xarray"
}
JSON
