Running the TPP docker image

From SPCTools

(Difference between revisions)
Jump to: navigation, search
Revision as of 03:51, 14 November 2018
Edeutsch (Talk | contribs)

← Previous diff		 Current revision
Edeutsch (Talk | contribs)

Line 1: Line 1:
=== Overview === === Overview ===
-The docker system allows the distribution of pre-built computational units called images, which can be run on any system with the docker software installed. The spctools/tpp image is built on the [http://biocontainers.pro BioContainers] ubuntu image, and uses many of the BioContainers conventions. On some systems you may have to run these commands using sudo, a mechanism for elevating user privileges for specific tasks. The initial download described below will be relatively slow the first time it is run, since most if not all the 'layers' will have to be downloaded. Subsequent invocations will generally be much faster.+Updated: 2023-02-21
 + 
 +The Docker system allows the distribution of pre-built computational units called images, which can be run on any system with the Docker software installed. The spctools/tpp image is built on the [http://biocontainers.pro BioContainers] Ubuntu image, and uses many of the BioContainers conventions. On some systems you may have to run these commands using sudo, a mechanism for elevating user privileges for specific tasks. The initial download described below will be relatively slow the first time it is run, since most if not all the 'layers' will have to be downloaded. Subsequent invocations will generally be much faster.
 + 
 +=== Installing Docker ===
 + 
 +Detailed installation guidance on how to install Docker on your computer is beyond the scope of this document, but if you're using Ubuntu 18.04 LTS or newer, it should be as easy as:
 + 
 +<pre style="white-space: pre-wrap">sudo apt --yes install docker.io
 +</pre>
=== Downloading spctools/tpp docker image === === Downloading spctools/tpp docker image ===
Line 10: Line 19:
'' Trying to pull repository docker.io/spctools/tpp ... '' '' Trying to pull repository docker.io/spctools/tpp ... ''
'' latest: Pulling from docker.io/spctools/tpp'' '' latest: Pulling from docker.io/spctools/tpp''
- '' Digest: sha256:686e9cc696fcbfd118a1ded28ae2d31218cbddd0daed68ac811400cc8833fa95''+ '' Digest: sha256:37220874949d6f710eec6661ef57ec2b3cc42f9066d1496a283c4eb32387e4da''
'' Status: Image is up to date for spctools/tpp:latest'' '' Status: Image is up to date for spctools/tpp:latest''
 +
 +If you get a "permission denied" error, you probably need to put '''sudo''' right at the beginning of each docker command, e.g.: '''sudo docker pull spctools/tpp''', and all
 +subsequent docker commands in this document!!
=== Verifying that the image has been downloaded === === Verifying that the image has been downloaded ===
-To verify that you've successfully downloaded the image, you can use the images command below, and hopefully see spctools/tpp entry(s):+To verify that you've successfully downloaded the image, you can use the images command below, and hopefully see spctools/tpp entry(s): (don't forget to prepend '''sudo''' if you need to)
''' docker images ''' ''' docker images '''
- '' REPOSITORY TAG IMAGE ID CREATED SIZE ''+ '' REPOSITORY TAG IMAGE ID CREATED SIZE ''
- '' spctools/tpp latest ebf55696681a 24 hours ago 3.2GB ''+ '' spctools/tpp latest 8939acb4ab6a 44 minutes ago 2.91GB ''
- '' spctools/tpp version5.2 ebf55696681a 24 hours ago 3.2GB ''+
=== Running a specific TPP program from the docker image === === Running a specific TPP program from the docker image ===
-If you want to run a specific program, e.g. comet, from the TPP installation, you can invoke it along with any arguments as illustrated below, where we have also mapped the local directory /tmp outside the container to the /data directory inside the Docker container, which is the current working directory inside the container by default:+If you want to run a specific program, e.g. comet, from the TPP installation, you can invoke it along with any arguments as illustrated below, where we have also mapped the local directory /tmp/tppdata outside the container to the /data directory inside the Docker container, which is the current working directory inside the container by default. You may have to adjust the permissions on the local directory if the docker process has trouble writing to it.
- ''' docker run -v /tmp:/data spctools/tpp comet -p '''+ ''' mkdir /tmp/tppdata
 + ''' chmod 777 /tmp/tppdata
 + ''' docker run -v /tmp/tppdata:/data spctools/tpp comet -p '''
'' Created: comet.params.new '' '' Created: comet.params.new ''
-You should find a freshly created comet.params.new file in /tmp after the command completes.+You should find a freshly created comet.params.new file in /tmp/tppdata after the command completes.
 + 
 +=== Obtaining a copy of the default parameter files ===
 + 
 +There is directory of default parameter files included in the docker image. To make a copy of this directory in the TPP GUI workspace, you would run:
 + 
 + '''docker run -v /tmp/tppdata:/data spctools/tpp cp -R /usr/local/tpp/params /data/'''
 + 
 +If you only want to run tools like Comet and PeptideProphet from the command line, that's all. You just ran Comet with the -p flag.
 +If you also want to run the TPP GUI, then read on!
 + 
=== Running the TPP GUI via Docker === === Running the TPP GUI via Docker ===
To run the TPP GUI, you can invoke the following command (Linux syntax): To run the TPP GUI, you can invoke the following command (Linux syntax):
- ''' mkdir /tmp/tpp+ ''' docker run -dit --user=root -p 10401:10401 -v /tmp/tppdata:/data spctools/tpp apache2ctl -DFOREGROUND '''
- ''' docker run -dit --user=root -p 10401:10401 -v /tmp/tpp:/data spctools/tpp ''' +
'' 350dc6eaafe113186c2ec23810bdbc442347a86c2632284435a4b6b713013771 '' '' 350dc6eaafe113186c2ec23810bdbc442347a86c2632284435a4b6b713013771 ''
-This will start a container running a web server from the spctools/tpp image, map port 10401 on the local machine to the default TPP web server port in the container to enable access, and map a directory of your choosing (/tmp/tpp in this case) to /data, the root directory for files in the TPP GUI. This will give you access to your data in the TPP GUI. the directory should be exist before starting the TPP GUI.+This will start a container running a web server from the spctools/tpp image, map port 10401 on the local machine to the default TPP web server port in the container to enable access, and map a directory of your choosing (/tmp/tppdata in this case) to /data, the root directory for files in the TPP GUI. This will give you access to your data in the TPP GUI. The directory should be exist before starting the TPP GUI.
-=== Checking to make sure the docker is running ===+=== Checking to make sure the Docker image is running ===
''' docker ps ''' ''' docker ps '''
'' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES '' '' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ''
'' 350dc6eaafe1 spctools/tpp "/bin/sh -c 'apache2…" 3 seconds ago Up 1 second 0.0.0.0:10401->10401/tcp suspicious_kilby '' '' 350dc6eaafe1 spctools/tpp "/bin/sh -c 'apache2…" 3 seconds ago Up 1 second 0.0.0.0:10401->10401/tcp suspicious_kilby ''
-You should see at least one spctools/tpp container running. To use the GUI, direct your browser to the URL http://myhost:10401/tpp/cgi-bin/tpp_gui.pl where myhost is the network name of your computer (can also be IP address) You should be prompted to log in as user guest (password is guest)+You should see at least one spctools/tpp container running. To use the GUI, direct your browser to the URL http://myhost:10401/tpp/cgi-bin/tpp_gui.pl where myhost is the network name of your computer (can also be IP address). You should be prompted to log in as user guest (password is guest). See test analysis tutorial below to try a quick analysis.
- +
-=== Obtaining a copy of the default parameter files ===+
- +
-There is directory of default parameter files included in the docker image. To download this directory to your local system (for example into the directory that you will mount in the TPP GUI example above, you would run:+
- +
- '''docker run -v /tmp/tpp:/data spctools/docker cp -R /usr/local/tpp/params /data/'''+
=== Stopping the GUI when you're done === === Stopping the GUI when you're done ===
Line 57: Line 73:
'' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES '' '' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES ''
'' 350dc6eaafe1 spctools/tpp "/bin/sh -c 'apache2…" 3 seconds ago Up 1 second 0.0.0.0:10401->10401/tcp suspicious_kilby '' '' 350dc6eaafe1 spctools/tpp "/bin/sh -c 'apache2…" 3 seconds ago Up 1 second 0.0.0.0:10401->10401/tcp suspicious_kilby ''
- '''docker stop 350dc6eaafe1'''+ ''' docker stop 350dc6eaafe1 '''
 + 
 +Even after you stop the GUI, any data that you generated will still be there in '/tmp/tppdata' or wherever your data directory was mapped to.
 + 
 +=== Troubleshooting Notes ===
 + 
 +If you discover that you cannot create directories or write files with Petunia in a container with a Linux host, either the target directory does not have suitable permissions set, or it may be that you're running SELinux (Security Enhanced Linux) via Fedora/CentOS/Red Hat, and you may need to turn that off temporarily to resolve permissions problems with something like:
 + 
 + '''setenforce 0'''
 + 
 + 
 +== Testing the container and GUI with a sample dataset (optional) ==
 + 
 +If you want to test your installation with a search and a PeptideProphet processing, try this recipe (you'll need to restart your container if you just stopped it in the step above):
 + 
 +<pre>
 +Navigate to:
 +http://xxx.xxx.xxx.xxx:10401/tpp/cgi-bin/tpp_gui.pl
 +- Login with guest and password
 + 
 +## In the Petunia interface in the Web browser:
 +[Files]
 +[Create new directory] tests
 +Go into tests
 + 
 +[TPP Tools] [Fetch Datasets]
 + Choose target directory for downloaded files
 + [Add Files] Go to the top level /local/data
 + - Check box next to tests
 + - (Select)
 + Specify Dataset ID
 + Paste into URL box: http://www.peptideatlas.org/export/refData/QuickYeastUPS1.zip
 + (Fetch Dataset)
 + Wait a few moments and [Refresh] until the job is done
 + Click on [this directory] and there should only be a subdirectory "QuickYeastUPS1"
 + 
 +[Files]
 +- Go to /local/data/params/
 +- Check box next to comet.params
 +- Click (Copy) button
 +- Go to /local/data/tests/QuickYeastUPS1
 +- Click (Paste) button
 +- On the same line as comet.params, click [Params]
 +Make the following changes (they might already be set, but check):
 + peptide_mass_tolerance = 20
 + peptide_mass_units = 2
 + isotope_error = 3
 +- (Save Search Parameters File)
 + 
 +[Pipeline: Comet]
 +[TPP Tools] [Comet Search]
 + Choose mz[X]ML Input Files
 + [Add Files] Select /local/data/tests/QuickYeastUPS1/UPS1_50000amol_R1.mzML
 + Choose Comet Parameters File
 + [Add Files] Select comet.params
 + Choose a sequence database
 + [Add Files] Select Yeast_UPS_cRAP.fasta
 + [Run Comet Search]
 + Wait a few moments and [Refresh] until the job is done
 + 
 +[TPP Tools] [Analyze Peptides]
 +- (Add Files)
 +- Check box next to UPS1_50000amol_R1.pep.xml
 +- (Select)
 +- Under -PEPTIDEPROPHET OPTIONS- check box next to "Use accurate mass binning"
 +- Under -IPROPHET OPTIONS- Check box next to "RUN iProphet"
 +- Scroll to bottom and (Run XInteract)
 +- Wait a few moments and [Refresh] until the job is done
 +- Make sure no errors
 +- click on [PepXML] link in /local/data/tests/QuickYeastUPS1/interact.ipro.pep.xml [ PepXML ]
 + 
 +- Click on a probability and view the plots
 +- Go back to the PepXML Viewer tab
 +- Click on a value in the Ions column
 + 
 +[TPP Tools] [Analyze Proteins]
 +- (Add Files)
 +- Check box next to interact.ipro.pep.xml
 +- (Select)
 +- Checkmark "Input is from iProphet"
 +- (Run ProteinProphet)
 +- Wait a few moments and [Refresh] until the job is done
 +- click on [ProtXML] link in /local/data/tests/QuickYeastUPS1/interact.prot.xml [ ProtXML ]
 +- You should see a list of UPS and yeast proteins detected. Click around to explore
 + 
 +[TPP Tools] [Export mzIdentML]
 +- (Add Files)
 +- Check box next to interact.prot.xml
 +- (Select)
 +- Wait a few moments and [Refresh] until the job is done
 + 
 +</pre>
 + 
 +Finis!
 +You'll find all your output from the analysis in /tmp/tppdata (unless you used different mapping parameters above).

Current revision

Contents

[edit]

Overview

Updated: 2023-02-21

The Docker system allows the distribution of pre-built computational units called images, which can be run on any system with the Docker software installed. The spctools/tpp image is built on the BioContainers Ubuntu image, and uses many of the BioContainers conventions. On some systems you may have to run these commands using sudo, a mechanism for elevating user privileges for specific tasks. The initial download described below will be relatively slow the first time it is run, since most if not all the 'layers' will have to be downloaded. Subsequent invocations will generally be much faster.

[edit]

Installing Docker

Detailed installation guidance on how to install Docker on your computer is beyond the scope of this document, but if you're using Ubuntu 18.04 LTS or newer, it should be as easy as: 

sudo apt --yes install docker.io
[edit]

Downloading spctools/tpp docker image

As mentioned above, this may be slow the first time it is run. Subsequent runs should be considerably faster. The example below shows a pull of the latest (default) version, you can also specify a specific version if desired. 

docker pull spctools/tpp
 Using default tag: latest
 Trying to pull repository docker.io/spctools/tpp ... 
 latest: Pulling from docker.io/spctools/tpp
 Digest: sha256:37220874949d6f710eec6661ef57ec2b3cc42f9066d1496a283c4eb32387e4da
 Status: Image is up to date for spctools/tpp:latest

If you get a "permission denied" error, you probably need to put sudo right at the beginning of each docker command, e.g.: sudo docker pull spctools/tpp, and all subsequent docker commands in this document!!

[edit]

Verifying that the image has been downloaded

To verify that you've successfully downloaded the image, you can use the images command below, and hopefully see spctools/tpp entry(s): (don't forget to prepend sudo if you need to) 

 docker images 
  REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE 
  spctools/tpp        latest              8939acb4ab6a        44 minutes ago      2.91GB


[edit]

Running a specific TPP program from the docker image

If you want to run a specific program, e.g. comet, from the TPP installation, you can invoke it along with any arguments as illustrated below, where we have also mapped the local directory /tmp/tppdata outside the container to the /data directory inside the Docker container, which is the current working directory inside the container by default. You may have to adjust the permissions on the local directory if the docker process has trouble writing to it. 

 mkdir /tmp/tppdata
 chmod 777 /tmp/tppdata
 docker run -v /tmp/tppdata:/data spctools/tpp comet -p 
  Created:  comet.params.new

You should find a freshly created comet.params.new file in /tmp/tppdata after the command completes.

[edit]

Obtaining a copy of the default parameter files

There is directory of default parameter files included in the docker image. To make a copy of this directory in the TPP GUI workspace, you would run: 

 docker run -v /tmp/tppdata:/data  spctools/tpp cp -R /usr/local/tpp/params /data/

If you only want to run tools like Comet and PeptideProphet from the command line, that's all. You just ran Comet with the -p flag. If you also want to run the TPP GUI, then read on!


[edit]

Running the TPP GUI via Docker

To run the TPP GUI, you can invoke the following command (Linux syntax): 

 docker run -dit --user=root -p 10401:10401 -v /tmp/tppdata:/data spctools/tpp apache2ctl -DFOREGROUND   
   350dc6eaafe113186c2ec23810bdbc442347a86c2632284435a4b6b713013771

This will start a container running a web server from the spctools/tpp image, map port 10401 on the local machine to the default TPP web server port in the container to enable access, and map a directory of your choosing (/tmp/tppdata in this case) to /data, the root directory for files in the TPP GUI. This will give you access to your data in the TPP GUI. The directory should be exist before starting the TPP GUI.

[edit]

Checking to make sure the Docker image is running 

 docker  ps 
  CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                      NAMES 
  350dc6eaafe1        spctools/tpp        "/bin/sh -c 'apache2…"   3 seconds ago       Up 1 second         0.0.0.0:10401->10401/tcp   suspicious_kilby

You should see at least one spctools/tpp container running. To use the GUI, direct your browser to the URL http://myhost:10401/tpp/cgi-bin/tpp_gui.pl where myhost is the network name of your computer (can also be IP address). You should be prompted to log in as user guest (password is guest). See test analysis tutorial below to try a quick analysis.

[edit]

Stopping the GUI when you're done

When you're done using the GUI, you can stop it with something like this: 

 docker  ps 
  CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                      NAMES 
  350dc6eaafe1        spctools/tpp        "/bin/sh -c 'apache2…"   3 seconds ago       Up 1 second         0.0.0.0:10401->10401/tcp   suspicious_kilby 
 docker stop 350dc6eaafe1

Even after you stop the GUI, any data that you generated will still be there in '/tmp/tppdata' or wherever your data directory was mapped to.

[edit]

Troubleshooting Notes

If you discover that you cannot create directories or write files with Petunia in a container with a Linux host, either the target directory does not have suitable permissions set, or it may be that you're running SELinux (Security Enhanced Linux) via Fedora/CentOS/Red Hat, and you may need to turn that off temporarily to resolve permissions problems with something like: 

 setenforce 0


[edit]

Testing the container and GUI with a sample dataset (optional)

If you want to test your installation with a search and a PeptideProphet processing, try this recipe (you'll need to restart your container if you just stopped it in the step above): 

Navigate to:
http://xxx.xxx.xxx.xxx:10401/tpp/cgi-bin/tpp_gui.pl
- Login with guest and password

## In the Petunia interface in the Web browser:
[Files]
[Create new directory] tests
Go into tests

[TPP Tools] [Fetch Datasets]
 Choose target directory for downloaded files
   [Add Files] Go to the top level /local/data
     - Check box next to tests
     - (Select)
 Specify Dataset ID 
   Paste into URL box: http://www.peptideatlas.org/export/refData/QuickYeastUPS1.zip
 (Fetch Dataset)
 Wait a few moments and [Refresh] until the job is done
 Click on [this directory] and there should only be a subdirectory "QuickYeastUPS1"

[Files]
- Go to /local/data/params/
- Check box next to comet.params
- Click (Copy) button
- Go to /local/data/tests/QuickYeastUPS1
- Click (Paste) button
- On the same line as comet.params, click [Params]
Make the following changes (they might already be set, but check):
  peptide_mass_tolerance = 20
  peptide_mass_units = 2
  isotope_error = 3
- (Save Search Parameters File)

[Pipeline: Comet]
[TPP Tools] [Comet Search]
 Choose mz[X]ML Input Files
  [Add Files] Select /local/data/tests/QuickYeastUPS1/UPS1_50000amol_R1.mzML
 Choose Comet Parameters File
  [Add Files] Select comet.params
 Choose a sequence database
  [Add Files] Select Yeast_UPS_cRAP.fasta
 [Run Comet Search]
 Wait a few moments and [Refresh] until the job is done

[TPP Tools] [Analyze Peptides]
- (Add Files)
- Check box next to UPS1_50000amol_R1.pep.xml
- (Select)
- Under -PEPTIDEPROPHET OPTIONS- check box next to "Use accurate mass binning"
- Under -IPROPHET OPTIONS- Check box next to "RUN iProphet"
- Scroll to bottom and (Run XInteract)
- Wait a few moments and [Refresh] until the job is done
- Make sure no errors
- click on [PepXML] link in /local/data/tests/QuickYeastUPS1/interact.ipro.pep.xml [ PepXML ]

- Click on a probability and view the plots
- Go back to the PepXML Viewer tab
- Click on a value in the Ions column

[TPP Tools] [Analyze Proteins]
- (Add Files)
- Check box next to interact.ipro.pep.xml
- (Select)
- Checkmark "Input is from iProphet"
- (Run ProteinProphet)
- Wait a few moments and [Refresh] until the job is done
- click on [ProtXML] link in /local/data/tests/QuickYeastUPS1/interact.prot.xml [ ProtXML ]
- You should see a list of UPS and yeast proteins detected. Click around to explore

[TPP Tools] [Export mzIdentML]
- (Add Files)
- Check box next to interact.prot.xml
- (Select)
- Wait a few moments and [Refresh] until the job is done

Finis! You'll find all your output from the analysis in /tmp/tppdata (unless you used different mapping parameters above).

Retrieved from "http://tools.proteomecenter.org/wiki/index.php?title=Running_the_TPP_docker_image"
Personal tools