cis-X

cis-X searches for activating regulatory variants in the tumor genome.

Activating regular variants usually cause the cis-activation of target genes. To find cis-activated genes, allelic specific/imbalance expressions (ASE) and outlier high expression (OHE) signals are used. Variants in the same topologically associated domains with the candidates can then be searched, including structural variants (SV), copy number aberrations (CNA), and single nucleotide variations (SNV) and insertion/deletions (indel).

A transcription factor binding analysis is also done, using motifs from HOCOMOCO v10 models.

cis-X currently only works with hg19 (GRCh37).

More details and examples on running cis-X can be found in the user guide.

Installation

Installation is simply unpacking the source to a working directory and adding $CIS_X_HOME/bin to PATH.

Prerequisites

See cis-X run and cis-X seed for the required tools and references.

Usage

cis-X

USAGE:
    cis-X <SUBCOMMAND> [args...]

SUBCOMMANDS:
    ref-exp  Generate reference expression matrices
    run      Search for activating regulatory variants in the tumor genome
    seed     Download and generate a set of common references

For more details on how to run each command, see its respective README: ref-exp, run, and seed.

Docker

cis-X has a Dockerfile to create a Docker image, which sets up and installs all the required dependencies (sans references). To use this image, install Docker for your platform.

For typical inputs, cis-X requires at least 4 GiB of RAM. This resource can be increased for the desktop version of Docker by going to Docker preferences > Advanced > Memory.

Build

In the cis-X project directory, build the Docker image.

$ docker image build --tag cis-x .

Run

The Docker image uses bin/cis-X as its entrypoint, giving access to all of its commands.

The image assumes two working directories: /data for inputs and /results for outputs. /data can be read-only, whereas /results needs write access. External references (see cis-X seed) also need to be mounted to /opt/cis-x/refs/external. For example, mounting to these directories requires three flags:

--mount type=bind,source=$HOME/research/data,target=/data,readonly \
--mount type=bind,source=/tmp/references,target=/opt/cis-x/refs/external,readonly \
--mount type=bind,source=$(pwd)/cis-x-out,target=/results \

The source directives can point to any absolute path that can be accessed locally. They do not need to match their target directory. Also note that the results directory must exist before running the command.

Examples

cis-X seed

A basic example is running cis-X seed, which downloads and preprocesses required reference files to a directory. To run this locally, the seed subcommand is used, passing the destination directory of the resulting files.

$ cis-X seed /tmp/refs/external

To run this in a container using the Docker image, pass the subcommand and arguments as the command the container runs.

$ docker container run cis-x seed /tmp/refs/external

This, however, writes files to the container, rather than the host. To write files to the host from the container, mount the host destination directory to the container, e.g., $(pwd)/refs/external to /opt/cis-x/refs/external. The argument passed to the command must match the target directory.

$ docker container run \
    --mount type=bind,source=$(pwd)/refs/external,target=/opt/cis-x/refs/external \
    cis-x \
    seed \
    /opt/cis-x/refs/external

cis-X run

The following template shows the minimum set of arguments to execute the run command, with variables showing what needs to be set.

$ docker container run \
    --mount type=bind,source=$DATA_DIR,target=/data,readonly \
    --mount type=bind,source=$REFS_DIR,target=/opt/cis-x/refs/external,readonly \
    --mount type=bind,source=$RESULT_DIR,target=/results \
    cis-x \
    run \
    -s $SAMPLE_ID \
    -o /results \
    -l /data/$MARKERS \
    -g /data/$CNV_LOH_REGIONS \
    -b /data/$BAM \
    -e /data/$GENE_EXPRESSION_TABLE \
    -m /data/$SOMATIC_SNV_INDEL \
    -v /data/$SOMATIC_SV \
    -c /data/$SOMATIC_CNV \
    -d $DISEASE

Note that pathname arguments are relative to the container's target. For example, mounting $HOME/research and with an input located at $HOME/research/sample-001/markers.txt, the corresponding argument is /data/sample-001/markers.txt.

See the Docker reference for run for more container run options. See cis-X run for more runtime options.

Demo

The next example runs cis-X with demo data (cis-X-demo.tar.gz).

Set up the project home directory with the demo data. The following commands assume the demo is extracted to a tmp directory in the root of the project.

$ git clone https://github.com/stjude/cis-x.git
$ cd cis-x
$ docker image build --tag cis-x .
$ mkdir tmp
$ wget --directory-prefix tmp http://ftp.stjude.org/pub/software/cis-x/cis-X-demo.tar.gz
$ tar xf tmp/cis-X-demo.tar.gz --directory tmp
$ wget --directory-prefix tmp https://www.stjuderesearch.org/site/docs/zhang/cancer_gene_census.txt.gz
$ gzip --decompress --stdout tmp/cancer_gene_census.txt.gz > tmp/demo/ref/cancer_gene_census.txt

Then run cis-X.

$ docker container run \
    --mount type=bind,source=$(pwd)/tmp/demo/data,target=/data,readonly \
    --mount type=bind,source=$(pwd)/tmp/demo/ref,target=/opt/cis-x/refs/external,readonly \
    --mount type=bind,source=$(pwd)/tmp,target=/results \
    cis-x \
    run \
    -s SJALL018373_D1 \
    -o /results \
    -l /data/SJALL018373_D1.test.wgs.markers.txt \
    -g /data/SJALL018373_D1.test.wgs.cnvloh.txt \
    -b /data/SJALL018373_D1.test.RNAseq.bam \
    -e /data/SJALL018373_D1.test.RNASEQ_all_fpkm.txt \
    -m /data/SJALL018373_D1.test.mut.txt \
    -v /data/SJALL018373_D1.test.sv.txt \
    -c /data/SJALL018373_D1.test.cna.txt \
    -d TALL \
    -a drop \
    -w 10 \
    -r 10 \
    -f 5