impy.lazy package

Submodules

impy.lazy.core module

impy.lazy.core.arange(stop: int, dtype: DTypeLike = None) → LazyImgArray[source]

impy.lazy version of numpy.arange. This function has additional parameters axes and name. Original docstring follows.

axesstr, optional

Image axes. Must be same length as image dimension.

name: str, optional

Image name.

like: MetaArray, optional

Reference array from which name and axes will be copied.

Return evenly spaced values from start to stop with step size step.

The values are half-open [start, stop), so including start and excluding stop. This is basically the same as python’s range function but for dask arrays.

When using a non-integer step, such as 0.1, the results will often not be consistent. It is better to use linspace for these cases.

Parameters:

  • start (int, optional) – The starting value of the sequence. The default is 0.

  • stop (int) – The end of the interval, this value is excluded from the interval.

  • step (int, optional) – The spacing between the values. The default is 1 when not specified. The last value of the sequence.

  • chunks (int) – The number of samples on each block. Note that the last block will have fewer samples if len(array) % chunks != 0. Defaults to “auto” which will automatically determine chunk sizes.

  • dtype (numpy.dtype) – Output dtype. Omit to infer it from start, stop, step Defaults to None.

  • like (array type or None) – Array to extract meta from. Defaults to None.

Returns:

samples

Return type:

dask array

See also

dask.array.linspace

impy.lazy.core.array(arr: ArrayLike, /, dtype: DTypeLike = None, *, copy: bool = True, chunks='auto', name: str = None, axes: str = None, like: MetaArray | None = None) → LazyImgArray[source]

make an LazyImgArray object, like np.array(x)

Parameters:

  • arr (array-like) – Base array.

  • copy (bool, default is True) – If True, a copy of the original array is made.

  • dtype (data type, optional) – Image data type.

  • name (str, optional) – Name of image.

  • axes (str, optional) – Image axes.

Return type:

LazyImgArray

impy.lazy.core.asarray(arr: ArrayLike, dtype: DTypeLike | None = None, *, name: str | None = None, axes: str | None = None, like: MetaArray | None = None, chunks='auto') → LazyImgArray[source]

make an LazyImgArray object, like np.asarray(x)

Parameters:

  • arr (array-like) – Base array.

  • dtype (data type, optional) – Image data type.

  • name (str, optional) – Name of image.

  • axes (str, optional) – Image axes.

  • copy (bool, default is True) – If True, a copy of the original array is made.

Return type:

ImgArray

impy.lazy.core.empty(shape: ShapeLike, dtype: DTypeLike = <class 'numpy.uint16'>, *, name: str | None = None, axes: AxesLike | None = None, like: MetaArray | None = None) → LazyImgArray[source]

impy.lazy version of numpy.empty. This function has additional parameters axes and name. Original docstring follows.

axesstr, optional

Image axes. Must be same length as image dimension.

name: str, optional

Image name.

like: MetaArray, optional

Reference array from which name and axes will be copied.

Blocked variant of empty_like

Follows the signature of empty_like exactly except that it also features optional keyword arguments chunks: int, tuple, or dict and name: str.

Original signature follows below.

empty_like(prototype, dtype=None, order=’K’, subok=True, shape=None)

Return a new array with the same shape and type as a given array.

Parameters:

  • prototype (array_like) – The shape and data-type of prototype define these same attributes of the returned array.

  • dtype (data-type, optional) –

    Overrides the data type of the result.

    New in version 1.6.0.

  • order ({'C', 'F', 'A', or 'K'}, optional) –

    Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if prototype is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of prototype as closely as possible.

    New in version 1.6.0.

  • subok (bool, optional.) – If True, then the newly created array will use the sub-class type of prototype, otherwise it will be a base-class array. Defaults to True.

  • shape (int or sequence of ints, optional.) –

    Overrides the shape of the result. If order=’K’ and the number of dimensions is unchanged, will try to keep order, otherwise, order=’C’ is implied.

    New in version 1.17.0.

Returns:

out – Array of uninitialized (arbitrary) data with the same shape and type as prototype.

Return type:

ndarray

See also

ones_like

Return an array of ones with shape and type of input.

zeros_like

Return an array of zeros with shape and type of input.

full_like

Return a new array with shape of input filled with value.

empty

Return a new uninitialized array.

Notes

This function does not initialize the returned array; to do that use zeros_like or ones_like instead. It may be marginally faster than the functions that do set the array values.

Examples

>>> a = ([1,2,3], [4,5,6])                         # a is array-like
>>> np.empty_like(a)
array([[-1073741821, -1073741821,           3],    # uninitialized
       [          0,           0, -1073741821]])
