Command-line utilities to assist in building and publishing Galaxy tools.
- Free software: Academic Free License version 3.0
- Documentation: https://planemo.readthedocs.io.
- Code: https://github.com/galaxyproject/planemo
This quick start demonstrates using
planemo commands to help
develop Galaxy tools.
For a traditional Python installation of Planemo, first set up a virtualenv
planemo (this example creates a new one in
.venv) and then
pip. Planemo requires 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 tool development. You can choose from open virtualization format (OVA, .ova), Docker, or Vagrant appliances.
This quick start will assume you have a directory with one or more
tool XML files. If none is available, one can be quickly created for
planemo as follows
mkdir mytools; cd mytools; planemo
Planemo can check tools containing XML for common problems and best
practices using the
(also aliased as
$ planemo lint
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
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
can be used to test a tool or a directory of tools.
$ planemo test --galaxy_root=../galaxy randomlines.xml
--galaxy_root is defined,
planemo will check for a default in
~/.planemo.yml and finally
search the tool’s parent directories for a Galaxy root directory.
Planemo can also download and configure a disposable Galaxy instance for
--install_galaxy instead of
$ planemo t --install_galaxy
Planemo will create a HTML output report in the current directory named
tool_test_output.html (override with
--test_output). See an
of such a report for Tophat.
Once tools have been linted and tested - the tools can be viewed in a
Galaxy interface using the
$ planemo serve
serve requires a Galaxy root and one can be
explicitly specified with
--galaxy_root or installed dynamically
Conda Package Manager¶
Conda is package manager that among many other things can be used to manage Python packages. Please read a few notes regarding the setup:
Planemo cannot be installed via Conda and then run Galaxy inside the same Conda environment currently.
galaxy-lib is a dependency of Planemo and having this on the Python path prevents correct operation of Galaxy.
Conda dependency resolution can be used for Galaxy tools,
This allows Galaxy to map conda recipes to
requirementtags on tools
Just install planemo normally via pip into a virtual environment or via brew and use the appropriate commands and options:
$ planemo conda_init $ planemo conda_install . $ planemo test --galaxy_branch release_16.04 --conda_dependency_resolution . $ planemo serve --galaxy_branch release_16.04 --conda_dependency_resolution .
The test and serve commands above require the target Galaxy to be 16.01 or higher.
Galaxy can also simply run inside an existing conda environment and rather than using dependency resolution Conda packages can just be picked up from the
Note: This isn’t a well supported approach yet, and when possible Planemo and Galaxy should not be installed inside of Conda and the conda dependency resolution (as described above) should be used to allow tools to find Conda packages.
To run Galaxy within a Conda environment, Planemo must be installed outside the Conda environment - via pip into a virtual environment or via homebrew. In the former case, don’t place the virtualenv’s
bindirectory on your PATH - it will conflict with Conda. Just reference Planemo directly
To run Galaxy from within the environment you will need to install Galaxy dependencies into the conda environment. Target the development branch of Galaxy for this since it has “unpinned” dependencies that are easier to fullfill for conda.
(conda-env-test) $ conda install numpy bx-python pysam # install the hard ones using conda (conda-env-test) $ cd $GALAXY_ROOT (conda-env-test) $ ./scripts/common_startup.sh --skip-venv --dev-wheels # install remaining ones using pip via Galaxy (conda-env-test) $ cd /path/to/my/tools (conda-env-test) $ /path/to/planemo_venv/bin/planemo test --skip_venv . (conda-env-test) $ /path/to/planemo_venv/bin/planemo serve --skip_venv .
A small test script in the Planemo source tree demonstrates this.
When tools are ready to be published to GitHub, it may be valuable to setup continuous integration to test changes committed and new pull requests. Travis CI is a service providing free testing and deep integration with GitHub.
$ planemo travis_init . $ # setup Ubuntu 12.04 w/tool dependencies $ vim .travis/setup_custom_dependencies.bash $ git add .travis.yml .travis $ git commit -m "Add Travis CI testing infrastructure for tools." $ git push # and register repository @ http://travis-ci.org/
In this example the file
install the dependencies required to test your files on to the Travis user’s
This testing approach may only make sense for smaller repositories with a
handful of tools. For larger repositories, such as tools-devteam or
tools-iuc simply linting tool and tool shed artifacts may be more feasible.
Check out the
.travis.yml file used by the IUC as example.
A shell can be launched to explore the Docker environment referenced by tools that are annotated with publically registered Docker images.
$ (planemo docker_shell bowtie2.xml)
For Docker containers still in development - a Dockerfile can be associated with a tool by sticking it in the tool’s directory. Planemo can then build and tag a Docker image for this tool and launch a shell into it using the following commands.
$ planemo docker_build bowtie2.xml # assumes Dockerfile in same dir $ (planemo docker_shell --from_tag bowtie2.xml)
Common Workflow Language¶
Planemo includes highly experimental support for running a subset of valid Common Workflow Language (CWL) tools using a fork of Galaxy enhanced to run CWL tools.
$ planemo project_init --template cwl_draft3_spec $ planemo serve --cwl cwl_draft3_spec/cat1-tool.cwl
The Galaxy development team was exploring (the effort has since shifted towards
Conda) different options for integrating Homebrew and linuxbrew with Galaxy.
One angle is resolving the tool requirements using
brew. An experimental
approach for versioning of brew recipes will be used. See full discussion on
the homebrew-science issues page
Information on the implementation can be found
https://github.com/jmchilton/platform-brew until a more permanent project home
$ planemo brew_init # install linuxbrew (only need if not already installed) $ planemo brew # install dependencies for all tools in directory. $ planemo brew bowtie2.xml # install dependencies for one tool $ which bowtie2 bowtie2 not found $ . <(planemo brew_env --shell bowtie2.xml) # shell w/brew deps resolved (bowtie2)$ which bowtie2 /home/john/.linuxbrew/Cellar/bowtie2/2.1.0/bin/bowtie2 (bowtie2)$ exit $ . <(planemo brew_env bowtie2.xml) # or just source deps in cur env $ which bowtie2 /home/john/.linuxbrew/Cellar/bowtie2/2.1.0/bin/bowtie2