From 54d40c718f89a3c2a95dc7ffef5c77027d094dab Mon Sep 17 00:00:00 2001 From: VinzentRisch <100149044+VinzentRisch@users.noreply.github.com> Date: Fri, 9 Jun 2023 15:03:07 +0200 Subject: [PATCH] ENH: Change Readme file (#6) * ENH: Create Readme fiel * changed installation instructions * removed two files --- README.md | 104 ++++++++++++++++++++++++++---------------------------- 1 file changed, 51 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index c407d0b..b7594bc 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,51 @@ -# q2-plugin-template -A skeleton for QIIME 2 plugins. - -To use this template for a new plugin creation, you'll first need to create a new plugin repo by clicking the `Use this template` button. -Fill out the new repository name and description. Following that initial setup, in your new plugin repo you still -need to adjust the following elements: - -- exchange `amr` and `amr` with the name of your plugin -- adjust all the required fields in `setup.py` and `plugin_setup.py` -- adjust the developer name in all the copyright headers and the license file -- add `versioneer` support for version management: - - install `versioneer` [(link)](https://github.com/python-versioneer/python-versioneer) into any python environment: `pip install versioneer` - - from the project directory, run `versioneer install` to create/modify all the required files - - add the `# flake8: noqa` flag on top of the `versioneer.py` file for the file to be ignore by lint checks - -Enjoy! - -### Development using Dev Containers (Visual Studio Code) -To streamline the plugin development process, you can use support for Docker containers built into -VS Code in a form of __Dev Containers__ (see [here](https://code.visualstudio.com/docs/remote/containers) for more information). -In this approach a Docker container will be created and configured (using the provided specification) and your VS Code environment -will be attached to this container where you can continue developing as usual. You only need to specify which version of QIIME 2 you -want to use (see below) and the respective Docker image will be pulled and used to create the container. - -The elements you need to use the QIIME 2 devcontainer are: -- container spec located under [.devcontainer.json](.devcontainer.json) in your project directory -- `requirements.txt` file listing all the project-specific conda dependencies that should be installed in the environment -- `prep-dev-container` section in the [Makefile](Makefile) - -The only parts that you should need to modify are the packages listed in the `requirements.txt` file. If you are setting up Dev Containers in an already existing repo you will need to copy the files/section listed above. -Once you have your requirements ready follow those steps to get started: -1. Install VS Code (if needed) and enable launch from command line (see [here](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line) for macOS instructions). -2. In your terminal, navigate to the repo you want to open in the devcontainer and execute: - ```shell - export QIIME_VERSION=2022.2 && code . - ``` - Replace `2022.2` with the version of QIIME 2 that you would like to use. - While it is possible to open those containers without going through the terminal, it is required in our setup to define the desired QIIME version. -3. When prompted, reopen the folder in a Dev Container by clicking on "Reopen in container". -4. The Docker image will be pulled (happens only once per image) and the corresponding container will be created and configured - this may take a few minutes. -5. Once container configuration is finished you should be good to go: you can start developing as usual. The conda environment in the container is already configured and should have your plugin installed inside. - -### Development with git hooks and setting up a dev environment -To make your life a bit easier, you can use `git hooks` to automate certain tasks while working with Git (see [here](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) for more details). -Here, we are making use of the `pre-commit` tool which allows us to configure all the hooks in [one place](.pre-commit-config.yaml). -The pre-commit hook configured here will automatically run linting and formatting tasks before any commit (i.e. on `git commit`). In the configuration file -you will see that the pre-push hook is commented-out - it is just more complicated to configure an environment for running that hook (given all the different -conda dependencies that the plugin/QIIME 2 may have). - -To set up your dev environment, including the hooks, simply run `make dev` in an existing conda environment - this will install all the required tooling. -You don't need to do anything else - the hooks will be automatically executed whenever you commit. - -_Note:_ If, for whatever reason, you need to skip the hooks, you can append the `--no-verify` flag to the git command - the hooks won't be executed. +# q2-amr +![CI](https://github.com/bokulich-lab/q2-assembly/actions/workflows/ci.yml/badge.svg) +[![codecov](https://codecov.io/gh/bokulich-lab/q2-assembly/branch/main/graph/badge.svg?token=THMBOFUZR0)](https://codecov.io/gh/bokulich-lab/q2-assembly) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) + +QIIME 2 plugin for antimicrobial resistance gene annotation of MAGs and metagenomic reads. + +## Installation +To install _q2-amr_, follow the installation steps described below. + +```shell +mamba create -yn q2-amr \ +-c conda-forge -c bioconda -c qiime2 -c defaults \ +-c https://packages.qiime2.org/qiime2/2023.5/tested \ +--no-channel-priority \ +qiime2 q2cli q2templates q2-types q2-types-genomics rgi altair + +conda activate q2-amr + +pip install --no-deps --force-reinstall \ +git+https://github.com/misialq/rgi.git@py38-fix \ +git+https://github.com/bokulich-lab/q2-amr.git +``` + +Refresh cache and check that everything worked: +```shell +qiime dev refresh-cache +qiime info +``` + +## Functionality +This QIIME 2 plugin contains actions used to annotate short single/paired-end +sequencing reads and MAGs with antimicrobial resistance genes. Currently, the [CARD](https://card.mcmaster.ca) database is supported (for details on +the implementation and usage, please refer to the [rgi](https://github.com/arpcard/rgi) documentation). Below you will +find an overview of actions available in the plugin. + +| Action | Description | Underlying tool | +|----------------------------|--------------------------------------------------------------------------------------|---------------------------------------| +| fetch-card-db | Download CARD data. | [rgi](https://github.com/arpcard/rgi) | +| annotate-mags-card | Annotate MAGs with antimicrobial resistance gene information from CARD. | [rgi](https://github.com/arpcard/rgi) | +| annotate-reads-card | Annotate metagenomic reads with antimicrobial resistance gene information from CARD. | [rgi](https://github.com/arpcard/rgi) | +| heatmap | Create a heatmap from annotate-mags-card output files. | | +| visualize-annotation-stats | Plot annotate-reads-card annotation statistics. | | + + +## Dev environment +This repository follows the _black_ code style. To make the development slightly easier +there are a couple of pre-commit hooks included here that will ensure that your changes +follow that formatting style. Before you start working on the code, please +install the hooks by executing `make dev` in your conda environment. From then on, +they will be run automatically every time you commit any changes.