Skip to content

I/O Helpers

The copick_utils.io module provides convenience wrappers for reading and writing copick data as NumPy arrays, handling availability checks and OME-Zarr plumbing for you.

Readers

copick_utils.io.readers.tomogram 

tomogram(run, voxel_size: float = 10, algorithm: str = 'wbp', raise_error: bool = False, verbose=True)

Read a tomogram from a copick run as a NumPy array.

Resolves the tomogram {algorithm}@{voxel_size} for the run. If it is not found, reports the available voxel spacings / algorithms (raising or printing depending on raise_error / verbose).

Parameters:

  • run –

    The copick run to read from.

  • voxel_size (float, default: 10 ) –

    Voxel spacing to query, in angstroms.

  • algorithm (str, default: 'wbp' ) –

    Tomogram algorithm / type to read (e.g. wbp).

  • raise_error (bool, default: False ) –

    Raise ValueError if the tomogram is missing instead of returning None.

  • verbose –

    Print a diagnostic message listing what is available when the tomogram is missing.

Returns:

  • –

    The tomogram as a NumPy array of shape (Z, Y, X), or None if it is

  • –

    missing and raise_error is False.

copick_utils.io.readers.segmentation 

segmentation(run, voxel_spacing: float, name: str, user_id=None, session_id=None, raise_error=False, verbose=True)

Read a segmentation from a copick run as a NumPy array.

Resolves the segmentation matching name (optionally filtered by user_id and session_id) at the given voxel spacing. If none matches, reports the available segmentations.

Parameters:

  • run –

    The copick run to read from.

  • voxel_spacing (float) –

    Voxel spacing of the segmentation, in angstroms.

  • name (str) –

    Segmentation / pickable-object name.

  • user_id –

    Restrict to this user id (optional).

  • session_id –

    Restrict to this session id (optional).

  • raise_error –

    Raise ValueError if no segmentation matches instead of returning None.

  • verbose –

    Print a diagnostic message listing what is available when no segmentation matches.

Returns:

  • –

    The segmentation as a NumPy array of shape (Z, Y, X), or None if none

  • –

    matches and raise_error is False.

copick_utils.io.readers.coordinates 

coordinates(run, name: str, user_id: str, session_id: str = None, voxel_size: float = 10, raise_error: bool = False, verbose: bool = True)

Read pick coordinates from a copick run as an array of voxel indices.

Looks up the picks for name (optionally filtered by user_id and session_id) and returns their locations divided by voxel_size. If several pick sets match, the first is used; if none match, reports the available picks.

Parameters:

  • run –

    The copick run to read from.

  • name (str) –

    Pickable-object / protein name.

  • user_id (str) –

    Identifier of the user that generated the picks.

  • session_id (str, default: None ) –

    Identifier of the session that generated the picks (optional).

  • voxel_size (float, default: 10 ) –

    Voxel spacing used to scale physical coordinates to voxels.

  • raise_error (bool, default: False ) –

    Raise ValueError if no picks match instead of returning None.

  • verbose (bool, default: True ) –

    Print a diagnostic message when no picks (or several) match.

Returns:

  • –

    An (N, 3) array of (z, y, x) coordinates in voxel space, or None if no

  • –

    picks match and raise_error is False.

Writers

copick_utils.io.writers.tomogram 

tomogram(run, input_volume, voxel_size=10, algorithm='wbp')

Write a volumetric tomogram into a copick run as OME-Zarr.

Reuses the voxel spacing and tomogram for algorithm if they exist, creating them otherwise, then writes input_volume (building the multiscale pyramid).

Parameters:

  • run –

    The copick run to write into.

  • input_volume –

    The tomogram volume to write, shape (Z, Y, X).

  • voxel_size –

    Voxel spacing in angstroms.

  • algorithm –

    Tomogram algorithm / type to write under (e.g. wbp).

copick_utils.io.writers.segmentation 

segmentation(run, seg_vol, user_id, name='segmentation', session_id='0', voxel_size=10, multilabel=True)

Write a segmentation into a copick run as OME-Zarr.

Reuses an existing segmentation matching name / user_id / session_id at the given voxel spacing if present, creating a new one otherwise, then writes seg_vol as uint8.

Parameters:

  • run –

    The copick run to write into.

  • seg_vol –

    The label volume to write, shape (Z, Y, X).

  • user_id –

    User id to attribute the segmentation to.

  • name –

    Segmentation name. Defaults to segmentation.

  • session_id –

    Session id for the segmentation. Defaults to 0.

  • voxel_size –

    Voxel spacing in angstroms.

  • multilabel –

    Whether the segmentation holds multiple labels.

Usage Examples

Read a tomogram and pick coordinates

import copick
from copick_utils.io import readers

root = copick.from_file("config.json")
run = root.get_run("TS_001")

# Tomogram as a NumPy array (Z, Y, X).
volume = readers.tomogram(run, voxel_size=10.0, algorithm="wbp")

# Pick coordinates as an (N, 3) array.
coords = readers.coordinates(run, name="ribosome", user_id="alice", session_id="1")

Write a segmentation back into the run

from copick_utils.io import writers

writers.segmentation(
    run,
    seg_vol,                 # NumPy label volume (Z, Y, X)
    user_id="copick-utils",
    name="membrane",
    session_id="0",
    voxel_size=10.0,
    multilabel=True,
)