=================================================== Instructions on how to run Metagenome Orchestra (Orchestra or Mago for short) within a Singularity container. Orchestra homepage: http://mago.fe.uni-lj.si =================================================== ------------------ SYSTEM PREPARATION ------------------ Make sure that Singularity is installed on your system. Singularity also needs installed squashfs file system to work properly, but some Linux distributions do not install it automatically. You can check, whether singularity is installed by opening Linux terminal and executing: singularity --version If Singularity is present, it responds by printing its version. If this does not happen, please search the internet on how to install Singularity on your Linux distribution (it is fairly easy). --------------------------------------------------- Please note the reported version, since command line for running Mago slightly differs between singularty 2.6.x and singularity 3.x. --------------------------------------------------- Note that a proper Singularity response above does not imply the presence of the squashfs file system. If the instructions below do not work as expected, please assure that squashfs is installed by using package manager that comes with your Linux system. Some Linux distributions also require that a user, which handles Singularity images is a member of "singularity" group. On many (but not all) Linux distributions a user is added to the group by one of the following commands: sudo usermod -aG singularity or sudo useradd -g singularity This will succeed only, if your Linux system defines group "singularity". Otherwise, this step is probably not needed. After making any of the above changes, it may be necessary to logout/login or even restart the system for the changes to become effective. -------------------------------------------------- DOWNLOADING ORCHESTRA IMAGE -------------------------------------------------- Download Orchestra image from Orchestra web site http://mago.fe.uni-lj.si/mago_V2_2.simg and save it in a local directory of your choice. The file can be downloaded by your favourite web browser, or by executing the following command within Linux terminal located in the target download directory: wget http://mago.fe.uni-lj.si/mago_V2_2.simg Below it is assumed that the file is downloaded to your home directory /home/user_name. Consequently, this file is referred to as /home/user_name/mago_V2_2.simg Please adjust the below commands to reflect the actual target directory on your system. ------------------------------- RUNNING ORCHESTRA DEMO PIPELINE ------------------------------- To test Orchestra setup and to get the impression about how Orchestra works, we prepared a simple demo setup. It can be downloaded from: http://mago.fe.uni-lj.si/mago_demo_V2_2.zip The file can be downloaded by your favourite web browser, or by executing the following command within Linux terminal located in the target download directory: wget http://mago.fe.uni-lj.si/mago_demo_V2_2.zip Save file to a directory of your choice. In the following it is assumed that this is directory /home/user_name, and consequently the downloaded file is referred to as /home/user_name/mago_demo_V2_2.zip. When following the instructions below, please adjust commands to reflect the actual path on your system. Open Linux terminal in the directory, where the downloaded file is located. Execute command: unzip mago_demo_V2_2.zip This will unpack the contents of the file to a directory /home/user_name/mago_demo_V2_2 Within directory /home/user_name/mago_demo_V2_2 there are four files with DNA sequences (*.fastq), a directory with reference genomes (FastANI_ref), as well as configuration file demo_simg.txt for executing Orchestra within a Singularity container (there are also two other configuration files for Orchestra Docker container and for Orchestra VirtualBox virtual machine). Open file /home/user_name/mago_demo_V2_2/demo_simg.txt in a text editor, and locate the following three lines near the beginning of the file: out_directory_root = /home/john_doe/mago_demo_output input_R1_reads_file = /home/mago/mago_demo_V2_2/*frag_1.fastq input_R2_reads_file = /home/mago/mago_demo_V2_2/*frag_2.fastq as well as the following line at the end od the file FastANI_reference_genome_pattern = /home/mago/mago_demo_V2_2/FastANI_ref/Pseudo*.fna Modify all four template paths /home/john_doe/... to reflect the actual directory structure on your system, e.g. /home/user_name/mago_demo_V2_2/... Start Orchestra processing by executing the following one-line (!!!) command: for singularity version 2.6.x ------------------------------- singularity run /home/user_name/mago_V2_2.simg /home/user_name/mago_demo_V2_2/demo_simg.txt for singularity version 3.x ------------------------------- singularity run --writable-tmpfs /home/user_name/mago_V2_2.simg /home/user_name/mago_demo_V2_2/demo_simg.txt Orchestra should start processing. File demo_simg.txt instructs Orchestra to output results of processing to directory that you have specified by parameter out_directory_root. In this directory, the newly created files should start appearing as a result of Orchestra execution. ----------------------------------- RUNNING YOUR OWN ORCHESTRA PIPELINE ----------------------------------- 1. In a typical Singularity setup your Linux home directory is visible within Singularity container and is mapped to the same path in it. Therefore, in a typical situation directory /home/user_name where user_name is your Linux user name, is visible to Orchestra. Please note that (almost) all other directories in your Linux system are NOT visible to Orchestra. Consequently, your input files (reads, scaffolds, config.txt) should be located within your home directory. Orchestra's Singularity image also provides two other paths /scratch and /data for sharing files with it. These are enabled by default on many systems. (If you are an experienced Singularity user, you may check for the presence or other directory mappings, or define your own ones.) 2. Download config_template.txt from http://mago.fe.uni-lj.si/config_template_V2_2.txt into the directory of your preference Rename the file to something meaningful (e.g. config_test.txt). 5. Set parameters within config_test.txt according to your preferences. Recall that Orchestra can access only files within your Linux home directory, and/or potentially other defined shared locations as /data and /scratch. In the same way, set Orchestra's output directory to a directory within your Linux home directory, e.g. /home/user_name/test_out. Set other parameters as well. At least you need to specify steps to be performed (a selection of binners, ...) 6. Open Linux terminal and run Orchestra by issuing the following one-line (!!!) command: for singularity version 2.6.x ------------------------------- singularity run /home/user_name/mago_V2_2.simg /home/user_name/some_dir/config_test.txt for singularity version 3.x ------------------------------- singularity run --writable-tmpfs /home/user_name/mago_V2_2.simg /home/user_name/some_dir/config_test.txt