Command reference

This is the documentation for the individual commands. The help documented here can be invoked also at the command prompt with command -h, for example to get the help for ylim:

ylim -h

Parameters in square brackets are optional and the default argument is indicated by the = sign. The syntax … indicate that the argument can be repeated multiple times. For example:

ylim min max [track_regex = .*]...

Means that ylim takes two mandatory arguments, min and max. The optional argument, track_regex, defaults to .* and can be repated multiple times.

Find

find

find [-all] [-c] [-F] regex [track]

Find the first record in track containing regex. The search for regex starts from the end of the current window (so the current window is not searched) and moves forward on the current chromosome. At the end of the current chromosome move to the next chromosomes and then restart at the start of the initial one. The search stops at the first match found. track can be omitted if there is only one track loaded otherwise all the tracks matching the track pattern will be searched until a valid match is found.

  • -all: Return the region containing all the regex matches.

  • -c Match in CASE SENSITIVE mode. Default is case insensitive (changed in v1.12).

  • -F: Interpret regex as a fixed, literal string instead of as a regex.

Examples:

find -all ACTB genes.gtf -> Find all the matches of ACTB. Case ignored
find -c 'ACTB gene'      -> Find the first match of 'ACTB gene'. Case sensitive

Use single quotes to define patterns containing spaces.

seqRegex

seqRegex [-iupac] [-c] [regex]

Find regex in reference sequence and show matches as an additional track. Options:

  • regex Regex to search. If missing the seq regex track is removed.

  • -iupac Enable the interpretation of the IUPAC ambiguity code. NB: This option simply converts IUPAC chracters to the corresponding regex.

  • -c Enable case-sensitive matching. Default is to ignore case.

Examples:

seqRegex ACTG        -> Case insensitive, actg matched
seqRegex -c ACTG     -> Case sensitive, will not match actg
seqRegex -iupac ARYG -> Interpret (converts) R as [AG] and Y as [CT]
seqRegex             -> Disable regex matching track

To save matches to file, see the print command. This command is ignored if the reference fasta sequence is missing.

See also: search for searching an aligning patterns with mismatches.

bookmark

bookmark [-d] [-n name] [-print] [> file] [chrom:from-to]

Creates a track to save positions of interest. Without arguments, add the current position to the bookmark track. Options:

  • chrom:from-to Bookmark this region. If chrom is omitted, use the current chromosome.

  • -d Remove the bookmark at coordinates [chrom:from-to].

  • -n name Use name for this new bookmark.

  • -print prints to screen the list of current bookmarks.

  • > file saves the bookmark track to file.

Examples:

bookmark              -> Add the current window to bookmarks.
bookmark 100          -> Bookmark position 100 on current chrom
bookmark 100-110      -> Bookmark position 100-110 on current chrom
bookmark chr1:100     -> Bookmark position chr1:100
bookmark -d chr1:100  -> Delete bookmark at chr1:100
bookmark > books.txt  -> Save to file books.txt
bookmark -print       -> Show table of bookmarks

Display

grep

grep [-i = .*] [-e = ''] [-c] [-F] [-v] [track_regex = .*]...

Similar to grep command, filter for features including or excluding patterns. Options:

  • -i regex Show features matching this regex.

  • -e regex Exclude features matching this regex.

  • -c Match in CASE SENSITIVE mode. Default is case insensitive (changed in v1.12).

  • -F Interpret regex in -i and -e as a fixed, literal string instead of as a regex.

  • -v Invert selection: apply changes to the tracks not selected by list of track_regex

  • track_regex Apply to tracks matched by track_regex.

NOTES

  • Use single quotes to delimit patterns containing spaces e.g. -i 'ACTB gene'

Regex -i and -e are applied to the raw lines as read from source file and it is applied only to annotation tracks (GFF, BED, VCF, etc). For example:

grep -i RNA -e mRNA gtf gff

