Basic Usage

You may run VNTRseek with the command

vntrseek startstep endstep --dbsuffix dbsuffix

Where startstep is the step you wish to start with and endstep is the last step you want to run. If you only want to run one step, either set both to the same value, or omit endstep.

For new runs, startstep would be 0 and if you wanted to run the whole pipeline, endstep would be 19 (but see next section on initializing a new run).

The --dbsuffix argument is required as this is how VNTRseek knows which configuration file to use.

Do not use '.' or '-' in dbsuffix. Use only characters allowed in MySQL identifiers.

Initializing a run

For a new run, the command above will not be sufficient. VNTRseek needs to know at minimum: what you will name your run (dbsuffix), where the read files are stored (fasta_dir), where the output will go (output_root), how many processes it can run at once (nprocesses), a temporary directory it can use (tmpdir), the directory to which it should write files to be viewed by vntrview (html_dir), and the names of the input reference set profiles and sequences (reference_file and reference_seq). If you have already created a set of indistinguishables, use the reference_indist option to give the name of this file, otherwise set reference_indist_produce to be 1. If your MySQL server is hosted on a machine other than the one you are running the pipeline on, set host. Also set the database user that VNTRseek will log onto MySQL as (login).

Here is an example of how someone might initialize a VNTRseek run (we recommend executing only step 0 for a new run):

vntrseek 0 --dbsuffix genome_sample_one --fasta_dir /path/to/fasta_or_fastq/files --output_root /path/to/output --nprocesses 8 --tmpdir /tmp --html_dir /path/to/output/html_out --reference_file refset.leb36 --reference_seq refset.seq --reference_indist refset.indist --host other.host.edu --login vntruser

Note that none of the reference options use a full path. This is because VNTRseek expects these files to be found in the same directory that VNTRseek is installed in. This command also assumes that the machine has at least 8 processors available.

While there is an option to set the MySQL user password, for security we do not recommend using it. Instead, edit the configuration file created after issuing the initialization command, and look for (or add) the option PASS and set it there. The configuration file is, by default, only readable by the owner.

VNTRseek configuration file

When VNTRseek is run for the first time with a dbsuffix, it creates a configuration of the form dbsuffix.vs.cnf in the user's home directory. The file is populated with all possible options, with default or dummy values for most options. Subsequent calls to vntrseek need only the dbsuffix option as the rest can be drawn from the file.

Of course, you could avoid using a long command like the one above by simply running a command like vntrseek 0 --dbsuffix dbname and then editing the configuration file, if you prefer. However, initializing with as many options as possible will set those values in the configuration file for you.

The configuration format is simply OPTION = value, one option/value pair per line. Comment lines begin with #.

Special commands

• Clear error: vntrseek 100 --dbsuffix dbsuffix
  • If an error is encountered when running the pipeline, set startstep to 100. Because of temporary files, don't run step 3 without step 2 and don't run steps 13-17 without step 12.
  • If you set endstep as well, this actually sets the next step to run.
• Return next step: vntrseek 99 --dbsuffix dbsuffix Useful when scripting runs of VNTRseek. Also useful when running on a cluster, as a script can decide whether to request more processors when the next step requires them.

Full list of options

  --HELP                        prints this help message
  --LOGIN                       mysql login
  --PASS                        mysql pass
  --HOST                        mysql host (default localhost)
  --NPROCESSES                  number of processors on your system
  --MIN_FLANK_REQUIRED          minimum required flank on both sides for a read TR to be considered (default 10)
  --MAX_FLANK_CONSIDERED        maximum flank length used in flank alignments, set to big number to use full flank (default 50)
  --MIN_SUPPORT_REQUIRED        minimum number of mapped reads which agree on copy number to call an allele (default 2)
  --DBSUFFIX                    suffix for database name
  --SERVER                      server name, used for html generating links
  --STRIP_454_KEYTAGS           for 454 platform, strip leading 'TCAG', 0/1 (default 0)
  --IS_PAIRED_READS             data is paired reads, 0/1 (default 0)
  --HTML_DIR                    html directory (must be writable and executable!)
  --FASTA_DIR                   input data directory (plain or gzipped fasta/fastq files)
  --OUTPUT_ROOT                 output directory (must be writable and executable!)
  --TMPDIR                      temp (scratch) directory (must be writable!)
  --REFERENCE_FILE              reference profile file (default set in global config file)
  --REFERENCE_SEQ               reference sequence file (default set in global config file)
  --REFERENCE_INDIST            reference indistinguishables file (default set in global config file)
  --REFERENCE_INDIST_PRODUCE    generate a file of indistinguishable references, 0/1 (default 0)
  --REFS_TOTAL                  total number of reference TRs prior to filtering (default set in global config file)