planemo

planemo copied to clipboard

.. figure:: https://raw.githubusercontent.com/jmchilton/planemo/master/docs/planemo_logo.png :alt: Planemo Logo :align: center :figwidth: 100% :target: https://github.com/galaxyproject/planemo

Command-line utilities to assist in developing Galaxy_ and Common Workflow Language_ artifacts - including tools, workflows, and training materials.

.. image:: https://readthedocs.org/projects/planemo/badge/?version=latest :target: http://planemo.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

.. image:: https://badge.fury.io/py/planemo.svg :target: https://pypi.python.org/pypi/planemo/ :alt: Planemo on the Python Package Index (PyPI)

.. image:: https://github.com/galaxyproject/planemo/workflows/Python%20CI/badge.svg :target: https://github.com/galaxyproject/planemo/actions?query=workflow%3A%22Python+CI%22

.. image:: https://travis-ci.org/galaxyproject/planemo.png?branch=master :target: https://travis-ci.org/galaxyproject/planemo :alt: Build Status

• Free software: MIT License
• Documentation: https://planemo.readthedocs.io.
• Code: https://github.com/galaxyproject/planemo

Quick Start

Obtaining

For a traditional Python installation of Planemo, first set up a virtualenv for planemo (this example creates a new one in .venv) containing Python 3.7 or newer and then install with pip. Planemo must be installed with pip 7.0 or newer.

::

$ virtualenv .venv; . .venv/bin/activate
$ pip install "pip>=7" # Upgrade pip if needed.
$ pip install planemo

For information on updating Planemo, installing the latest development release, or installing Planemo via Bioconda <https://github.com/bioconda/bioconda-recipes>__

• checkout the installation <http://planemo.readthedocs.io/en/latest/installation.html>__ documentation.

Planemo is also available as a virtual appliance <https://planemo.readthedocs.io/en/latest/appliance.html>_ bundled with a preconfigured Galaxy server and set up for Galaxy_ and Common Workflow Language_ tool development. You can choose from open virtualization format (OVA_, .ova) or Docker_ appliances.

Basics - Galaxy

This quick start will assume you have a directory with one or more Galaxy tool XML files. If no such directory is available, one can be quickly created for demonstrating planemo as follows project_init --template=demo mytools; cd mytools.

Planemo can check tool XML files for common problems and best practices using the lint command <http://planemo.readthedocs.org/en/latest/commands.html#lint-command>_ (also aliased as l).

::

$ planemo lint

Like many planemo commands - by default this will search the current directory and use all tool files it finds. It can be explicitly passed a path to tool files or a directory of tool files.

::

$ planemo l randomlines.xml

The lint command takes in additional options related to reporting levels, exit code, etc. These options are described in the docs <http://planemo.readthedocs.org/en/latest/commands.html#lint-command>_ or (like with all commands) can be accessed by passing --help to it.

::

$ planemo l --help
Usage: planemo lint [OPTIONS] TOOL_PATH

Once tools are syntactically correct - it is time to test. The test command <http://planemo.readthedocs.org/en/latest/commands.html#test-command>__ can be used to test a tool or a directory of tools.

::

$ planemo test --galaxy_root=../galaxy randomlines.xml

If no --galaxy_root is defined, Planemo will download and configure a disposable Galaxy instance for testing.

Planemo will create a HTML output report in the current directory named tool_test_output.html (override with --test_output). See an example <http://galaxyproject.github.io/planemo/tool_test_viewer.html?test_data_url=https://gist.githubusercontent.com/jmchilton/9d4351c9545d34209904/raw/9ed285d3cf98e435fc4a743320363275949ad63c/index>_ of such a report for Tophat.

Once tools have been linted and tested - the tools can be viewed in a Galaxy interface using the serve (s) command <http://planemo.readthedocs.org/en/latest/commands.html#serve-command>__.

::

$ planemo serve

Like test, serve requires a Galaxy root and one can be explicitly specified with --galaxy_root or installed dynamically with --install_galaxy.

For more information on building Galaxy tools in general please check out Building Galaxy Tools Using Planemo_.

