Algorithms¶

Create algorithms, combine them into collections, and run them.

algorithm ¶

Algorithm ¶

Algorithm(
    run_algorithm_func: Callable[P, Any],
    parameters: Optional[Dict[str, Any]] = None,
    name: Optional[str] = None,
    description: Optional[str] = None,
    tags: Optional[List[str]] = None,
    project_url: str = "https://github.com/Imaging-Server-Kit/imaging-server-kit",
    metadata_file: str = "metadata.yaml",
    samples: Optional[List[Dict[str, Any]]] = None,
    tileable: bool = False,
)

Bases: AlgorithmRunner, Generic[P]

An algorithm built by wrapping a Python function.

Algorithms are usually created with the @sk.algorithm decorator rather than instantiated directly. They can still be called like the wrapped function, and also implement the shared AlgorithmRunner interface (run(), get_sample(), info(), etc.).

Parameters:

Name	Type	Description	Default
`run_algorithm_func`	`callable`	The Python function to convert.	required
`parameters`	`dict`	Parameter annotations, mapping parameter names to data layers (e.g. `{"sigma": sk.Float(min=0, default=1.0)}`). Parameters that are not annotated are resolved from type hints, default values, or variable names.	`None`
`name`	`str`	A name for the algorithm. Defaults to the name of the function.	`None`
`description`	`str`	A short description, displayed on the algorithm documentation page. Defaults to the docstring of the function.	`None`
`tags`	`list of str`	A list of tags (arbitrary), displayed on the algorithm documentation page.	`None`
`project_url`	`str`	A link to a related project, or to the original project, displayed on the algorithm documentation page.	`'https://github.com/Imaging-Server-Kit/imaging-server-kit'`
`metadata_file`	`str`	A path to a YAML file with algorithm metadata.	`"metadata.yaml"`
`samples`	`list of dict`	Samples for the algorithm. Each sample is a dictionary mapping parameter names to example values. Sample images can be NumPy arrays, URLs, or paths to local files readable by `skimage.io.imread`.	`None`
`tileable`	`bool`	Whether the algorithm can be run tile-by-tile.	`False`

Attributes:

Name	Type	Description
`name`	`str`	The name of the algorithm.
`parameters_model`	`BaseModel`	A Pydantic model used to validate the algorithm parameters.
`samples`	`list of dict`	The samples of the algorithm.
`algo_info`	`dict`	Metadata about the algorithm.
`algorithms`	`list of str`	A list containing the name of the algorithm.
`tileable`	`bool`	Whether the algorithm can be run tile-by-tile.

info ¶

info(algorithm: Optional[str] = None) -> None

Create and open the algorithm info page in a web browser.

get_signature_params ¶

get_signature_params(
    algorithm: Optional[str] = None,
) -> List[str]

List parameter names of the algo run function.

algorithm ¶

algorithm(func: Callable[P, Any]) -> Algorithm[P]

algorithm(
    func: None = None,
    *,
    parameters: Optional[Dict[str, Any]] = None,
    name: Optional[str] = None,
    description: Optional[str] = None,
    tags: Optional[List[str]] = None,
    project_url: str = "https://github.com/Imaging-Server-Kit/imaging-server-kit",
    metadata_file: str = "metadata.yaml",
    samples: Optional[List[Dict[str, Any]]] = None,
    tileable: bool = False,
) -> Callable[[Callable[P, Any]], Algorithm[P]]

algorithm(
    func: Optional[Callable] = None,
    parameters: Optional[Dict[str, Any]] = None,
    name: Optional[str] = None,
    description: Optional[str] = None,
    tags: Optional[List[str]] = None,
    project_url: str = "https://github.com/Imaging-Server-Kit/imaging-server-kit",
    metadata_file: str = "metadata.yaml",
    samples: Optional[List[Dict[str, Any]]] = None,
    tileable: bool = False,
) -> Union[
    Algorithm[P],
    Callable[[Callable[P, Any]], Algorithm[P]],
]

Convert a Python function into an algorithm.

Typically used as a decorator, with or without arguments: @sk.algorithm or @sk.algorithm(...).

Parameters:

