intake_io

Subpackages

• intake_io.dataset
  • intake_io.dataset.cache
  • intake_io.dataset.dataset
  • intake_io.dataset.split
  • intake_io.dataset.util
• intake_io.fsspec
  • intake_io.fsspec.flywheel
  • intake_io.fsspec.render
• intake_io.source
  • intake_io.source.auto
  • intake_io.source.base
  • intake_io.source.bioformats
  • intake_io.source.dicom
  • intake_io.source.directory
  • intake_io.source.filepattern
  • intake_io.source.imageio
  • intake_io.source.klb
  • intake_io.source.list
  • intake_io.source.nifti
  • intake_io.source.nrrd
  • intake_io.source.tif

Submodules

• intake_io.autodetect
• intake_io.io
• intake_io.util

Package Contents

Functions

get_axes(x: Any) → str	Get axis order given image, shape or number of dimensions.
get_spatial_axes(x: Any)
get_spacing(image: Union[xarray.Dataset, xarray.DataArray], axes: Optional[str] = None) → Union[Tuple[Optional[float], Ellipsis], Optional[float]]	Get pixel spacing of image or specific image axes.
get_spacing_units(image: Union[xarray.Dataset, xarray.DataArray], axes: Optional[str] = None) → Union[Tuple[Optional[str], Ellipsis], Optional[str]]	Get pixel spacing unit of image or specific image axes.
to_numpy(image: Union[xarray.Dataset, xarray.DataArray, numpy.ndarray]) → numpy.ndarray	Get pixel array of image.
to_xarray(image: Any, spacing: Union[Dict[str, Optional[float]], Tuple[Optional[float], Ellipsis], None] = None, axes: Optional[str] = None, coords: Optional[Dict[str, Any]] = None, spacing_units: Union[Dict[str, Optional[str]], Tuple[Optional[str], Ellipsis], None] = None, name: Optional[str] = None, attrs: Optional[Dict[str, Any]] = None, partition: Optional[Any] = None) → xarray.DataArray	Combine inputs to xarray.DataArray.
get_catalog(sources: Iterable[intake.source.DataSource], filepath: Optional[str] = None) → str	Get catalog yml of data sources.
partition_gen(image: Union[xarray.DataArray, xarray.Dataset], inner_axes: str, uri: str, multikey: bool = False, sep_outer: str = '.', sep_inner: str = '_') → Generator[Tuple[Union[xarray.DataArray, xarray.Dataset], str], None, None]
clean_yaml(data: Dict[str, Any], rename_to: Optional[str] = None) → Dict[str, Any]	Utility function to clean YAML representation of intake source.
autodetect
imload(uri: str, partition: Optional[Any] = None, metadata_only: bool = False, **kwargs) → xarray.Dataset	Load image, autodetect source type.
imsave(image: Any, uri: str, compress: Optional[bool] = None, partition: Optional[str] = None, **kwargs)	Save image, autodetect format.

intake_io.get_axes(x: Any) → str

Get axis order given image, shape or number of dimensions.

Supported axes

Name	Dimension
i	image index
t	time
c	channel
z	z
y	y
x	x

Uses metadata where available (xarray data structures), otherwise assumes itczyx-ordering (intake_io default) using the last ndim axes. The only exception are 2D RGB images, which may be cyx or yxc.

Parameters

image –

One of the following types:

• xarray.Dataset

• xarray.DataArray

• numpy.ndarray

• dask.Array

• tuple (shape)

• int (number of dimensions)

Returns

Axis order, e.g. “tzyx”

intake_io.get_spatial_axes(x: Any)

intake_io.get_spacing(image: Union[xarray.Dataset, xarray.DataArray], axes: Optional[str] = None) → Union[Tuple[Optional[float], Ellipsis], Optional[float]]

Get pixel spacing of image or specific image axes.

The return value for an axis without spacing metadata is either None or 1.0, depending on what format the image was loaded from. None is preferred.

Parameters

• image – Image

• axes – Specific axes and ordering, or None for all axes in image dim order.

Returns

Pixel spacing as tuple, or directly if a single axis is requested.

intake_io.get_spacing_units(image: Union[xarray.Dataset, xarray.DataArray], axes: Optional[str] = None) → Union[Tuple[Optional[str], Ellipsis], Optional[str]]

Get pixel spacing unit of image or specific image axes.

The return value for an axis without spacing metadata is None.

Parameters

• image – Image

• axes – Specific axes and ordering, or None for all axes in image dim order.

Returns

Pixel spacing units as tuple, or directly if a single axis is requested.

intake_io.to_numpy(image: Union[xarray.Dataset, xarray.DataArray, numpy.ndarray]) → numpy.ndarray

Get pixel array of image.

Parameters

image – Image

Returns

Array

intake_io.to_xarray(image: Any, spacing: Union[Dict[str, Optional[float]], Tuple[Optional[float], Ellipsis], None] = None, axes: Optional[str] = None, coords: Optional[Dict[str, Any]] = None, spacing_units: Union[Dict[str, Optional[str]], Tuple[Optional[str], Ellipsis], None] = None, name: Optional[str] = None, attrs: Optional[Dict[str, Any]] = None, partition: Optional[Any] = None) → xarray.DataArray

Combine inputs to xarray.DataArray.

Preserve metadata where available and possible.

Parameters

• image – The image.

• spacing – Time resolution and pixel spacing, as dict (axes are keys) or tuple (in image axes order, ignoring the discontinuous axes “c” and “i”). Axes without pixel spacing metadata can be omitted (dict) or set to None (dict and tuple).

