lib5c.util.donut module

Module containing utility functions related to creating and using donut-shaped windows in the style of Rao et al. (Cell 2014).

lib5c.util.donut.donut_footprint(p, w)[source]

Constructs a donut footprint matrix.

Parameters
  • p (int) – The inner radius of the donut.

  • w (int) – The outer radius of the donut.

Returns

Square matrix containing 1s in the positions selected by the footprint and 0s in the positions ignored by the footprint.

Return type

np.ndarray with int dtype

Notes

This function is duplicated in lib5c.algorithms.donut_filters.donut_filt() to preserve easy synchronization of that inherited module.

Examples

>>> donut_footprint(1, 3)
array([[1, 1, 1, 0, 1, 1, 1],
       [1, 1, 1, 0, 1, 1, 1],
       [1, 1, 0, 0, 0, 1, 1],
       [0, 0, 0, 0, 0, 0, 0],
       [1, 1, 0, 0, 0, 1, 1],
       [1, 1, 1, 0, 1, 1, 1],
       [1, 1, 1, 0, 1, 1, 1]])
lib5c.util.donut.lower_left_footprint(p, w)[source]

Creates a lower left donut filter footprint.

Parameters
  • p (int) – Inner radius of donut.

  • w (int) – Outer radius of donut.

Returns

The desired footprint. Square array with shape (2*w+1, 2*w+1).

Return type

np.ndarray

lib5c.util.donut.make_donut_selector(i, j, p, w, n)[source]

Creates a boolean selector array with a donut shape around a particular coordinate to be used to index into a square matrix of known size.

Parameters
  • i (int) – The row index of the point around which the donut should be constructed.

  • j (int) – The column index of the point around which the donut should be constructed.

  • p (int) – The inner radius of the donut.

  • w (int) – The outer radius of the donut.

  • n (int) – The size of the target matrix.

Returns

The donut selector. It will have boolean dtype and shape (n, n).

Return type

np.ndarray

Examples

>>> make_donut_selector(5, 4, 1, 3, 10).astype(int)
array([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 1, 1, 1, 0, 1, 1, 1, 0, 0],
       [0, 1, 1, 1, 0, 1, 1, 1, 0, 0],
       [0, 1, 1, 0, 0, 0, 1, 1, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 1, 1, 0, 0, 0, 1, 1, 0, 0],
       [0, 1, 1, 1, 0, 1, 1, 1, 0, 0],
       [0, 1, 1, 1, 0, 1, 1, 1, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])
>>> make_donut_selector(5, 1, 1, 3, 10).astype(int)
array([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [1, 0, 1, 1, 1, 0, 0, 0, 0, 0],
       [1, 0, 1, 1, 1, 0, 0, 0, 0, 0],
       [0, 0, 0, 1, 1, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 1, 1, 0, 0, 0, 0, 0],
       [1, 0, 1, 1, 1, 0, 0, 0, 0, 0],
       [1, 0, 1, 1, 1, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])
>>> make_donut_selector(5, 8, 1, 3, 10).astype(int)
array([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 1, 1, 1, 0, 1],
       [0, 0, 0, 0, 0, 1, 1, 1, 0, 1],
       [0, 0, 0, 0, 0, 1, 1, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 1, 1, 0, 0, 0],
       [0, 0, 0, 0, 0, 1, 1, 1, 0, 1],
       [0, 0, 0, 0, 0, 1, 1, 1, 0, 1],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])
>>> make_donut_selector(1, 5, 1, 3, 10).astype(int)
array([[0, 0, 1, 1, 0, 0, 0, 1, 1, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 1, 1, 0, 0, 0, 1, 1, 0],
       [0, 0, 1, 1, 1, 0, 1, 1, 1, 0],
       [0, 0, 1, 1, 1, 0, 1, 1, 1, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])
>>> make_donut_selector(8, 5, 1, 3, 10).astype(int)
array([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 1, 1, 1, 0, 1, 1, 1, 0],
       [0, 0, 1, 1, 1, 0, 1, 1, 1, 0],
       [0, 0, 1, 1, 0, 0, 0, 1, 1, 0],
       [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
       [0, 0, 1, 1, 0, 0, 0, 1, 1, 0]])
lib5c.util.donut.pad_and_crop(x, margin, limit)[source]

Utility function to assist in padding and cropping footprints.

Parameters
  • x (int) – The coordinate of the point in question.

  • margin (int) – The size of a buffer around x which should not be included in the padding. In the context of padding and cropping footprints, this is the outer radius of the footprint. Whatever part of the margin extends beyond the limit must be cropped away.

  • limit (int) – The coordinate of the edge (extreme allowed index) of the desired final matrix.

Returns

The first int is the number of pixels to pad by, the second is the number of pixels that must be cropped away after padding.

Return type

int, int

Examples

>>> pad_and_crop(0, 3, 0)
(0, 3)
>>> pad_and_crop(5, 3, 5)
(0, 3)
>>> pad_and_crop(3, 3, 0)
(0, 0)
>>> pad_and_crop(3, 2, 5)
(0, 0)
>>> pad_and_crop(5, 3, 0)
(2, 0)
>>> pad_and_crop(3, 3, 10)
(4, 0)