Name	Type	Description	Default
`func`	`callable`	The Python function to convert. Passed implicitly when used as a decorator.	`None`
`parameters`	`dict`	Parameter annotations, mapping parameter names to data layers (e.g. `{"sigma": sk.Float(min=0, default=1.0)}`). Parameters that are not annotated are resolved from type hints, default values, or variable names.	`None`
`name`	`str`	A name for the algorithm. Defaults to the name of the function.	`None`
`description`	`str`	A short description, displayed on the algorithm documentation page. Defaults to the docstring of the function.	`None`
`tags`	`list of str`	A list of tags (arbitrary), displayed on the algorithm documentation page.	`None`
`project_url`	`str`	A link to a related project, or to the original project, displayed on the algorithm documentation page.	`'https://github.com/Imaging-Server-Kit/imaging-server-kit'`
`metadata_file`	`str`	A path to a YAML file with algorithm metadata.	`"metadata.yaml"`
`samples`	`list of dict`	Samples for the algorithm. Each sample is a dictionary mapping parameter names to example values. Sample images can be NumPy arrays, URLs, or paths to local files readable by `skimage.io.imread`.	`None`
`tileable`	`bool`	Whether the algorithm can be run tile-by-tile.	`False`

Returns:

Type	Description
`Algorithm`	The algorithm. When called with keyword arguments only, a decorator returning the algorithm.

Examples:

>>> @sk.algorithm(parameters={"threshold": sk.Integer(min=0, max=255, default=128)})
... def threshold_algo(image, threshold):
...     return sk.Mask(image > threshold)

Algorithm ¶

Algorithm(
    run_algorithm_func: Callable[P, Any],
    parameters: Optional[Dict[str, Any]] = None,
    name: Optional[str] = None,
    description: Optional[str] = None,
    tags: Optional[List[str]] = None,
    project_url: str = "https://github.com/Imaging-Server-Kit/imaging-server-kit",
    metadata_file: str = "metadata.yaml",
    samples: Optional[List[Dict[str, Any]]] = None,
    tileable: bool = False,
)

Bases: AlgorithmRunner, Generic[P]

An algorithm built by wrapping a Python function.

Algorithms are usually created with the @sk.algorithm decorator rather than instantiated directly. They can still be called like the wrapped function, and also implement the shared AlgorithmRunner interface (run(), get_sample(), info(), etc.).

Parameters:

Name	Type	Description	Default
`run_algorithm_func`	`callable`	The Python function to convert.	required
`parameters`	`dict`	Parameter annotations, mapping parameter names to data layers (e.g. `{"sigma": sk.Float(min=0, default=1.0)}`). Parameters that are not annotated are resolved from type hints, default values, or variable names.	`None`
`name`	`str`	A name for the algorithm. Defaults to the name of the function.	`None`
`description`	`str`	A short description, displayed on the algorithm documentation page. Defaults to the docstring of the function.	`None`
`tags`	`list of str`	A list of tags (arbitrary), displayed on the algorithm documentation page.	`None`
`project_url`	`str`	A link to a related project, or to the original project, displayed on the algorithm documentation page.	`'https://github.com/Imaging-Server-Kit/imaging-server-kit'`
`metadata_file`	`str`	A path to a YAML file with algorithm metadata.	`"metadata.yaml"`
`samples`	`list of dict`	Samples for the algorithm. Each sample is a dictionary mapping parameter names to example values. Sample images can be NumPy arrays, URLs, or paths to local files readable by `skimage.io.imread`.	`None`
`tileable`	`bool`	Whether the algorithm can be run tile-by-tile.	`False`

Attributes:

Name	Type	Description
`name`	`str`	The name of the algorithm.
`parameters_model`	`BaseModel`	A Pydantic model used to validate the algorithm parameters.
`samples`	`list of dict`	The samples of the algorithm.
`algo_info`	`dict`	Metadata about the algorithm.
`algorithms`	`list of str`	A list containing the name of the algorithm.
`tileable`	`bool`	Whether the algorithm can be run tile-by-tile.

combine ¶

combine(
    algorithms: List[Algorithm], name: str = "algorithms"
) -> MultiAlgorithm

Combine algorithms, or plain Python functions, into a collection.

Parameters:

Name	Type	Description	Default
`algorithms`	`list of Algorithm or callable`	The algorithms to combine. Plain Python functions are converted to algorithms.	required
`name`	`str`	A name for the collection.	`"algorithms"`

