superdsm.c2freganal

class superdsm.c2freganal.C2F_RegionAnalysis

Bases: Stage

Implements the Coarse-to-fine region analysis scheme.

This stage requires y and dsm_cfg for input and produces y_mask, atoms, adjacencies, seeds, clusters for output. Refer to Inputs and outputs for more information on the available inputs and outputs.

Hyperparameters

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

c2f-region-analysis/seed_connectivity: Image points which are adjacent to each other are not to determine the atomic image regions. Adjacency of such image points is determined using either 4-connectivity or 8-connectivity. Must be either 4 or 8. Defaults to 8.
c2f-region-analysis/min_atom_radius: No region determined by the Coarse-to-fine region analysis scheme is smaller than a circle of this radius (in terms of the surface area). Corresponds to min_region_radius in Kostrykin and Rohr (TPAMI 2023, Supplemental Materials 5 and 8). Defaults to 15, or to AF_min_atom_radius × radius if configured automatically (and AF_min_atom_radius defaults to 0.33).
c2f-region-analysis/max_atom_norm_energy: No atomic image region \(\omega\) determined by the Coarse-to-fine region analysis has a normalized energy \(r(\omega)\) smaller than this value. Corresponds to max_norm_energy1 in Kostrykin and Rohr (TPAMI 2023, Supplemental Materials 5 and 8). Defaults to 0.05.
c2f-region-analysis/min_norm_energy_improvement: Each split performed during the computation of the atomic image regions must improve the normalized energy \(r(\omega)\) of an image region \(\omega\) by at least this factor (see Coarse-to-fine region analysis). Given that an image region is split into the sub-regions \(\omega_1, \omega_2\), the improvement of the split is defined by the fraction \(\max\{ r(\omega_1), r(\omega_1) \} / r(\omega_1 \cup \omega_2)\). Lower values of the fraction correspond to better improvements. Defaults to 0.1.
c2f-region-analysis/max_cluster_marker_irregularity: Threshold for the “irregularity” of image regions, which is used to determine the output y_mask. Image regions with an “irregularity” higher than this value are masked as “empty” image regions and discarded from further considerations. This is the threshold for the P/A ratio described in Kostrykin and Rohr (TPAMI 2023, see Section 3.1 and max_pa_ratio in Supplemental Material 8). Defaults to 0.2.

Note

This stage takes the DSM-related hyperparameters as an input. Due to a bug in the original implementation, the value set for the hyperparameter dsm/background_margin was disrespected and a value of 20 was always used instead. However, the impact on the results is only subtle. Having this issue fixed, the results are mostly consistent with those originally reported in Kostrykin and Rohr (TPAMI 2023, the hyperparameter \(\alpha\) is changed from 0.1 to 0.2 for the GOWT1-2 dataset when using SuperDSM, see the examples/GOWT1-2/default/adapted/task.json file).

configure(pipeline, input_id, *args, radius, **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 = 'c2f-region-analysis': The stage identifier.

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

outputs: Collection[str] = ['y_mask', 'atoms', 'adjacencies', 'seeds', 'clusters']: List of fields produced by this stage.

process(y, dsm_cfg, 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.