wsireg modules

WsiReg2D API

class wsireg.wsireg2d.WsiReg2D(project_name: str | None = None, output_dir: str | Path | None = None, cache_images: bool = True, config: str | Path | None = None)[source]

Bases: object

Class to define a 2D registration graph and execute the registrations and transformations of the graph

Parameters:

  • project_name (str) – Project name will prefix all output files and directories

  • output_dir (str) – Directory where registration data will be stored

  • cache_images (bool) – whether to store images as they are preprocessed for registration (if you need to repeat or modify settings this will avoid image io and preprocessing)

  • config (str or Path) – path to a 2D wsireg YAML configuration

project_name

Global project name, will be appended to all output files and folders

Type:

str

output_dir

Directory where registration data will be stored

Type:

Path

image_cache

Directory where images are cached after preprocessing

Type:

Path

modalities

dictionary of modality information (file path, spatial res., preprocessing), defines a graph node

Type:

dict

modalities

list of all modality names

Type:

list

n_modalities

number of modalities (nodes) in the graphs

Type:

int

reg_paths

dictionary of a modalities path from node to node

Type:

dict

reg_graph_edges

generated dictionary of necessary registrations to move modalities to their target modality

Type:

dict

n_registrations

number of explicit registrations (edges) in the graphs

Type:

int

transformation_paths

generated dictionary of necessary source - target transformations to transform modalities to their target modality

Type:

dict

transformations

per modality dictionary containing transformation parameters for each registration

Type:

dict

attachment_images

images to be transformed along the path of the defined graph, assoicated to a given modality (masks, other registered images)

Type:

dict

attachment_shapes

shape data attached to a modality to be transformed along the graph

Type:

dict

registration_iter_data

elastix data for each iteration in the registration sorted by transformation model and resolution

Type:

Dict[str,Dict[int, Dict[int, Dict[str, np.ndarray]]]]

registration_tform_data

elastix transform data for each resolution sorted by transformation model and resolution

Type:

Dict[str, Dict[int, Dict[int, Dict[str, str]]]]

add_attachment_images(attachment_modality: str, modality_name: str, image_fp: str | Path, image_res: int | float = 1, channel_names: List[str] | None = None, channel_colors: List[str] | None = None) → None[source]

Images which are unregistered between modalities, but are transformed following the path of one of the graph’s modalities.

Parameters:

  • attachment_modality (str) – image modality to which the new image are attached

  • modality_name (str) – name of the added attachment image

  • image_fp (str) – path to the attachment modality, it will be imported and transformed without preprocessing

  • image_res (float) – spatial resolution of attachment image data’s in units per px (i.e. 0.9 um / px)

  • channel_names (List[str]) – names for the channels to go into the OME-TIFF

  • channel_colors (List[str]) – channels colors for OME-TIFF (not implemented)

add_attachment_shapes(attachment_modality: str, shape_set_name: str, shape_files: List[Path | str]) → None[source]

Add attached shapes

Parameters:

  • attachment_modality (str) – image modality to which the shapes are attached

  • shape_set_name (str) – Unique name identifier for the shape set

  • shape_files (list of file paths) – list of shape data in geoJSON format or list of dicts containing following keys: “array” = np.ndarray of xy coordinates, “shape_type” = geojson shape type (Polygon, MultiPolygon, etc.), “shape_name” = class of the shape(“tumor”,”normal”,etc.)

add_data_from_config(config_filepath)[source]
add_merge_modalities(merge_name, modalities)[source]
add_modality(modality_name: str, image_fp: Path | str | ndarray, image_res: int | float = 1, channel_names: List[str] | None = None, channel_colors: List[str] | None = None, preprocessing: ImagePreproParams | Dict[str, Any] | None = None, mask: ndarray | str | Path | None = None, prepro_dict: Dict[str, Any] | None = None, output_res: int | float | Tuple[int, int] | Tuple[float, float] | None = None) → None[source]

Add an image modality (node) to the registration graph

Parameters:

  • modality_name (str) – Unique name identifier for the modality

  • image_fp (str) – file path to the image to be read

  • image_res (float) – spatial resolution of image in units per px (i.e. 0.9 um / px)

  • channel_names (List[str]) – names for the channels to go into the OME-TIFF

  • channel_colors (List[str]) – channels colors for OME-TIFF (not implemented)

  • mask (Union[str, Path, np.ndarray]) – path to binary mask (>0 is in) image for registration and/or cropping or a geoJSON with shapes that will be processed to a binary mask

  • preprocessing (ImagePreproParams) – preprocessing parameters for the modality for registration. Registration images should be a xy single plane so many modalities (multi-channel, RGB) must “create” a single channel. Defaults: multi-channel images -> max intensity project image RGB -> greyscale then intensity inversion (black background, white foreground)

  • output_res (Union[Tuple[int,int], Tuple[float,float]]) – change output spacing/resolution when resampling images, default will be the spacing of the final target image

  • prepro_dict (dict) – deprecated version kept temporarily