>>> a = np.array([[1., 2., 3.],[4.,5.,6.]])
>>> np.empty_like(a)
array([[ -2.00000715e+000,   1.48219694e-323,  -2.00000572e+000], # uninitialized
       [  4.38791518e-305,  -2.00000715e+000,   4.17269252e-309]])
impy.lazy.core.full(shape: ShapeLike, fill_value: Any, dtype: DTypeLike = <class 'numpy.uint16'>, *, name: str | None = None, axes: AxesLike | None = None, like: MetaArray | None = None) → LazyImgArray[source]

impy.lazy version of numpy.full. This function has additional parameters axes and name. Original docstring follows.

axesstr, optional

Image axes. Must be same length as image dimension.

name: str, optional

Image name.

like: MetaArray, optional

Reference array from which name and axes will be copied.

Blocked variant of full_like

Follows the signature of full_like exactly except that it also features optional keyword arguments chunks: int, tuple, or dict and name: str.

Original signature follows below.

Return a full array with the same shape and type as a given array.

Parameters:

  • a (array_like) – The shape and data-type of a define these same attributes of the returned array.

  • fill_value (array_like) – Fill value.

  • dtype (data-type, optional) – Overrides the data type of the result.

  • order ({'C', 'F', 'A', or 'K'}, optional) – Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible.

  • subok (bool, optional.) – If True, then the newly created array will use the sub-class type of a, otherwise it will be a base-class array. Defaults to True.

  • shape (int or sequence of ints, optional.) –

    Overrides the shape of the result. If order=’K’ and the number of dimensions is unchanged, will try to keep order, otherwise, order=’C’ is implied.

    New in version 1.17.0.

Returns:

out – Array of fill_value with the same shape and type as a.

Return type:

ndarray

See also

empty_like

Return an empty array with shape and type of input.

ones_like

Return an array of ones with shape and type of input.

zeros_like

Return an array of zeros with shape and type of input.

full

Return a new array of given shape filled with value.

Examples

>>> x = np.arange(6, dtype=int)
>>> np.full_like(x, 1)
array([1, 1, 1, 1, 1, 1])
>>> np.full_like(x, 0.1)
array([0, 0, 0, 0, 0, 0])
>>> np.full_like(x, 0.1, dtype=np.double)
array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1])
>>> np.full_like(x, np.nan, dtype=np.double)
array([nan, nan, nan, nan, nan, nan])

>>> y = np.arange(6, dtype=np.double)
>>> np.full_like(y, 0.1)
array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1])

>>> y = np.zeros([2, 2, 3], dtype=int)
>>> np.full_like(y, [0, 0, 255])  
array([[[  0,   0, 255],
        [  0,   0, 255]],
       [[  0,   0, 255],
        [  0,   0, 255]]])
impy.lazy.core.imread(path: str, chunks='auto', *, name: str | None = None, squeeze: bool = False) → LazyImgArray[source]

Read an image lazily. Image file is first opened as an memory map, and subsequently converted to numpy.ndarray or cupy.ndarray chunkwise by dask.array.map_blocks.

Parameters:

  • path (str) – Path to the file.

  • chunks (optional) – Specify chunk sizes. By default, yx-axes are assigned to the same chunk for every slice of image, whild chunk sizes of the rest of axes are automatically set with “auto” option.

  • name (str, optional) – Name of array.

  • squeeze (bool, default is False) – If True and there is one-sized axis, then call np.squeeze.

Return type:

LazyImgArray

impy.lazy.core.indices(dimensions: ShapeLike, dtype: DTypeLike = <class 'numpy.uint16'>, *, name: str | None = None, axes: AxesLike | None = None, like: MetaArray | None = None) → AxesTuple[LazyImgArray][source]

Copy of numpy.indices.

Parameters:

  • dimensions (shape-like) – The shape of the grid.

  • dtype (dtype, optional) – Data type of the result.

  • name (str, optional) – Name of the result arrays.

  • axes (AxesLike, optional) – Axes of the result arrays.

  • like (MetaArray, optional) – Reference array from which name and axes will be copied.

Return type:

tuple of LazyImgArray

impy.lazy.core.ones(shape: ShapeLike, dtype: DTypeLike = <class 'numpy.uint16'>, *, name: str | None = None, axes: AxesLike | None = None, like: MetaArray | None = None) → LazyImgArray[source]

impy.lazy version of numpy.ones. This function has additional parameters axes and name. Original docstring follows.

axesstr, optional

Image axes. Must be same length as image dimension.

name: str, optional

Image name.

like: MetaArray, optional

Reference array from which name and axes will be copied.

Blocked variant of ones_like

