cryosparc.star

Helper module for reading and writing relion star files.

Functions:

read(file)	Read the given STAR file into memory.
write(file, data[, name, labels])	Write a star file with a single "data_" block.
write_blocks(file, blocks)	Write a single star file composed of multiple data blocks:

cryosparc.star.read(file: Union[str, PurePath, IO[str]]) → Dict[str, NDArray]

Read the given STAR file into memory.

Parameters:

file (str | Path | IO) – Path or file handle to .star file.

Returns:

a dictionary of numpy record arrays

Each key is a block name found in the star file (e.g., "particles" for block data_particles and "" for block data_)

Return type:

dict[str, NDArray]

Examples

Read a star file with a sole data_ block

>>> from cryosparc import star
>>> data = star.read('particles.star')['']
>>> data
array([...])

Read a star file with multiple blocks

>>> blocks = star.read('particles_with_optics.star')
>>> blocks['particles']
array([...])
>>> blocks['optics']
array([...])

cryosparc.star.write(file: Union[str, PurePath, IO[str]], data: Any, name: str = '', labels: Optional[List[str]] = None)

Write a star file with a single “data_” block. Data may be provided as either a numpy record array or a collection of tuples with a specified labels argument.

Parameters:

• file (str | Path | IO) – File path or handle to write.

• data (any) – Numpy record array or Python list of tuples.

• name (str) – Name of data block, to be prepended with “data_” when written to the star file. Defaults to “”.

• labels (list[str], optional) – Names of each column in the data. Not required if given a numpy record array that includes the names. Defaults to None.

Examples

With array of tuples

>>> from cryosparc import star
>>> star.write('one.star', [
...     (123., 456.),
...     (789., 987.)
... ], labels=['rlnCoordinateX', 'rlnCoordinateY'])

With numpy record array

>>> arr  = np.core.records.fromrecords([
...     (123., 456.),
...     (789., 987.)
... ], names=[('rlnCoordinateX', 'f8') , ('rlnCoordinateY', 'f8')])
>>> star.write('two.star', arr)

cryosparc.star.write_blocks(file: Union[str, PurePath, IO[str]], blocks: Mapping[str, NDArray])

Write a single star file composed of multiple data blocks:

Parameters:

• file (str | Path | IO) – File path or handle to write.

• blocks (Mapping[str, NDArray]) – Dictionary of record arrays to write.

Examples

With optics group and particles

>>> from cryosparc import star
>>> import numpy as np
>>> optics = np.core.records.fromrecords([
...     ('mydata', ..., 0.1, 0.1)
... ], names='rlnOpticsGroupName,...,rlnBeamTiltX,rlnBeamTiltY'])
>>> particles = np.core.records.fromrecords([
...     (123., 456.), ... (789., 987.),
... ], names='rlnCoordinateX,rlnCoordinateY')
>>> star.write('particles.star', {
...     'optics': optics,
...     'particles': particles
... })