Skip to content

Add documentation for output action attributes #13236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mvdbeek merged 2 commits into from
Jan 31, 2022
Merged

Add documentation for output action attributes #13236

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d00f055
add documentation for output action attributes
bernt-matthias Jan 24, 2022
bf4f0e3
remove wrong sentence about tool provided metadata
bernt-matthias Jan 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions lib/galaxy/tool_util/parser/output_actions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -400,6 +400,7 @@ def __init__(self, parent, elem):
self.column = elem.get('column', None) # None is append
if self.column:
self.column = int(self.column)
# TODO not supported in xsd
self.iterate = util.string_as_bool(elem.get("iterate", 'False'))

def filter_options(self, options, other_values):
Expand Down Expand Up @@ -583,6 +584,7 @@ def filter_options(self, options, other_values):

# helper classes
# determine cast function
# TODO add float
def parse_cast_attribute(cast):
if cast == 'string_as_bool':
cast = util.string_as_bool
Expand Down
135 changes: 118 additions & 17 deletions lib/galaxy/tool_util/xsd/galaxy.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4857,6 +4857,8 @@ Galaxy, including:
<xs:complexType name="Actions">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
The functionality of the ``actions`` tag should be replaced by
[tool provided metadata](https://planemo.readthedocs.io/en/latest/writing_advanced.html#tool-provided-metadata).
Copy link
Member

@jmchilton jmchilton Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just don't know that I think this is true. The XML may be undocumented but at least it is structured and declarative. In terms of how the workflow editor works, job collection, etc.. it seems we can be a lot smarter about output actions. It feels like tool provided metadata should be the fallback (despite me knowing a lot more about it and such).

Copy link
Member

@mvdbeek mvdbeek Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are these the actions this refers to ? https://docs.galaxyproject.org/en/master/dev/schema.html#tool-outputs-data-actions

Copy link
Contributor Author

@bernt-matthias bernt-matthias Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are these the actions this refers to ?

Yes

I just don't know that I think this is true.

That is such a wonderful sentence ;).

So let's just remove my sentence about the tool provided metadata.


The ``actions`` directive allows tools to dynamically take actions related to an
``output`` either unconditionally or conditionally based on inputs. These
Expand Down Expand Up @@ -5066,14 +5068,31 @@ if none of the nested options apply.</xs:documentation>
</xs:complexType>
<xs:complexType name="ActionsOption">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en"><![CDATA[
1. Load options from a data table, a parameter (or its metadata), or a file
2. Filter the options using all filters defined by the contained ``filter`` tags.
3. Chose a value in a given line (``offset``) and ``column``

The options can be considered as a table where each line is an option. The values
in the columns can be used for filtering.

The different data sources can be loaded as follows:

- ``from_data_table``: load the options from the data table with the given ``name``.
- ``from_param``: Initialize a single option containing the value of the
referred parameter (``name``) or its metadata (``param_attribute``)
- ``from_file``: Load the file the given ``name`` (in Galaxy's tool data path), columns
are defined by the given ``separator`` (default is tab).
]]></xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="filter" type="ActionsConditionalFilter" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="type" type="ActionsOptionType">
<xs:attribute name="type" type="ActionsOptionType" use="required">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en"><![CDATA[
Source of the tabular data ``from_data_table``, ``from_param``, or ``from_file``.
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="name" type="xs:string">
Expand Down Expand Up @@ -5152,72 +5171,154 @@ against.</xs:documentation>
</xs:annotation>
<xs:attribute name="type" type="ActionsConditionalFilterType" use="required">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[]]></xs:documentation>
<xs:documentation xml:lang="en"><![CDATA[
``param_value``

- get the value of a refered parameter (``ref``) or the value given by ``value``
- if ``param_attribute`` is given the corresponding attribute of the value of the reffered parameter is used ``ref``
- cast this value with the function given by ``cast``
- compare the each the value in the column given by ``column`` (also casted) with the determined value using the function given by ``compare``
- if the result of the comparison is equal to the boolean given by ``keep`` the value is kept

``insert_column``

- insert a column with a value in the options
- if ``column`` is given then the column is inserted before this column, otherwise the column is appended
- the value can be given by ``ref`` or ``value``

``column_strip``

Strip (remove certain characters from the suffix / prefix) values in a column.
The characters to strip can be given by ``strip`` (deafult is whitespace
characters)

``multiple_splitter``

Split the values in a ``column`` by a given ``separator``. And replace the
original column with the with columns containing the result of splitting.

``column_replace``

Replace values in a column. The old and new values can be given

- as static values ``old_value`` or ``new_value``
- dynamically by the contents in (another) column ``old_column`` or ``new_colum``

``metadata_value``

Filter values in ``column`` by the metadata element ``name`` of the referred
parameter ``ref`` depending on the results of the comparison function given by
with ``compare`` and the value of ``keep`` (i.e. if the result of the
comparision is equal to ``keep`` then keep the option).

``boolean``

Cast the values in ``column`` using the cast function given by ``cast``
(unaccessible / uncastable values are interpreted as False). The result of this
cast is then casted with the bool function. If the final result is equal to
``keep`` the option.

``string_function``

Apply a string function to the values in ``column``. The string function is given by ``name``.

]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="compare" type="CompareType">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<!-- TOOD xsd only allows startswith and re_search code also supports eq, neq, gt, gte, lt, lte, in, endswith -->
<xs:documentation xml:lang="en"><![CDATA[
Function to use for the comparision. One of startswith, re_search.
Applies to: ``param_value``, ``metadata_value``
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="ref" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en"><![CDATA[
Name of an input parameter (parameters in conditionals or sections are referred using the dot syntax, e.g. ``cond.paramname``).
Applies to ``param_value``, ``insert_column``, ``metadata_value``
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="value" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en"><![CDATA[
Fixed value to use for the comparison.
Applies to ``param_value``, ``insert_column``
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="column" type="xs:integer">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en"><![CDATA[
Column of the options (0 based).
Applies to ``param_value``, ``insert_column``, ``column_strip``, ``multiple_splitter``, ``column_replace``, ``metadata_value``, ``boolean``, ``string_function``
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="keep" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en"><![CDATA[
Keep the value if the filter condition is met. default: true
Applies to ``param_value``, ``metadata_value``, ``boolean``
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="cast" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<!-- float might be nice -->
<xs:documentation xml:lang="en"><![CDATA[
one of string_as_bool, int, str function used for casting the value.
Applies to ``param_value``, ``boolean``</xs:documentation>
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="param_attribute" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en">
Which atttribute of the parameter value referred by ``ref`` to use. Separate with ``.``.
Applies to ``param_value``</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="separator" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en">Applies to ``multiple_splitter``</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="strip" type="PermissiveBoolean">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en">Applies to ``column_strip``</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="old_column" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en">Applies to ``column_replace``</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="old_value" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en">Applies to ``column_replace``</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="new_column" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en">Applies to ``column_replace``</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="new_value" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"></xs:documentation>
<xs:documentation xml:lang="en">Applies to ``column_replace``</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="name" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="en"><![CDATA[
For ``metadata_value`` this is the name of the metadata to use. For ``string``
function the string function to use (currently ``lower`` or ``upper``).
Applies to ``metadata_value``, ``string_function``
]]></xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
Expand Down