HILIVE(1)

💖 HILIVE(1) 💖

okay bestie, gather round — this is a User Commands page from section 1 of the manual, and it's all about a little thing called hilive. She's iconic, she's realtime, and she's about to change your whole sequencing life. 🦋

---

✨ NAME ✨

hilive — Realtime Alignment of Illumina Reads 🧬💅

---

✨ SYNOPSIS ✨

hilive [options]

literally that's it, just run her with whatever options you need 👑

---

✨ DESCRIPTION ✨

So here's the tea, bestie 🍓 — HiLive is a read mapping tool, and she does NOT wait around like some other tools. Nope. She maps Illumina HiSeq reads (or reads from anything comparable, ngl) straight onto a reference genome right in the moment when they are produced. Like, as they're being born. Mid-generation. Main character energy fr fr. 😭✨

And the payoff? Read mapping is finished as soon as the sequencer is finished generating the data. No awkward waiting-around era, no "let me process that real quick" arc. When the sequencer says done, the mapping says done too. Periodt. 💅👑

iykyk — this is the whole vibe of the tool: realtime, no cap.

---

🎀 REQUIRED OPTIONS 🎀

These three? Not optional. They're the main characters, bestie.

• -b, --bcl-dir — Illumina's BaseCalls directory, aka the folder holding the sequence info for all your reads. The raw material, the whole vibe 💖
• -i, --index — the path to your HiLive index. Point at it, love it, use it.
• -r, --reads — the length and types of the read segments. Tell HiLive what shape your reads are, no cap.

You can hand these over on the command line or stick them in the config file. Either way works, queen.

---

✨ GENERAL OPTIONS ✨

• -h, --help — prints this help message and dips. That's it, that's the whole job.
• -l, --license — prints the license info and exits. Legal girlies rise up.
• -c, --config arg — path to a config file. It's in .ini format, so keep it cute. Duplicate keys are not permitted — instead, use comma-separated lists. And heads up: parameters from the command line always beat settings in the config file. Command line stays winning 👑

Example for a config.ini:

bcl-dir=./BaseCalls lanes=1 out-cycle=50,100

• --runinfo arg — path to Illumina's runInfo.xml file. If you specify it, read lengths, lane count and tile count all get set automatically to match the sequencing run. So convenient 🦋 But — parameters from the command line or the config file are prioritized over whatever comes out of the runInfo.xml.
• --continue arg — continue an interrupted HiLive run starting from a specified cycle. And this part is important, so listen: we strongly recommend loading the config file that was automatically created for the original run, so you continue with identical settings. That config file (hilive_config.ini) lives in the temporary directory you specified with --temp-dir. Don't skip this, fr fr.

---

🌸 SEQUENCING OPTIONS 🌸

• -b, --bcl-dir arg — Illumina's BaseCalls directory which contains the sequence information of the reads. (Yes, it's the same one as up top, she's just visiting again.)
• -l, --lanes arg — which lanes get considered for read alignment. [Default: 1-8]
• -t, --tiles arg — which tiles get considered for read alignment. [Default: [1-2][1-3][01-16] (96 tiles)]
• -T, --max-tile arg — the highest tile number. HiLive will compute the tile numbers from it, respecting the correct surface count, swath count and tile count for Illumina sequencing. Basically it's a shortcut for --tiles. Iconic.

Example:

--max-tile 2216

will activate all tiles in [1-2][1-2][01-16].

• -r, --reads arg — length and types of the read segments. Each segment is either a read ('R') or a barcode ('B'). Give the segments in the correct order, exactly as the sequencing machine produces them. [REQUIRED]

Example:

--reads 101R,8B,8B,101R

specifies paired-end sequencing with 2x101bp reads and 2x8bp barcodes.

• -B, --barcodes arg — the barcode(s) of the sample(s) to consider for read alignment. Barcodes have to match the barcode length(s) you set with --reads. Delimit different segments of the same barcode with '-', and different barcodes with ','. [Default: All barcodes]

Example:

-b ACCG-ATTG,ATGT-TGAC

for two different barcodes of length 2x4bp.

• --run-id arg — ID of the sequencing run. Should be obtained from runInfo.xml.
• --flowcell-id arg — ID of the flowcell. Should be obtained from runInfo.xml.
• --instrument-id arg — ID of the sequencing machine. Should be obtained from runInfo.xml.

---

💅 REPORT OPTIONS 💅

• -o, --out-dir arg — path to the directory used for the output files. If it doesn't exist yet, it gets created for you. [Default: ./out]
• -f, --out-format arg — format of the output files. Right now, SAM and BAM are supported. [Default: BAM]
• -O, --out-cycles arg — the cycles for which alignment output gets written. The respective temporary files are kept. [Default: write only after the last cycle]
• -M, --out-mode 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.
• --report-unmapped — turns on reporting of unmapped reads. [Default: false]
• --extended-cigar — activates extended CIGAR format for the alignment output files ('=' for matches and 'X' for mismatches, instead of using 'M' for both). [Default: false]
• --force-resort — always sort temporary alignment files before writing output. Existing sorted align files get overwritten. This is only necessary if the temp directory is used more than once for new alignments, and in general it's not recommended for most applications. [Default: false (only sort if no sorted files exist)]
• --max-softclip-ratio arg — maximal relative length of the front softclip (only relevant during output). [Default: 0.2]