Follows the signature of ones_like exactly except that it also features optional keyword arguments chunks: int, tuple, or dict and name: str.

Original signature follows below.

Return an array of ones with the same shape and type as a given array.

Parameters:

  • a (array_like) – The shape and data-type of a define these same attributes of the returned array.

  • dtype (data-type, optional) –

    Overrides the data type of the result.

    New in version 1.6.0.

  • order ({'C', 'F', 'A', or 'K'}, optional) –

    Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible.

    New in version 1.6.0.

  • subok (bool, optional.) – If True, then the newly created array will use the sub-class type of a, otherwise it will be a base-class array. Defaults to True.

  • shape (int or sequence of ints, optional.) –

    Overrides the shape of the result. If order=’K’ and the number of dimensions is unchanged, will try to keep order, otherwise, order=’C’ is implied.

    New in version 1.17.0.

Returns:

out – Array of ones with the same shape and type as a.

Return type:

ndarray

See also

empty_like

Return an empty array with shape and type of input.

zeros_like

Return an array of zeros with shape and type of input.

full_like

Return a new array with shape of input filled with value.

ones

Return a new array setting values to one.

Examples

>>> x = np.arange(6)
>>> x = x.reshape((2, 3))
>>> x
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.ones_like(x)
array([[1, 1, 1],
       [1, 1, 1]])

>>> y = np.arange(3, dtype=float)
>>> y
array([0., 1., 2.])
>>> np.ones_like(y)
array([1.,  1.,  1.])
impy.lazy.core.zeros(shape: ShapeLike, dtype: DTypeLike = <class 'numpy.uint16'>, *, name: str | None = None, axes: AxesLike | None = None, like: MetaArray | None = None) → LazyImgArray[source]

impy.lazy version of numpy.zeros. This function has additional parameters axes and name. Original docstring follows.

axesstr, optional

Image axes. Must be same length as image dimension.

name: str, optional

Image name.

like: MetaArray, optional

Reference array from which name and axes will be copied.

Blocked variant of zeros_like

Follows the signature of zeros_like exactly except that it also features optional keyword arguments chunks: int, tuple, or dict and name: str.

Original signature follows below.

Return an array of zeros with the same shape and type as a given array.

Parameters:

  • a (array_like) – The shape and data-type of a define these same attributes of the returned array.

  • dtype (data-type, optional) –

    Overrides the data type of the result.

    New in version 1.6.0.

  • order ({'C', 'F', 'A', or 'K'}, optional) –

    Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible.

    New in version 1.6.0.

  • subok (bool, optional.) – If True, then the newly created array will use the sub-class type of a, otherwise it will be a base-class array. Defaults to True.

  • shape (int or sequence of ints, optional.) –

    Overrides the shape of the result. If order=’K’ and the number of dimensions is unchanged, will try to keep order, otherwise, order=’C’ is implied.

    New in version 1.17.0.

Returns:

out – Array of zeros with the same shape and type as a.

Return type:

ndarray

See also

empty_like

Return an empty array with shape and type of input.

ones_like

Return an array of ones with shape and type of input.

full_like

Return a new array with shape of input filled with value.

zeros

Return a new array setting values to zero.

Examples

>>> x = np.arange(6)
>>> x = x.reshape((2, 3))
>>> x
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.zeros_like(x)
array([[0, 0, 0],
       [0, 0, 0]])

>>> y = np.arange(3, dtype=float)
>>> y
array([0., 1., 2.])
>>> np.zeros_like(y)
array([0.,  0.,  0.])

impy.lazy.random module

class impy.lazy.random.ImageGenerator(rng: Generator)[source]

Bases: object

normal(loc: float | ndarray = 0.0, scale: float | ndarray = 1.0, size: int | tuple[int, ...] | None = None, *, axes: Iterable[str | Axis] | None = None, name: str | None = None, like: MetaArray | LazyImgArray = None, chunks='auto') → LazyImgArray[source]
poisson(lam: float, size: int | tuple[int, ...] | None = None, *, axes: Iterable[str | Axis] | None = None, name: str | None = None, like: MetaArray | LazyImgArray = None, chunks='auto') → LazyImgArray[source]
random(size: int | tuple[int, ...] | None = None, dtype=<class 'numpy.float32'>, *, axes: ~typing.Iterable[str | ~impy.axes._axis.Axis] | None = None, name: str | None = None, like: ~impy.arrays.bases.metaarray.MetaArray | ~impy.arrays.lazy.LazyImgArray = None, chunks='auto') → LazyImgArray[source]
random_uint16(size, *, name: str = None, axes: str = None, like: MetaArray | LazyImgArray = None, chunks='auto') → LazyImgArray[source]
random_uint8(size: int | tuple[int], *, name: str = None, axes: str = None, like: MetaArray | LazyImgArray = None, chunks='auto') → LazyImgArray[source]
standard_exponential(size: int | tuple[int, ...] | None = None, dtype=None, method: Literal['zig', 'inv'] = None, *, axes: Iterable[str | Axis] | None = None, name: str | None = None, like: MetaArray | LazyImgArray = None, chunks='auto') → LazyImgArray[source]
standard_normal(size: int | tuple[int, ...] | None = None, dtype=None, *, axes: Iterable[str | Axis] | None = None, name: str | None = None, like: MetaArray | LazyImgArray = None, chunks='auto') → LazyImgArray[source]
impy.lazy.random.default_rng(seed) → ImageGenerator[source]

