Command line usage

To analyze a file of variants, just type:

oc run input.vcf -l hg38

See the input format specifications for supported input file formats.

The above command will run all installed annotators on the provided input file and produce Excel and sqlite output in same directory as the input file. The terminal output will look something like this:

Running converter...
    Converter (converter)           finished in 0.441s
Running gene mapper...
    UCSC hg38 Gene Mapper (hg38)    finished in 0.188s
Running annotators...
        biogrid: started at Thu Jun  6 18:30:03 2019
        biogrid: finished at Thu Jun  6 18:30:03 2019
        biogrid: runtime 0.013s
    annotator(s) finished in 0.128s
Running aggregator...
    Variants                        finished in 0.013s
    Genes                           finished in 0.010s
    Samples                         finished in 0.008s
    Tags                            finished in 0.018s
Running post-aggregators...
    Tag Sampler (tagsampler)        finished in 0.005s
    VCF Info (vcfinfo)              finished in 0.006s
Finished normally. Runtime: 1.239s

To run a subset of the annotators that are installed, use the -a option:

oc run ./input.vcf -l hg38 -a cosmic ndex

This command would run just the 2 specified annotators (they be installed)

If you would like tab delimited output use -t text or -t text excel for both.

oc run ./input.vcf -l hg38 -t text

The following optional parameters can be included on the OpenCRAVAT command line AFTER the input file. oc run ./input.vcf [command line options]

Option

Description

-h

Shows help message.

-a <annotato rs>

Annotators to run. List of annotator names separated by spaces.

-e <annotato rs>

Run all installed annotators except those listed. List of annotator names separated by spaces.

-n <prefix>

Output filename prefix. Default is the input file name.

-d <director y>

Directory for output files. Default is the directory of the input file.

-c <config>

Path to custom config file, to override cravat.yml settings.

-v

Returns verbose output.

-t <format>

excel,text - Reporters to run.

-l <genome>

hg38,hg19,hg18 - Reference genome of input. Default is hg38.

-x

Force rebuild of the existing result database.

To see all supported command line options type:

oc run -h

Submitting Multiple Files

As of version 1.4.2, openCRAVAT supports the submission of multiple input files in one job. In the command line, this can be done by including multiple paths in the positional arguments as so cravat a.vcf b.vcf c.vcf .... OpenCRAVAT will merge the variants found in the input files and process each unique variant once. All input formats accepted by openCRAVAT can be submitted in multiple files. However, all files must be the in the same format.

Sample IDs are altered when multiple files are submitted to track which file(s) variants occurred in. The format will be inputFileName_originalSampleID. For example, assume two files are submitted, jane.vcf and john.vcf. Each file contains two identically named samples, normal and tumor. In the results, there will be four sample IDs: jane_normal, jane_tumor, john_normal, and john_tumor.

Working with modules

The oc module command tree is used to find modules, and change which are installed on your local system.

Option

Description

Type

-h, –help

Shows help message.

Information

ls

lists modules.

Information

install

installs modules.

System settings

update

updates modules.

System settings

uninstall

uninstalls modules.

System settings

info

shows module information.

Information

install-base

installs base modules.

System settings

For additional help on a specific command, add -h to the command: oc module [command] -h

See available annotators with: oc module ls -a -t annotator

Get a more detailed description for a module of interest, type: oc module info [annotator]

Install an annotator: oc module install [annotator]

See where modules are currently stored: oc config md

Change the modules directory: oc config md [dirPath]

Working with completed jobs

Creating a report

Create a new report with the oc report command. The report will overwrite an existing report of the same type.

oc report job.sqlite -t tsv vcf

The -t flag is required to select the reporter(s) to run. Find more reporters with oc module ls -a -t reporter.

Adding annotators

It is possible to add annotators to a completed job. Simply pass the job’s sqlite db as the input file to oc run, and include a list of annotators to add.

oc run job.sqlite -a chasmplus vest

The selected annotators will be added to the job. Note that a new report will not be generated. That must be done manually if desired.

Upgrading a database

In rare cases, an older database will not be able to use features in newer versions of OpenCRAVAT. If you are getting errors when using newer features, use oc util update-result to modify the database to work with the latest installed version of OpenCRAVAT

Send command line job to the graphical interface

Jobs that are run on the command line will not automatically appear in the graphical interface. Add an existing OpenCRAVAT job to the jobs table in the interactive interface with the following command:

oc send-gui test.sqlite

Command line manual

The root command oc is used in combination with several keywords to run OpenCRAVAT on the terminal.

Option

Description

-h

Shows help message.

run

Run a job

report

Generate a report from a job

gui

Start the GUI

module

Change installed modules

config

View and change configuration settings

new

Create new modules

store

Publish modules to the store

util

Utilities

version

Show version

feedback

Send feedback to the developers

oc run | Run a job

