cryosparc.util

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.

print_table(headings, rows)

Utility to print a formatted table given a list of headings (strings) and list of rows (list of strings same length as headings).

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 Tuple[T, None] | Tuple[None, E]

cryosparc.util.bopen(file: 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: Iterator[V] | Sequence[V]) → V | None#
cryosparc.util.first(it: 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: int | None = None, val: number = np.float32(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.print_table(headings: List[str], rows: List[List[str]])#

Utility to print a formatted table given a list of headings (strings) and list of rows (list of strings same length as headings).

cryosparc.util.random_integers(rng: n.random.Generator, low: int, high: int | None = None, size: int | ~typing.Tuple[int, ...] | 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: 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