Installation

Firstly, you must know that SHERLOCK is a package that lies on many different dependencies whose versions are fixed. Hence, we strongly encourage all the users to use a Python virtual environment, preferently built with a conda distribution. If anaconda is available in your distribution, please try using it. You can install it following the next instructions https://docs.anaconda.com/free/anaconda/install/linux/

Once you installed it, you’d have to create a new environment for SHERLOCK: conda create -n sherlockenv python=3.10 anaconda

Some of the SHERLOCK dependencies need numpy and Cython before being installed and therefore you should install them before trying the SHERLOCK installation. Take also into account that the dependencies brought by SHERLOCK also need additional operating system tools that need to be installed separately (C++ compiler, Fortran compiler, etc). So, be aware of counting with the next OS packages installed in your environment (e.g. for Python3 in a Linux distribution):

build-essential
libssl-dev
python3.10
python3-pip
libbz2-dev
libssl-dev
libreadline-dev
libffi-dev
libsqlite3-dev
tk-dev
libpng-dev
libfreetype6-dev
llvm-9
llvm-9-dev
gfortran
gcc
locales
python3-tk
python3.10-dev

In case you are running a non-Linux distribution you will need to guess your OS packages matching the ones we mention for Linux.

Therefore, once you have got the OS tools, the SHERLOCK package can be installed in several ways. The cleanest one is by running:

conda activate sherlockenv
wget https://raw.githubusercontent.com/PlanetHunters/SHERLOCK/master/requirements.txt
python3 -m pip install -r requirements.txt

An additional installation method is running the next commands:

conda activate sherlockenv
python3 -m pip install numpy
python3 -m pip install Cython
python3 -m pip install sherlockpipe

Docker usage

If you are not running on Linux or you’re just curious, you can also use our Docker image from DockerHub or build it from our Dockerfile. Therefore, you can also use as a Singularity container meanwhile they support Docker. You would need to install Docker. Once you’ve got it, the steps to get the SHERLOCK container up and running are:

sudo docker pull sherlockpipe/sherlockpipe:latest
sudo docker run -v someAbsoluteDirectoryFromYourHost:/home/sherlock --name sherlock -it sherlockpipe/sherlockpipe:latest /bin/bash

This way you will be logged into a container with the ability of running SHERLOCK, with your host work directory mounted into the SHERLOCK container. Let’s say that you have prepared a properties.yaml file with a SHERLOCK execution definition into your host work directory. You could then execute the next commands in your container:

cd /home/sherlock
python3 -m sherlockpipe --properties properties.yaml --explore

And voilà! SHERLOCK should be running in explore mode for your defined targets. Any outputs created by SHERLOCK in the current directory are automatically mapped into your host work directory, so you can inspect them easily on your machine.

Dependencies

All the needed dependencies should be included by your pip installation of SHERLOCK. If you are interested you can inspect the requirements list under setup.py.

Testing

SHERLOCK comes with a light automated tests suite that can be executed with:

tox

This suite tests several points from the pipeline for the supported Python versions:

  • The construction of the SHERLOCK Python object.

  • The parameters setup of the SHERLOCK Python object.

  • The provisioning of objects of interest files.

  • Load and filtering of objects of interest.

  • Different kind of short SHERLOCK executions.

In case you want to test the entire SHERLOCK functionality we encourage you to run some (or all) the manual examples. If so, please read the instructions provided there to execute them.