Skip to content

Commit

Permalink
Update instructions in CONTRIBUTING.md.
Browse files Browse the repository at this point in the history
  • Loading branch information
@donkirkby
donkirkby committed Oct 19, 2020
1 parent 0b6229a commit d5975a6
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 144 deletions.
156 changes: 12 additions & 144 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,152 +12,23 @@ you planning to submit your own fix in a pull request?
[issues]: https://github.com/cfe-lab/MiCall/issues

## Development
This will document the installation steps to get MiCall running locally on your workstation.
The steps are for Eclipse with PyDev on Ubuntu, adapt as needed to your preferred IDE or operating system.
To see how all the tools should be installed, follow the steps in `Dockerfile`
and `dev.dockerfile`. If you prefer, you can run your development environment
under docker, as described in `dev.dockerfile`. The same installation steps are
also listed in the `Singularity` file. The docker file runs with debian, and the
singularity file runs with CentOS.

If you want to see what's currently being worked on, check out the active tasks
in our [milestones].

[milestones]: https://github.com/cfe-lab/MiCall/milestones

### Java and Python
1. Check that you are running a 64-bit operating system, or bowtie2 won't work.
Check About this Computer under the gear menu.
2. If you want to edit Python code using PyDev and Eclipse, you will need to
install Java. Check the version of Java you have installed:

java -version

3. If the java version is lower than 1.7, then install JDK7:

sudo apt-get install openjdk-7-source

4. Check that you are now using the new version. If not, configure it.

java -version
sudo update-alternatives --config java
java -version

5. Check the version of Python you have installed:

python --version

6. If the Python version is lower than 2.7, then install it:

sudo apt-get install python2.7

7. Install [pip the Python package manager][pip] and some packages for Python:

sudo apt-get install python-pip
sudo pip install testfixtures
sudo pip install requests
sudo pip install python-Levenshtein

[pip]: https://pip.pypa.io/en/latest/installing.html

### Eclipse
1. Install Eclipse, although you might prefer a more recent version from the [Eclipse web site][eclipse]:

sudo apt-get install eclipse

2. Launch Eclipse. From the Help menu, choose either Eclipse Marketplace... or Install New Software....
3. In the marketplace, just type PyDev and search. In the install wizard, use the [PyDev update site][pydev].
4. After installing PyDev, open Window: Preferences. Navigate down to PyDev: Interpreters: Python Interpreter.
5. Click the Quick Auto-Config button. Click OK.
6. From the File menu, choose Import.... Navigate down to Git: Projects from Git.
7. Choose Clone URI, and paste this URI: https://github.com/cfe-lab/MiCall.git
8. Take all the branches, and select master as your initial branch.
9. Select import existing projects, and finish the import.

[eclipse]: https://www.eclipse.org/downloads/
[pydev]: http://pydev.org/updates

### Python
Check that Python is already installed.

python --version

We have tested with Python 3.7.

On Windows, you can install [Anaconda Python][anaconda].

[anaconda]: http://continuum.io/downloads

