Skip to main content

Calculate both pre and post frequencies for ChIP or ATAC style data

Project description

cisVar is a pipeline to estimate pre-ChIP frequencies from pooled post-ChIP frequencies via a regression on the genotypes of the individuals in the pool. To use this code you must have a mapped BAM file for each pool (a single pool is fine) as well as genotype info for all individuals in the pool in VCF format. Additional information can be provided also, see below for information.

For an overview of this method, or to cite this work, please see the following:

Tehranchi, Ashley K., Marsha Myrthil, Trevor Martin, Brian L. Hie, David Golan, and Hunter B. Fraser. “Pooled ChIP-Seq Links Variation in Transcription Factor Binding to Complex Disease Risk.” Cell 165, no. 3 (April 21, 2016): 730–41.

This code was written by Ashley Tehranchi with minor modifications by Mike Dacre. It was produced at Stanford University, but is released here under the MIT license.

Current version: 2.0.0b3

Overview is the pipeline written in python3 and uses regression_qtls.R (regression_qtls.R is called inside of so you will not run it directly).

In addition, the code at scripts/ can be used to create combined and merged (per-SNP) pandas dataframes from the outputs of for multiple samples.

A complete example Snakemake pipeline is provided in pipeline, you should be able to run it by modifying only the cisvar_config.json file, see the Snakemake section below.

Right now the default minor allele frequency filter is 0.1>MAF<0.99. To change these and other regression constants, edit the regressions_qtls.R script.


Install via PyPI:

pip install cisVar

Or install from github:

pip install

Alternatively, you can just clone the repo and use it directly from there.

git clone

It should work with python 2 or 3, but python 3 is highly recommended.


Requires samtools v1.9 and bedtools v2.26.0 as well as the following python modules (installed automatically by pip):

pandas, numpy, psutil, snakemake, wget

Additionally requires that R with Rscript are installed, with the ggplot2 module installed.


To run this code on your own data you need:

  • VCF(s) with genotypes and ref/alt alleles for every SNP you wish to test
  • A mapped BAM file, ideally this will make use of Hornet to remove reference bias.

In addition, the following data can be helpful:

  • A list of individuals to filter genotypes with (one newline separated file of individuals per pool)
  • A file with ref and alt alleles for your SNPs of interest, to modify those in the genotype VCF files (BED/VCF/txt)
  • A file to limit the SNPs to consider to a subset of those in the VCF (BED/VCF/txt)

