superdsm.dsmcfg

class superdsm.dsmcfg.DSM_Config

Bases: Stage

Fetches the hyperparameters from the dsm namespace and provides them as an output.

The purpose of this stage is to provide the hyperparameters from the dsm namespace as the output dsm_cfg, which is a dictionary of the hyperparameters without the leading dsm/ namespace prefix. This enables any stage to access the DSM-related hyperparameters, like the C2F_RegionAnalysis and GlobalEnergyMinimization stages, without having to access the dsm hyperparameter namespace. Refer to Inputs and outputs for more information on the available inputs and outputs.

Hyperparameters

The following hyperparameters are fetched:

dsm/cachesize: The maximum number of entries used for caching during convex programming. This concerns invocations of the callback function F used by the cvxopt solver for nonlinear problems. Defaults to 1.
dsm/cachetest: The test function to be used for cache testing. If None, then numpy.array_equal will be used. Using other functions like numpy.allclose has shown to introduce numerical instabilities. Defaults to None.
dsm/init: Either a function or a string. If this is function, then it will be called to determine the initialization, and the dimension of the vector \(\xi\) will be passed as a parameter. If this is a string, then the initialization corresponds to the result of convex programming using elliptical models (if set to elliptical, see Supplemental Material 6 of Kostrykin and Rohr, TPAMI 2023) or a zeros vector of is used (otherwise). Defaults to elliptical.
dsm/smooth_amount: Corresponds to \(\sigma_G\) described in Deformable shape models. Defaults to 10, or to AF_smooth_amount × scale if computed automatically (forced to \(\geq 4\) and AF_smooth_amount defaults to 0.2).
dsm/smooth_subsample: Corresponds to the amount of sub-sampling used to obtain the matrix \(\tilde G_\omega\) in Kostrykin and Rohr (TPAMI 2023, Section 3.3). Defaults to 20, or to AF_smooth_subsample × scale if computed automatically (forced to \(\geq 8\) and AF_smooth_subsample defaults to 0.4).
dsm/epsilon: Corresponds to the constant \(\epsilon\) which is used for the smooth approximation of the regularization term \(\|\xi\|_1 \approx \mathbb 1^\top_\Omega \sqrt{\xi^2 + \epsilon} - \sqrt{\epsilon} \cdot \#\Omega\) (see Supplemental Material 2 of Kostrykin and Rohr, TPAMI 2023). Defaults to 1.
dsm/alpha: Governs the regularization of the deformations and corresponds to \(\alpha\) described in Convex energy minimization. Increasing this value leads to a smoother segmentation result. Defaults to 0.5, or to AF_alpha × scale^2 if computed automatically (where AF_alpha corresponds to \(\alpha_\text {factor}\) in Kostrykin and Rohr, TPAMI 2023, and defaults to 5e-4).
dsm/scale: Fixed factor used during convex programming to slightly improve numerical stabilities. Defaults to 1000.
dsm/gaussian_shape_multiplier: The Gaussian function with standard deviation \(\sigma_G\) used to construct the block Toeplitz matrix \(G_\omega\) is cut off after \(4 \sigma_G\) multiplied by this value (see Deformable shape models). Defaults to 2.
dsm/smooth_mat_dtype: A string indicating the data type used for the matrix \(G_\omega\). Defaults to float32.
dsm/smooth_mat_max_allocations: Maximum number of simultaneous allocation of the matrix \(\tilde G_\omega\) during parallel processing (see Section 3.3 of Kostrykin and Rohr, TPAMI 2023, each allocation might require a considerable amount of system memory).
dsm/background_margin: Governs the amount of image background included in the obtained image region. This is the width of the “stripe” of background retained around each connected foreground region (in pixels). See Supplemental Material 6 of Kostrykin and Rohr (TPAMI 2023) for details, however, due to a transmission error, the threshold \(\sigma_G\) in Eq. (S11) was misstated by a factor of 2 (the correct threshold is \(2 \sigma_G\)). Defaults to 20, or to AF_background_margin × scale if computed automatically (forced to \(\geq 8\) and AF_background_margin defaults to 0.4).
dsm/cp_timeout: The maximum run time of convex programming for each object (in seconds). The convex optimization will be interrupted if it takes longer than that (the cvxprog() function will report the status fallback in this case). If this is set to None, the run time is not limited. Defaults to 300 (i.e. 5 minutes).

configure(pipeline, input_id, *args, scale, **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 = 'dsm': The stage identifier.

outputs: Collection[str] = ['dsm_cfg']: List of fields produced by this stage.

process(pipeline, config, status=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.