To Index

Quick Start Guide for cisCall

cisCall contains the following three modules:

Notice: cisCall 201604 Edition is obsolete. Please use the latest version. We finished providing the cisCall VirtualBox image file.

For your convenience, we have prepared a cisCall virtual machine as an Oracle VirtualBox image in which all prerequisite resources and environments necessary to run cisCall are included.

In this page, we explain how to run cisCall in the above cisCall virtual machine, including:

  • How to run cisCall for a short example of test data
  • How to run cisCall for user-prepared data

To set up your own cisCall environments without using the VirtualBox image, see cisCall installation section.

1. Outline of the cisCall Virtual Machine

  • cisCall version: cisCall 201604 Edition
    Reference files for cisCall are based on hg19.
  • OS: CentOS-6.8-x86_64-minimal
  • Specification: 4 CPU cores, 32 GB memory, 120 GB fixed HDD
  • Network: NAT connection
  • Port for VRDP connection: 5017

A host OS must have enough power to run the cisCall virtual machine. X-Window is not required for a host OS.

2. Set Up the cisCall Virtual Machine

2.1. Install VirtualBox and its Extension Pack on the Host OS

If VirtualBox has been installed on your computer, skip this section and go to the Obtaining the cisCall VirtualBox Image section.

We assume that the yum command is available on your computer (host OS). If you use another installation command, please change the commands below accordingly. Root authority is required for these steps.

  1. Obtain the yum repository for VirtualBox and store it as /etc/yum.repos.d/virtualbox.repo on the host OS.

  2. Install VirtualBox on the host OS. 

     $ sudo yum search VirtualBox
     .... suitable versions are shown ....
 $ sudo yum install VirtualBox-5.0.x86_64

  3. Check the exact version of the installed VirtualBox. 

     $ yum list installed | grep -i virtualbox
 VirtualBox-5.0.x86_64                 5.0.24_108355_el6-1              @virtualbox

  4. Download the VirtualBox extension pack and install it. The VirtualBox and extension versions must match.

    $ wget http://download.virtualbox.org/virtualbox/5.0.24/Oracle_VM_VirtualBox_Extension_Pack-5.0.24_108355.vbox-extpack
$ sudo VBoxManage extpack install Oracle_VM_VirtualBox_Extension_Pack-5.0.24_108355.vbox-extpack

2.2. Obtaining the cisCall VirtualBox Image

2.2.1. Obtaining the cisCall VirtualBox Image Files

Notice: We finished providing the cisCall VirtualBox image file.

The cisCall VirtualBox image file (tarball) is split into two files owing to its large size. Obtain the following files.

2.2.2. Reconstruct the cisCall VirtualBox Image File

Concatenate the above two split files into CentOS6.8-minimal_cisCall_public.tar.gz to reconstruct the cisCall VirtualBox image file.

$ cat CentOS6.8-minimal_cisCall_public_split.aa \
      CentOS6.8-minimal_cisCall_public_split.ab \
      > CentOS6.8-minimal_cisCall_public.tar.gz

The concatenated file is as follows:

  • CentOS6.8-minimal_cisCall_public.tar.gz:
    • md5sum: 5ff69d45f3bd0e8951f5131857f4b84c
    • size: 14566030257

2.2.3. Extract the cisCall VirtualBox Image

Extract the above CentOS6.8-minimal_cisCall_public.tar.gz file as follows:

$ tar xzvf CentOS6.8-minimal_cisCall_public.tar.gz

The CentOS6.8-minimal_cisCall_public directory is then generated, in which all extracted content is stored.

2.3. Start the cisCall Virtual Machine on the Host OS

  1. Register the cisCall VirutalBox image file into VirtualBox.
    Registration requires the absolute full path to CentOS6.8-minimal_cisCall_public/CentOS6.8-minimal_cisCall_public.vbox in the cisCall VirtualBox image.

     $ VBoxManage registervm /home/user/VirtualBox_Vbox/CentOS6.8-minimal_cisCall_public/CentOS6.8-minimal_cisCall_public.vbox

    The registered virtual machine (VM) names can be checked using VBoxManage list vms.

  2. Start the cisCall virtual machine with the registered VM name.

     $ VBoxManage startvm CentOS6.8-minimal_cisCall_public --type headless

