debian/changelog

-hilive (2.0a-1) UNRELEASED; urgency=medium
+hilive (2.0a-1) unstable; urgency=medium
 
   * New upstream version
   * New URL on Github
@@ -6,7 +6,7 @@ hilive (2.0a-1) UNRELEASED; urgency=medium
   * Standards-Version: 4.4.1
   * Build-Depends: libboost-iostreams-dev
 
- -- Andreas Tille <tille@debian.org>  Mon, 07 Oct 2019 11:02:50 +0200
+ -- Andreas Tille <tille@debian.org>  Mon, 07 Oct 2019 13:48:50 +0200
 
 hilive (1.1-3) unstable; urgency=medium
 

debian/hilive-build.1

-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
-.TH HILIVE-BUILD "1" "July 2016" "hilive-build 0.0+20150926" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.11.
+.TH HILIVE-BUILD "1" "October 2019" "hilive-build 2.0a" "User Commands"
 .SH NAME
 hilive-build \- Index creation tool for HiLive - Realtime Alignment of Illumina Reads
 .SH SYNOPSIS
-.B hilive-build
-[\fI\,options\/\fR] \fI\,INPUT\/\fR
-.SH DESCRIPTION
-HiLive index builder v0.1
-Index creation tool for HiLive \- Realtime Alignment of Illumina Reads
-Copyright \(co 2015, Martin S. Lindner
-HiLive is open\-source software. Check with \fB\-\-license\fR for details.
-.PP
-Fixed k\-mer size: 15
-.TP
-INPUT
-Reference genomes in (multi\-) FASTA format
-.SS "General:"
+.B hilive\-build
+[options]
+.SH OPTIONS
+.SS "GENERAL OPTIONS:"
 .TP
 \fB\-h\fR [ \fB\-\-help\fR ]
 Print this help message and exit
 .TP
-\fB\-\-license\fR
+\fB\-l\fR [ \fB\-\-license\fR ]
 Print licensing information and exit
-.SH OPTIONS
+.SS "REQUIRED OPTIONS:"
+.TP
+\fB\-i\fR [ \fB\-\-input\fR ] arg
+Reference genome(s) in (multi\-)FASTA format.
+[REQUIRED]
+.TP
+\fB\-o\fR [ \fB\-\-out\-prefix\fR ] arg
+Output file prefix. Several files with the same
+prefix will be created. [REQUIRED]
+.SS "OTHER OPTIONS:"
 .TP
-\fB\-o\fR [ \fB\-\-outfile\fR ] arg
-Set output file name [Default: INPUT.kix]
+\fB\-\-do\-not\-convert\-spaces\fR
+Do not convert all spaces in reference ids to
+underscores [Default: converting is on]
 .TP
-\fB\-t\fR [ \fB\-\-trim\fR ] arg
-Ignore k\-mers with more than t occurrences. [Default:
-no limit]
+\fB\-\-trim\-after\-space\fR
+Trim all reference ids after first space [Default: false]
+.SH EXAMPLE
+hilive\-build \fB\-\-input\fR hg19.fa \fB\-\-out\-prefix\fR ./index/hg19
 .SH AUTHOR
 This manpage was written by Andreas Tille for the Debian distribution and can be used for any other usage of the program.

debian/hilive.1

-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
-.TH HILIVE "1" "July 2016" "hilive 0.0+20150926" "User Commands"
+.TH HILIVE "1" "October 2019" "hilive 2.0a" "User Commands"
 .SH NAME
 hilive \- Realtime Alignment of Illumina Reads
 .SH SYNOPSIS
 .B hilive
-[\fI\,options\/\fR] \fI\,BC_DIR INDEX CYCLES\/\fR
+[options]
 .SH DESCRIPTION
-HiLive v0.1 \- Realtime Alignment of Illumina Reads
-Copyright \(co 2015, Martin S. Lindner
-HiLive is open\-source software. Check with \fB\-\-license\fR for details.
-.PP
-Fixed k\-mer size: 15
+HiLive is a read mapping tool that maps Illumina HiSeq (or comparable)
+reads to a reference genome right in the moment when they are produced.
+This means, read mapping is finished as soon as the sequencer is
+finished generating the data.
+.SH OPTIONS
+.SS "REQUIRED OPTIONS:"
 .TP
-BC_DIR
-Illumina BaseCalls directory of the sequencing run to analyze
+\fB\-b\fR [\-\-bcl\-dir]
+Illumina's BaseCalls directory which contains the sequence information of the reads.
 .TP
-INDEX
-Path to k\-mer index file (*.kix)
+\fB\-i\fR [\-\-index]
+Path to the HiLive index.
 .TP
-CYCLES
-Total number of cycles for read 1
-.SS "General:"
+\fB\-r\fR [\-\-reads]
+Length and types of the read segments.
+.PP
+Required options might be specified either on the command line or in the config file.
+.SS "GENERAL OPTIONS:"
 .TP
 \fB\-h\fR [ \fB\-\-help\fR ]
-Print this help message and exit
+Print this help message and exit.
+.TP
+\fB\-l\fR [ \fB\-\-license\fR ]
+Print license information and exit.
 .TP
-\fB\-\-license\fR
-Print licensing information and exit
-.SS "IO settings:"
+\fB\-c\fR [ \fB\-\-config\fR ] arg
+Path to a config file. Config file is in
+\&.ini format. Duplicate keys are not
+permitted. Instead, use comma\-separated
+lists. Parameters obtained from the command
+line are prioritized over settings made in
+the config file.
 .TP
-\fB\-\-temp\fR arg
-Temporary directory for the alignment files
-[Default: use BaseCalls directory]
+Example for a config.ini:
+bcl\-dir=./BaseCalls
+lanes=1
+out\-cycle=50,100
 .TP
-\fB\-S\fR [ \fB\-\-sam\fR ] arg
-Create SAM files for each tile. [Default: no
-SAM files]
+\fB\-\-runinfo\fR arg
+Path to Illumina's runInfo.xml file. If
+specified, read lengths, lane count and
+tile count are automatically set in
+accordance with the sequencing run.
+Parameters obtained from the command line
+or config file are prioritized over
+settings obtained from the runInfo.xml.
 .TP
-\fB\-k\fR [ \fB\-\-keep\-files\fR ]
-Keep intermediate alignment files [Default:
-false]
+\fB\-\-continue\fR arg
+Continue an interrupted HiLive run from a
+specified cycle. We strongly recommend to
+load the config file that was automatically
+created for the original run to continue
+with identical settings. This config file
+(hilive_config.ini) can be found in the
+temporary directory specified with
+\fB\-\-temp\-dir\fR.
+.SS "SEQUENCING OPTIONS:"
+.TP
+\fB\-b\fR [ \fB\-\-bcl\-dir\fR ] arg
+Illumina's BaseCalls directory which
+contains the sequence information of the
+reads.
 .TP
 \fB\-l\fR [ \fB\-\-lanes\fR ] arg
-Select lane [Default: all lanes]
+Specify the lanes to be considered for read
+alignment. [Default: 1\-8]
 .TP
 \fB\-t\fR [ \fB\-\-tiles\fR ] arg
-Select tile numbers [Default: all tiles]
-.SS "Alignment settings:"
+Specify the tiles to be considered for read
+alignment. [Default: [1\-2][1\-3][01\-16] (96
+tiles)]
+.TP
+\fB\-T\fR [ \fB\-\-max\-tile\fR ] arg
+Specify the highest tile number. The tile
+numbers will be computed by this number,
+considering the correct surface count,
+swath count and tile count for Illumina
+sequencing.
+This parameter serves as a shortcut for
+\fB\-\-tiles\fR.
+.TP
+Example:
+\fB\-\-max\-tile\fR 2216
+.TP
+will activate all tiles in
+[1\-2][1\-2][01\-16].
+.TP
+\fB\-r\fR [ \fB\-\-reads\fR ] arg
+Length and types of the read segments. Each
+segment is either a read ('R') or a barcode
+('B'). Please give the segments in the
+correct order as they are produced by the
+sequencing machine. [REQUIRED]
+.TP
+Example:
+\fB\-\-reads\fR 101R,8B,8B,101R
+.TP
+specifies paired\-end sequencing with
+2x101bp reads and 2x8bp barcodes.
+.TP
+\fB\-B\fR [ \fB\-\-barcodes\fR ] arg
+Barcode(s) of the sample(s) to be
+considered for read alignment. Barcodes
+must match the barcode length(s) as
+specified with \fB\-\-reads\fR. Delimit different
+segments of the same barcodes by '\-' and
+different barcodes by ','. [Default: All
+barcodes]
+.TP
+Example:
+\fB\-b\fR ACCG\-ATTG,ATGT\-TGAC
+.IP
+for two different barcodes of length 2x4bp.
+.TP
+\fB\-\-run\-id\fR arg
+ID of the sequencing run. Should be
+obtained from runInfo.xml.
+.TP
+\fB\-\-flowcell\-id\fR arg
+ID of the flowcell. Should be obtained from
+runInfo.xml.
+.TP
+\fB\-\-instrument\-id\fR arg
+ID of the sequencing machine. Should be
+obtained from runInfo.xml.
+.SS "REPORT OPTIONS:"
+.TP
+\fB\-o\fR [ \fB\-\-out\-dir\fR ] arg
+Path to the directory that is used for the
+output files. The directory will be created
+if it does not exist. [Default: ./out]
+.TP
+\fB\-f\fR [ \fB\-\-out\-format\fR ] arg
+Format of the output files. Currently, SAM
+and BAM format are supported. [Default:
+BAM]
+.TP
+\fB\-O\fR [ \fB\-\-out\-cycles\fR ] arg
+Cycles for that alignment output is
+written. The respective temporary files are
+kept. [Default: write only after the last
+cycle]
+.TP
+\fB\-M\fR [ \fB\-\-out\-mode\fR ] arg
+The output mode. [Default: ANYBEST]
+[ALL|A]: Report all found alignments.
+[BESTN#|N#]: Report the # best found
+alignments.
+[ALLBEST|H]: Report all found alignments
+with the best score.
+[ANYBEST|B]: Report one best alignment.
+[UNIQUE|U]: Report only unique alignments.
+.TP
+\fB\-\-report\-unmapped\fR
+Activate reporting unmapped reads.
+[Default: false]
+.TP
+\fB\-\-extended\-cigar\fR
+Activate extended CIGAR format for the
+alignment output files ('=' for matches and
+\&'X' for mismatches instead of using 'M' for
+both). [Default: false]
+.TP
+\fB\-\-force\-resort\fR
+Always sort temporary alignment files
+before writing output. Existing sorted
+align files are overwritten. This is only
+necessary if the temp directory is used
+more than once for new alignments. In
+general, this is not recommended for most
+applications. [Default: false (only sort if
+no sorted files exist)]
+.TP
+\fB\-\-max\-softclip\-ratio\fR arg
+Maximal relative length of the front
+softclip (only relevant during output)
+[Default: 0.2]
+.TP
+Further explanation:
+HiLive uses an approach that requires one
+exact match of a k\-mer at the beginning of
+an alignment. This can lead to unaligned
+regions at the beginning of the read which
+we report as 'softclips'. With this
+parameter, you can control the maximal
+length of this region.
+.SS "ALIGNMENT OPTIONS:"
+.TP
+\fB\-i\fR [ \fB\-\-index\fR ] arg
+Path to the HiLive index. Please use the
+executable 'hilive\-build' to create a new
+HiLive index that is delivered with this
+program. The index consists of several
+files with the same prefix. Please include
+the file prefix when specifying the index
+location.
+.TP
+\fB\-m\fR [ \fB\-\-align\-mode\fR ] arg
+Alignment mode to balance speed and
+accuracy [very\-fast|fast|balanced|accurate|
+very\-accurate]. This selected mode
+automatically sets other parameters.
+Individually configured parameters are
+prioritized over settings made by selecting
+an alignment mode. [Default: balanced]
+.TP
+\fB\-\-anchor\-length\fR arg
+Length of the alignment anchor (or initial
+seed) [Default: set by the selected
+alignment mode]
+.TP
+\fB\-\-error\-interval\fR arg
+The interval to tolerate more errors during
+alignment (low=accurate; great=fast).
+[Default: 'anchor\-length'/2]
+.TP
+\fB\-\-seeding\-interval\fR arg
+The interval to create new seeds
+(low=accurate; great=fast). [Default:
+\&'anchor\-length'/2]
+.TP
+\fB\-\-max\-softclip\-length\fR arg
+The maximum length of a front softclip when
+creating new seeds. In contrast to
+\fB\-\-max\-softclip\-ratio\fR, this parameter may
+have effects on runtime and mapping
+accuracy. [Default: 'readlength/2]
+.TP
+\fB\-\-barcode\-errors\fR arg
+The number of errors that are tolerated for
+the barcode segments. A single value can be
+provided to be applied for all barcode
+segments. Alternatively, the value can be
+set for each segment individually.
+[Default: 1]
+.TP
+Example:
+\fB\-\-barcode\-errors\fR 2 [2 errors for all barcode segments]
+.IP
+\fB\-\-barcode\-errors\fR 2,1 [2 errors for the first, 1 error for the second segment]
+.TP
+\fB\-\-align\-undetermined\-barcodes\fR
+Align all barcodes. Reads with a barcode
+that don't match one of the barcodes
+specified with '\-\-barcodes' will be
+reported as undetermined. [Default: false]
+.TP
+\fB\-\-min\-basecall\-quality\fR arg
+Minimum basecall quality for a nucleotide
+to be considered as a match [Default: 1
+(everything but N\-calls)]
+.TP
+\fB\-\-keep\-invalid\-sequences\fR
+Keep sequences of invalid reads, i.e. with
+unconsidered barcode or filtered by the
+sequencer. This option must be activated to
+report unmapped reads. [Default: false]
+.SS "SCORING OPTIONS:"
+.TP
+\fB\-s\fR [ \fB\-\-min\-as\fR ] arg
+Minimum alignment score. [Default: Set
+automatically based on the alignment mode
+and match/mismatch scores]
+.TP
+\fB\-\-match\-score\fR arg
+Score for a match. [Default: 0]
+.TP
+\fB\-\-mismatch\-penalty\fR arg
+Penalty for a mismatch. [Default: 6]
+.TP
+\fB\-\-insertion\-opening\-penalty\fR arg
+Penalty for insertion opening. [Default: 5]
+.TP
+\fB\-\-insertion\-extension\-penalty\fR arg Penalty for insertion extension. [Default: 3]
+.TP
+\fB\-\-deletion\-opening\-penalty\fR arg
+Penalty for deletion opening. [Default: 5]
+.TP
+\fB\-\-deletion\-extension\-penalty\fR arg
+Penalty for deletion extension. [Default:
+3]
 .TP
-\fB\-e\fR [ \fB\-\-min\-errors\fR ] arg (=2)
-Number of errors tolerated in read alignment
+\fB\-\-max\-gap\-length\fR arg
+Maximal permitted consecutive gap length.
+Increasing this parameter may lead to
+highly increased runtime! [Default: 3]
 .TP
-\fB\-H\fR [ \fB\-\-best\-hit\fR ]
-Report only the best alignmnet(s) for each
-read
+\fB\-\-softclip\-opening\-penalty\fR arg
+Penalty for softclip opening (only relevant
+during output). [Default:
+\&'mismatch\-penalty']
 .TP
-\fB\-N\fR [ \fB\-\-best\-n\fR ] arg (=2)
-Report the N best alignmnets for each read
+\fB\-\-softclip\-extension\-penalty\fR arg
+Penalty for softclip extension (only
+relevant during output). [Default:
+\&'mismatch\-penalty'/'anchor\-length']
+.SS "TECHNICAL OPTIONS:"
 .TP
-\fB\-\-disable\-ohw\-filter\fR
-Disable the One\-Hit Wonder filter
+\fB\-\-temp\-dir\fR arg
+Temporary directory to store the alignment
+files and hilive_config.ini. [Default:
+\&./temp]
 .TP
-\fB\-\-start\-ohw\fR arg (=20)
-First cycle to apply One\-Hit Wonder filter
+\fB\-k\fR [ \fB\-\-keep\-files\fR ] arg
+Keep intermediate alignment files for these
+cycles. The last cycle is always kept.
+[Default: Keep files of output cycles]
 .TP
-\fB\-w\fR [ \fB\-\-window\fR ] arg (=5)
-Set the window size to search for alignment
-continuation, i.e. maximum insertion/deletion
-size
+Further Explanations:
+HiLive comes with a separated executable
+\&'hilive\-out'. This executable can be used
+to produce alignment files in SAM or BAM
+format from existing temporary files. Thus,
+output can only be created for cycles for
+that keeping the temporary alignment files
+is activated. Temporary alignment files are
+also needed if an interrupted run is
+continued with the '\-\-continue' parameter.
 .TP
-\fB\-\-min\-quality\fR arg (=1)
-Minimum allowed basecall quality
-.SS "Technical settings:"
+\fB\-K\fR [ \fB\-\-keep\-all\-files\fR ]
+Keep all intermediate alignment files. This
+option may lead to huge disk space
+requirements. [Default: false]
 .TP
 \fB\-\-block\-size\fR arg
 Block size for the alignment input/output
-stream in Bytes. Use \fB\-K\fR or \fB\-M\fR to specify in
-Kilobytes or Megabytes
+stream in Bytes. Append 'K' or 'M' to
+specify in Kilobytes or Megabytes,
+respectively. [Default: 64M]
 .TP
-\fB\-K\fR
-Interpret the block\-size argument as Kilobytes
-instead of Bytes
+Example:
+\fB\-\-block\-size\fR 1024 [1024 bytes]
+\fB\-\-block\-size\fR 64K [64 Kilobytes]
+\fB\-\-block\-size\fR 64M [64 Megabytes]
 .TP
-\fB\-M\fR
-Interpret the block\-size argument as Megabytes
-instead of Bytes
+\fB\-\-compression\fR arg
+Compression of temporary alignment files.
+[Default: LZ4]
+0: no compression.
+1: Deflate (smaller).
+2: LZ4 (faster).
 .TP
-\fB\-c\fR [ \fB\-\-compression\fR ] arg (=2)
-Compress alignment files. 0: no compression
-(default) 1: Deflate (smaller) 2: LZ4 (faster)
+\fB\-n\fR [ \fB\-\-num\-threads\fR ] arg
+Number of threads to spawn (including
+output threads). [Default: 1]
 .TP
-\fB\-n\fR [ \fB\-\-num\-threads\fR ] arg (=1)
-Number of threads to spawn
+\fB\-N\fR [ \fB\-\-num\-out\-threads\fR ] arg
+Maximum number of threads to use for
+output. More threads may be used for output
+automatically if threads are idle.
+[Default: 'num\-threads'/2]
+.SH EXAMPLE
+hilive \fB\-\-bcl\-dir\fR ./BaseCalls \fB\-\-index\fR ./reference/hg19 \fB\-\-reads\fR 101R
 .SH AUTHOR
 This manpage was written by Andreas Tille for the Debian distribution and can be used for any other usage of the program.