Sigflow: Streamline Analysis Workflows for Mutational Signatures

<img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/shixiangwang/sigflow"> <img alt="Docker Automated build" src="https://img.shields.io/docker/automated/shixiangwang/sigflow"> <img alt="Docker Image Version (latest by date)" src="https://img.shields.io/docker/v/shixiangwang/sigflow?color=blue"> <img alt="Docker Image Size (latest by date)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow"> <img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/shixiangwang/sigflow">

       .__        _____.__                 
  _____|__| _____/ ____\  |   ______  _  __
 /  ___/  |/ ___\   __\|  |  /  _ \ \/ \/ /
 \___ \|  / /_/  >  |  |  |_(  <_> )     / 
/____  >__\___  /|__|  |____/\____/ \/\_/  
     \/  /_____/  

Sigflow provides useful mutational signature analysis workflows. It can auto-extract mutational signatures, fit mutation data to all/specified COSMIC reference signatures (SBS/DBS/INDEL) and run bootstrapping analysis for studying signature stability.

Any bugs or suggestions please report to GitHub issues, I will respond as soon as possible.

<details> <summary>Table of content</summary>

• Sigflow: Streamline Analysis Workflows for Mutational Signatures
  • Installation
  • Use Sigflow docker image
  • Usage
    • Commands and options
    • Input
  • Use cases
    • extract command
    • fit command
    • bt command
    • show command
    • How to use Docker to run Sigflow
  • Updates
  • Test
  • Other tools
  • Citation
  • License

</details>

Installation

If you would like to use Docker, skip the following installation step and go to PART 'Use Sigflow docker image' directly.

Using Sigflow Docker image is recommended for users without experiences in programming, especially in R.

Requirements:

• R (>3.6).
• R package sigminer.
• R package docopt.

Steps:

1. Install R - follow the instructions at https://cran.r-project.org/.
2. Install R packages, run

install.packages("docopt")
install.packages("BiocManager")
BiocManager::install("sigminer", dependencies = TRUE)
# Update Sigminer version
install.packages("remotes")
remotes::install_github("ShixiangWang/sigminer")
# Install specific version by
# remotes::install_github("ShixiangWang/sigminer@v1.0.17")

3. Clone this repository, run

$ git clone https://github.com/ShixiangWang/sigflow

4. Link the R script as a executable file (command)

$ cd sigflow
$ ln -s $PWD/sigflow.R /usr/local/bin/sigflow  # You can choose another place instead of /usr/bin/sigflow

5. Try calling sigflow

sigflow -h

Maybe you need to restart your terminal.

Use Sigflow docker image

Use specified version (recommended way):

# docker pull shixiangwang/sigflow:version, e.g.
$ docker pull shixiangwang/sigflow:1.0

NOTE: Sigflow version has no prefix v.

Current available tag versions:

• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/0.1?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/0.1">
• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/1.0?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/1.0">
• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/1.1?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/1.1">
• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/1.2?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/1.2">
• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/1.3?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/1.3">
• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/1.5?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/1.5">
• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/2.0?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/2.0">
• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/2.1?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/2.1">
• <img alt="Docker Image Version" src="https://img.shields.io/docker/v/shixiangwang/sigflow/2.2?color=blue"> <img alt="Docker Image Size (tag)" src="https://img.shields.io/docker/image-size/shixiangwang/sigflow/2.2">

Use latest version:

$ docker pull shixiangwang/sigflow:latest

The latest version uses the latest (successful build) commit from GitHub, so it may have not been prepared or fully tested. So, be careful!

Run the docker by:

$ docker run shixiangwang/sigflow

See test/test_docker.sh for examples.

If you want to go into the docker container terminal, run

$ docker run --rm --entrypoint /bin/bash -it shixiangwang/sigflow

Usage

Commands and options

All Sigflow commands and options are described as the following.

=================================================================
sigflow: Streamline Analysis Workflows for Mutational Signatures.

Author: Shixiang Wang (wangshx@shanghaitech.edu.cn)
Copyright: AFL@2020 [https://opensource.org/licenses/AFL-3.0]

Desc:
  There are several subcommands.
  ==
  extract - extract signatures by either automatic or semi-automatic way.
            Of note, when you use manual way, you need to run 2 times, 
            firstly you should set --manual to get signature estimation results,
            and secondly you should set --manual --number N to get N signatures.
  ==
  fit     - fit signatures in >=1 samples based on COSMIC reference signatures.
  ==
  bt      - run bootstrap signature fitting analysis in >=1 samples.
  ==
  show    - show some useful information or plots. See README for details.

Usage:
  sigflow extract --input=<file> [--output=<outdir>] [--mode=<class>] [--manual --number <sigs>] [--max <max>] [--genome=<genome>] [--nrun=<runs>] [--cores=<cores>] [--sigprofiler] [--refit] [--hyper] [--verbose]
  sigflow fit --input=<file> [--output=<outdir>] [--index=<index>] [--mode=<class>] [--genome=<genome>] [--verbose]
  sigflow bt  --input=<file> [--output=<outdir>] [--index=<index>] [--mode=<class>] [--genome=<genome>] [--nrun=<runs>] [--verbose]
  sigflow show [--isearch=<keyword>] [--index=<index> --mode=<class>] [--output=<outdir>] [--verbose]
  sigflow (-h | --help)
  sigflow --version

Options:
  -h --help     Show help message.
  --version     Show version.
  -i <file>, --input <file>       input CSV/EXCEL/MAF file or VCF directory path.
  -o <outdir>, --output <outdir>  output directory path [default: ./sigflow_result/].
  --index <index>                 reference signature index separated by comma, e.g. '1,2,3' [default: ALL].
  -m <class>, --mode <class>      extract/fit mode, can be one of SBS, DBS, ID, MAF (for three types), CN (not supported in fit subcommand) [default: SBS].
  --manual                        enable manual extraction, set -N=0 for outputing signature estimation firstly.
  -N <sigs>, --number <sigs>      extract specified number of signatures [default: 0].
  --max <max>                     maximum signature number, default is auto-configured, should >2 [default: -1].
  -g <genome>, --genome <genome>  genome build, can be hg19, hg38 or mm10, [default: hg19].
  -r <runs>, --nrun <runs>        run times of NMF (extract) or bootstrapping (bt) to get results [default: 30].
  -T <cores>, --cores <cores>     cores to run the program, large dataset will benefit from it [default: 1].
  --refit                         refit the de-novo signatures with quadratic programming or nnls (SigProfiler).
  --hyper                         enable hyper mutation handling in COSMIC signatures (not used by SigProfiler approach).
  --sigprofiler                   enable automatic extraction by SigProfiler software.
  --isearch <keyword>             search and how cancer type specific reference signature index by keyword, e.g. breast.
  -v, --verbose                   print verbose message.

=================================================================

Input

Sigflow supports input data in VCF/MAF/CSV/EXCEL format. The file format is auto-detected by Sigflow.

For SBS/DBS/INDEL data in CSV (including TSV) or EXCEL format, the following columns typically described in MAF format are necessary:

• Hugo_Symbol: gene symbol
• Chromosome: chromosome name, e.g. "chr1"
• Start_Position: start positionof the variant (1-based)
• End_Position: end position of the variant (1-based)
• Reference_Allele: reference allele of the variant, e.g. "C"
• Tumor_Seq_Allele2: tumor sequence allele, e.g. "T"
• Variant_Classification: variant classification, e.g. "Missense_Mutation"
• Variant_Type: variant type, e.g. "SNP"
• Tumor_Sample_Barcode: sample identifier

For copy number seg