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.

Assign alternative “canonical” transcript

In some cases, the MANE canonical transcript does not suit analysis needs. To assign alternative transcripts as canonical for the annotation job, use the —primary-transcript option. It works like this:

oc run input -l hg19 --primary-transcript selected_transcripts.txt

The selected_transcripts.txt file should be tab-delimited with two columns: hugo and ENST.

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
–module-option csvreporter.pages=sample	Include additional report output files
–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