superdsm.globalenergymin

class superdsm.globalenergymin.GlobalEnergyMinimization

Bases: Stage

Implements the global energy minimization (see Joint segmentation and cluster splitting).

This stage implements Algorithm 1 and Criterion 2 from Kostrykin and Rohr (TPAMI 2023). The stage requires y, y_mask, atoms, adjacencies, dsm_cfg for input and produces y_img, cover, objects, performance for output. Refer to Inputs and outputs for more information on the available inputs and outputs.

For Algorithm 1, there are two behaviours implemented which differ in the definition of the upper bound \(c_{ \text{max}}\). In exact pruning mode, the original definition from the paper is used,

\[c_{\text{max}} = \operatorname{MSC}(\mathscr U) - \sum_{u \in U \setminus X} \nu(\{u\}),\]

which guarantees that \(\operatorname{MSC}(\mathscr U_{\# U}) = \operatorname{MSC}(\mathbb P(U))\). On the other hand, the isbi24 pruning mode corresponds to the algorithm described in Kostrykin and Rohr (ISBI 2024), which yields a more greedy behaviour. Depending on the data, this can be significantly faster, without degrading the segmentation or cluster splitting performance.

Hyperparameters

The following hyperparameters can be used to control this pipeline stage:

global-energy-minimization/pruning: Mist be either exact or isbi24, as described above. Defaults to exact.
global-energy-minimization/beta: Corresponds to the sparsity parameter \(\beta\) described in Joint segmentation and cluster splitting. Defaults to 0, or to AF_beta × scale^2 if configured automatically, where AF_beta corresponds to \(\beta_\text{factor}\) in Kostrykin and Rohr (TPAMI 2023) and defaults to 0.66. Due to a transmission error, the values reported for AF_beta in the paper were misstated by a factor of 2 (Section 3.3, Supplemental Material 8).
global-energy-minimization/max_iter: The number of iterations to perform for solving the min-weight set-cover (see solve_minsetcover() and Algorithm 2 in Kostrykin and Rohr, TPAMI 2023). Iterations use an increasingly conservative merging strategy (i.e. the sparsity parameter \(\beta\) is reduced). Defaults to 5.
global-energy-minimization/gamma: The factor used to reduce the sparsity parameter \(\beta\) after the first iteration (this is the parameter \(\gamma\) of Algorithm 2 in Kostrykin and Rohr, TPAMI 2023, where \(0 < \gamma < 1\)). Defaults to 0.8.
global-energy-minimization/max_seed_distance: Maximum distance allowed between two seed points of atomic image regions which are grouped into an image region corresponding to single object (cf. Coarse-to-fine region analysis). This can be used to enforce that the segmented objects will be of a maximum size, and thus to limit the computational cost by using prior knowledge. Defaults to infinity, or to AF_max_seed_distance × diameter if configured automatically (and AF_max_seed_distance defaults to infinity).
global-energy-minimization/max_work_amount: Used to recognize a computationally intractable amount of objects due to misconfigured hyperparameters. If the number of objects could exceed this threshold, a ValueError is raised. The number of objects is estimated based on the structure of the adjacency graph of the atomic image regions (see Coarse-to-fine region analysis). Defaults to 10e6.

configure(pipeline, input_id, *args, scale, diameter, **kwargs)

Returns the rules to adopt hyperparameters based on the input data.

Sometimes it can be necessary to automatically adopt hyperparameters based on the input data. For those cases where linear adoptation is suitable, this method can be overridden to return the rules which specify how to adopt the hyperparameters. The rules are then applied by the repype.pipeline.Pipeline.configure() method.

The rules must be specified by the following structure:

{
    'key': [
        factor,
        default_user_factor,
    ],
}

The rules are resolved by mapping the above structure to the arguments of the repype.pipeline.create_config_entry() function. In this example, two new hyperparameters are created:

The hyperparameter AF_key is created and defaults to the value of default_user_factor.
The hyperparameter key is created and defaults to the value of the hyperparameter AF_key times the value of factor.

In addition, a third element can be added to the list to further constrain the resulting values:

{
    'key': [
        factor,
        default_user_factor,
        {
            type: 'float',
            min: 0.0,
            max: 1.0,
        },
    ],
}

Parameters:

pipeline – The pipeline object that this stage is a part of.
input_id – The identifier of the input data to adopt the hyperparameters for.
*args – Sequential arguments passed to Pipeline.configure.
**kwargs – Keyword arguments passed to Pipeline.configure.

id: str = 'global-energy-minimization': The stage identifier.

inputs: Collection[str] = ['y', 'y_mask', 'atoms', 'adjacencies', 'dsm_cfg']: List of fields read by this stage.

outputs: Collection[str] = ['y_img', 'cover', 'objects', 'performance']: List of fields produced by this stage.

process(y, y_mask, atoms, adjacencies, dsm_cfg, pipeline, config, status=None, log_root_dir=None)

Processes the input fields of this stage of the pipeline.

This method implements a stage of the pipeline with the provided inputs and configuration parameters. It then returns the outputs produced by the stage.

Parameters:

pipeline – The pipeline object that this stage is a part of.
config – The hyperparameters to be used for this stage.
status – A status object to report the progress of the computations.
**inputs – The fields of the pipeline read by this stage. Each key-value pair represents an input field and the corresponding value.

Returns:

A dictionary containing the outputs of this stage. Each key-value pair in the dictionary represents an output field and the corresponding value.

Raises:

NotImplementedError – If the method is not implemented by the subclass.

class superdsm.globalenergymin.PerformanceReport(**kwargs)

Bases: object

Reports the pruning performance of the global energy minimization method.

direct_solution_trial_count: The number of cases in which Criterion 2 was evaluated (see Kostrykin and Rohr, TPAMI 2023).

direct_solution_success_count: The number of cases in which Criterion 2 yielded a closed-form solution (see Kostrykin and Rohr, TPAMI 2023).

iterative_object_count: The number of objects which would be computed if bruteforce was used instead of Algorithm 1.

iterative_computed_object_count: The number of objects computed by Algorithm 1 (see Kostrykin and Rohr, TPAMI 2023).

overall_object_count: The overall number of objects which would be computed if neither Algorithm 1 nor Criterion 2 was used.

overall_computed_object_count: The overall number of computed objects.

nontrivial_object_count: The overall number of objects which would be computed if neither Algorithm 1 nor Criterion 2 was used (except for trivial regions of possibly clustered objects).

nontrivial_computed_object_count: The overall number of computed objects (except for trivial regions of possibly clustered objects).

For regions of possibly clustered objects, for which the cardinality \(\# U\) of the universe \(U\) is 1 or 2, always all possible objects must be computed. Since only 3 objects are possible at most (the region of possbily clustered objects either corresponds to two objects or to a single object), such regions are called trivial.

attributes = ['direct_solution_trial_count', 'direct_solution_success_count', 'iterative_object_count', 'iterative_computed_object_count', 'overall_object_count', 'overall_computed_object_count', 'nontrivial_object_count', 'nontrivial_computed_object_count']: List of supported keyword arguments and attributes.

property direct_solution_success: The number of cases in which Criterion 2 yielded a closed-form solution, normalized by the number of cases in which Criterion 2 was evaluated (see Kostrykin and Rohr, TPAMI 2023).

property iterative_pruning_success: The number of objects pruned by Algorithm 1, normalized by the number of objects which would be computed if bruteforce was used instead of Algorithm 1 (see Kostrykin and Rohr, TPAMI 2023).

property nontrivial_pruning_success

The number of pruned objects within non-trivial regions of possibly clustered objects, normalized by the number of objects in those regions which would be computed if neither Algorithm 1 nor Criterion 2 was used (see Kostrykin and Rohr, TPAMI 2023).

This is the key performance indicator for the overall pruning performance.

property overall_pruning_success: The number of pruned objects, normalized by the number of objects which would be computed if neither Algorithm 1 nor Criterion 2 was used (see Kostrykin and Rohr, TPAMI 2023).