annotate measure_image_quality.xml @ 3:08a2cf887a44 draft

"planemo upload for repository https://github.com/bgruening/galaxytools/tree/master/tools commit c3917e27eb1c1deeb381aa0dc8161c07699562fb"

<tool id="cp_measure_image_quality" name="MeasureImageQuality" version="@CP_VERSION@">
    <description>measure features that indicate image quality</description>

    <macros>
        <import>macros.xml</import>
        <xml name="macro_calc_threshold">
            <conditional name="con_use_all_methods">
                <param name="use_all_methods" type="select" display="radio" label="Use all thresholding methods?">
                    <help>
                        <![CDATA[
                            Select 'Yes' to calculate thresholds using all the available methods. Only the global methods are used. While most methods are straightfoward, some methods have additional parameters that require special handling:
                            <br> - Otsu: Thresholds for all combinations of class number, minimization parameter and middle class assignment are computed.
                            <br> - Mixture of Gaussians (MoG): Thresholds for image coverage fractions of 0.05, 0.25, 0.75 and 0.95 are computed.
                            See the IdentifyPrimaryObjects module for more information on thresholding methods.
                            ]]>
                    </help>
                    <option value="Yes">Yes</option>
                    <option value="No">No</option>
                </param>
                <when value="Yes" />
                <when value="No">
                    <repeat name="rpt_threshold_method" title="new threshold method" min="1">
                        <conditional name="con_threshold_methods">
                            <param name="select_threshold_method" type="select" label="Select a thresholding method">
                                <help>
                                    This setting allows you to apply automatic thresholding methods used in the Identify modules.
                                    Only the global methods are applied. For more help on thresholding, see the Identify modules.
                                </help>
                                <option value="Otsu">Otsu</option>
                                <option value="MoG">MoG</option>
                                <option value="Background">Background</option>
                                <option value="RobustBackground">Robust background</option>
                                <option value="RidlerCalvard">Ridler Calvard</option>
                                <option value="Kapur">Kapur</option>
                                <option value="MCT">MCT</option>
                            </param>
                            <when value="Otsu">
                                <expand macro="otsu_method" />
                            </when>
                            <when value="MoG">
                                <expand macro="mog_method" />
                            </when>
                            <when value="Background" />
                            <when value="RobustBackground" />
                            <when value="RidlerCalvard" />
                            <when value="Kapur" />
                            <when value="MCT" />
                        </conditional>
                    </repeat>
                </when>
            </conditional>
        </xml>

        <xml name="otsu_method">
            <param name="otsu_weighted_entropy" label="Minimize the weighted variance or the entropy?" type="select">
                <option value="Weighted variance">Weighted variance</option>
                <option value="Entropy">Entropy</option>
            </param>
            <conditional name="con_threshold_classes">
                <param name="threshold_classes" label="Two-class or three-class thresholding?" type="select">
                    <help>
                        Select Two classes if the grayscale levels are readily distinguishable into foreground (i.e., objects) and background. 
                        Select Three classes if there is a middle set of grayscale levels that belongs to neither the foreground nor background.
                        For example, three-class thresholding may be useful for images in which you have nuclear staining along with a low-intensity non-specific cell staining. 
                        Where two-class thresholding might incorrectly assign this intermediate staining to the nuclei objects, three-class thresholding allows you to assign it to the foreground or background as desired. 
                        However, in extreme cases where either there are almost no objects or the entire field of view is covered with objects, three-class thresholding may perform worse than two-class.
                    </help>
                    <option value="Two classes">Two classes</option>
                    <option value="Three classes">Three classes</option>
                </param>
                <when value="Three classes">
                    <param name="pixel_foreground_or_background" label="Assign pixels in the middle intensity class to the foreground or the background?" type="select">
                        <option value="Foreground">Foreground</option>
                        <option value="Background">Background</option>
                    </param>
                </when>
                <when value="Two classes" />
            </conditional>
        </xml>

        <xml name="mog_method">
            <param name="mog_fraction_cover" label="Typical fraction of the image covered by objects" type="float" value="0.1" min="0.0" max="1.0"/>
        </xml>
    </macros>

    <expand macro="py_requirements"/>
    <expand macro="cmd_modules" />

    <configfiles>
        <inputs name="inputs" />

        <configfile name="script_file">
import json
import sys
import os

FOURSPACES=@SPACES@

input_json_path = sys.argv[1]
input_pipeline= sys.argv[2]

params = json.load(open(input_json_path, "r"))

