BioHPC Cloud:
: User Guide

Run the pipeline in "screen" persistant session. If you have run previous version caper and atac-seq-pipeline, or you run into problems with this pipeline, delete the .caper directory to reset caper ("rm -fr $HOME/.caper")

Instructions to run latest version

pip install caper --upgrade

mkdir /workdir/$USER
cd /workdir/$USER

git clone https://github.com/ENCODE-DCC/atac-seq-pipeline.git
cd atac-seq-pipeline

wget -O atac-seq-pipeline.sif https://encode-pipeline-singularity-image.s3.us-west-2.amazonaws.com/atac-seq-pipeline_v2.2.2.sif

2. Prepare reference genome database

1) If you work with human and mouse data, the Encode project provides pre-prepared genome database. Go to this page , under the section for "Reference genome", you will find URL of the reference genome database. For example, "https://storage.googleapis.com/encode-pipeline-genome-data/genome_tsv/v3/hg38.tsv". You will need this URL later.

2) If you work with other species, follow the instructions below to prepare the reference genome database.

• Edit the script "/workdir/$USER/atac-seq-pipeline/scripts/build_genome_data.sh",  setting the values for GENOME, DEST_DIR, TSV, MITO_CHR_NAME.  The chromsome names match between the genome files. For plant genome, you might want to create a new genome fasta file with mitochondria and chloroplast merged, and call it a mitochandria genome. 
• Run these commands to create genome database. After it is done, you should see a directory /workdir/$USER/$DEST_DIR with a .tsv file inside. You will need this .tsv file later. 

cd /workdir/$USER/atac-seq-pipeline
cp /PATH/TO/your.genome.fa.gz ./
singularity run --bind $PWD --pwd $PWD atac-seq-pipeline.sif ./scripts/build_genome_data.sh

3. Put your atac-seq data files ( *.fastq.gz) into the directory /workdir/$USER/atac-seq-pipeline

4. Prepare a .json text file to specify all input files, and keep it in /workdir/$USER/atac-seq-pipeline

• You can modify from this example file (for local files, replace URL with file or directory name). Detailed documentation of the json file can be found in this page (The section under "Input JSON file")

6. run pipeline
You might want to restrict number of simultaneously jobs when running the caper command (e.g. limit to up to 4 jobs, --max-concurrent-tasks 4), otherwise, all available cores on the server will be used.

export PATH=~/.local/bin:$PATH
caper run atac.wdl -i my.json --singularity atac-seq-pipeline.sif --max-concurrent-tasks 4

7. summarize results

cd atac
ls -l
cd xxxxxxx         #replace xxxxxxx with the run directory you get from ls -l
croo metadata.json
qc2tsv qc/qc.json > qc.tsv

The results should be in the directories "peak" "qc" and "signal" , report files croo*, and QC table qc.tsv 

Instructions to run v2.1.1 (for v2.1.1 and  v 1.10 see below)

Run the pipeline in "screen" persistant session.

1. Install caper version 2.1.3 in your home directory. Copy atac-seq-pipeline to the server you are working on, and set environment

pip install caper==2.1.3 croo qc2tsv --upgrade

mkdir /workdir/$USER
cd /workdir/$USER
cp -r /programs/atac-seq-pipeline-2.1.1 /workdir/$USER

2. Prepare reference genome database

1) If you work with human and mouse data, the Encode project provides pre-prepared genome database. Go to this page , under the section for "Reference genome", you will find URL of the reference genome database. For example, "https://storage.googleapis.com/encode-pipeline-genome-data/genome_tsv/v3/hg38.tsv". You will need this URL later.

2) If you work with other species, follow the instructions below to prepare the reference genome database.