For more information on developing Galaxy workflows with Planemo checkout best practices for Galaxy Workflows_ and the description of Planemo's test format_. For information on developing Galaxy training materials checkout the contributing documentation <https://training.galaxyproject.org/training-material/topics/contributing/>__ on training.galaxyproject.org.

Basics - Common Workflow Language

This quick start will assume you have a directory with one or more Common Workflow Language_ YAML files. If no such directory is available, one can be quickly created for demonstrating planemo as follows planemo project_init --template=seqtk_complete_cwl mytools; cd mytools.

Planemo can check tools YAML files for common problems and best practices using the lint command <http://planemo.readthedocs.org/en/latest/commands.html#lint-command>_ (also aliased as l).

::

$ planemo lint

Like many planemo commands - by default this will search the current directory and use all tool files it finds. It can be explicitly passed a path to tool files or a directory of tool files.

::

$ planemo l seqtk_seq.cwl

The lint command takes in additional options related to reporting levels, exit code, etc. These options are described in the docs <http://planemo.readthedocs.org/en/latest/commands.html#lint-command>_ or (like with all commands) can be accessed by passing --help to it.

::

$ planemo l --help
Usage: planemo lint [OPTIONS] TOOL_PATH

Once tools are syntactically correct - it is time to test. The test command <http://planemo.readthedocs.org/en/latest/commands.html#test-command>__ can be used to test a CWL tool, workflow, or a directories thereof.

::

$ planemo test --engine cwltool seqtk_seq.cwl

Planemo will create a HTML output report in the current directory named tool_test_output.html. Check out the file seqtk_seq_tests.yml for an example of Planemo test for a CWL tool. A test consists of any number of jobs (with input descriptions) and corresponding output assertions.

Checkout the Commmon Workflow User Guide_ for more information on developing CWL tools in general and Building Common Workflow Language Tools_ for more information on using Planemo to develop CWL tools.

Tool Shed

Planemo can help you publish tools to the Galaxy Tool Shed. Check out Publishing to the Tool Shed_ for more information.

Conda

Planemo can help develop tools and Conda packages in unison. Check out the Galaxy <http://planemo.readthedocs.io/en/latest/writing_advanced.html#dependencies-and-conda>__ or CWL <http://planemo.readthedocs.io/en/latest/writing_advanced_cwl.html#dependencies-and-conda-cwl>__ version of the "Dependencies and Conda" tutorial for more information.

Docker and Containers

Planemo can help develop tools that run in "Best Practice" containers for scientific workflows. Check out the Galaxy <http://planemo.readthedocs.io/en/latest/writing_advanced.html#dependencies-and-containers>__ or CWL <http://planemo.readthedocs.io/en/latest/writing_advanced_cwl.html#dependencies-and-containers-cwl>__ version of the "Dependencies and Containers" tutorial for more information.

.. _Galaxy: http://galaxyproject.org/ .. _GitHub: https://github.com/ .. _Conda: http://conda.pydata.org/ .. _Docker: https://www.docker.com/ .. _Vagrant: https://www.vagrantup.com/ .. _Travis CI: http://travis-ci.org/ .. _tools-devteam: https://github.com/galaxyproject/tools-devteam .. _tools-iuc: https://github.com/galaxyproject/tools-iuc .. _Building Galaxy Tools Using Planemo: http://planemo.readthedocs.io/en/latest/writing_standalone.html .. _Publishing to the Tool Shed: http://planemo.readthedocs.org/en/latest/publishing.html .. _Common Workflow Language: https://www.commonwl.org/ .. _Commmon Workflow User Guide: http://www.commonwl.org/user_guide/ .. _Building Common Workflow Language Tools: http://planemo.readthedocs.io/en/latest/writing_cwl_standalone.html .. _OVA: https://en.wikipedia.org/wiki/Open_Virtualization_Format .. _test format: https://planemo.readthedocs.io/en/latest/test_format.html .. _best practices for Galaxy Workflows: https://planemo.readthedocs.io/en/latest/best_practices_workflows.html