Further explanation, bestie, because this one confuses people:

HiLive uses an approach that requires one exact match of a k-mer at the beginning of an alignment. That can leave unaligned regions at the start of the read, and we report those as 'softclips'. With this parameter you get to control the maximal length of that region. 🫶

---

🔥 ALIGNMENT OPTIONS 🔥

• -i, --index arg — path to the HiLive index. Please use the executable 'hilive-build' to create a new HiLive index (it's delivered with this program). The index consists of several files with the same prefix — so include that file prefix when you specify the index location. Don't forget the prefix, I'm begging 🙈
• -m, --align-mode arg — alignment mode to balance speed and accuracy: [very-fast|fast|balanced|accurate|very-accurate]. Picking a mode automatically sets other parameters. But — individually configured parameters are prioritized over the settings made by the alignment mode. [Default: balanced]
• --anchor-length arg — length of the alignment anchor (or initial seed). [Default: set by the selected alignment mode]
• --error-interval arg — the interval to tolerate more errors during alignment (low = accurate; great = fast). [Default: 'anchor-length'/2]
• --seeding-interval arg — the interval to create new seeds (low = accurate; great = fast). [Default: 'anchor-length'/2]
• --max-softclip-length arg — the maximum length of a front softclip when creating new seeds. In contrast to --max-softclip-ratio, this parameter may have effects on runtime and mapping accuracy. [Default: 'readlength/2]
• --barcode-errors arg — the number of errors tolerated for the barcode segments. You can give a single value that applies to all barcode segments, or set the value for each segment individually. [Default: 1]

Example:

--barcode-errors 2      [2 errors for all barcode segments]

--barcode-errors 2,1    [2 errors for the first, 1 error for the second segment]

• --align-undetermined-barcodes — align all barcodes. Reads with a barcode that doesn't match one of the barcodes specified with '--barcodes' will be reported as undetermined. [Default: false]
• --min-basecall-quality arg — minimum basecall quality for a nucleotide to be considered a match. [Default: 1 (everything but N-calls)]
• --keep-invalid-sequences — keep sequences of invalid reads, i.e. reads with an unconsidered barcode or reads filtered by the sequencer. This option must be activated to report unmapped reads. [Default: false]

---

⭐ SCORING OPTIONS ⭐

• -s, --min-as arg — minimum alignment score. [Default: set automatically based on the alignment mode and match/mismatch scores]
• --match-score arg — score for a match. [Default: 0]
• --mismatch-penalty arg — penalty for a mismatch. [Default: 6]
• --insertion-opening-penalty arg — penalty for insertion opening. [Default: 5]
• --insertion-extension-penalty arg — penalty for insertion extension. [Default: 3]
• --deletion-opening-penalty arg — penalty for deletion opening. [Default: 5]
• --deletion-extension-penalty arg — penalty for deletion extension. [Default: 3]
• --max-gap-length arg — maximal permitted consecutive gap length. ⚠️ Increasing this parameter may lead to highly increased runtime! [Default: 3]
• --softclip-opening-penalty arg — penalty for softclip opening (only relevant during output). [Default: 'mismatch-penalty']
• --softclip-extension-penalty arg — penalty for softclip extension (only relevant during output). [Default: 'mismatch-penalty'/'anchor-length']

---

🧚 TECHNICAL OPTIONS 🧚

• --temp-dir arg — temporary directory to store the alignment files and hilive_config.ini. [Default: ./temp]
• -k, --keep-files arg — keep intermediate alignment files for these cycles. The last cycle is always kept. [Default: keep files of output cycles]

Further explanations, because this is a whole thing:

HiLive comes with a separated executable 'hilive-out'. You can use that executable to produce alignment files in SAM or BAM format from existing temporary files. So basically: output can only be created for cycles where keeping the temporary alignment files is activated. And temporary alignment files are also needed if an interrupted run gets continued with the '--continue' parameter. So like... don't delete your temp files, bestie 😭

• -K, --keep-all-files — keep all intermediate alignment files. Heads up: this option may lead to huge disk space requirements. [Default: false]
• --block-size arg — block size for the alignment input/output stream, in Bytes. Append 'K' or 'M' to specify Kilobytes or Megabytes respectively. [Default: 64M]

Example:

--block-size 1024    [1024 bytes]
--block-size 64K     [64 Kilobytes]
--block-size 64M     [64 Megabytes]

• --compression arg — compression of temporary alignment files. [Default: LZ4]
  • 0: no compression.
  • 1: Deflate (smaller).
  • 2: LZ4 (faster).
• -n, --num-threads arg — number of threads to spawn (including output threads). [Default: 1]
• -N, --num-out-threads 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]

---

🌈 EXAMPLE 🌈

hilive --bcl-dir ./BaseCalls --index ./reference/hg19 --reads 101R

✨ AUTHOR ✨

okay bestie, credits time, because we always give flowers where flowers are due 💐

This manpage was written by Andreas Tille for the Debian distribution — and here's the slay part: it can be used for any other usage of the program too. no gatekeeping, no weird license drama, just a manpage out here being freely usable for literally anything else you wanna point it at 🫶

---

and that's a wrap on the whole page, bestie 🎀 you just made it through hilive 2.0a, dated October 2019, living in the HILIVE(1) spot of the manual. go read your docs, run your commands, and be the main character of your own terminal ✨💅👑