annotate idr_download_by_ids.xml @ 11:cbd605a24336 draft

"planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/idr_download commit b68715960d1107593db13dd9e1dbd8d4b905cc6f"

<?xml version="1.0"?>
<tool id="idr_download_by_ids" name="IDR/OMERO Download" version="0.44" profile="18.09">
    <description>- download images from any OMERO instance 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.10.1">omero-py</requirement>
        <requirement type="package" version="0.4.2">pylibtiff</requirement>
    </requirements>
    <command detect_errors="exit_code"><![CDATA[
        
        #if $omero_instance_type.omero_instance == "priv":
            ## the user wants to use a non-public OMERO instance
            ## check if credentials are set in the user-preferences, if not warn the user and exit
            #set $username = $__user__.extra_preferences.get('omero_account|username', "")
            #set $password = $__user__.extra_preferences.get('omero_account|password', "")

            #if $omero_instance_type.galaxy_test_param != 'true' and ($username == "" or $password ==""):
                echo "OMERO connection credentials are empty. Set your credentials via: User -> Preferences -> Manage Information" 1>&2 &&
                exit 1 &&
            #end if
        #end if
        
        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
        #elif str($image_ids.source) == 'dataset':
            cat '${image_ids.id_spec}'
        #else:
            echo '${image_ids.id_dataset_omero}'
        #end if
        | python '$__tool_directory__/idr_download_by_ids.py' 
        #if str($image_ids.source) == 'omeroDatasetID':
            --dataset
        #end if
        #if $image_region.original == "original":
            --download-original
        #else:
            #set $channel = str($image_region.channel).strip()
            #if $channel:
                -c '$channel'
            #end if
            -f $image_region.frame
            -z $image_region.z_section
            #if str($image_region.clip_image.select):
                ${image_region.clip_image.select} ${image_region.clip_image.x_coord} ${image_region.clip_image.y_coord} ${image_region.clip_image.width} ${image_region.clip_image.height}
            #end if
        #end if
        $skip_failed
        $download_tar
        #if $omero_instance_type.omero_instance =='priv':
            -oh '$omero_instance_type.omero_host'
            $omero_instance_type.omero_secured
            -cf '$credentials'
        #end if
        2> >(tee -a $out_log >&2)
    ]]></command>
    <configfiles>
        <configfile name="credentials"><![CDATA[
#if $omero_instance_type.omero_instance =='priv' and $omero_instance_type.galaxy_test_param == 'true':
    ## as a test for a private instance we actually use a public instance, but with credentials
    #set $username = 'public'
    #set $password = 'public'
#else:
    #set $username = $__user__.extra_preferences.get('omero_account|username', "")
    #set $password = $__user__.extra_preferences.get('omero_account|password', "")
#end if
{
    "username": "$username",
    "password": "$password"
}
        ]]></configfile>
    </configfiles>