Returns:

Type	Description
`MultiAlgorithm`	The algorithm collection.

Examples:

>>> multi_algo = sk.combine([threshold_algo, gaussian_algo], name="my-algorithms")

MultiAlgorithm ¶

MultiAlgorithm(
    algorithms: List[Algorithm], name: str = "algorithms"
)

Bases: AlgorithmRunner

A collection of algorithms exposed under a single interface.

Collections are usually created with sk.combine() rather than instantiated directly. They implement the shared AlgorithmRunner interface, where methods take an algorithm argument to select an algorithm by name.

Parameters:

Name	Type	Description	Default
`algorithms`	`list of Algorithm`	The algorithms in the collection. If several algorithms have the same name, only the last one is kept.	required
`name`	`str`	A name for the collection.	`"algorithms"`

Attributes:

Name	Type	Description
`algorithms_dict`	`dict`	A dictionary mapping algorithm names to algorithms.
`algorithms`	`list of str`	The names of the algorithms in the collection.

Shared interface¶

Algorithms, collections, and clients implement the methods below.

AlgorithmRunner ¶

Bases: ABC

Interface shared by sk.Algorithm, sk.MultiAlgorithm, and sk.Client.

The same code can run an algorithm locally, as part of a collection, or remotely on an algorithm server. Subclasses provide _stream() (how to execute, or request, the computation for one tile of parameters) and inherit run(), which handles parameter resolution, tiling, domain restriction, and result merging identically across all three.

In collections and clients, methods take an algorithm argument to select an algorithm by name. When it is omitted, the first available algorithm is used.

Attributes:

Name	Type	Description
`name`	`str`	A name identifying the runner.
`algorithms`	`list of str`	The names of the available algorithms.

run ¶

run(
    *args,
    algorithm: Optional[str] = None,
    tiled: bool = False,
    tile_size: int = 64,
    tile_overlap: float = 0.0,
    tile_delay: float = 0.0,
    tile_randomize: bool = False,
    stack: Union[Stack, Viewer] = None,
    domain: Optional[Domain] = None,
    **algo_params,
) -> Union[Stack, Viewer]

Run an algorithm with a set of parameters.

Parameters:

Name	Type	Description	Default
`*args`		Algorithm parameters, passed by position, matching the signature of the algorithm's function (e.g. `algo.run(image, threshold=100)`).	`()`
`algorithm`	`str`	Name of the algorithm to run (only needed with collections and clients).	`None`
`tiled`	`bool`	Run the algorithm tile-by-tile. Requires an algorithm defined with `tileable=True`.	`False`
`tile_size`	`int or tuple of int`	Tile size in pixels: a single value, or one value per axis.	`64`
`tile_overlap`	`float`	Overlap between neighbouring tiles, relative to the tile size.	`0.0`
`tile_delay`	`float`	Extra delay between tiles, in seconds.	`0.0`
`tile_randomize`	`bool`	Process the tiles in a random order.	`False`
`stack`	`Stack or Viewer`	A stack, or a Napari viewer, to collect the results into. By default, a new stack is created.	`None`
`domain`	`Domain`	A region to which the computation is restricted.	`None`
`**algo_params`		Algorithm parameters, passed by name.	`{}`

Returns:

Type	Description
`Stack or Viewer`	The results, as a stack of layers. If a Napari viewer was passed as `stack`, the viewer is returned.

Raises:

Type	Description
`ValidationError`	If parameter values are invalid.
`TypeError`	If unknown parameters are passed.
`AlgorithmRuntimeError`	If `tiled=True` is used with an algorithm that is not tileable, or if the algorithm raises an error.

get_sample `abstractmethod` ¶

get_sample(algorithm: Optional[str], idx: int = 0) -> Stack

Get a sample of an algorithm.

Parameters:

Name	Type	Description	Default
`algorithm`	`str`	Name of the algorithm (only needed with collections and clients).	required
`idx`	`int`	Index of the sample.	`0`

Returns:

Type	Description
`Stack`	The sample, as a stack of parameter layers, or `None` if the algorithm has no samples.

get_n_samples `abstractmethod` ¶

get_n_samples(algorithm: Optional[str]) -> int

