Skip to content

CopickRun

copick.models.CopickRun

Encapsulates all data pertaining to a physical location on a sample (i.e. typically one tilt series and the associated tomograms). This includes voxel spacings (of the reconstructed tomograms), picks, meshes, and segmentations.

Attributes:

  • meta (CopickRunMeta) –

    Metadata for this run.

  • root (CopickRoot) –

    Reference to the root project this run belongs to.

  • voxel_spacings (List[CopickVoxelSpacing]) –

    Voxel spacings for this run. Either populated from config or lazily loaded when CopickRun.voxel_spacings is accessed for the first time.

  • picks (List[CopickPicks]) –

    Picks for this run. Either populated from config or lazily loaded when CopickRun.picks is accessed for the first time.

  • meshes (List[CopickMesh]) –

    Meshes for this run. Either populated from config or lazily loaded when CopickRun.meshes is accessed for the first time.

  • segmentations (List[CopickSegmentation]) –

    Segmentations for this run. Either populated from config or lazily loaded when CopickRun.segmentations is accessed for the first time.

  • tilt_series (List[CopickTiltSeries]) –

    Tilt series for this run, lazily loaded when CopickRun.tilt_series is accessed for the first time.

split 

split: Optional[str]

The ML split this run belongs to (train/val/test/custom).

Supported by the mlcroissant backend (stored in runs.csv). Returns None on backends without a structured place for split metadata (filesystem, cryoet_data_portal).

query_voxelspacings 

query_voxelspacings() -> List[CopickVoxelSpacing]

Override this method to query for voxel_spacings.

Returns:

  • List[CopickVoxelSpacing] –

    List[CopickVoxelSpacing]: List of voxel spacings for this run.

query_picks 

query_picks() -> List[CopickPicks]

Override this method to query for picks.

Returns:

  • List[CopickPicks] –

    List[CopickPicks]: List of picks for this run.

query_filaments 

query_filaments() -> List[CopickFilaments]

Override this method to query for filaments. Runs of backends without filaments have none.

query_tilt_series 

query_tilt_series() -> List[CopickTiltSeries]

Override this method to query for tilt series. Runs of backends without tilt series have none.

query_alignments 

query_alignments() -> List[CopickAlignment]

Override this method to query for alignments. Runs of backends without alignments have none.

query_meshes 

query_meshes() -> List[CopickMesh]

Override this method to query for meshes.

Returns:

  • List[CopickMesh] –

    List[CopickMesh]: List of meshes for this run.

query_segmentations 

query_segmentations() -> List[CopickSegmentation]

Override this method to query for segmentations.

Returns:

  • List[CopickSegmentation] –

    List[CopickSegmentation]: List of segmentations for this run.

get_voxel_spacing 

get_voxel_spacing(voxel_size: float, **kwargs) -> Union[CopickVoxelSpacing, None]

Get voxel spacing object by voxel size value.

Parameters:

  • voxel_size (float) –

    Voxel size value to search for.

  • **kwargs –

    Additional keyword arguments for the voxel spacing metadata.

Returns:

  • CopickVoxelSpacing ( Union[CopickVoxelSpacing, None] ) –

    The voxel spacing object with the given voxel size value, or None if not found.

user_picks 

user_picks() -> List[CopickPicks]

Get all user generated picks (i.e. picks that have CopickPicks.session_id != 0).

Returns:

  • List[CopickPicks] –

    List[CopickPicks]: List of user-generated picks.

tool_picks 

tool_picks() -> List[CopickPicks]

Get all tool generated picks (i.e. picks that have CopickPicks.session_id == 0).

Returns:

  • List[CopickPicks] –

    List[CopickPicks]: List of tool-generated picks.

get_picks 

get_picks(object_name: Union[str, Iterable[str]] = None, user_id: Union[str, Iterable[str]] = None, session_id: Union[str, Iterable[str]] = None, **kwargs) -> List[CopickPicks]

Get picks by name, user_id or session_id (or combinations).

Parameters:

  • object_name (Union[str, Iterable[str]], default: None ) –

    Name of the object to search for.

  • user_id (Union[str, Iterable[str]], default: None ) –

    User ID to search for.

  • session_id (Union[str, Iterable[str]], default: None ) –

    Session ID to search for.

  • **kwargs –

    Additional parameters for subclass implementations.