<inputs>
        <conditional name="omero_instance_type">
            <param name="omero_instance" type="select" label="Which OMERO instance to connect?"
                   help="By default, the tool will download a tarball containing individual images from IDR into your Galaxy history. If you 
                   need to connect to your own instance, set your connection username and password from User->Preference->Manage Information" >
                <option value="idr">IDR</option>
                <option value="priv">other OMERO instance</option>
            </param>
            <when value="priv">
                <param name="omero_host" type="text" label="OMERO host URL">
                    <validator type="regex" message="Enter a valid host location, for example, your.omero.server">^[a-zA-Z0-9._-]*$</validator>
                    <validator type="expression" message="No two dots (..) allowed">'..' not in value</validator>
                </param>
                <param name="omero_secured" type="boolean" label="Secured connection?" checked="true" truevalue="--omero-secured" falsevalue=""
                        help="Select Yes if your OMERO instance is running with SSL, otherwise select No">
                </param>
                <param name="galaxy_test_param" type="hidden" value="false" />
            </when>
            <when value="idr" />
        </conditional>

        <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>
                <option value="omeroDatasetID">All images from a single Dataset ID</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>
            <when value="omeroDatasetID">
                <param name="id_dataset_omero" type="integer" min = "0" value = "9059" label="Dataset ID"/>
            </when>
        </conditional>

        <conditional name="image_region">
            <param name="original" type="select" label="Which images do you want to download?">
                <option value="TIFF" selected="true">Exported TIFF (single channel, single stack)</option>
                <option value="original">Original file (file uploaded to omero, only available for private instances)</option>
            </param>
            <when value="original"/>
            <when value="TIFF">
                <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>
            </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." />
        <param name="download_tar" type="boolean" checked="true" truevalue="--download-tar" falsevalue=""
        label="Download images in a tarball?"
        help="By default, the tool will download a tarball containing individual images into your Galaxy history. This option is strongly recommended, especially for a large number of files. With this option set to No, you will download a collection of images, only suggested for a small number of files." >
        </param>
    </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" />
            <filter>not download_tar</filter>
        </collection>
        <data name="output_tar" format="tar" from_work_dir="./downloads/images.tar" label ="Images tarball">
            <filter>download_tar</filter>
        </data> 
    </outputs>
    <tests>
        <test>
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <param name="source" value="dataset" />
            <param name="id_spec" value="ids.txt" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/>
                <param name="channel" value="PCNT" />
                <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="0" />
            </conditional>
            <param name="download_tar" value="false" />
            <output_collection name="output_file" type="list">
                <element name="Centrin_PCNT_Cep215_20110506_Fri-1545_0_SIR_PRJ__1884807__3__3__5__5" ftype="tiff" file="test0.tiff"/>
            </output_collection>
        </test>
        <test>
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <param name="source" value="link" />
            <param name="id_spec" value="1884807" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/> 
                <param name="channel" value="PCNT" />
                <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" />
            </conditional>
            <param name="download_tar" value="false" />
            <output_collection name="output_file" type="list">
                <element name="Centrin_PCNT_Cep215_20110506_Fri-1545_0_SIR_PRJ__1884807__3__3__5__5" ftype="tiff" file="test1.tiff"/>
            </output_collection>
        </test>
        <test>
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <param name="source" value="link" />
            <param name="id_spec" value="1884807" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/> 
                <param name="channel" value="PCNT" />
                <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" />
            </conditional>
            <param name="download_tar" value="false" />
            <output_collection name="output_file" type="list">
                <element name="Centrin_PCNT_Cep215_20110506_Fri-1545_0_SIR_PRJ__1884807__3__3__5__5" ftype="tiff" file="test2.tiff"/>
            </output_collection>
        </test>
        <test>
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <param name="source" value="link" />
            <param name="id_spec" value="https://idr.openmicroscopy.org/webclient/?show=image-9036708|image-9036710|image-9036711" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/> 
                <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" />
            </conditional>
            <param name="download_tar" value="false" />
            <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">
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <!-- 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" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/> 
                <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" />
            </conditional>
            <param name="download_tar" value="false" />
        </test>
        <test>
            <!-- Repeat test with non-existing image-ID 9036708999,
            but use skip-failed option -->
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <param name="source" value="link" />
            <param name="id_spec" value="https://idr.openmicroscopy.org/webclient/?show=image-9036708999|image-9036710|image-9036711" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/> 
                <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" />
            </conditional>
            <param name="skip_failed" value="true" />
            <param name="download_tar" value="false" />
            <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>
        <test>
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <!-- Test for download images in a tarball -->
            <param name="source" value="dataset" />
            <param name="id_spec" value="ids_tar.txt" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/> 
                <param name="channel" value="Hoechst" />
                <conditional name="clip_image">
                    <param name="select" value="--rectangle" />
                    <param name="x_coord" value="0" />
                    <param name="y_coord" value="0" />
                    <param name="width" value="671" />
                    <param name="height" value="511" />
                </conditional>
                <param name="frame" value="0" />
            </conditional>
            <output name="output_tar">
                    <assert_contents>
                        <has_size value="1382400" />
                        <has_archive_member path=".*/*__1828167__0__0__671__511.tiff" >
                            <has_size value="685896" />
                        </has_archive_member>
                        <has_archive_member path=".*/*__1828658__0__0__671__511.tiff" >
                            <has_size value="685896" />
                        </has_archive_member>
                    </assert_contents>
            </output>
        </test>
        <test>
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="priv" />
                 <param name="omero_host" value="idr.openmicroscopy.org" />
                 <param name="omero_secured" value="true" />
                 <param name="galaxy_test_param" value="true" />
            </conditional>
            <param name="source" value="dataset" />
            <param name="id_spec" value="ids.txt" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/> 
                <param name="channel" value="PCNT" />
                <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="0" />
            </conditional>
            <param name="download_tar" value="false" />
            <output_collection name="output_file" type="list">
                <element name="Centrin_PCNT_Cep215_20110506_Fri-1545_0_SIR_PRJ__1884807__3__3__5__5" file="test0.tiff"/>
            </output_collection>
        </test>
        <test expect_failure="true">
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="priv" />
                 <param name="omero_host" value="idr.openmicroscopy.org" />
                 <param name="omero_secured" value="true" />
            </conditional>
            <param name="source" value="dataset" />
            <param name="id_spec" value="ids.txt" />
            <conditional name="image_region">
                <param name="original" value="TIFF"/> 
                <param name="channel" value="PCNT" />
                <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="0" />
            </conditional>
            <param name="download_tar" value="false" />
            <assert_stderr>
                <has_text text="OMERO connection credentials are empty. Set your credentials via: User -> Preferences -> Manage Information" />
            </assert_stderr >
        </test>
        <test>
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <!-- Test for download all images from a dataset -->
            <param name="source" value="omeroDatasetID" />
            <param name="id_dataset_omero" value="9059" />
            <param name="download_tar" value="false" />
            <output_collection name="output_file" type="list" count="4">
                <element name="171101_LeadingEdgeDeletionPSMMovies01_15_R3D__9036711__0__0__1024__1024">
                    <assert_contents>
                        <has_size value="2097286" />
                    </assert_contents>
                </element>
                <element name="171101_LeadingEdgeDeletionPSMMovies01_15_R3D_D3D__9036708__0__0__1024__1024">
                    <assert_contents>
                        <has_size value="2097286" />
                    </assert_contents>
                </element>
                <element name="171101_LeadingEdgeDeletionPSMMovies01_15_R3D_D3D_zproj__9036710__0__0__1024__1024">
                    <assert_contents>
                        <has_size value="2097286" />
                    </assert_contents>
                </element>
                <element name="171101_LeadingEdgeDeletionPSMMovies01_15_R3D_REF__9036709__0__0__1024__1024">
                    <assert_contents>
                        <has_size value="2097286" />
                    </assert_contents>
                </element>
            </output_collection>
        </test>
        <test>
            <conditional name="omero_instance_type">
                 <param name="omero_instance" value="idr" />
            </conditional>
            <!-- Test for download all original files from a dataset -->
            <!-- Impossible in idr: -->
            <param name="source" value="omeroDatasetID" />
            <param name="id_dataset_omero" value="9059" />
            <param name="skip_failed" value="true" />
            <param name="download_tar" value="false" />
            <conditional name="image_region">
                <param name="original" value="original"/> 
            </conditional>
            <output_collection name="output_file" type="list" count="0">
            </output_collection>
        </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).

Finally, if you want to download all images of a single dataset. Specify the id as 
All images from a single Dataset ID.

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>