• Edit the script "/workdir/$USER/atac-seq-pipeline-2.1.1/build_genome_data_mod.sh",  setting the values for GENOME, GENOME DEST_DIR, REF_FA, MITO_CHR_NAME, the rest of the parameters are optional.  Make sure that you need to use the full path for file name and destination directory, for example, /workdir/$USER/atac-seq-pipeline-2.1.1/genomedb, /workdir/$USER/atac-seq-pipeline-2.1.1/mygenome.fasta.  The chromsome names match between the genome files. For plant genome, you might want to create a new genome fasta file with mitochondria and chloroplast merged, and call it a mitochandria genome. 
• Run these commands to create genome database. After it is done, you should see a directory /workdir/$USER/$DEST_DIR with a .tsv file inside. You will need this .tsv file later. 

cd /workdir/$USER/atac-seq-pipeline-2.1.1
cp /PATH/TO/your.genome.fa.gz ./
singularity exec atac-seq-pipeline.sif ./build_genome_data_mod.sh

3. Put your atac-seq data files ( *.fastq.gz) into the directory /workdir/$USER/atac-seq-pipeline-2.1.1

4. Prepare a .json text file to specify all input files, and keep it in /workdir/$USER/atac-seq-pipeline-2.1.1

• You can modify from this example file (for local files, replace URL with file or directory name). Detailed documentation of the json file can be found in this page (The section under "Input JSON file")
   

5. Set number of cpu per task.
Optionally, you can modify the file /workdir/$USER/atac-seq-pipeline-2.1.1/atac.wdl, and change the number of cpu per task (under "group: resource_parameter"). In most cases, there is no need to change (for example, default setting for aligner bowtie2 is 6 cores per job which is good). However, you might want to restrict number of simultaneously jobs when running the caper command (e.g. limit to up to 4 jobs, --max-concurrent-tasks 4), otherwise, all available cores on the server will be used.

6. run pipeline

export PATH=~/.local/bin:$PATH
caper run atac.wdl -i my.json --singularity atac-seq-pipeline.sif

7. summarize results

cd atac
ls -l
cd xxxxxxx         #replace xxxxxxx with the run directory you get from ls -l
croo metadata.json
qc2tsv qc/qc.json > qc.tsv

The results should be in the directories "peak" "qc" and "signal" , report files croo*, and QC table qc.tsv 

Run pipeline with example data files

Here is how to run test data set provided by the pipeline developer (run software in "screen" persistent session)

export PATH=~/.local/bin:$PATH
export ATACROOT=/workdir/$USER/atac-seq-pipeline-2.1.1 

mkdir /workdir/$USER
cd /workdir/$USER/
cp -r /programs/atac-seq-pipeline-2.1.1 /workdir/$USER

#download test data set
wget https://raw.githubusercontent.com/ENCODE-DCC/atac-seq-pipeline/master/example_input_json/ENCSR356KRQ_subsampled.json

#process test dataset
caper run $ATACROOT/atac.wdl -i ENCSR356KRQ_subsampled.json --singularity $ATACROOT/atac-seq-pipeline.sif

If no --output directory specified, the output directory is atac. The result files under atac, in execution directory, the files are documented in https://encode-dcc.github.io/wdl-pipelines/output_atac.html.

# After the work is finished, organize output results with croo

cd atac
ls -l 
cd xxxxxxx  #replace xxxxxxx with the run directory you get from "ls -l"
croo metadata.json
qc2tsv qc/qc.json  > qc.tsv

The results should be in the directories "peak" "qc" and "signal" , report files croo*, and QC table qc.tsv 

Instructions to run v1.10.0

1. Copy software directory to the server you are working on, and set environment

export PYTHONPATH=/programs/caper/lib/python3.6/site-packages:/programs/caper/lib64/python3.6/site-packages
export PATH=/programs/caper/bin:$PATH
export version=1.10.0

mkdir /workdir/$USER
cd /workdir/$USER
cp -r /programs/atac-seq-pipeline-${version} /workdir/$USER

2. Prepare reference genome database