Will show the rows containing ‘RNA’ but will hide those containing ‘mRNA’, applies to tracks whose name matches ‘gtf’ or ‘gff’. With no arguments reset to default: grep -i .* -e ^$ .* which means show everything, hide nothing, apply to all tracks.

awk

awk [-off ...] [-F sep_re] [-v VAR=var] [-V] '<script>' [track_regex = .*]...

Advanced feature filtering using awk syntax. awk offers finer control then grep to filter records in tabular format.

Awk is column oriented. Awk splits each line into a list using a given regular expression as delimiter (default delimiter is the TAB character). To access an item, i.e. a column, use the syntax $n where n is the position of the item in the list, e.g. $3 will access the third field (i.e. 3rd column). The variable $0 holds the entire line as single string.

Awk understands numbers and mathematical operators. With awk you can filter records by numeric values in one or more fields since numbers are handled as such. You can also perform arithmetic operations and filter on the results.

OPTIONS

  • -off track_re ... Turn off awk filtering for tracks captured by the list of regexes.

  • -F <sep_re> Use regular expression <sep_re> as column separator. Default is ‘t’ (tab). To separate on white space use e.g. ‘b’ (backspace) or ‘s’ (any white space). Do not use ‘ ‘.

  • -v VAR=var Pass to awk script the variable VAR with value var. Can be repeated.

  • script The awk script to be executed. Must wrapped in single quotes.

  • -V Invert selection: apply changes to the tracks not selected by list of track_regex

ADDITIONAL FEATURES

Function get(...) can indistinctly be applied to GTF, GFF, SAM records and to INFO and FORMAT fields in VCF files. Double quoting around <tag> is optional.

  • get(tag) on GTF

Return the value of tag attribute.

  • get(tag, [value_idx]) on GFF

Return the value of tag attribute. If the attribute contains multiple values return the value at index value_idx (1-based). If value_idx is missing (as default), return the entire value as it is.

  • get(tag) on SAM

Return the value of the given sam tag.

  • get(tag, [value_index]) on VCF

Return the value of the given INFO tag. If the tag contains multiple values, optionally return only the value at index value_index. If necessary, prepend ‘INFO/’ to tag to disambiguate it from FORMAT tags or if the header does not contain this tag. If the tag is of type ‘Flag’, return 1 if present, 0 otherwise.

  • get(tag, [sample_idx], [value_idx]) on VCF

Return the value of the FORMAT tag for sample index sample_idx (default to 1, first sample). If the tag contains multiple values, optionally return the value at index value_idx. If necessary, prepend ‘FMT/’ to tag to disambiguate it from INFO tags or if the header does not contain this tag. If the tag is of type ‘Flag’, return 1 if present, 0 otherwise.

  • getAlnEnd() on SAM

Returns the position of the alignment end. For example, select reads ending after position 1000`here <http://jonasjacek.github.io/colours/>`_

Examples:

setConfig metal
setConfig /path/to/mytheme.conf
   setConfig max_reads_in_stack 20000 <- Reset this param only

Parameters and current settings:

background                         231     # Background colour
foreground                         0       # Foreground colour
seq_a                              12      # Colour for nucleotide A
seq_c                              9       # Colour for nucleotide C
seq_g                              2       # Colour for nucleotide G
seq_t                              11      # Colour for nucleotide T
seq_other                          0       # Colour for any other nucleotide
soft_clip_colour                   false   # Colour for soft-clipped characters. 'false' use the same (fainted) colour as for the for unclipped
shade_low_mapq                     249     # Colour for shading reads with low MAPQ
low_mapq                           5       # Shade reads below this MAPQ
methylated_foreground              231     # Foreground colour for methylated C
unmethylated_foreground            231     # Foreground colour for unmethylated C
methylated_background              9       # Background colour for methylated C
unmethylated_background            12      # Background colour for unmethylated C
title_colour                       0       # Default Colour for titles
feature_background_positive_strand 147     # Colour for features on forward strand
feature_background_negative_strand 224     # Colour for features on reverse strand
feature_background_no_strand       249     # Colour for features without strand information
footer                             12      # Colour for footer line
chrom_ideogram                     0       # Colour for chromosome ideogram
ruler                              0       # Colour for ruler
max_reads_in_stack                 2000    # Max number of reads to accumulate when showing read tracks
shade_baseq                        13      # Shade read base when quality is below this threshold
shade_structural_variant           33      # Background colour for reads suggesting structural variation or 'false' for no shading
highlight_mid_char                 true    # Highlight mid-character in read tracks?
nucs_as_letters                    true    # Show read nucleotides as letters at single base resolution?
stop_codon                         9       # Colour for stop codon
start_codon                        2       # Colour for start codon
codon                              249     # Colour for codons other than start and stop
python                             python3 # Python executable. Use full path if there is no python on PATH