add_reg_path(src_modality_name: str, tgt_modality_name: str, thru_modality: str | None = None, reg_params: str | ~<unknown>.RegModel | ~typing.List[str] | ~typing.List[~<unknown>.RegModel] = ['rigid'], override_prepro: dict = {'source': None, 'target': None})[source]

Add registration path between modalities as well as a thru modality that describes where to attach edges.

Parameters:

  • src_modality_name (str) – modality that has been added to graph to be transformed to tgt_modality

  • tgt_modality_name (str) – modality that has been added to graph that is being aligned to

  • thru_modality (str) – modality that has been added to graph by which another should be run through

  • reg_params (list of RegModel/str or str) – Elastix registration parameters, from RegModel or as a string corresponding to one of the parameter maps enumerated in wsireg.parameter_maps.reg_params.RegModel

  • override_prepro (dict) – set specific preprocessing for a given registration edge for the source or target image that will override the set modality preprocessing FOR THIS REGISTRATION ONLY.

add_shape_set(attachment_modality: str, shape_set_name: str, shape_files: List[Path | str], image_res: int | float) → None[source]

Add a shape set to the graph

Parameters:

  • attachment_modality (str) – image modality to which the shapes are attached

  • shape_set_name (str) – Unique name identifier for the shape set

  • shape_files (list of file paths) – list of shape data in geoJSON format or list of dicts containing following keys: “array” = np.ndarray of xy coordinates, “shape_type” = geojson shape type (Polygon, MultiPolygon, etc.), “shape_name” = class of the shape(“tumor”,”normal”,etc.)

  • image_res (float) – spatial resolution of shape data’s associated image in units per px (i.e. 0.9 um / px)

find_path(start_modality: str, end_modality: str, path: List[str] | None = None) → List[str] | None[source]

Find a path from start_modality to end_modality in the graph

property modalities: Dict[str, Any]

Image modality information stored as a dictionary where keys are images and values are all image modality related information.

property modality_names: List[str]

List of all the modality names.

property reg_graph_edges
property reg_paths: Dict[str, List[str]]

Dictionary of paths between modalities by modality name. Keys are modality name and the values are a list of modalities it passes through.

register_images(parallel=False)[source]

Start image registration process for all modalities

Parameters:

parallel (bool) – whether to run each edge in parallel (not implemented yet)

remove_merge_modality(merge_modality: str) → None[source]
remove_modality(modality: str) → None[source]
reset_registered_modality(modalities)[source]
save_config(output_file_path: str | Path | None = None, registered: bool = False) → str[source]
save_transformations()[source]

Save all transformations for a given modality as JSON

setup_project_output(project_name: str | None = None, output_dir: str | Path | None = None) → None[source]

Set up the project directory and image cache.

Parameters:

  • project_name (str) – Project name will prefix all output files and directories

  • output_dir (str) – Directory where registration data will be stored

property shape_set_names: List[str]

Name of all shape sets

property shape_sets

Shape data stored as a dictionary where keys are shape sets and values are all shape related information.

transform_images(file_writer='ome.tiff', transform_non_reg=True, remove_merged=True, to_original_size=True)[source]

Transform and write images to disk after registration. Also transforms all attachment images

Parameters:

  • file_writer (str) – output type to use, sitk writes a single resolution tiff, “zarr” writes an ome-zarr multiscale zarr store

  • transform_non_reg (bool) – whether to write the images that aren’t transformed during registration as well

  • remove_merged (bool) – whether to remove images that are stored in merged store, if True, images that are merged will not be written as individual images as well

  • to_original_size (bool) – write images that have been cropped for registration back to their original coordinate space

property transform_paths
transform_shapes()[source]

Transform all attached shapes and write out shape data to geoJSON.

property transformations
wsireg.wsireg2d.main()[source]
wsireg.wsireg2d.wsireg_run(graph_configuration: str | Path | WsiReg2D, write_images: bool = True, to_original_size: bool = False, transform_non_reg: bool = True, remove_merged: bool = True, file_writer: str = 'ome.tiff', testing: bool = False)[source]

Subpackages