• axes – The image axes, e.g. “tyz”.

• coords – Axis coordinates for axes not covered by the spacing parameter (e.g. channel names), or to overwrite the spacing parameter with e.g. non-uniform spacing values.

• spacing_units – Time resolution and pixel spacing units, as dict (axes are keys) or tuple (in image axes order, ignoring the discontinuous axes “c” and “i”). Axes without pixel spacing metadata can be omitted (dict) or set to None (dict and tuple).

• name – Name

• attrs – Additional metadata

• partition – Partition

Returns

Image and any metadata

intake_io.get_catalog(sources: Iterable[intake.source.DataSource], filepath: Optional[str] = None) → str

Get catalog yml of data sources.

Parameters

• sources – Data sources

• filepath – File path to save catalog to, or None if saving the result to file is not intended.

Returns

The yml text

intake_io.partition_gen(image: Union[xarray.DataArray, xarray.Dataset], inner_axes: str, uri: str, multikey: bool = False, sep_outer: str = '.', sep_inner: str = '_') → Generator[Tuple[Union[xarray.DataArray, xarray.Dataset], str], None, None]

intake_io.clean_yaml(data: Dict[str, Any], rename_to: Optional[str] = None) → Dict[str, Any]

Utility function to clean YAML representation of intake source.

Used during creation of YAML catalog from list of sources.

Parameters

• data – Dict[str, Any]

• rename_to – Optional[str]

Returns

Cleaned dict

intake_io.autodetect(uri: str, **kwargs) → intake.source.DataSource

Autodetect intake source given URI.

Keyword arguments are passed to the source constructor.

If no other source is more suitable, it returns an instance of intake_io.source.ImageIOSource, which uses imageio.

This function doesn’t check whether the data can actually be loaded.

Parameters

• uri – URI (e.g. file system path or URL)

• kwargs – Arguments passed to the source constructor

Returns

Data source

intake_io.imload(uri: str, partition: Optional[Any] = None, metadata_only: bool = False, **kwargs) → xarray.Dataset

Load image, autodetect source type.

Parameters

• uri (str) –

• partition (Optional[Any]) – Load only a partition of the image

• metadata_only (bool) – Load metadata only

• kwargs –

  Additional arguments passed to the source constructor. Notable fields supported by all subclasses of intake_io.source.base.ImageSource are:

  • output_axis_order (Optional[str]) – Deviate from default “itczyx” output axis ordering, or None to use original axis ordering of the data

  • metadata (Optional[Dict[str, Any]]) – Add or overrule metadata fields, for instance:

    metadata={
        "axes": "tcxy",                      # specify input axis order
        "spacing": {"t": 0.3},               # overrule spacing
        "spacing_units": {"t": "ms"},        # overrule spacing unit
        "coords": {"c": ["nuclei", "actin"]} # use specific channel names
    }
    

Returns

image

Return type

xarray.Dataset

intake_io.imsave(image: Any, uri: str, compress: Optional[bool] = None, partition: Optional[str] = None, **kwargs)

Save image, autodetect format.

Format is chosen based on URI extension. Defaults to .zarr if no extension is given.

image is automatically split into multiple files if the output format doesn’t support saving it in a single file. For instance, TIF hyperstacks support single arrays with up to tzcyx axes. An xarray.Dataset with multiple variables (e.g. “image” and “segmentation”) and extra axes (e.g. multiple image arrays along the i-axis) is saved as multiple files according to the following pattern (axes are separated by ., key and value are separated by _):

/path/to/filename.var_image.i_00.tif
/path/to/filename.var_image.i_01.tif
...
/path/to/filename.var_segmentation.i_00.tif
/path/to/filename.var_segmentation.i_01.tif
...

The indexes used in the file name are the actual xarray.DataArray coordinates along their respective axes, e.g. if our i coordinates are [3, 10] or ["control", "treatment"] then we’ll get file names containing “i_03” or “i_treatment”. The data variable key (e.g. “var_segmentation” in the example above) is omitted from the output file name if image doesn’t have multiple data variables or if it isn’t an xarray.Dataset.

The partition argument controls the partitioning scheme. By default, image is split only if needed, and into as few files as possible. In contrast, e.g. partition="tyx" partitions the data into files containing only the given axes, in order (axes are reordered as needed), yielding e.g. the following file pattern:

/path/to/filename.var_image.i_03.c_actin.tif
/path/to/filename.var_image.i_03.c_nuclei.tif
/path/to/filename.var_image.i_21.c_actin.tif
/path/to/filename.var_image.i_21.c_nuclei.tif
...
/path/to/filename.var_segmentation.i_03.c_actin.tif
/path/to/filename.var_segmentation.i_03.c_nuclei.tif
/path/to/filename.var_segmentation.i_21.c_actin.tif
/path/to/filename.var_segmentation.i_21.c_nuclei.tif
...

See File patterns section of this documentation for help with loading these file patterns.

Parameters

• image (Any) –

• uri (str) –

• compress (Optional[bool]) – Whether or not to compress the data. Default value None defers decision to backend. Where applicable, compression algorithm and parameters are chosen as a trade-off of compatibility, compression ratio and I/O performance. If compression is requested but unsupported, the data is saved uncompressed and no exception is raised.

• partition (Optional[str]) – Partition the data as needed into multiple files, each containing the given axes, in the given order. By default, as few files as possible are created.