QIIME 2 plugin for ZSH

Community Contributions
,
1

After having installed, uninstalled and reinstalled a number of Q2 environments I figured there was room for making that repetitive process slightly easier. As zsh is these days one of the most popular shells, I wrapped a couple of shell scripts into the zsh QIIME 2 plugin. This post briefly describes the installation and main functionality of that plugin. It is a mix of functions that could (hopefully) be useful for at least some QIIME 2 users and/or plugin developers.

It's an early version still so if you try it out and stumble upon an issue, please do reach out (here or directly on GitHub). Also, feature requests (and any other feedback for that matter) are more than welcome :speech_balloon: :slightly_smiling_face:.

Functionality

The plugin provides three main functionalities:

  1. Command prompt modification (currently only for the Powerlevel10k theme)

    When you are working in an activated conda environment that has QIIME 2 installed within, you will be able to see the version of QIIME 2 installed in that environment. Additionally, dev version will be marked as such, as in these examples:

    for latest QIIME 2 2021.4 release: prompt_dev
    for latest QIIME 2 2021.8 dev release: prompt_prod

  2. Aliases

    The plugin provides a couple of aliases for the most common QIIME 2 commands that can be used if you don't like to type all these words: :robot:

    Alias Command
    q2 qiime
    q2cit qiime tools citations
    q2xt qiime tools extract
    q2xp qiime tools export
    q2i qiime tools import
    q2it qiime tools import --show-importable-types
    q2if qiime tools import --show-importable-formats
    q2rc qiime dev refresh-cache
    q2p qiime tools peek
    q2v qiime tools view
    q2val qiime tools validate
    q2ins qiime tools inspect-metadata
    piqr pip install . && qiime dev refresh-cache

  3. Functions

    A couple of functions for setting up new/existing environments are also provided - see an overview below:

  • set_up_full_env - sets up a full QIIME 2 conda environment, using the latest QIIME 2 release (equivalent to what is described in the documentation under Native installation section) - no need to check what the latest QIIME 2 release is, no yaml fetching.

    set_up_full_env <env_name>

    where env_name is the name for the new conda environment

  • set_up_dev_env - sets up a minimal QIIME 2 environment (qiime2, q2cli, q2-types), using the latest dev release - maybe more useful for plugin developers; it also installs a couple of useful dev packages by calling the extend_env function (see below)

    set_up_dev_env <env_name>

    where env_name is the name for the new conda environment

  • extend_env - adds a couple of useful dev packages to an existing environment (q2lint, flake8, coverage, wget, pytest-xdist)

Installation

[Prerequisites] In order to use the plugin you will need to have already installed:

  • zsh shell with the Oh My Zsh framework
  • command prompt modification (see below) only works on the Powerlevel10k shell theme - more coming in the future perhaps (by popular demand :laughing:)
  • conda and QIIME 2

If you followed the typical Oh My ZSH installation route (as per their documentation), just follow these steps:

  • clone the zsh-qiime2 repository under the plugins subdirectory of oh-my-zsh:
    git clone https://github.com/misialq/zsh-qiime2.git $ZSH_CUSTOM/plugins/zsh-qiime2
  • add zsh-qiime2 to the list of plugins in your .zshrc file:
    plugins=(... zsh-qiime2)
  • (only for Powerlevel10k users) to enable prompt modification, add qiime2 to the list of segments in the .p10k.zsh file, e.g.:
    typeset -g POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(
# =========================[ Line #1 ]=========================
qiime2
status                  # exit code of the last command
...
  • source the .zshrc file:
    source ~/.zshrc
    or simply restart your terminal.

That's it! Happy QIIME'ing!

5 Likes