Skip to content

Latest commit

 

History

History
18 lines (10 loc) · 3.98 KB

conventions.md

File metadata and controls

18 lines (10 loc) · 3.98 KB

Naming and Annotation Conventions for Tools in the Image Community in Galaxy*

*) formerly known as the Galaxy Imaging Community

We acknowledge the existence of the IUC recommendations for tool names but decide for a somewhat different pattern, (i) to avoid too long tool names due to the inclusion of tool suits, (ii) to comply with the fact that many Galaxy tools in our community are thin tool wrappers around established tools (e.g., tool suites or other Conda packages), while (iii) many others implement their main functionality directly within the wrapper.

Naming. Generally, the name of Galaxy tools in our community should be expressive and concise, while stating the purpose of the tool as precisely as possible. Consistency of the namings of Galaxy tools is important to ensure that they can be found easily. To maintain consistency, we consider phrasing names as imperatives a good practice, like for example Analyze particles or Perform segmentation using watershed transformation. An acknowledged exception from this rule are the names of tool wrappers of major tool suites, where the name of a tool wrapper should be chosen identically to the module or function of the tool which is wrapped (e.g., MaskImage in CellProfiler).

Tool description. If a Galaxy tool is a thin tool wrapper (e.g., part of a major tool suite), then the name of the wrapped tool (and only the name of the wrapped tool, subsequent to the term with as in with Bioformats) should be used as the description of the tool (e.g., Bioformats, CellProfiler, ImageJ2, ImageMagick, SpyBOAT, SuperDSM). This ensures that the tool is found by typing the name of the wrapped tool into the Search field on Galaxy EU. The tool description should be empty if a tool is either not part of a major tool suite, or the main functionality of the tool is implemented in the wrapper.

Annotations. Tools within our community should be annotated with the EDAM operation code operation_3443 (Image analysis). The bio.tools and BIII registries should be used to annotate the main project behind a Galaxy tool. For those which are thin tool wrappers, this is simply the wrapped tool itself (e.g., tools from the ImageJ2 tool suite are annotated with imagej for bio.tools and imagej2 for BIII).

We point out that there is a global list of precedential bio.tools annotations in Galaxy which outweighs the annotations made in the XML specification of a Galaxy tool (and thus the annotations of a tool reported within the web interface of Galaxy might be divergent). However, since the precedential annotations are subject to possible changes and to avoid redundant work, we do not aim to reflect those in our specifications (those which we make in the XML specifications of Galaxy tools). We are aware of the following limitations of the naming and annotation pattern described above, which we seek to possibly address in the future:

  1. If a Galaxy tool has a bio.tools annotation, then its EDAM operation code is inherited from the bio.tools annotation. The EDAM operation code of the bio.tools annotation is precedential over the EDAM operation code given in the XML specification of a Galaxy tool.

  2. Our main motivation for prominently exposing the name of the wrapped tool in the tool description has been to account for the fact that tools with similar functionality (and hence similar names) exist across different tool suites. However, they can also exist across different plugins within the same tool suite (such as ImageJ2). To also account for that, we might want to take the suggested scheme one step further and to also include the name of the corresponding plugin in the tool description (as in with ImageJ2, bUnwrapJ).