Positional argument: input - Input file(s). One or more variant files in a supported format.

Optional arguments:

Option

Description

-h, –help

show this help message and exit

-a ANNOTATORS [ANNOTATORS …]

annotators to run

-e EXCLUDES [EXCLUDES …]

annotators to exclude

-n RUN_NAME

name of cravat run

-d OUTPUT_DIR

directory for output files

–startat [STAGE]

starts at given stage {converter,mapper,annotator,aggregator,postaggregator,reporter}

–repeat [STAGE]

forces re-run of given stage {converter,mapper,annotator,aggregator,postaggregator,reporter}

–endat [STARGE]

ends after given stage.{converter,mapper,annotator,aggregator,postaggregator,reporter}

–skip [STAGE]

Skips given stage(s). {converter,mapper,annotator,aggregator,postaggregator,reporter}

-c CONF

path to a conf file

–cs CONFS

configuration string

-v

verbose

-t {excel,tsv,vcf,text,csv}

[{excel,tsv,vcf,text,csv} …] report types. If omitted, default one in cravat.yml is used

-l {hg38,hg19,hg18}

reference genome of input. CRAVAT will lift over to hg38 if needed

-x

deletes the existing result database and creates a new one

–newlog

deletes the existing log file and creates a new one

–note NOTE

note will be written to the run status file

–mp MP

number of processes to use to run annotators

-i

{cravat,vcf,oldcravat} Force input format

–temp-files

Leave temporary files after run is complete

–writeadmindb

Write job information to admin db after job completion

–jobid JOBID

Job ID for server version

–version

Shows open-cravat version

–separatesample

Separate variant results by sample

report | Generate a report from a job

oc report is used to generate output reports

Positional argument: dbpath - Path to aggregator output

Optional arguments:

Option

Description

-h, –help

show this help message and exit

-t [FORMAT]

report types, {excel,csv,tsv,text,vcf}

-f FILTERPATH

Path to filter file

-F FILTERNAME

Name of filter (stored in aggregator output)

-s SAVEPATH

Path to save file

-c CONFPATH

path to a conf file

–module-name MODULE_NAME

report module name

–nogenelevelonvariantlevel

Prevent gene level result from being added to variant level result

–confs CONFS

Configuration string

–inputfiles INPUTFILES [INPUTFILES …]

Original input file path

–separatesample

Write each variant-sample pair on a separate line

-d OUTPUT_DIR

directory for output files

gui | Start the GUI

Positional argument: result - Path to a CRAVAT result SQLite file

Optional arguments:

Option

Description

-h, –help

Show this help message and exit

–multiuser

Runs in multiuser mode

–headless

Do not open the cravat web page

–http-only

Force not to accept https connection

–debug

Console echoes exceptions written to log file

module | Change installed modules

View, install, inspect, and uninstall modules

Command

Description

ls

List modules

install

Install modules

uninstall

Uninstall modules

update

Update modules

info

Module details

install-base

Install base modules

config | Configuration settings

View and change configuration settings

Command

Description

md

Change modules directory

system

Show system config

cravat

Show cravat config

new | Create new modules

Create new annotator, and generate an example input file.

Command

Description

example-input

Make example input file

annotator

Create new annotator

store | Publish modules to the store

Publish modules to the store

Command | Description

publish | Publish a module

new-account

Create an account

change-pw

Change password

reset-pw

Request password reset

verify-email

Request email verification

check-login

Check login credentials

util | Utilities

Utilities to test modules, update results databases, and send command line jobs to the GUI.

Command

Description

test

Test installed modules

update-result

Update old result database to newer format

send-gui

Copy a command line job into the GUI list

version | Show version

oc version displays the currently installed version of OpenCRAVAT

feedback | Send feedback to the developers

oc feedback opens the GitHub issues tracker at https://github.com/KarchinLab/open-cravat/issues.

1.7.0 Command Deprecation

OpenCRAVAT 1.7.0 introduced a single command tree, oc, which centralizes functions that previously were spread across possible through multiple command line tools: cravat, wcravat, cravat-admin, cravat-report, cravat-test, and cravat-util. The table below maps old commands to the oc tree. Users are encouraged to shift to using oc. Old root commands will be deprecated in a later version.

Old Program

Command

New Command

cravat

oc run

wcravat

oc gui

cravat-view

oc gui job.sqlite

cravat-report

oc report

cravat-admin

md

oc config md

install-base

oc module install-base

install

oc module install

update

oc module update

uninstall

oc module uninstall

info

oc module info

publish

oc store publish

create-account

oc store new-account

reset-password

oc store reset-pw

verify-email

oc store verify-email

check-login

oc store check-login

make-example-input

oc new example-input

new-annotator

oc new annotator

report-issue

oc feedback

show-system-conf

oc config system

show-cravat-conf

oc config cravat

version

oc version

cravat-test

oc util test

cravat-util

migrate-result