explainSamFlag

explainSamFlag INT [INT ...]

Explain the list of bitwise SAM flags. Decode one or more sam flags to human readable form and print them as a table. Similar to https://broadinstitute.github.io/picard/explain-flags.html

show

show <arg>

Show or set features to display. The argument arg takes the following choices:

  • genome: Show chromosomes sorted by size

    • -n int: Show up to int number of chromosomes or -1 for no limit (default 50)

  • trackInfo: Show information on tracks.

  • gruler: Toggle the display of the genomic coordinates as ruler.

  • pctRuler: Toggle the display of the column number of the terminal (useful for navigation within the current genomic window).

arg can be just a prefix of the argument name, e.g. show ge will be recognized as show genome.

recentlyOpened

recentlyOpened [-grep = .*]

List recently opened files. Files are listed with their absolute path.

  • -n INT Return only the last INT files.

  • -grep <pattern> Filter for files (strings) matching pattern. Use single quotes to define patterns containing spaces, e.g. -grep 'goto chr1'.

open

open [-c int] [-s int] [-e int] [-score int] [-z] [-sep auto] [-n auto] [-m #] [files | URLs | indexes]...

Add tracks from local or remote files. The list of files can be a list of file names or URLs. For local files, glob characters (wildcard) are expanded as in Bash (but note that currently globs in directory names are not expanded.)

Alternatively, the files to open can be given as numeric indexes of recently opened files (see command recentlyOpened). The last opened file has index 1, the second last 2, etc.

In addition to standard genomic data files (bam, vcf, gff, etc), it is possible to load generic tabular files

These options are relevant only for generic tabular files. Indexes are 1-based (i.e. first column has index 1):

  • -c int Column index of chromosome

  • -s int Column index of start position

  • -e int Column index of end position (if unset, assume features are 1 bp long)

  • -score int Column index of score to plot (if unset, assume features are intervals, not quantitative)

  • -z Start position is zero-based (like bed files)

  • -sep char Column character separator. Auto-detected if unset

  • -n int Skip these many lines before reading data. Auto-detected if unset.

  • -m char Comment characters: Skip lines starting with this character

Examples:

open peaks.bed genes.*.gtf        <- Note use of wildecard
open http://remote/host/peaks.bed <- From URL
open 1 2 3                        <- The three most recent files

reload

reload [track_regex = .*]...

Reload track files. reload is useful when an input track file is edited by external actions and you want to reload it in the current session. This is easier than dropping and re-opening tracks with dropTracks … && open … since track formattings and filters are preserved.

A track is dropped if it cannot be reloaded, for example when the sequence dictionary has become incompatible with the current one.

Examples:

reload       <- reload all tracks
reload .bam  <- reload files matching '.bam'

dropTracks

dropTracks [-t] [-v] track_regex [track_regex]...

Drop tracks matching any of the listed regexes. * -t (test) flag only shows which tracks would be removed but do not remove them.

  • -v Invert selection: apply changes to the tracks not selected by list of track_regex

Examples:

dropTracks bam

orderTracks

orderTracks [track_regex]...

Reorder tracks according to the list of regexes or sort by name. Not all the tracks need to be listed, the missing ones follow the listed ones in unchanged order. Without arguments sort track by tag name. For example, given the track list: [hela.bam#1, hela.bed#2, hek.bam#3, hek.bed#4]:

orderTracks #2 #1   -> [hela.bed#2, hela.bam#1, hek.bam#3, hek.bed#4]
orderTracks bam bed -> [hela.bam#1, hek.bam#3, hela.bed#2, hek.bed#4]
orderTracks . bam  -> 'bam' tracks go last
orderTracks         -> name sort [hela.bam#1, hela.bed#2, hek.bam#3, hek.bed#4]

posHistory

posHistory [-n INT=10]

List the visited positions. Recorded positions include the current and the previous sessions of ASCIIGenome.

-n INT Show only the last INT positions. Show all if <= 0.

history

history [-n INT] [-grep = .*]

List the executed commands. Commands executed in previous sessions of ASCIIGenome are in /.asciigenome_history

  • -n INT Return only the last INT commands.

  • -grep <pattern> Filter for commands (strings) matching pattern. Use single quotes to define patterns containing spaces, e.g. -grep 'goto chr1'

save

save [>>] [filename = chrom_start_end.txt']

Save screenshot to file as text or pdf format. The default file name is generated from the current coordinates and the default format is plain text. If the file name has extension ‘.pdf’ then save as pdf. To append to an existing file use >>. The string %r in the file name is replaced with the current coordinates. Examples:

save mygene.txt    -> Save to mygene.txt as text
save >> mygene.txt -> Append to mygene.txt
save               -> Save to chrom_start-end.txt as text
save .pdf          -> Save to chrom_start-end.pdf as pdf
save mygene.%r.pdf -> Save to mygene.chr1_100-200.pdf as pdf

sys

sys [-L] command

Execute a system command. By default the given command is executed as a string passed to Bash as bash -c string. With the -L option the command is executed literally as it is. Note that with the -L option globs are not expanded by Java. Examples:

sys pwd                          <- Print working directory name
sys ls *.bam                     <- List files ending in .bam
sys bcftools view -h vars.vcf.gz <- Print vcf header

q

q

Quit

h

h

help, h, -h, and ? show this help. For help on individual commands use one of:

command -h
?command
help command

e.g. ylim -h

Session

sessionOpen

sessionOpen [-f session.yml] [sessionName|index]

Open a previous session Since a session file can hold multiple sessions, choose the session to open by name or index. Without arguments, reproduce the settings from the last time ASCIIGenome exited regardless of whether those settings were savedin a session.

  • -f Read sessions from this yaml file. Default: /.asciigenome/session.yaml

  • sessioName|index Session name or index to open. The index refers to sessions in reverse chronological order (1: last opened, 2: second last, etc). Default: 1

Examples:

sessionOpen // Reproduce the settings from last exit of ASCIIGenome
sessionOpen 1 // Last session saved in default session file
sessionOpen -f ss.yml myTracks // Open `myTracks` from ss.yml

sessionSave

sessionSave [-f session.yml] [sessionName]

Save current session Note a session file can hold multiple sessions. I.e., there’s no need to save each session to a separate file. Execute sessionList to get the current session file and name.

  • -f Save session to this file. Default: /.asciigenome/session.yaml

  • sessioName If given, save session with this name (equivalent to a typical “save as” command). Otherwise save to the current session (equivalent to the usual Ctrl+S shortcut)

Examples:

sessionSave // Save to current session, if any has been opened
sessionSave mySession // Save to default session file
sessionSave -f ss.yml mySession // Save to ss.yml

sessionList

sessionList [-f session.yml]

List sessions in file and report current session file and name. Sessions are listed in reverse chronological order (i.e., most recent last)

  • -f List sessions in this file. Default: /.asciigenome/session.yaml

  • -n List up to this many sessions. Default 10

sessionDelete

sessionDelete [-f session.yml] <sessionName>

Delete session by name. * -f List sessions in this file. Default: /.asciigenome/session.yaml

  • sessionName Session name to delete