Returns:

  • List[CopickPicks] –

    List[CopickPicks]: List of picks that match the search criteria.

get_filaments 

get_filaments(object_name: Union[str, Iterable[str]] = None, user_id: Union[str, Iterable[str]] = None, session_id: Union[str, Iterable[str]] = None) -> List[CopickFilaments]

Get filaments by object name, user_id or session_id (or combinations).

Parameters:

  • object_name (Union[str, Iterable[str]], default: None ) –

    Name of the object to search for.

  • user_id (Union[str, Iterable[str]], default: None ) –

    User ID to search for.

  • session_id (Union[str, Iterable[str]], default: None ) –

    Session ID to search for.

Returns:

  • List[CopickFilaments] –

    List[CopickFilaments]: List of filaments that match the search criteria.

get_tilt_series_list 

get_tilt_series_list(ts_type: Union[str, Iterable[str]] = None, **kwargs) -> List[CopickTiltSeries]

Get tilt series by type.

Parameters:

  • ts_type (Union[str, Iterable[str]], default: None ) –

    Type(s) of the tilt series to retrieve. Default: all.

  • **kwargs –

    Additional parameters for subclass implementations.

Returns:

  • List[CopickTiltSeries] –

    List[CopickTiltSeries]: The tilt series of the given type(s).

get_tilt_series 

get_tilt_series(ts_type: str, **kwargs) -> Optional[CopickTiltSeries]

Get a tilt series by type.

Parameters:

  • ts_type (str) –

    Type of the tilt series.

  • **kwargs –

    Additional parameters for subclass implementations.

Returns:

  • CopickTiltSeries ( Optional[CopickTiltSeries] ) –

    The first tilt series of the given type, or None if there is none.

get_alignment 

get_alignment(name: str, **kwargs) -> Optional[CopickAlignment]

Get an alignment by name.

Parameters:

  • name (str) –

    Name of the alignment.

  • **kwargs –

    Additional parameters for subclass implementations.

Returns:

  • CopickAlignment ( Optional[CopickAlignment] ) –

    The alignment, or None if there is none of this name.

get_alignments 

get_alignments(tilt_series: Union[CopickTiltSeries, str, None] = None, valid_only: bool = False, alignment_type: Optional[str] = None, method: Optional[str] = None) -> List[CopickAlignment]

Get alignments, best first: preferred ones, then the CryoET Data Portal's standard ones, local before global ones, then by portal identifier and name.

Parameters:

  • tilt_series (Union[CopickTiltSeries, str, None], default: None ) –

    The tilt series (or its type) the alignments align. Default: any.

  • valid_only (bool, default: False ) –

    Whether to leave out alignments that do not come from their author or have no per-section parameters (e.g. CryoET Data Portal placeholders).

  • alignment_type (Optional[str], default: None ) –

    GLOBAL or LOCAL. Default: any.

  • method (Optional[str], default: None ) –

    Alignment method. Default: any.

Returns:

  • List[CopickAlignment] –

    List[CopickAlignment]: The matching alignments.

user_meshes 

user_meshes() -> List[CopickMesh]

Get all user generated meshes (i.e. meshes that have CopickMesh.session_id != 0).

Returns:

  • List[CopickMesh] –

    List[CopickMesh]: List of user-generated meshes.

tool_meshes 

tool_meshes() -> List[CopickMesh]

Get all tool generated meshes (i.e. meshes that have CopickMesh.session_id == 0).

Returns:

  • List[CopickMesh] –

    List[CopickMesh]: List of tool-generated meshes.

get_meshes 

get_meshes(object_name: Union[str, Iterable[str]] = None, user_id: Union[str, Iterable[str]] = None, session_id: Union[str, Iterable[str]] = None) -> List[CopickMesh]

Get meshes by name, user_id or session_id (or combinations).

Parameters:

  • object_name (Union[str, Iterable[str]], default: None ) –

    Name of the object to search for.

  • user_id (Union[str, Iterable[str]], default: None ) –

    User ID to search for.

  • session_id (Union[str, Iterable[str]], default: None ) –

    Session ID to search for.

