/planemo

Command-line utilities to assist in developing tools for the Galaxy project.

Primary LanguagePythonMIT LicenseMIT

Planemo Logo

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

Documentation Status Planemo on the Python Package Index (PyPI)

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 - checkout the installation documentation.

Planemo is also available as a virtual appliance 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 (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 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 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 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.

$ 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 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 (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 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 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 or 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 or CWL version of the "Dependencies and Containers" tutorial for more information.