Example pipeline: prep -F SampleName -i individuals.txt.gz --chrom-format chr /path/to/geno/*vcf.gz mpileup -F SampleName -f fastaFile -B sortedBam post -F SampleName -r readDepth -a allelesFile geno -F SampleName -r readDepth -i individualsFile -g genotypesFile qtls -F SampleName -r readDepth -n numberIndividuals tidy -F SampleName -r readDepth

scripts/ {sample}.readDepth.regression.pd

A readDepth of 20 is generally optimal, the sample name can be whatever you want, but should be unique per sample. {sample} is a placeholder to allow any number of samples to be combined in the last step.


The above pipeline can be automated with Snakemake.

To use, install cisVar, navigate to the root of your project, and run get_snake to copy the Snakefile and config file over . Then edit the cisvar_config.json file to match your needs.

You will also need to edit the Snakefile to set the script_prep string to match what is needed by your system.

The following are the config options for that file:

Option Description
name A general name for this run, file prefix will be <name>.<sample>.<read_depth>
sample_name The name of the sample, default is population. Used only in the combination of multiple samples.
samples A list of samples, can just be a list, or a dictionary of {sample:group}, the ‘group’ in this case allows the use of the same genotype files for multiple samples, can also be a path to a separate json file
read_depth An integer depth to require for each SNP to be considered
max_cores Used only when parsing VCFs, if you have multiple VCF files ( e.g. per chromosome), they will be parsed in parallel up to this many cores (or max avaialable on machine)
sort_vcfs Either 1 or 0, if 1 assumes that VCF files contain a chr# string in the file name, and sorts the order of files to be chr1->22,X,Y,MT. Don’t use if your VCFs don’t have chr# in the name
chrom_form at ‘chr’, ‘num’, ‘ignore’: Force format of chromosome name to be chr# or #. This ensures that all input files have the same format. Use ignore to do nothing.
bams A path to the mapped BAM files, must contain the {sample} string (unless you only have one bam), e.g. /path/to/{sample}.sorted.bam, {sample} must be in samples
cisVar Path to the cisVar repository
vcfs Can be a single path (for one vcf), a list of vcfs, or a glob string (e.g. /path/to/vcfs/*.vcf.comm.gz)
genome_fa Path to a FastA file of the genome you mapped to, single file only.
inds Optional: used to filter VCFs so that the genotype files contain only the individuals in the sample, e.g. /path/to/inds/{sample}.ind.txt.gz. Newline separated file of individuals.
locs Optional: a BED/VCF/text file of SNP locations to consider, used to limit the total to be a subset of the genotype file.
alleles Optional: a BED/VCF/text file of alternate ref/alt alleles. Must be a subset of the genotype VCFs. If there is an entry in this file, it’s ref/alt alleles will be used instead of those in the genotype file

Note the last three files are optional, also if samples is a dict, then the value will be used in place of the sample. For example, if you have two samples for the same population that are yri1 and yri2, but they both use the same genotype file yri.geno.vcf, you can make samples {'yri1': 'yri', 'yri2': 'yri'} and then yri will be used to pick the ind, loc, and allele files


To run on a cluster, run get_snake with -x and edit the cluster.json file to match your cluster environment, then run e.g.:

snakemake -j 100 --cluster-config cluster.json \
--cluster "sbatch -n {threads} -t {params.time} --mem={resources.mem_mb} -p {cluster.queue} -o {cluster.out} -e {cluster.err}" \


snakemake -j 100 --cluster-config cluster.json \
--cluster "qsub -l nodes=1:ppn={threads} -l walltime={params.time} -l mem={resources.mem_mb}MB -o {cluster.out} -e {cluster.err}" \

To set the maximum allowed memory per job, add the argument --resources mem_mb=32000. Note, this is for the whole pipeline, not per job, because snakemake is stupid.

To also combine files, replace all with combine at the end of the command.

Script help

Below are help options available on the command line for cisVar, all these steps are run by the above snakemake pipeline.

usage: [-h] {prep,mpileup,post,geno,qtls,tidy,get_snake} ...

cisVar: Find cis QTLs based on an experimental selection method

Ashley Tehranchi <>

Stanford University

Version: 2.0.0b1
Created: 2015-12-12
Updated: 2018-05-16

Example usage:
cisVar prep -F test_new -i individuals.txt.gz --chrom-format chr
cisVar mpileup -F <SampleName> -f <fastaFile> -B <sortedBam>
cisVar post -F <SampleName> -r <readDepth>
cisVar geno -F <SampleName> -r <readDepth> -i <individualsFile>
cisVar qtls -F <SampleName> -r <readDepth> -n <numberIndividuals>
cisVar tidy -F <SampleName> -r <readDepth> -p out.dataframe.pandas -t out.dataframe.txt

The qtls regression step will use approximately 32GB of memory on an averaged-
sized dataset.

The geno step will use approximately 20GB of memory on the same dataset.

positional arguments:
    prep                Prepare genotype files
    mpileup (m)         Run mpileup
    post (p)            Run POST frequency calculation
    geno (g)            Munge genotypes to prepare for regression
    qtls (q, regression, r)
                        Run the regression
    tidy (t)            Tidy up regression, call open/clsoed

optional arguments:
  -h, --help            show this help message and exit


This step converts VCFs into genotype and individual files that can be used by the pipeline.

usage: prep [-h] [-F PREFIX_NAME] [-r TRIAL_DEPTHS] [-i ALL_INDS]
                      [-l LIMIT_FILE] [-a ALLELE_FILE]
                      [--chrom-format {chr,num,ignore}] [--include-indels]
                      [-c CORES]
                      vcf_files [vcf_files ...]

Prepare genotype files

optional arguments:
  -h, --help            show this help message and exit

Run Options:
                        sample/population name (default: cis_var)
                        minimum read depth per variant (default: 20)

Prep Options:
  -i ALL_INDS, --all-inds ALL_INDS
                        File of individuals in all groups, one per line
  -l LIMIT_FILE, --limit-file LIMIT_FILE
                        BED/VCF/txt file of SNPs to consider
  -a ALLELE_FILE, --allele-file ALLELE_FILE
                        BED/VCF/txt file of alleles to override VCF allels
                        (subset of vcf)
  --chrom-format {chr,num,ignore}
                        chr: make format "chr#", num: make format "#", ignore:
                        do nothing (default: ignore)
  --include-indels      Do not skip indels
  -c CORES, --cores CORES
                        Number of cores to use (default: all)
  vcf_files             VCF files with genotypes


This is just a simple wrapper for samtools mpileup

usage: mpileup [-h] [-F PREFIX_NAME] [-r TRIAL_DEPTHS] -f

Run mpileup

optional arguments:
  -h, --help            show this help message and exit

Run Options:
                        sample/population name (default: cis_var)
                        minimum read depth per variant (default: 20)

mpileup Options:
                        fasta file with all chromosomes (Required)
                        sorted BAM file (Required)
                        BED to use instead of the BED generated in the prep
                        phase (Do not use if possible, use prep with limit


This step actually calculates the POST-frequencies for the data.

usage: post [-h] [-F PREFIX_NAME] [-r TRIAL_DEPTHS] [-a GENOSFILE]

Run POST frequency calculation

optional arguments:
-h, --help            show this help message and exit

Run Options:
                    sample/population name (default: cis_var)
                    minimum read depth per variant (default: 20)

POST Options (Deprecated):
                    The genotypes file, (Optional, default is file created
                    in prep)


This step converts the genotype file made in the prep step into a matrix that can be used in the regression. It is important that this genotype file is perfectly sorted to match the outputs of the POST step.

usage: geno [-h] [-F PREFIX_NAME] [-r TRIAL_DEPTHS] [-g GENOSFILE]
                      [-i INDIVIDUALSLIST]

Munge genotypes to prepare for regression

optional arguments:
  -h, --help            show this help message and exit

Run Options:
                        sample/population name (default: cis_var)
                        minimum read depth per variant (default: 20)

Genotype Options:
                        The genotypes file, (Optional, default is file created
                        in prep)
                        list of individuals matching genotype matrix; one indv
                        per line


This is the actual regression step, it makes sure all the files are in the right place and then calls regression_qtls.R to do the actual regression.

usage: qtls [-h] [-F PREFIX_NAME] [-r TRIAL_DEPTHS] [-n NUMINDV]

Run the regression

optional arguments:
  -h, --help            show this help message and exit

Run Options:
                        sample/population name (default: cis_var)
                        minimum read depth per variant (default: 20)

Regression Options:
  -n NUMINDV, --numberIndividuals NUMINDV
                        The number of individuals in the pool (if omitted,
                        calculated from genotype file length)

The regression produces z-scores and p-values, and additionally writes coefficients and some simple summary plots in separate files.


This step calls the open/closed alleles and produces a final integrated file with all available data as both a tad-delimited file and as a pandas dataframe.

usage: tidy [-h] [-F PREFIX_NAME] [-r TRIAL_DEPTHS] [-b BEDFILE]
                      [-t TEXTFILE] [-p PANDASFILE]

Tidy up regression, call open/closed

optional arguments:
  -h, --help            show this help message and exit

Run Options:
                        sample/population name (default: cis_var)
                        minimum read depth per variant (default: 20)

  -b BEDFILE, --bedfile BEDFILE
                        BED file to extract rsIDs from (optional)

  -t TEXTFILE, --textfile TEXTFILE
                        Parsed output
  -p PANDASFILE, --pandasfile PANDASFILE
                        Parsed dataframe


This option just downloads the Snakefile and config files from this repo, for easy access when code is installed via pip.

usage: get_snake [-h] [-x]

Download Snakefile and config to current dir

optional arguments:
  -h, --help   show this help message and exit
  -x, --extra  Get additional sample and cluster configs

This script is separate and is in the scripts folder. It takes a search string as an input and produces both combined and merged DataFrames. The combined dataframe is just all dataframes combined in order with sample data added as a column and to the index. The merged dataframe is a collapsed dataframe that has one entry per SNP with p-values combined using Fisher’s method and supporting population data. It also includes information on the level of support for the open and closed calls.

The search string should match your prefix and depth from the main pipeline. For example, if you used a name of ‘cis_var’ plus a sample name (the variable part) of e.g. CEU and YRI, and a read depth of 20, your search string would be: cis_var.{sample}.20.regression.pd.

The script will write cis_var.combined.20.regression.pd and cis_var.merged.20.regression.pd.

usage: [-h] [-c COLUMN_NAME] [--no-merge] search_str

Combine a bunch of cisVar pandas files by sample (e.g. population).

Requires a search string such as prefix.{sample}.regression.pd.

    A simple merger of all DataFrames
    A per-snp merger based on p-value

positional arguments:
  search_str            e.g. name.{sample}.regression.pd, used to find files

optional arguments:
  -h, --help            show this help message and exit
  -c COLUMN_NAME, --column-name COLUMN_NAME
                        Name for combine column, e.g. population
  --no-merge            Produce only a combined dataframe, not a merged
                        dataframe. merging can add half an hour over
                        combination, which takes seconds


There is an additional script in scripts called plot_fun.R that takes a single argument—the output of the regression step (e.g. cis_var.YRI.20.totals.txt) and creates a simple density pre-freq vs post freq plot.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
cisVar-2.0.0b3.tar.gz (45.3 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page