Returns:

  • List[CopickMesh] –

    List[CopickMesh]: List of meshes that match the search criteria.

user_segmentations 

user_segmentations() -> List[CopickSegmentation]

Get all user generated segmentations (i.e. segmentations that have CopickSegmentation.session_id != 0).

Returns:

  • List[CopickSegmentation] –

    List[CopickSegmentation]: List of user-generated segmentations.

tool_segmentations 

tool_segmentations() -> List[CopickSegmentation]

Get all tool generated segmentations (i.e. segmentations that have CopickSegmentation.session_id == 0).

Returns:

  • List[CopickSegmentation] –

    List[CopickSegmentation]: List of tool-generated segmentations.

get_segmentations 

get_segmentations(user_id: Union[str, Iterable[str]] = None, session_id: Union[str, Iterable[str]] = None, is_multilabel: bool = None, name: Union[str, Iterable[str]] = None, voxel_size: Union[float, Iterable[float]] = None, *, is_instance: Optional[bool] = False, is_panoptic: Optional[bool] = False, **kwargs) -> List[CopickSegmentation]

Get segmentations by user_id, session_id, name, type or voxel_size (or combinations).

Without a type, this selects binary and multilabel segmentations, the types every client reads: pass is_instance=True or is_panoptic=True for the other types, or is_instance=None, is_panoptic=None for any type. segmentations lists all of them.

Parameters:

  • user_id (Union[str, Iterable[str]], default: None ) –

    User ID to search for.

  • session_id (Union[str, Iterable[str]], default: None ) –

    Session ID to search for.

  • is_multilabel (bool, default: None ) –

    Whether the segmentation is multilabel or not.

  • name (Union[str, Iterable[str]], default: None ) –

    Name of the segmentation to search for.

  • voxel_size (Union[float, Iterable[float]], default: None ) –

    Voxel size to search for.

  • is_instance (Optional[bool], default: False ) –

    Whether to select instance segmentations (True) or not (False, the default); None selects any type. Binary segmentations are is_multilabel=False, is_instance=False, is_panoptic=False.

  • is_panoptic (Optional[bool], default: False ) –

    Whether to select panoptic segmentations (True) or not (False, the default); None selects any type.

  • **kwargs –

    Additional parameters for subclass implementations.

Returns:

  • List[CopickSegmentation] –

    List[CopickSegmentation]: List of segmentations that match the search criteria.

new_voxel_spacing 

new_voxel_spacing(voxel_size: float, exist_ok: bool = False, **kwargs) -> CopickVoxelSpacing

Create a new voxel spacing object.

Parameters:

  • voxel_size (float) –

    Voxel size value for the contained tomograms.

  • exist_ok (bool, default: False ) –

    Whether to raise an error if the voxel spacing already exists.

  • **kwargs –

    Additional keyword arguments for the voxel spacing metadata.

Returns:

Raises:

  • ValueError –

    If a voxel spacing with the given voxel size already exists for this run.

new_picks 

new_picks(object_name: str, session_id: str, user_id: Optional[str] = None, exist_ok: bool = False) -> CopickPicks

Create a new picks object.

Parameters:

  • object_name (str) –

    Name of the object to pick.

  • session_id (str) –

    Session ID for the picks.

  • user_id (Optional[str], default: None ) –

    User ID for the picks.

  • exist_ok (bool, default: False ) –

    Whether to raise an error if the picks already exists.

Returns:

  • CopickPicks ( CopickPicks ) –

    The newly created picks object.

Raises:

  • ValueError –

    If picks for the given object name, session ID and user ID already exist, if the object name is not found in the pickable objects, or if the user ID is not set in the root config or supplied.

new_filaments 

new_filaments(object_name: str, session_id: str, user_id: Optional[str] = None, exist_ok: bool = False) -> CopickFilaments

Create a new, empty set of traced filaments.

Parameters:

  • object_name (str) –

    Name of the pickable object the filaments are of. A warning is logged if the object is not declared a filament.

  • session_id (str) –

    Session ID for the filaments.

  • user_id (Optional[str], default: None ) –

    User ID for the filaments.

  • exist_ok (bool, default: False ) –

    Whether to return existing filaments instead of raising an error.