Get the number of samples of an algorithm.

Parameters:

Name	Type	Description	Default
`algorithm`	`str`	Name of the algorithm (only needed with collections and clients).	required

Returns:

Type	Description
`int`	The number of samples.

info `abstractmethod` ¶

info(algorithm: Optional[str]) -> None

Open the documentation page of an algorithm in a web browser.

Parameters:

Name	Type	Description	Default
`algorithm`	`str`	Name of the algorithm (only needed with collections and clients).	required

get_parameters `abstractmethod` ¶

get_parameters(algorithm: Optional[str]) -> Dict

Get the JSON schema of the parameters of an algorithm.

Parameters:

Name	Type	Description	Default
`algorithm`	`str`	Name of the algorithm (only needed with collections and clients).	required

Returns:

Type	Description
`dict`	The JSON schema of the algorithm parameters.

is_tileable `abstractmethod` ¶

is_tileable(algorithm: Optional[str]) -> bool

Whether an algorithm can be run tile-by-tile.

Parameters:

Name	Type	Description	Default
`algorithm`	`str`	Name of the algorithm (only needed with collections and clients).	required

Returns:

Type	Description
`bool`	`True` if the algorithm was defined with `tileable=True`.

get_signature_params `abstractmethod` ¶

get_signature_params(algorithm: Optional[str]) -> List[str]

Get the parameter names of the function of an algorithm, in order.

Parameters:

Name	Type	Description	Default
`algorithm`	`str`	Name of the algorithm (only needed with collections and clients).	required

Returns:

Type	Description
`list of str`	The parameter names.

run_generator ¶

run_generator(
    algorithm: str,
    params_stack: Stack,
    tiling_ctx: Optional[TilingSpecs] = None,
)

Lower-level generator variant of run().

Parameters:

Name	Type	Description	Default
`algorithm`	`str`	Name of the algorithm to run.	required
`params_stack`	`Stack`	The algorithm parameters, as a stack of layers.	required
`tiling_ctx`	`TilingSpecs`	Tiling specifications. If `None`, the parameters are processed as a single tile.	`None`

Yields:

Type	Description
`tuple of (Stack, Stack)`	One `(result_tile, params_tile)` pair per tile and per yielded result.

Shortcuts¶

run ¶

run(
    runner: AlgorithmRunner,
    *args,
    algorithm: Optional[str] = None,
    tiled: bool = False,
    tile_size: int = 64,
    tile_overlap: float = 0.0,
    tile_delay: float = 0.0,
    tile_randomize: bool = False,
    stack: Union[Stack, Viewer] = None,
    domain: Optional[Domain] = None,
    **algo_params,
) -> Union[Stack, Viewer]

Run an algorithm. Equivalent to runner.run(...).

See AlgorithmRunner.run for the description of the parameters.

Parameters:

Name	Type	Description	Default
`runner`	`AlgorithmRunner`	An algorithm, an algorithm collection, or a client.	required

Returns:

Type	Description
`Stack or Viewer`	The results, as returned by `runner.run(...)`.

info ¶

info(
    runner: AlgorithmRunner, algorithm: Optional[str] = None
)

Open the documentation page of an algorithm. Equivalent to runner.info(...).

Parameters:

Name	Type	Description	Default
`runner`	`AlgorithmRunner`	An algorithm, an algorithm collection, or a client.	required
`algorithm`	`str`	Name of the algorithm (only needed with collections and clients).	`None`

Algorithms¶

algorithm ¶

Algorithm ¶

info ¶

get_signature_params ¶

algorithm ¶

Algorithm ¶

combine ¶

MultiAlgorithm ¶

Shared interface¶

AlgorithmRunner ¶

run ¶

get_sample abstractmethod ¶

get_n_samples abstractmethod ¶

info abstractmethod ¶

get_parameters abstractmethod ¶

is_tileable abstractmethod ¶

get_signature_params abstractmethod ¶

run_generator ¶

Shortcuts¶

run ¶

info ¶

get_sample `abstractmethod` ¶

get_n_samples `abstractmethod` ¶

info `abstractmethod` ¶

get_parameters `abstractmethod` ¶

is_tileable `abstractmethod` ¶

get_signature_params `abstractmethod` ¶