2.4. Access the cisCall Virtual Machine from a Remote Client in Your Host OS or in Another Computer

  1. Start a remote desktop protocol (RDP) client (e.g., Windows Remote Desktop or Linux rdesktop) in your host OS or in another computer.

  2. Specify <IP address of host OS>:5017 as the destination to access.
    5017 is the port that is set to the cisCall virtual machine for the connection using VRDP. See Changing the VRDE Port to change the port to change the port.

  3. Login with the following user information:

    • User: cisusr
    • Password: cisusrcisusr

    The cisCall modules and all prerequisite files are stored in /home/cisusr/cisCall in the virtual machine.

3. Run cisCall for Short Example Test Data in the cisCall Virtual Machine

3.1. cisCall Short Example Test Data and Execution Directory

We prepared the following directories under /home/cisusr/cisCall in the cisCall virtual machine to run cisCall for a short example of test data.

  • cisMuton_example:

    • Target (foreground) sample data: derived from a drug-resistant lung cancer cell-line sample purchased from a company
    • Control (background) sample data: derived from the corresponding normal cell-line sample purchased from a company
    • A mutation on KRAS (chr12, 25398285) should be detected by cisMuton.

  • cisFusion_example:

    • Target (foreground) sample data: derived from a lung cancer cell-line sample purchased from a company
    • Control (background) sample data: derived from the same normal cell-line as above
    • A fusion SLC34A2 and ROS1 (chr4:25666629:down|chr6:117658326:down, chr4:25666626:up|chr6:117658308:up) should be detected by cisFusion.

  • cisCton_example:

    • Target (foreground) sample data: derived from the same drug-resistant lung cancer cell-line sample as above
    • Control (background) sample data: derived from the same normal cell-line sample as above
    • A CNA on MT2A (chr16) should be detected by cisCton.

3.2. Running cisCall for the Short Example Test Data

To run cisCall for the short example of test data, apply the following:

  • cisMuton:
    Change the current directory to /home/cisusr/cisCall/cisMuton_example and execute ./example.muton.sh.
  • cisFusion:
    Change the current directory to /home/cisusr/cisCall/cisFsuion_example and execute ./example.fusion.sh.
  • cisCton:
    Change the current directory to /home/cisusr/cisCall/cisCton_example and execute ./example.cton.sh.

These jobs require the following amount of processing time:

  • cisMuton example: about 2 hours
  • cisFusion example: about 30 minutes
  • cisCton example: about 3 hours

3.3. cisCall Output

The output call files are stored in each execution directory as follows:

  • cisMuton:
    output/fg_sample_data.PANEL_FOR_TEST/Muton/Call.normal_sample_data/
    The most important output file is the call file: call.case0.txt
  • cisFusion:
    output/fg_sample_data.PANEL_FOR_TEST/Fusion/Call.normal_sample_data/
    The most important output file is the call file: AlnWexome_LmtOneside_Mq10_Single.txt
  • cisCton:
    output/fg_sample_data.PANEL_FOR_TEST/Cton/
    The most important output file is the call file: gene.cnv_target_dup.txt

Output files for the short example of test data can be got at the following locations:

4. Running cisCall for User-Prepared Data in the cisCall Virtual Machine

In this section, we explain how to run cisCall for your own data in the cisCall virtual machine.

The procedure is as follows:

  1. Prepare your data (e.g., .fastq files and .bed files for region definitions) in your host OS.

  2. Make a new directory in the cisCall virtual machine in which cisCall will run.

  3. Transfer your data into the cisCall virtual machine using the scp command.

  4. Run cisCall in the execution directory.

4.1. Make the Network Reachable

First, in the cisCall virtual machine, check the network connection to the host OS using ping command or other similar means.

If the network is unreachable, please refer to Changing the Network Settings section to make it reachable.