Returns:

  • CopickFilaments ( CopickFilaments ) –

    The newly created (or existing) filaments.

Raises:

  • ValueError –

    If the filaments already exist and exist_ok is False, if the object name is not found in the pickable objects, or if the user ID is not set in the root config or supplied.

new_tilt_series 

new_tilt_series(ts_type: str, exist_ok: bool = False, **kwargs) -> CopickTiltSeries

Create a new tilt series. Its images are written with CopickTiltSeries.from_numpy.

Parameters:

  • ts_type (str) –

    Type of the tilt series.

  • exist_ok (bool, default: False ) –

    Whether to return an existing tilt series of this type instead of raising an error.

  • **kwargs –

    Additional keyword arguments for the tilt series metadata class.

Returns:

  • CopickTiltSeries ( CopickTiltSeries ) –

    The newly created (or existing) tilt series.

Raises:

  • ValueError –

    If a tilt series of this type exists and exist_ok is False, or the type contains '@'.

new_alignment 

new_alignment(name: str, tilt_series: Union[CopickTiltSeries, str], sections: Iterable[CopickSectionAlignment] = (), reference_volume: Optional[CopickReferenceVolume] = None, exist_ok: bool = False, **kwargs) -> CopickAlignment

Create and store a new alignment of a tilt series of this run.

Parameters:

  • name (str) –

    Name of the alignment.

  • tilt_series (Union[CopickTiltSeries, str]) –

    The tilt series (or its type) the alignment aligns.

  • sections (Iterable[CopickSectionAlignment], default: () ) –

    Per-section parameters, in the CETS frame (see CopickSectionAlignment).

  • reference_volume (Optional[CopickReferenceVolume], default: None ) –

    The volume the parameters refer to.

  • exist_ok (bool, default: False ) –

    Whether to return an existing alignment of this name instead of raising an error.

  • **kwargs –

    Further fields of CopickAlignmentFile.

Returns:

  • CopickAlignment ( CopickAlignment ) –

    The newly created (or existing) alignment.

Raises:

  • ValueError –

    If the alignment exists and exist_ok is False, the name contains '@', the tilt series is not in the run or holds already aligned images, or a section is not in the tilt series.

new_mesh 

new_mesh(object_name: str, session_id: str, user_id: Optional[str] = None, exist_ok: bool = False, **kwargs) -> CopickMesh

Create a new mesh object.

Parameters:

  • object_name (str) –

    Name of the object to mesh.

  • session_id (str) –

    Session ID for the mesh.

  • user_id (Optional[str], default: None ) –

    User ID for the mesh.

  • exist_ok (bool, default: False ) –

    Whether to raise an error if the mesh already exists.

  • **kwargs –

    Additional keyword arguments for the mesh metadata.

Returns:

  • CopickMesh ( CopickMesh ) –

    The newly created mesh object.

Raises:

  • ValueError –

    If a mesh for the given object name, session ID and user ID already exist, if the object name is not found in the pickable objects, or if the user ID is not set in the root config or supplied.

new_segmentation 

new_segmentation(voxel_size: float, name: str, session_id: str, is_multilabel: bool = False, user_id: Optional[str] = None, exist_ok: bool = False, *, is_instance: bool = False, is_panoptic: bool = False, **kwargs) -> CopickSegmentation

Create a new segmentation object.

Parameters:

  • voxel_size (float) –

    Voxel size for the segmentation.

  • name (str) –

    Name of the segmentation. For binary and instance segmentations, the name of a pickable object.

  • session_id (str) –

    Session ID for the segmentation.

  • is_multilabel (bool, default: False ) –

    Whether the segmentation is multilabel (several objects, voxel = object label).

  • user_id (Optional[str], default: None ) –

    User ID for the segmentation.

  • exist_ok (bool, default: False ) –

    Whether to raise an error if the segmentation already exists.

  • is_instance (bool, default: False ) –

    Whether the segmentation is an instance segmentation (one object, voxel = instance ID).

  • is_panoptic (bool, default: False ) –

    Whether the segmentation is a panoptic segmentation (channels: object label, instance ID).

  • **kwargs –

    Additional keyword arguments for the segmentation metadata.