### Bowtie and HyPhy
1. Download the latest version of [bowtie2's binaries for Linux][bowtie2].
2. Right click and choose Extract Here. Change the folder owner to root, move it to /opt, and add it to the path.

chmod g-w -R bowtie2-2.2.1
sudo chown root:root -R bowtie2-2.2.1
sudo mv bowtie2-2.2.1 /opt
# Do this for the default version of bowtie2
cd /opt/bowtie2-2.2.1
for f in bowtie2* ; do sudo ln -s /opt/bowtie2-2.2.1/$f /usr/local/bin/$f; done
# Do this for other versions that have to be called explicitly
cd /opt/bowtie2-2.2.8
for f in bowtie2* ; do sudo ln -s /opt/bowtie2-2.2.8/$f /usr/local/bin/$f-2.2.1; done
# Now try a smoke test.
cd ~
bowtie2 --version

3. HyPhy is not needed by the main pipeline, only some of the helper utilities,
so you can probably skip it. Before you can build HyPhy, you will need these
libraries:

sudo apt-get install build-essential python-dev libcurl4-openssl-dev libcrypto++-dev libssl-dev

On CentOS 6, the newest versions of HyPhy fail to compile. The newest version that works is
v2.2.5. In order to compile this version, assuming you're using the Software Collections `python27` package,
you only need to add two packages, which you can do using `yum`:

sudo yum install libcurl-devel openssl-devel

4. There is a newer package for HyPhy in the
[hyphy-python project][hyphy-python]. Consider testing that before the next
installation, but so far we've just downloaded the latest source (or v2.2.5 on CentOS 6).

5. Download the latest [source for HyPhy][hyphy]. Right click the zip file and choose Expand Here. Then run the setup script:

cd ~/Downloads/hyphy-master/src/lib
sudo python setup.py install

You can test it out if you like.

cd Examples/Python
python BasicHyPhy.py # Just check that there are no obvious errors.

[bowtie2]: http://sourceforge.net/projects/bowtie-bio/files/bowtie2/
[hyphy]: https://github.com/veg/hyphy
[hyphy-python]: https://github.com/veg/hyphy-python

### Cutadapt library
In order to support more than one version of this library installed in parallel,
install it in a Python virtual environment, then put a symbolic link to it on
the path.

sudo virtualenv /usr/local/share/vcutadapt-1.11
sudo /usr/local/share/vcutadapt-1.11/bin/pip install cutadapt==1.11
sudo ln -s /usr/local/share/vcutadapt-1.11/bin/cutadapt /usr/local/bin/cutadapt-1.11

### Gotoh library
MiCall uses an implementation of a modified Gotoh algorithm for pairwise sequence alignment.
This is written in the C++ source file `gotoh.cpp`, so you will need the
Python 3 development tools. To compile this into a shared library
that can be accessed from Python, go to `micall/alignment` and enter the following:
```
sudo python setup.py install
```
This assumes that you have superuser permissions on your system. We have tested this
installation on OS-X and Ubuntu. If you're installing on Windows, you will need
to [install Visual C++ for Python][vcpp].

[vcpp]: http://stackoverflow.com/a/26127562/4794


### Matplotlib
To install it on Ubuntu, use pip:

sudo pip install matplotlib
We have tested with Python 3.8.

### BaseSpace
Set up the [native apps virtual machine][bsvm], and configure a shared folder
Expand Down Expand Up @@ -219,7 +90,8 @@ the one for the sample you're interested in. The remap step writes the mapping
results as `debug_remapX_debug.sam` and `debug_remapX_debug_ref.fasta`, where
`X` is the remapping iteration number. You should be able to open an assembly
in Tablet using those two files. If the SAM file contains multiple regions,
you'll probably have to sort it with the `micall/utils/sort_sam.py` script.
you'll probably have to sort it with the `micall/utils/sort_sam.py` script. That
same script can convert `prelim.csv` into a SAM file.

[tablet]: http://ics.hutton.ac.uk/tablet/

Expand Down Expand Up @@ -341,15 +213,11 @@ similar steps to setting up a development workstation. Follow these steps:
`/var/log/syslog` on Ubuntu.

14. Launch the basespace virtual machine, and build a new Docker image
from GitHub. Tag it with the release number. See the bash scripts above for
an easy way to do this.

sudo docker build -t docker.illumina.com/cfe_lab/micall:vX.Y https://github.com/cfe-lab/MiCall.git

15. Push the new image to the repository. You might have to log in to docker
before running this.
from GitHub. Tag it with the release number, and push it to the Illumina
repository. You might have to log in to docker before running this.

sudo docker push docker.illumina.com/cfe_lab/micall:vX.Y
cd /media/sf_micall
sudo python3 docker_build.py -t vX.Y

16. Edit the `callbacks.js` in the form builder, and add the `:vX.Y` tag to the
`containerImageId` field.
Expand Down
3 changes: 3 additions & 0 deletions dev.dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@
#
# docker run --rm -it --entrypoint pytest -w /opt/micall \
# --volume ~/git/micall:/opt/micall micall:dev
#
# That lets you edit the source code on your host system, but run it under
# docker with all the tools installed for you.

FROM docker.illumina.com/cfe_lab/micall:latest

Expand Down

0 comments on commit d5975a6

Please sign in to comment.