<?xml version="1.0"?>
<tool id="idr_download_by_ids" name="IDR Download" version="0.30" profile="18.09">
    <description>- download images from the Image Data Resource using image IDs</description>
    <macros>
        <xml name="region_spec" token_pos="upper-left corner">
            <param name="x_coord" type="integer" value="0" min="0"
            label="x-coordinate of region @POS@" />
            <param name="y_coord" type="integer" value="0" min="0"
            label="y-coordinate of region @POS@" />
            <param name="width" type="integer" value="0" min="0"
            label="Region width"
            help="Set to zero to extend the rectangle maximally along the x-axis of the image" />
            <param name="height" type="integer" value="0" min="0"
            label="Region height"
            help="Set to zero to extend the rectangle maximally along the y-axis of the image" />
        </xml>
    </macros>
    <requirements>
        <requirement type="package" version="5.6.0">python-omero</requirement>
        <requirement type="package" version="0.4.2">pylibtiff</requirement>
    </requirements>
    <command detect_errors="exit_code"><![CDATA[
        mkdir downloads && cd downloads &&
        #if str($image_ids.source) == 'link':
            python -c 'print("${image_ids.id_spec}".replace(",", "|").split("?show=")[-1].replace("|", "\n"))'
            ## https://idr.openmicroscopy.org/webclient/?show=image-3426274|image-3426275|image-3426276|image-3426277
        #else:
            cat '${image_ids.id_spec}'
        #end if
        | python '$__tool_directory__/idr_download_by_ids.py' 
        #set $channel = str($channel).strip()
        #if $channel:
            -c '$channel'
        #end if
        -f $frame
        -z $z_section
        #if str($clip_image.select):
            ${clip_image.select} ${clip_image.x_coord} ${clip_image.y_coord} ${clip_image.width} ${clip_image.height}
        #end if
        $skip_failed

        2> >(tee -a $out_log >&2)
    ]]></command>