1) If you work with human and mouse data, the Encode project provides pre-prepared genome database. Go to this page , under the section for "Reference genome", you will find URL of the reference genome database. For example, "https://storage.googleapis.com/encode-pipeline-genome-data/genome_tsv/v3/hg38.tsv". You will need this URL later.

2) If you work with other species, follow the instructions below to prepare the reference genome database.

• Edit the script "/workdir/$USER/atac-seq-pipeline-1.10.0/build_genome_data_mod.sh",  setting the values for GENOME, GENOME DEST_DIR REF_FA MITO_CHR_NAME, the rest of the parameters are optional.  Make sure that the chromsome names match between the genome files. For plant genome, you might want to create a new genome fasta file with mitochondria and chloroplast merged, and call it a mitochandria genome. 
• Run these commands to create genome database. After it is done, you should see a directory /workdir/$USER/$DEST_DIR with a .tsv file inside. You will need this .tsv file later. 

cd /workdir/$USER/atac-seq-pipeline-1.10.0
cp /PATH/TO/your.genome.fa.gz ./
singularity exec atac-seq-pipeline.sif ./build_genome_data.sh

3. Put your atac-seq data files ( *.fastq.gz) into the directory /workdir/$USER/atac-seq-pipeline-1.10.0

4. Prepare a .json text file to specify all input files, and keep it in /workdir/$USER/atac-seq-pipeline-1.10.0.

• You can modify from this example file (for local files, replace URL with file or directory name). Detailed documentation of the json file can be found in this page (The section under "Input JSON file")
   

5. Set number of cpu per task.
Optionally, you can modify the file /workdir/$USER/atac-seq-pipeline-1.10.0/atac.wdl, and change the number of cpu per task (under "group: resource_parameter"). In most cases, there is no need to change (for example, default setting for aligner bowtie2 is 6 cores per job which is good). However, you might want to restrict number of simultaneously jobs when running the caper command (e.g. limit to up to 4 jobs, --max-concurrent-tasks 4), otherwise, all available cores on the server will be used.

6. run pipeline

caper run atac.wdl -i my.json --singularity atac-seq-pipeline.sif

7. summarize results

cd atac
ls -l
cd xxxxxxx         #replace xxxxxxx with the run directory you get from ls -l
croo metadata.json
qc2tsv qc/qc.json > qc.tsv

The results should be in the directories "peak" "qc" and "signal" , report files croo*, and QC table qc.tsv 

Run pipeline with example data files

Here is how to run test data set provided by the pipeline developer (run software in "screen" persistent session)

export PYTHONPATH=/programs/caper/lib/python3.6/site-packages:/programs/caper/lib64/python3.6/site-packages
export PATH=/programs/caper/bin:$PATH
export version=1.10.0

mkdir /workdir/$USER
cd /workdir/$USER/
cp -r /programs/atac-seq-pipeline-${version} /workdir/$USER

#download test data set
wget https://storage.googleapis.com/encode-pipeline-test-samples/encode-atac-seq-pipeline/ENCSR356KRQ_subsampled_caper.json

#process test dataset
export ATACROOT=/workdir/$USER/atac-seq-pipeline-${version}

caper run $ATACROOT/atac.wdl -i ENCSR356KRQ_subsampled_caper.json --singularity $ATACROOT/atac-seq-pipeline.sif

If no --output directory specified, the output directory is atac. The result files under atac, in execution directory, the files are documented in https://encode-dcc.github.io/wdl-pipelines/output_atac.html.

# After the work is finished, organize output results with croo

export PYTHONPATH=/programs/caper/lib/python3.6/site-packages:/programs/caper/lib64/python3.6/site-packages
export PATH=/programs/caper/bin:$PATH
cd atac
ls -l 
cd xxxxxxx  #replace xxxxxxx with the run directory you get from "ls -l"
croo metadata.json
qc2tsv qc/qc.json  > qc.tsv

The results should be in the directories "peak" "qc" and "signal" , report files croo*, and QC table qc.tsv