diff --git a/lib/galaxy/tools/filter_empty_collection_1.1.0.xml b/lib/galaxy/tools/filter_empty_collection_1.1.0.xml index 02cb73e2631..fde51ce3eaa 100644 --- a/lib/galaxy/tools/filter_empty_collection_1.1.0.xml +++ b/lib/galaxy/tools/filter_empty_collection_1.1.0.xml @@ -42,21 +42,58 @@ Synopsis ======== -Removes empty datasets from a collection. +Removes empty (zero-byte) datasets from a collection. =========== Description =========== -This tool takes a dataset collection and filters out (removes) datasets that have no content (zero bytes). This is useful for continuing a multi-sample analysis when downstream tools require datasets to have content. +This tool takes a dataset collection and filters out elements that have no content. A dataset is considered empty if it contains zero bytes of actual data (including compressed archives that decompress to nothing). -Optionally, you can provide a replacement dataset. When a replacement is specified, empty elements are replaced with that dataset instead of being removed. +This is useful when a multi-sample analysis produces some empty outputs — for example, when a filtering step removes all reads for certain samples. Downstream tools often fail on empty inputs, so removing them lets the rest of the analysis proceed. + +Optionally, you can provide a **replacement dataset**. When specified, empty elements are replaced with that dataset instead of being removed. This preserves the collection size, which is important when element-wise pairing with another collection is needed. + +======== +Examples +======== + +**Remove empty elements** + +Given a list collection where one sample produced no output:: + + List: "Filtered reads" + + sample1 → reads.fastq (1.2 MB) + sample2 → reads.fastq (0 bytes) + sample3 → reads.fastq (800 KB) + +The output keeps only non-empty elements:: + + List: "Filtered reads (filtered empty datasets)" + + sample1 → reads.fastq (1.2 MB) + sample3 → reads.fastq (800 KB) + +------- + +**Replace instead of remove** + +If a replacement dataset is provided, empty elements are swapped rather than dropped, preserving the collection structure:: + + List: "Filtered reads (filtered empty datasets)" + + sample1 → reads.fastq (1.2 MB) + sample2 → replacement.fastq + sample3 → reads.fastq (800 KB) + +------- .. image:: ${static_path}/images/tools/collection_ops/filter_empty.svg - :alt: Filtering empty datasets + :alt: Filter empty datasets from collection :width: 500 ------ +------- .. class:: infomark diff --git a/lib/galaxy/tools/filter_failed_collection_1.1.0.xml b/lib/galaxy/tools/filter_failed_collection_1.1.0.xml index e6c081bf01b..3d58f5a9357 100644 --- a/lib/galaxy/tools/filter_failed_collection_1.1.0.xml +++ b/lib/galaxy/tools/filter_failed_collection_1.1.0.xml @@ -53,15 +53,52 @@ Removes datasets in the error (red) state from a collection. Description =========== -This tool takes a dataset collection and filters out (removes) datasets in the failed (red) state. This is useful for continuing a multi-sample analysis when one or more of the samples fails at some point. +This tool takes a dataset collection and filters out elements whose datasets are in the failed (red) state. A dataset enters this state when the tool that created it encountered an error during execution. -Optionally, you can provide a replacement dataset. When a replacement is specified, failed elements are replaced with that dataset instead of being removed. +This is useful when running a multi-sample analysis and one or more samples fail at some step. Rather than restarting the entire analysis, you can remove the failed elements and continue with the samples that succeeded. + +Optionally, you can provide a **replacement dataset**. When specified, failed elements are replaced with that dataset instead of being removed. This preserves the collection size, which is important when element-wise pairing with another collection is needed. + +======== +Examples +======== + +**Remove failed elements** + +Given a list collection where one sample's alignment failed:: + + List: "Aligned reads" + + sample1 → aligned.bam (ok) + sample2 → aligned.bam (error) + sample3 → aligned.bam (ok) + +The output keeps only successful elements:: + + List: "Aligned reads (filtered failed datasets)" + + sample1 → aligned.bam + sample3 → aligned.bam + +------- + +**Replace instead of remove** + +If a replacement dataset is provided, failed elements are swapped rather than dropped, preserving the collection structure:: + + List: "Aligned reads (filtered failed datasets)" + + sample1 → aligned.bam + sample2 → replacement.bam + sample3 → aligned.bam + +------- .. image:: ${static_path}/images/tools/collection_ops/filter_error.svg - :alt: Filter failed datasets + :alt: Filter failed datasets from collection :width: 500 ------ +------- .. class:: infomark diff --git a/lib/galaxy/tools/filter_null_1.1.0.xml b/lib/galaxy/tools/filter_null_1.1.0.xml index 7f074e520a5..215d1666a0c 100644 --- a/lib/galaxy/tools/filter_null_1.1.0.xml +++ b/lib/galaxy/tools/filter_null_1.1.0.xml @@ -44,11 +44,52 @@ Removes null (missing) elements from a collection. Description =========== -This tool takes a dataset collection and filters out null elements. Null elements can appear when workflows use conditional steps -- if a step is skipped, it may produce a null placeholder instead of a real dataset. +This tool takes a dataset collection and filters out null elements. A null element is a placeholder that contains no actual dataset — it appears when a workflow uses conditional steps and a step is skipped, or when an expression tool produces a ``null`` value. -Optionally, you can provide a replacement dataset. When a replacement is specified, null elements are replaced with that dataset instead of being removed. +This is useful for cleaning up collections produced by conditional workflows. Downstream tools cannot process null elements, so removing them ensures the rest of the analysis can proceed. ------ +Optionally, you can provide a **replacement dataset**. When specified, null elements are replaced with that dataset instead of being removed. This preserves the collection size, which is important when element-wise pairing with another collection is needed. + +======== +Examples +======== + +**Remove null elements** + +Given a list collection produced by a conditional workflow where one branch was skipped:: + + List: "Workflow outputs" + + sample1 → result.txt (ok) + sample2 → (null) + sample3 → result.txt (ok) + +The output keeps only real elements:: + + List: "Workflow outputs (without null datasets)" + + sample1 → result.txt + sample3 → result.txt + +------- + +**Replace instead of remove** + +If a replacement dataset is provided, null elements are swapped rather than dropped, preserving the collection structure:: + + List: "Workflow outputs (without null datasets)" + + sample1 → result.txt + sample2 → replacement.txt + sample3 → result.txt + +------- + +.. image:: ${static_path}/images/tools/collection_ops/filter_null.svg + :alt: Filter null elements from collection + :width: 500 + +------- .. class:: infomark diff --git a/static/images/tools/collection_ops/filter_empty.svg b/static/images/tools/collection_ops/filter_empty.svg index 6e4be27b030..3d4b8dbcb05 100644 --- a/static/images/tools/collection_ops/filter_empty.svg +++ b/static/images/tools/collection_ops/filter_empty.svg @@ -1,542 +1,54 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + List + + + sample1 + 1.2 MB + + + + sample2 + 0 bytes + + + sample3 + 800 KB + + sample2 is empty + + + + Filter + + + + List (filtered) + + + sample1 + + + sample3 + + empty element removed + diff --git a/static/images/tools/collection_ops/filter_error.svg b/static/images/tools/collection_ops/filter_error.svg index fb4d01ad199..114dbaed524 100644 --- a/static/images/tools/collection_ops/filter_error.svg +++ b/static/images/tools/collection_ops/filter_error.svg @@ -1,927 +1,54 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + List + + + sample1 + ok + + + + sample2 + error + + + sample3 + ok + + sample2 failed + + + + Filter + + + + List (filtered) + + + sample1 + + + sample3 + + failed element removed + diff --git a/static/images/tools/collection_ops/filter_null.svg b/static/images/tools/collection_ops/filter_null.svg new file mode 100644 index 00000000000..aa63f945f21 --- /dev/null +++ b/static/images/tools/collection_ops/filter_null.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + List + + + sample1 + ok + + + + sample2 + null + + + sample3 + ok + + sample2 is null + + + + Filter + + + + List (filtered) + + + sample1 + + + sample3 + + null element removed + +