Development

Installing the development version

To use the most recent IgDiscover version from Git, follow these steps.

  1. If you haven’t done so, install miniconda. See the first steps of the regular installation instructions. Do not install IgDiscover, yet!

  2. Clone the IgDiscover repository:

    git clone https://github.com/NBISweden/IgDiscover.git

    (Use the git@ URL instead if you are a developer.)

  1. Create a new Conda environment using the environment.yml file in the repository:

    cd IgDiscover
conda env create -n igdiscover -f environment.yml

    You can choose a different environment name by changing the name after the -n parameter. This may be necessary, when you already have a regular (non-developer) IgDiscover installation in an igdiscover environment that you don’t want to overwrite.

  2. Activate the environment:

    source activate igdiscover

    (Or use whichever name you chose above.)

  3. Install IgDiscover in “editable” mode:

    python3 -m pip install -e .

Whenever you want to update the software:

cd IgDiscover
git pull

It may also be necessary to repeat the python3 -m pip install -e . step.

IgBLAST result cache

For development, in particular when running tests repeatedly, you should enable the IgBLAST result cache. The cache stores IgBLAST output. If the same dataset with the same dataset is run a second time, the result is retrieved from the cache and IgBLAST is not re-run. This saves a lot of time when re-running datasets, but may also fill up the cache directory ~/.cache/igdiscover/. Also, in production, datasets are usually not re-run with the same settings, which is why caching is disabled by default.

To enable the cache, create a file ~/.config/igdiscover.conf with the following content:

use_cache: true

The file is in YAML format, but at the moment, no other settings are supported.

Building the documentation

Go to the doc/ directory in the repository, then run:

make

to build the documentation locally. Open _build/html/index.html in a browser. The layout is different from the version shown on Read the Docs, but allows you to preview any changes you may have made.

Making a release

We use setuptools_scm to manage version numbers. It extracts the version number from the most recent tag in Git. Thus, to increment the version number, create a Git tag:

git tag v0.5

The v prefix is mandatory.

Then:

  • Run pytest

  • Push the tag: git push --tags

  • The GitHub workflow will create a new build and deploy it to PyPI

  • Wait for the BiocondaBot to create a bump PR; adjust the dependencies if needed

Removing IgDiscover from a Linux system

If you have been playing around with different installation methods (pip, conda, git, python3 setup.py install etc.) you may have multiple copies of IgDiscover on your system and you will likely run into problems on updates. Here is a list you can follow in order to get rid of the installations as preparation for a clean re-install. Do not add sudo to the commands below if you get permission problems, unless explicitly told to do so! If one of the steps does not work, that is fine, just continue.

  1. Delete miniconda: Run the command which conda. The output will be something like /home/myusername/miniconda3/bin/conda. The part before bin/conda is the miniconda installation directory. Delete that folder. In this case, you would need to delete miniconda3 in /home/myusername.

  2. Run pip3 uninstall igdiscover. If this runs successfully and prints some messages about removing files, then repeat the same command! Do this until you get a message telling you that the package cannot be uninstalled because it is not installed.

  3. Repeat the previous step, but with pip3 uninstall sqt.

  4. If you have a directory named .local within your home directory, you may want to rename it: mv .local dot-local-backup You can also delete it, but there is a small risk that other software (not IgDiscover) uses that directory. The directory is hidden, so a normal ls will not show it. Use ls -la while in your home directory to see it.

  5. If you have ever used sudo to install IgDiscover, you may have an installation in /usr/local/. You can try to remove it with sudo pip3 uninstall igdiscover.

  6. Delete the cloned Git repository if you have one. This is the directory in which you run git pull.

Finally, you can follow the normal installation instructions and then the developer installation instructions.