4.2. Getting User-Prepared Data Ready on the Host OS

cisCall uses the following three variables for input file names consistently:

  • SAMPLE_NAME: target (foreground) sample name
  • BG_SAMPLE_NAME: target (foreground) sample name
  • GROUP: group name used to identify a group of input files in the execution directory

Please set these names. The names should not include .. For GROUP, the same group name have to be assigned to all input files between cisMuton and cisCton (since cisCton uses .bam files generated by cisMuton); a different group name can be used for input files for cisFusion.

See the User-Prepared Data section for more details.

4.3. Prepare the cisCall Execution Directory in the Virtual Machine

*Note: The execution directories for cisMuton, cisFusion, and cisCton must be separate.

  1. In the cisCall virtual machine, copy the following directories (stored as templates) to the new directories to be used as your cisCall execution directories.

    • cisMuton: /home/cisusr/cisCall/cisMuton_execdir_template
    • cisFusion: /home/cisusr/cisCall/cisFusion_execdir_template
    • cisCton: /home/cisusr/cisCall/cisCton_execdir_template

    Some files under the above directories are symbolic links to large files (under /home/cisusr/cisCall/resource). In order to save disk space, we recommend copying them using cp -PR.

  2. Change the prefix GROUP of all the files under the new directories to your defined ${GROUP}.

4.4. Transfer Your Data to the Virtual Machine

  1. Issue scp or other similar commands from the virtual machine to copy your data to the new execution directory.
    Note that network commands should be issued from the virtual machine to the outside, since the network uses a NAT connection.

  2. As for cisCton, at the cisCton execution directory, copy or make a symbolic link to the tmp directory generated by cisMuton under the cisMuton execution directory. cisCton uses .bam files generated under the tmp directory by cisMuton.

4.5. Run cisMuton/cisFusion on the Virtual Machine

4.5.1. Setting the Parameters

cisMuton/cisFusion require setting parameters that depend on conditions such as the sequencer type (Illumina or Ion) and target (foreground) sample type (FFPE or frozen/cell-line). To set these parameters, see the Setting Parameters section.

4.5.2. Removing Adapter Sequences

To remove adapter sequences in .fastq files using cisCall, see the Removing Adaptor Sequences section.
*Note: After removing adapter sequences with cisCall, -RA will be added to the sample names of the .fastq files.

4.5.3. Issuing a Command

Change the current directory to the cisMuton/cisFusion execution directory and issue the following command:

  • cisMuton: 
    $ perl /home/cisusr/cisCall/cisMuton/bin/qc_run.pl ${SAMPLE_NAME}:${BG_SAMPLE_NAME}:${GROUP}:MUTON,${OPTION}
  • cisFusion: 
    $ perl /home/cisur/cisCall/cisFusion/bin/qc_run.pl ${SAMPLE_NAME}:${BG_SAMPLE_NAME}:${GROUP}:FUSION,${OPTION}

See each caller page for cisMuton and cisFusion section for further options.

4.6. Run cisCton

In the current version, there is no step in which cisCton sets parameters.

cisMuton must be run before cisCton since cisCton uses .bam files generated by cisMuton.

4.6.1. Issuing a Command

Change the current directory to the cisCton execution directory and issue the following command:

$ python3 /home/cisusr/cisCall/cisCton/ciscall.py \
    -a CTON \
    -d ${cisCton_exexcution_directory} \
    -w ${cisCton_exexcution_directory} \
    -m /home/cisusr/cisCall/cisMuton/bin/samtools \
    -b /home/cisusr/cisCall/cisCton/utility/bigWigToBedGraph \
    ${SAMPLE_NAME} \
    ${BG_SAMPLE_NAME} \
    -p ${GROUP} \
    -r ${GROUP}.fasta \
    -g ${GROUP}.refGene.txt  \
    -l debug \
    ;

5. Contact Information

  • Contact e-mail address: cisCall_tech@ml.res.ncc.go.jp
To Index

results matching ""

    No results matching ""