def writemiq():
    _str = "\nMeasureImageQuality:[module_num:%d|svn_version:\\'Unknown\\'|variable_revision_number:5|show_window:False|notes:\\x5B\\x5D|batch_state:array(\\x5B\\x5D, dtype=uint8)|enabled:True|wants_pause:False]\n" % new_count

    for_images = params['calc_for_images']
    selected_images = ""

    if for_images == "All loaded images":
        _str += FOURSPACES + "Calculate metrics for which images?:%s\n" % for_images
    else:
        _str += FOURSPACES + "Calculate metrics for which images?:Select...\n"
        selected_images = params['calc_for_images']

    image_count = 1
    _str += FOURSPACES + "Image count:%d\n" % image_count

    if 'rpt_blur_measurements' in params['con_calc_blur_metrics']:
        scale_count = len(params['con_calc_blur_metrics']['rpt_blur_measurements'])
    else:
        scale_count = 1

    _str += FOURSPACES + "Scale count:%d\n" % scale_count

    calc_threshold = params['con_calc_threshold']['calc_threshold']
    if calc_threshold == "No":
        threshold_count = 1
        all_method = "No"
    else:
        all_method = params['con_calc_threshold']['con_use_all_methods']['use_all_methods']
    if all_method == "No":
        threshold_count = 1
    else:
        threshold_count = len(params['con_calc_threshold']['con_use_all_methods']['rpt_threshold_method'])

    _str += FOURSPACES + "Threshold count:%d\n" % threshold_count

    _str += FOURSPACES + "Select the images to measure:%s\n" % selected_images

    include_rescaling = params['include_rescaling_value']
    _str += FOURSPACES + "Include the image rescaling value?:%s\n" % include_rescaling

    calc_blur_metrics = params['con_calc_blur_metrics']['calc_blur_metrics']
    _str += FOURSPACES + "Calculate blur metrics?:%s\n" % calc_blur_metrics

    if calc_blur_metrics == "Yes" and 'rpt_blur_measurements' in params['con_calc_blur_metrics']:
        for bm in params['con_calc_blur_metrics']['rpt_blur_measurements']:
            _str += FOURSPACES + "Spatial scale for blur measurements:%d\n" % bm['blur_measurements']

    calc_saturation = params['calc_saturation_metrics']
    _str += FOURSPACES + "Calculate saturation metrics?:%s\n" % calc_saturation

    calc_intensity = params['calc_intensity_metrics']
    _str += FOURSPACES + "Calculate intensity metrics?:%s\n" % calc_intensity

    calc_threshold = params['con_calc_threshold']['calc_threshold']
    _str += FOURSPACES + "Calculate thresholds?:%s\n" % calc_threshold
    _str += FOURSPACES + "Use all thresholding methods?:%s\n" % all_method

    if all_method == "No":
        for method in params['con_calc_threshold']['con_use_all_methods']['rpt_threshold_method']:
            _str += FOURSPACES + "Select a thresholding method:%s\n" % method['con_threshold_methods']['select_threshold_method']
 
            fraction_cover = method['con_threshold_methods']['mog_fraction_cover'] if 'mog_fraction_cover' in method['con_threshold_methods'] else 0.1

            tt_classes = method['con_threshold_methods']['con_threshold_classes']['threshold_classes'] if 'con_threshold_classes' in method['con_threshold_methods'] else 'Two classes'

            minimize = method['con_threshold_methods']['otsu_weighted_entropy'] if 'otsu_weighted_entropy' in method['con_threshold_methods'] else 'Entropy'

            if tt_classes == "Three classes":
                pixel_intensity = method['con_threshold_methods']['con_threshold_classes']['pixel_foreground_or_background']
            else:
                pixel_intensity = "Foreground"

            _str += FOURSPACES + "Typical fraction of the image covered by objects:%.1f\n" % fraction_cover

            _str += FOURSPACES + "Two-class or three-class thresholding?:%s\n" % tt_classes

            _str += FOURSPACES + "Minimize the weighted variance or the entropy:%s\n" % minimize

            _str += FOURSPACES + "Assign pixels in the middle intensity class to the foreground or the background?:%s\n" % pixel_intensity

    return _str

