Arrays and locations¶

class vitrio.Array¶

Memory that holds an image, a stack of images or a volume.

An Array owns its memory, which is what the reads that are not given an array return. numpy.asarray(array) views that memory, and so do torch.from_dlpack and jax.numpy.from_dlpack, since an Array speaks DLPack and the buffer protocol. Nothing is copied, and the memory stays alive for as long as anything views it.

property data_type¶: The NumericalType of the elements.

property shape¶: The extents of the array, slowest axis first, as a tuple.

class vitrio.NumericalType(*values)¶

The data type of the elements of an array or of a file.

Anywhere a data type is asked for, so is whatever names one of these: the name as a string (“float32”), a numpy dtype or type (np.float32), or a member of this enumeration.

boolean = 0¶

int8 = 1¶

uint8 = 2¶

int16 = 3¶

uint16 = 4¶

int32 = 5¶

uint32 = 6¶

int64 = 7¶

uint64 = 8¶

float16 = 9¶

float32 = 10¶

float64 = 11¶

complex_float16 = 12¶

complex_float32 = 13¶

complex_float64 = 14¶

class vitrio.ImageDescriptor(extents: collections.abc.Sequence[int], core_rank: int, data_type: vitrio._binding.NumericalType)¶

What an image file holds: its extents, core rank and data type.

The extents are given slowest axis first. The last core_rank of them are the shape of one image or volume, and the ones before them stack those: an ImageDescriptor((10, 64, 96), 2, “float32”) is a stack of ten images of 64 by 96. query_descriptor returns the descriptor of a file, and write takes the one a file is created with.

Describe what a file holds.

Parameters:

extents – The extents of the file, slowest axis first.
core_rank – How many of the last extents are one image or volume.
data_type – The NumericalType of the elements.

property core_rank¶: How many of the last extents are one image or volume.

property data_type¶: The NumericalType of the elements.

property extents¶: The extents of the whole file, slowest axis first, as a tuple.

vitrio.get_core_extents(descriptor: vitrio._binding.ImageDescriptor) → tuple[int, ...]¶

Get the shape of one image or volume of a file.

These are the last core_rank extents of the descriptor, which leaves out the axis a stack stacks along. It is the shape the destination of a batch carries behind its leading extent.

Parameters:: descriptor – The ImageDescriptor of the file.
Returns:: The extents of one image or volume.
Return type:: tuple

class vitrio.ImageLocation¶

class vitrio.ImageLocation(self, key: str | os.PathLike, index_in_stack: int = 18446744073709551615)

Names an image: a file and, for a stack, the index of one in it.

A location without an index names the whole file. It is what the reads and writes of batches are given a list of, so that the images of a batch may come from any number of files.

Overloaded function.

__init__(self) -> None

Make a location that names no file.

__init__(self, key: str | os.PathLike, index_in_stack: int = 18446744073709551615) -> None

Name an image.

Parameters:

key – The file, as the path that opens it.
index_in_stack – The image of the stack, counting from zero. Defaults to naming the whole file.

from_string(text: str) → vitrio._binding.ImageLocation¶

Parse the spelling a STAR file of RELION uses.

It is written “index@key”, the index counting from one, or “key” for a whole file. ImageLocation.from_string(“3@stack.mrcs”) is the third image of the stack, whose index_in_stack is 2.

Parameters:: text – The location, as written.
Returns:: The location it names.
Return type:: ImageLocation
Raises:: ValueError – If text is not a location.

property has_index_in_stack¶: Whether the location names one image of a stack.

property index_in_stack¶

The image of the stack, counting from zero.

It is ImageLocation.no_stack_index for a location that names the whole file.

property key¶: The file, as the path that opens it.

class vitrio.ImageLocationGrouping(locations: collections.abc.Sequence[vitrio._binding.ImageLocation])¶

A list of locations gathered by the file they are in.

The images of a file are then known together, which is what takes them into a scratch in as few reads of each file as it can. Indexing it gives one Group for each file.

Group the locations by file.

Parameters:: locations – A list of ImageLocation.

class Group¶

The images of one file that a grouping holds.

property indices¶: The indices in the stack of its images, as a tuple.

property is_whole¶: Whether the group is the whole file, not images of it.

property key¶: The file.

class vitrio.IndexTable¶

class vitrio.IndexTable(self, rank: int)

A list of indices of the same rank, such as the centres of patches.

Every index has as many coordinates as the table has rank, slowest axis first. numpy.asarray(table) copies them into an array with a row for each index, and IndexTable.from_array does the converse.

Overloaded function.

__init__(self) -> None

Make an empty table, whose rank its first index sets.

__init__(self, rank: int) -> None

Make an empty table.

Parameters:: rank – How many coordinates each index has.

from_array(indices: ndarray[device='cpu', writable=False]) → vitrio._binding.IndexTable¶

Make a table from an array of integers with a row for each index.

Parameters:

indices – A two-dimensional array of integers, such as numpy’s.

Returns:

The table, with the rank of the rows.

Return type:

IndexTable

Raises:

TypeError – If the array does not hold integers.
ValueError – If it is not two-dimensional or holds a negative index.

add(self, index: collections.abc.Sequence[int]) → None¶

Add an index to the end.

Parameters:: index – Its coordinates, as many as the rank of the table.

clear(self) → None¶: Remove every index.

property rank¶: How many coordinates each index has.

reserve(self, count: int) → None¶: Make room for count indices, to allocate once.