Returns:

Raises:

  • ValueError –

    If a segmentation for the given name, session ID, user ID, voxel size and type already exist, if both is_multilabel and is_instance are set, if the object name is not found in the pickable objects, if the voxel size is not found in the voxel spacings, or if the user ID is not set in the root config or supplied.

refresh_voxel_spacings 

refresh_voxel_spacings() -> None

Refresh the voxel spacings.

refresh_picks 

refresh_picks() -> None

Refresh the picks.

refresh_meshes 

refresh_meshes() -> None

Refresh the meshes.

refresh_filaments 

refresh_filaments() -> None

Refresh the filaments.

refresh_segmentations 

refresh_segmentations() -> None

Refresh the segmentations.

refresh_tilt_series 

refresh_tilt_series() -> None

Refresh the tilt series.

refresh_alignments 

refresh_alignments() -> None

Refresh the alignments.

refresh 

refresh() -> None

Refresh all child types.

ensure 

ensure(create: bool = False) -> bool

Check if the run record exists, optionally create it if it does not.

Parameters:

  • create (bool, default: False ) –

    Whether to create the run record if it does not exist.

Returns:

  • bool ( bool ) –

    True if the run record exists, False otherwise.

delete 

delete() -> None

Delete the run record.

delete_voxel_spacings 

delete_voxel_spacings(voxel_size: float = None) -> None

Delete a voxel spacing by voxel size.

Parameters:

  • voxel_size (float, default: None ) –

    Voxel size to delete.

delete_picks 

delete_picks(object_name: str = None, user_id: str = None, session_id: str = None) -> None

Delete picks by name, user_id or session_id (or combinations).

Parameters:

  • object_name (str, default: None ) –

    Name of the object to delete.

  • user_id (str, default: None ) –

    User ID to delete.

  • session_id (str, default: None ) –

    Session ID to delete.

delete_meshes 

delete_meshes(object_name: str = None, user_id: str = None, session_id: str = None) -> None

Delete meshes by name, user_id or session_id (or combinations).

Parameters:

  • object_name (str, default: None ) –

    Name of the object to delete.

  • user_id (str, default: None ) –

    User ID to delete.

  • session_id (str, default: None ) –

    Session ID to delete.

delete_segmentations 

delete_segmentations(user_id: str = None, session_id: str = None, is_multilabel: bool = None, name: str = None, voxel_size: float = None, *, is_instance: Optional[bool] = False, is_panoptic: Optional[bool] = False) -> None

Delete segmentation by name, user_id or session_id (or combinations). Like get_segmentations, without a type this deletes binary and multilabel segmentations only.

Parameters:

  • user_id (str, default: None ) –

    User ID to delete.

  • session_id (str, default: None ) –

    Session ID to delete.

  • is_multilabel (bool, default: None ) –

    Whether the segmentation is multilabel or not.

  • name (str, default: None ) –

    Name of the segmentation to delete.

  • voxel_size (float, default: None ) –

    Voxel size to delete.

  • is_instance (Optional[bool], default: False ) –

    Whether to delete instance segmentations (True) or not (False, the default); None deletes any type.

  • is_panoptic (Optional[bool], default: False ) –

    Whether to delete panoptic segmentations (True) or not (False, the default); None deletes any type.

delete_filaments 

delete_filaments(object_name: str = None, user_id: str = None, session_id: str = None) -> None

Delete filaments by name, user_id or session_id (or combinations).

Parameters:

  • object_name (str, default: None ) –

    Name of the object to delete.

  • user_id (str, default: None ) –

    User ID to delete.

  • session_id (str, default: None ) –

    Session ID to delete.

delete_tilt_series 

delete_tilt_series(ts_type: str = None) -> None

Delete tilt series by type.

Parameters:

  • ts_type (str, default: None ) –

    Type of the tilt series to delete. Default: all.

delete_alignments 

delete_alignments(name: str = None, unlink: bool = True) -> None

Delete alignments by name.

Parameters:

  • name (str, default: None ) –

    Name of the alignment to delete. Default: all.

  • unlink (bool, default: True ) –

    Whether to remove the link from writable tomograms that record a deleted alignment.