with open(input_pipeline) as fin:
    lines = fin.readlines()

    k, v = lines[4].strip().split(':')

    module_count = int(v)
    new_count = module_count + 1
    lines[4] = k + ":%d\n" % new_count

    with open("output.cppipe", "w") as f:
        f.writelines(lines)
        f.write(writemiq())

    f.close()
        </configfile>
    </configfiles>

    <inputs>
        <expand macro="input_pipeline_param" />
        <param name="calc_for_images" type="text" label="Calculate metrics for which images?" value="All loaded images">
            <help>
                Image names are separated by comma and correspond to the values in the section NameAndType of the 'Starting module' tool.

            </help>
            <expand macro="text_validator" />
        </param>

        <param name="include_rescaling_value" type="select" display="radio" label="Include the image rescaling value?" help="Select 'Yes' to add the image’s rescaling value as a quality control metric. This value is recorded only for images loaded using the Input modules. This is useful in confirming that all images are rescaled by the same value, given that some acquisition device vendors may output this value differently. ">
            <option value="Yes">Yes</option>
            <option value="No">No</option>
        </param>

        <conditional name="con_calc_blur_metrics">
            <param name="calc_blur_metrics" type="select" display="radio" label="Calculate blur metrics?">
                <option value="Yes">Yes</option>
                <option value="No" selected="True">No</option>
            </param>
            <when value="Yes">
                <repeat name="rpt_blur_measurements" title="new scale" min="1">
                    <param name="blur_measurements" label="Spatial scale for blur measurements" type="integer" value="20">
                        <help>
                            Enter an integer for the window size N, in units of pixels. The LocalFocusScore is measured within an N × N pixel window applied to the image, and the Correlation of a pixel is measured with respect to its neighbors N pixels away.
                            A higher number for the window size N measures larger patterns of image blur whereas smaller numbers measure more localized patterns of blur. We suggest selecting a window size that is on the order of the feature of interest (e.g., the object diameter). You can measure these metrics for multiple window sizes by selecting additional scales for each image.
                        </help>
                    </param>
                </repeat>
            </when>
            <when value="No" />
        </conditional>

        <param name="calc_intensity_metrics" type="select" display="radio" label="Calculate intensity metrics?">
            <help>
                Select 'Yes' to calculate image-based intensity measures, namely the mean, maximum, minimum, standard deviation and median absolute deviation of pixel intensities. These measures are identical to those calculated by MeasureImageIntensity.
            </help>
            <option value="Yes">Yes</option>
            <option value="No">No</option>
        </param>
        <param name="calc_saturation_metrics" type="select" display="radio" label="Calculate saturation metrics">
            <help>
                Select 'Yes' to calculate the saturation metrics PercentMaximal and PercentMinimal, i.e., the percentage of pixels at the upper or lower limit of each individual image.
                For this calculation, the hard limits of 0 and 1 are not used because images often have undergone some kind of transformation such that no pixels ever reach the absolute maximum or minimum of the image format. Given the noise typical in images, both these measures should be a low percentage but if the images were saturated during imaging, a higher than usual PercentMaximal will be observed, and if there are no objects, the PercentMinimal value will increase.
            </help>
            <option value="Yes">Yes</option>
            <option value="No">No</option>
        </param>

        <conditional name="con_calc_threshold">
            <param name="calc_threshold" type="select" display="radio" label="Calculate thresholds?">
                <help>
                    Automatically calculate a suggested threshold for each image. One indicator of image quality is that these threshold values lie within a typical range. Outlier images with high or low thresholds often contain artifacts.
                </help>
                <option value="Yes">Yes</option>
                <option value="No">No</option>
            </param>
            <when value="Yes">
                <expand macro="macro_calc_threshold" />
            </when>
            <when value="No" />
        </conditional>

    </inputs>

    <outputs>
        <expand macro="output_pipeline_param" />
    </outputs>

    <tests>
        <test>
            <expand macro="test_input_pipeline_param" />

            <param name="calc_for_images" value="All loaded images" />
            <param name="include_rescaling_value" value="Yes" />

            <conditional name="con_calc_blur_metrics">
                <param name="calc_blur_metrics" value="Yes" />
                <repeat name="rpt_blur_measurements">
                    <param name="blur_measurements" value="20" />
                </repeat>
            </conditional>

            <param name="calc_intensity_metrics" value="Yes" />
            <param name="calc_saturation_metrics" value="Yes" />
            <conditional name="con_calc_threshold">
                <param name="calc_threshold" value="Yes" />
            </conditional>

            <conditional name="con_use_all_methods">
                <param name="use_all_methods" value="No" />
                <repeat name="rpt_threshold_method">
                    <conditional name="con_threshold_methods">
                        <param name="select_threshold_method" value="Otsu" />
                        <param name="otsu_weighted_entropy" value="Weighted variance" />
                        <conditional name="con_threshold_classes">
                            <param name="threshold_classes" value="Two classes" />
                        </conditional>
                    </conditional>
                </repeat>
            </conditional>

            <expand macro="test_out_file" file="measure_image_quality.cppipe" />
        </test>
    </tests>

    <help>
        <![CDATA[

            .. class:: infomark

            **What it does**

            This tool collects measurements indicating possible image aberrations, e.g., blur (poor focus), intensity, saturation (i.e., the percentage of pixels in the image that are at/near the maximum possible value, and at/near the minimum possible value).
            Details and guidance for each of these measures is provided in the settings help.
            Please note that for best results, this module should be applied to the original raw images, rather than images that have already been corrected for illumination.

            @COMMON_HELP@
            ]]>
    </help>

    <expand macro="citations" />
</tool>