Skip to main content

Getting started

Installing ethoscopy as a docker container with ethoscope-lab (recommended).

The ethoscope-lab docker container is the recommended way to use ethoscopy. A docker container is a pre-made image that will run inside any computer, independent of the operating system you use. The docker container is isolated from the rest of the machine and will not interfere with your other Python or R installations. It comes with its own dependencies and will just work. The docker comes with its own multi-user jupyter hub notebook so lab members can login into it directly from their browser and run all the analyses remotely from any computer, at home or at work. In the Gilestro laboratory we use a common workstation with the following hardware configuration.

CPU: 12x Intel(R) Xeon(R) CPU E5-1650 v3 @ 3.50GHz 
GPU: Intel(R) Xeon(R) CPU E5-1650 v3 @ 3.50GHz 
Hard drive: 1TB SSD for OS, 1TB 
SSD for homes and cache, 7.3 TB for ethoscope data 
Memory: 64GB

The workstation is accessible via the internet (behind VPN) so that any lab member can login into the service and run their analyses remotely. All the computational power is in the workstation itself so one can analyse ethoscope data from a tablet, if needs be. Follow the instruction below to install the ethoscope-lab docker container on your machine.

On linux

The best solution is to install this on the same computer that collects the ethoscope data so ethoscopy can have access to the db files directly stored in the machine. For most small installations, this computer could be the node. 

To install the docker you will have to find out the following information:

  • what is the internet name or address of the computer you want to access? This can be the IP or an actual name.
  • Where are your ethoscope data stored? On a regular node they would be in /ethoscope_data/results
  • Where do you want to share your users’ folders? This could be something like /home or /mnt/homes or anything like this.

Once these info are clear, you can proceed.

# Optional. Update the system to the latest version. You may want to restart after this. 
sudo pamac update 
# install docker 
sudo pacman -S docker 
# start the docker service 
sudo systemctl enable docker && sudo systemctl start docker 

# and finally download and run the ethoscope-lab docker container 
# the :ro flag means you are mounting that destination in read-only 
sudo docker run -d -p 8080:8080 \
      --name ethoscope-lab \
      --volume /ethoscope_data/results:/mnt/ethoscope_results:ro \
      --volume /home/:/home/ \
      --restart=unless-stopped \
      ggilestro/ethoscope-lab
On MacOS

Install the docker software from here. Open the terminal and run the same command as above, e.g.:

# download and run the ethoscope-lab docker container 
# the :ro flag means you are mounting that destination in read-only 
sudo docker run -d -p 8080:8080 \
      --name ethoscope-lab \
      --volume /path/to/ethoscope_data/:/mnt/ethoscope_results:ro \
      --volume /home/:/home/ \
      --restart=unless-stopped \
      ggilestro/ethoscope-lab
On Windows

Install the docker software from here. After installation, open the window terminal and issue the same command as above, only replacing the folder syntax as appropriate. For instance, if your ethoscope data are on z:\ethoscope_data and the user data are on c:\Users\folder use the following:

sudo docker run -d -p 8080:8080 \
      --name ethoscope-lab \
      --volume /z/ethoscope_data:/mnt/ethoscope_results:ro \
      --volume /c/Users/folders/:/home/ \
      --restart=unless-stopped \
      ggilestro/ethoscope-lab

Install ethoscopy in your Python space

Ethoscopy is on PyPi. You can install with pip3.

pip install ethoscopy

As of version 1.1.7, the required dependencies are:

Python >= 3.8
Pandas >= 1.4.2
Numpy >= 1.17.3, <1.25.0 Scipy >= 1.8
Hmmlearn == 0.2.8
Color >= 0.1.5
Astropy == 5.1
plotly >= 5.11.0
Back to top