Get the default random number generator.

impy.lazy.random.normal(loc=0.0, scale=1.0, size=None)[source]

Draw random samples from a normal (Gaussian) distribution.

The probability density function of the normal distribution, first derived by De Moivre and 200 years later by both Gauss and Laplace independently [2], is often called the bell curve because of its characteristic shape (see the example below).

The normal distributions occurs often in nature. For example, it describes the commonly occurring distribution of samples influenced by a large number of tiny, random disturbances, each with its own unique distribution [2].

Note

New code should use the ~numpy.random.Generator.normal method of a ~numpy.random.Generator instance instead; please see the random-quick-start.

Parameters:

  • loc (float or array_like of floats) – Mean (“centre”) of the distribution.

  • scale (float or array_like of floats) – Standard deviation (spread or “width”) of the distribution. Must be non-negative.

  • size (int or tuple of ints, optional) – Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. If size is None (default), a single value is returned if loc and scale are both scalars. Otherwise, np.broadcast(loc, scale).size samples are drawn.

Returns:

out – Drawn samples from the parameterized normal distribution.

Return type:

ndarray or scalar

See also

scipy.stats.norm

probability density function, distribution or cumulative density function, etc.

random.Generator.normal

which should be used for new code.

Notes

The probability density for the Gaussian distribution is

\[p(x) = \frac{1}{\sqrt{ 2 \pi \sigma^2 }} e^{ - \frac{ (x - \mu)^2 } {2 \sigma^2} },\]

where \(\mu\) is the mean and \(\sigma\) the standard deviation. The square of the standard deviation, \(\sigma^2\), is called the variance.

The function has its peak at the mean, and its “spread” increases with the standard deviation (the function reaches 0.607 times its maximum at \(x + \sigma\) and \(x - \sigma\) [2]). This implies that normal is more likely to return samples lying close to the mean, rather than those far away.

References

Examples

Draw samples from the distribution:

>>> mu, sigma = 0, 0.1 # mean and standard deviation
>>> s = np.random.normal(mu, sigma, 1000)

Verify the mean and the variance:

>>> abs(mu - np.mean(s))
0.0  # may vary

>>> abs(sigma - np.std(s, ddof=1))
0.1  # may vary

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, density=True)
>>> plt.plot(bins, 1/(sigma * np.sqrt(2 * np.pi)) *
...                np.exp( - (bins - mu)**2 / (2 * sigma**2) ),
...          linewidth=2, color='r')
>>> plt.show()

Two-by-four array of samples from the normal distribution with mean 3 and standard deviation 2.5:

>>> np.random.normal(3, 2.5, size=(2, 4))
array([[-4.49401501,  4.00950034, -1.81814867,  7.29718677],   # random
       [ 0.39924804,  4.68456316,  4.99394529,  4.84057254]])  # random
impy.lazy.random.random(size=None)[source]

Return random floats in the half-open interval [0.0, 1.0). Alias for random_sample to ease forward-porting to the new random API.

impy.lazy.random.random_uint16(size, *, name: str = None, axes: str = None, like: MetaArray | LazyImgArray = None, chunks='auto') → LazyImgArray[source]

Return a random uint16 image, ranging 0-65535.

Parameters:

  • size (int or tuple of int) – Image shape.

  • name (str, optional) – Image name.

  • axes (str, optional) – Image axes.

Returns:

Random Image in dtype np.uint16.

Return type:

ImgArray

impy.lazy.random.random_uint8(size: int | tuple[int], *, name: str = None, axes: str = None, like: MetaArray | LazyImgArray = None, chunks='auto') → LazyImgArray[source]

Return a random uint8 image, ranging 0-255.

Parameters:

  • size (int or tuple of int) – Image shape.

  • name (str, optional) – Image name.

  • axes (str, optional) – Image axes.

Returns:

Random Image in dtype np.uint8.

Return type:

ImgArray

Module contents