cryosparc.util

Functions:

bopen(file[, mode])	"with open(...)" alias for binary files that tranparently yields an open file or file-like object.
default_rng([seed])	Create a numpy random number generator or RandomState (depending on numpy version)
first()	Get the first item from the given iterator.
noopcontext()	Context manager that yields the given argument without modification.
padarray(arr[, dim, val])	Pad the given 2D or 3D array so that the x and y dimensions are equal to the given dimension.
random_integers(rng, low[, high, size, dtype])	Generic way to get random integers from a numpy random generator (or RandomState for older numpy).
strbytelen(s)	Get the number of bytes in a string's UTF-8 representation.
strencodenull(s)	Encode string-like value into UTF-8 binary ending with a null-character terminator .
topen(file[, mode])	"with open(...)" alias for text files that tranparently yields open file or file-like object.
trimarray(arr, shape)	Crop the given 2D or 3D array into the given shape.
u32bytesle(x)	Get the uint32 bytes of for integer x in little endian.
u32intle(buffer)	Get int from buffer representing a uint32 integer in little endian.

Classes:

hashcache(_f)

Simple utility class to cache the result of a mapping and avoid excessive heap allocation.

cryosparc.util.OpenBinaryMode(*args, **kwargs)

Binary file read or write open modes.

alias of Literal[‘rb’, ‘wb’, ‘xb’, ‘ab’, ‘r+b’, ‘w+b’, ‘x+b’, ‘a+b’]

cryosparc.util.OpenTextMode(*args, **kwargs)

Text file read or write open modes.

alias of Literal[‘r’, ‘w’, ‘x’, ‘a’, ‘r+’, ‘w+’, ‘x+’, ‘a+’]

cryosparc.util.Result(*args, **kwargs)

Use as the return type for functions that may return either a value or an error.

Example

>>> def safe_divide(x: float, y: float) -> Result[int, str]:
...     if y == 0:
...         return None, "divide by zero detected"
...     else:
...         return x / y, None

alias of Union[Tuple[T, None], Tuple[None, E]]

cryosparc.util.bopen(file: Union[str, PurePath, IO[bytes]], mode: Literal['rb', 'wb', 'xb', 'ab', 'r+b', 'w+b', 'x+b', 'a+b'] = 'rb')

“with open(…)” alias for binary files that tranparently yields an open file or file-like object.

Parameters:

• file (str | Path | IO) – binary file path or handle

• mode (OpenBinaryMode, optional) – File open mode. Defaults to “rb”.

Yields:

IO – Binary file handle

cryosparc.util.default_rng(seed=None) → Generator

Create a numpy random number generator or RandomState (depending on numpy version)

Parameters:

seed (Any, optional) – Seed to initialize generator with. Defaults to None.

Returns:

Random number generator

Return type:

numpy.random.Generator

cryosparc.util.first(it: Union[Iterator[V], Sequence[V]]) → Optional[V]

cryosparc.util.first(it: Union[Iterator[V], Sequence[V]], default: V) → V

Get the first item from the given iterator. Returns None if the iterator is empty.

Parameters:

it (Iterator[V] | Sequence[V]) – Iterator or list-like accessor.

Returns:

First item in the list or iterator (consuming it if required).

Return type:

V | None

class cryosparc.util.hashcache(_f: Callable[[K], V])

Simple utility class to cache the result of a mapping and avoid excessive heap allocation. Initialize with cache = hashcache(f) and use cache as the mapping function.

Examples

Unoptimized code for convering bytes to str:

>>> a = [b"Hello", b"Hello", b"Hello"]
>>> strs = list(map(bytes.decode, a))

The input array a has duplicate items. Using bytes.decode directly in the mapping causes Python to allocate a fresh string for each bytes.

Here is the optimized version with hashcache:

>>> a = [b"Hello", b"Hello", b"Hello"]
>>> strs = list(map(hashcache(bytes.decode), a))

This only allocates heap memory once for each unique item in the input list. After the first encounter, the map callable returns the previously-computed value of the same input, reducing heap usage and allocation calls by a factor of 3.

For this to be most effective, ensure the given f function is pure and stable (i.e., always returns the same result for a given input).

May also be used as a decorator (must take a single hashable argument):

>>> @hashcache
>>> def f(x): ...

cryosparc.util.noopcontext() → ContextManager[None]

cryosparc.util.noopcontext(x: T) → ContextManager[T]

Context manager that yields the given argument without modification.

Parameters:

x (T, optional) – Anything. Defaults to None.

Yields:

T – the given argument

cryosparc.util.padarray(arr: NDArray, dim: Optional[int] = None, val: number = 0.0)

Pad the given 2D or 3D array so that the x and y dimensions are equal to the given dimension. If not dimension is given, will use the maximum of the width and height.

Parameters:

• arr (NDArray) – 2D or 3D Numpy array to pad

• dim (int, optional) – Minimum desired dimension of micrograph. Defaults to None.

• val (float, optional) – Value to pad with, should be a numpy number instance with the same dtype as the given array. Defaults to n.float32(0).

Returns:

Padded copy of given array.

Return type:

NDArray

cryosparc.util.random_integers(rng: n.random.Generator, low: int, high: ~typing.Optional[int] = None, size: ~typing.Union[int, ~typing.Tuple[int, ...], ~typing.Literal[None]] = None, dtype: ~typing.Type[~cryosparc.util.INT] = <class 'numpy.uint64'>) → NDArray[INT]

Generic way to get random integers from a numpy random generator (or RandomState for older numpy).

Parameters:

• rng (numpy.random.Generator) – random number generator

• low (int) – Low integer value, inclusive

• high (int, optional) – High integer value, exclusive. Defaults to None.

• size (Shape, optional) – Size or shape of resulting array. Defaults to None.

• dtype (Type[numpy.integer], optional) – Type of integer values to generate. Defaults to numpy.uint64.

Returns:

Numpy array of randomly-generated integers.

Return type:

NDArray

cryosparc.util.strbytelen(s: str) → int

Get the number of bytes in a string’s UTF-8 representation.

Parameters:

s (str) – string to test encoding for.

Returns:

number of bytes in encoded string.

Return type:

int

cryosparc.util.strencodenull(s: Any) → bytes

Encode string-like value into UTF-8 binary ending with a null-character terminator .

Parameters:

s (any) – string-like entity to encode.

Returns:

encoded string

Return type:

bytes

cryosparc.util.topen(file: Union[str, PurePath, IO[str]], mode: Literal['r', 'w', 'x', 'a', 'r+', 'w+', 'x+', 'a+'] = 'r')

“with open(…)” alias for text files that tranparently yields open file or file-like object.

Parameters:

• file (str | Path | IO) – Readable text file path or handle.

• mode (OpenTextMode, optional) – File open mode. Defaults to “r”.

Yields:

IO – Text file handle.

cryosparc.util.trimarray(arr: NDArray, shape: Tuple[int, ...])

Crop the given 2D or 3D array into the given shape. Will trim from the middle. May be used to undo padding from padarray() function.

Parameters:

• arr (NDArray) – 3D or 3D numpy array to crop

• shape (Shape) – New desired shape.

Returns:

Trimmed copy of the given array.

Return type:

NDArray

cryosparc.util.u32bytesle(x: int) → bytes

Get the uint32 bytes of for integer x in little endian.

Parameters:

x (int) – Integer to encode.

Returns:

Encoded integer bytes

Return type:

bytes

cryosparc.util.u32intle(buffer: bytes) → int

Get int from buffer representing a uint32 integer in little endian.

Parameters:

buffer (bytes) – 4 bytes representing little-endian integer.

Returns:

decoded integer

Return type:

int