<inputs>
        <conditional name="image_ids">
            <param name="source" type="select" label="How would you like to specify the IDs of images to download?">
                <option value="link">As text (comma-separated list of IDs or a valid IDR link)</option>
                <option value="dataset">As a dataset (one image ID per line)</option>
            </param>
            <when value="link">
                <param name="id_spec" type="text"
                label="Image IDs to download"
                help="You can enter a single image-id, or a comma (or '|')-separated list of IDs. Alternatively, you can paste here a link to an image selection obtained through the IDR webclient.">
                    <sanitizer>
                        <valid><add value="|" /></valid>
                    </sanitizer>
                </param>
            </when>
            <when value="dataset">
                <param name="id_spec" type="data" format="txt"
                label="Select a dataset with image IDs (one per line)" />
            </when>
        </conditional>
        <param name="channel" type="text"
        label="Name of the channel to download"
        help="For all image IDs only the specified channel will be downloaded. If left empty, the first channel (whatever this is) will be downloaded by default." />
        <param name="z_section" type="integer" value="0" min="0"
        label="z-plane of images to download" />
        <param name="frame" type="integer" value="0" min="0"
        label="Image frame to download" />
        <conditional name="clip_image">
            <param name="select" type="select"
            label="Limit the download to a selected region of the image?">
                <option value="">No, download the entire image plane</option>
                <option value="--rectangle">Specify a region using its upper-left corner</option>
                <option value="--center">Specify a width x height region around a central point</option>
            </param>
            <when value="" />
            <when value="--rectangle">
                <expand macro="region_spec" />
            </when>
            <when value="--center">
                <expand macro="region_spec" pos="center" />
            </when>
        </conditional>
        <param name="skip_failed" type="boolean" checked="false" truevalue="--skip-failed" falsevalue=""
        label="Skip failed retrievals?"
        help="By default the tool will fail with an error on the first non-retrievable image ID. Here, you can choose to skip non-retrievable image IDs and continue downloading the available ones instead. The error log will contain warnings about failed IDs in this case." />
    </inputs>
    <outputs>
        <data name="out_log" format="txt" label="${tool.name} error log" />
        <collection name="output_file" type="list">
            <discover_datasets pattern="__name_and_ext__" directory="downloads" />
        </collection>
    </outputs>
    <tests>
        <test>
            <param name="source" value="dataset" />
            <param name="id_spec" value="ids.txt" />
            <param name="channel" value="615.0" />
            <conditional name="clip_image">
                <param name="select" value="--rectangle" />
                <param name="x_coord" value="3" />
                <param name="y_coord" value="3" />
                <param name="width" value="5" />
                <param name="height" value="5" />
            </conditional>
            <param name="frame" value="2" />
            <output_collection name="output_file" type="list">
                <element name="Centrin_PCNT_Cep215_20110506_Fri-1545_0_SIR_PRJ__1884807__3__3__5__5" file="test1.tiff"/>
            </output_collection>
        </test>
        <test>
            <param name="source" value="link" />
            <param name="id_spec" value="1884807" />
            <param name="channel" value="615.0" />
            <conditional name="clip_image">
                <param name="select" value="--rectangle" />
                <param name="x_coord" value="3" />
                <param name="y_coord" value="3" />
                <param name="width" value="5" />
                <param name="height" value="5" />
            </conditional>
            <param name="frame" value="2" />
            <output_collection name="output_file" type="list">
                <element name="Centrin_PCNT_Cep215_20110506_Fri-1545_0_SIR_PRJ__1884807__3__3__5__5" file="test1.tiff"/>
            </output_collection>
        </test>
        <test>
            <param name="source" value="link" />
            <param name="id_spec" value="1884807" />
            <param name="channel" value="615.0" />
            <conditional name="clip_image">
                <param name="select" value="--center" />
                <param name="x_coord" value="5" />
                <param name="y_coord" value="5" />
                <param name="width" value="5" />
                <param name="height" value="5" />
            </conditional>
            <param name="frame" value="2" />
            <output_collection name="output_file" type="list">
                <element name="Centrin_PCNT_Cep215_20110506_Fri-1545_0_SIR_PRJ__1884807__3__3__5__5" file="test1.tiff"/>
            </output_collection>
        </test>
        <test>
            <param name="source" value="link" />
            <param name="id_spec" value="https://idr.openmicroscopy.org/webclient/?show=image-9036708|image-9036710|image-9036711" />
            <param name="channel" value="Spo20(51-91)" />
            <param name="z_section" value="4" />
            <conditional name="clip_image">
                <param name="select" value="" />
            </conditional>
            <param name="frame" value="20" />
            <output_collection name="output_file" type="list" count="3">
                <element name="171101_LeadingEdgeDeletionPSMMovies01_15_R3D__9036711__0__0__1024__1024">
                    <assert_contents>
                        <has_size value="2097286" />
                    </assert_contents>
                </element>
            </output_collection>
            <output name="out_log">
                <assert_contents>
                    <has_text text="(ID: 9036710): Specified image plane (4) is out of bounds"/>
                    <has_n_lines n="1"/>
                </assert_contents>
            </output>
        </test>
        <test expect_failure="true">
            <!-- Test behavior with non-existing image-ID 9036708999 -->
            <param name="source" value="link" />
            <param name="id_spec" value="https://idr.openmicroscopy.org/webclient/?show=image-9036708999|image-9036710|image-9036711" />
            <param name="channel" value="Spo20(51-91)" />
            <param name="z_section" value="4" />
            <conditional name="clip_image">
                <param name="select" value="" />
            </conditional>
            <param name="frame" value="20" />
        </test>
        <test>
            <!-- Repeat test with non-existing image-ID 9036708999,
            but use skip-failed option -->
            <param name="source" value="link" />
            <param name="id_spec" value="https://idr.openmicroscopy.org/webclient/?show=image-9036708999|image-9036710|image-9036711" />
            <param name="channel" value="Spo20(51-91)" />
            <param name="z_section" value="4" />
            <conditional name="clip_image">
                <param name="select" value="" />
            </conditional>
            <param name="frame" value="20" />
            <param name="skip_failed" value="true" />
            <output_collection name="output_file" type="list" count="2">
                <element name="171101_LeadingEdgeDeletionPSMMovies01_15_R3D__9036711__0__0__1024__1024">
                    <assert_contents>
                        <has_size value="2097286" />
                    </assert_contents>
                </element>
            </output_collection>
            <output name="out_log">
                <assert_contents>
                    <has_text text="9036708999: Unable to find an image with this ID in the database. Skipping download!" />
                    <has_text text="(ID: 9036710): Specified image plane (4) is out of bounds" />
                    <has_n_lines n="2"/>
                </assert_contents>
            </output>
        </test>
    </tests>
    <help><![CDATA[
Download image data from the IDR_ (Image Data Resource) - a public repository
of reference image datasets from published scientific studies.

.. _IDR: https://idr.openmicroscopy.org/about/

-----

.. class:: infomark

**Input**

A set of image IDs as can be obtained from the IDR webclient_ like this:

1. Select the wells you want to download in the thumbnails.

2. Select at the bottom the images in those wells that you want to download (one well might contain several images).

3. Click on the 'Link' button on the top right of the page and copy the provided URL.

4. Paste the URL into the input field of this tool, for example:

    https://idr.openmicroscopy.org/webclient/?show=image-9036708|image-9036710|image-9036711

Alternatively, you can simply provide a list of known image IDs in the text
input field (comma or '|'-separated ), or as an input file (each ID on a
separate line).

Most images in the IDR have more than two dimensions. Thus, there are
parameters available which allow you to select a particular recording channel,
z-plane or time frame to download.
You can also select a region which will be used to crop the images, rather
than downloading the entire file.

.. _webclient: https://idr.openmicroscopy.org/


-----

.. class:: infomark

**Output**

Downloaded images will be saved in TIFF format. If you selected multiple image
IDs to download, these will be saved as elements of a collection.

The accompanying error log dataset may hold valuable information about requests
that could not be fulfilled exactly as specified, or that were found to be
ambiguous.
    ]]></help>
    <citations>
        <citation type="doi">10.1038/nmeth.4326</citation>
    </citations>
</tool>