.. _command_reference: .. This document is autogenerated by CommandList.reStructuredTextHelp(). Do not edit it here. Edit source code then run tests in CommandListTest.updateReStructuredFile() to recreate this file. 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. Navigation ---------- goto ++++ :code:`goto chrom[:from[-to]] | chrom [from [to]]` Go to region `chrom:from-to` or to `chrom:from` or to the start of `chrom`. The region may be separated by `:` and `-` or by spaces. The character ':' is a shortcut for `goto`. Examples:: goto chr8:1-1000 # Go to region 1-1000 on chr8 goto chr8 1 1000 # Use spaces instead goto chr8 1-1000 # Same as above goto chr8 1 - 1000 # Same as above goto chr8 1 1,000 # Comma in numbers is ok goto chr8:10 # Go to position 10 on chr8 goto chr8 # Go to start of chr8 goto chr8 10 30 50 # Go to chr8:10-50 :chr8 # Colon ':' shortcut INT +++ :code:`INT from [c | to]` Go to position `from` or to region `from to` on current chromosome. If a list of integers is given, the first and last are taken as *from* and *to*. This is handy to copy and paste intervals from the ruler above the prompt. * :code:`c` set the position of *from* at the center of the screen. * :code:`to` set the new window in the region delimited by *from* and *to*. Examples:: 10 -> Will jump to position 10 10 1000 -> Go to region 10-1000 10 250 500 750 1000 -> Same as above again 750 c -> Put the position 750 right in the middle 750c -> Same as '750 c' space is optional PERCENT +++++++ :code:`PERCENT from [c | to]` Zoom into the current window delimited by given PERCENT of screen. PERCENT is a number in the range 0-1 mapping to the given percent of the current genomic window. Similar to the `:code:INT` command, one number moves the genomic window to the position located at PERCENT and two numbers will zoom into the region PERCENT-PERCENT. This command is useful to quickly focus an a feature of interest, such as a ChIP-Seq peak or a variant. * :code:`c` set the position of *from* at the center of the screen. * :code:`to` set the new window in the region delimited by *from* and *to*. Examples:: 0.25 -> Jump to position at 25% of current screen. .25 -> Same as above. .25 .75 -> Zoom into the interval between 25-75% of current screen. .25 c -> Put the position at 25% of current screen right in the middle. .25c -> Same as '.25 c' (space is optional). plus + ++++++ :code:`+ INT [k|m]` Move forward by `INT` bases. Suffix K/M recognized. Suffixes k (kilo) and M (mega) are expanded to x1000 and x1,000,000. Examples:: +2m +10k +10.5k minus - +++++++ :code:`- INT [k|m]` Move backwards by INT bases. Suffix K/M recognized. Suffixes k (kilo) and M (mega) are expanded to x1000 and x1,000,000. Examples:: -100 -10k -10.5m f - forward +++++++++++ :code:`f [NUM=0.1]` Move forward NUM times the size of the current window, 1/10 by default. b - backward ++++++++++++ :code:`b [NUM=0.1]` Move backward NUM times the size of the current window, 1/10 by default ff ++ :code:`ff` Move forward by 1/2 of a window. A shortcut for `f 0.5` bb ++ :code:`bb` Move backward by 1/2 of a window. A shortcut for `b 0.5` ] + :code:`] INT=1` Move forward by INT screen columns Same as **[** but moves forward. See **[** for details [ + :code:`[ INT=1` Move backwards by INT screen columns. The **[** character can be repeated and each **[** will move by one column. Examples:: [ -> Move one screen column [[[ -> Move three columns [ 3 -> Same as above [3 -> Same as above (space is optional) zi ++ :code:`zi [INT = 1]` Zoom in INT times. Each zoom halves the window size. To zoom quickly use INT= 5 or 10 e.g. `zi 10` zo ++ :code:`zo [INT = 1]` Zoom out INT times. Each zoom doubles the window size. To zoom quickly use INT= 5 or 10 e.g. `zo 10` extend ++++++ :code:`extend [mid|window] [INT|FLOAT left] [INT|FLOAT right]` Extend the current window left and/or right. If left or right are integers, extend by this many bases. If the are floats, extend by this percent of the current window size If only one number is given extend both left and right. Negative numbers will shrink instead of extend the window. * :code:`window` (default): Extend the current window left and right * :code:`mid` The new window is given by the midpoint of the current window plus and left and right. Examples:: extend 10 // Extend left and right by 10 bases extend 10 20 // Extend left 10 and right by 20 bases extend 0.1 // Extend left and right by 10% of the current window size extend -0.1 // Shrink by 10% of the current window size extend mid 1000 // Extend the midpoint of the current window by 1kb l - left ++++++++ :code:`l` Go to the Left half of the current window. Alternate the left and right command to quickly focus on a point of interest. r - right +++++++++ :code:`r` Go to the Right half of the current window. Alternate the left and right command to quickly focus on a point of interest. p + :code:`p` Go to the previous visited position. Similar to the back and forward arrows of an Internet browser. n + :code:`n` Go to the next visited position. Similar to the back and forward arrows of an Internet browser. next ++++ :code:`next [-back] [-start] [-c] [-zo INT=5] [track]` Move to the next feature not overlapping the current coordinates. By default `next` centers the window on the next feature and zooms out. * :code:`-back` Search backwards. I.e. move to next feature on the left of the current position. * :code:`-start` Set the window right at the start of the feature, without centering and zooming out. * :code:`-c` Set the window so that the start of the feature is right in the middle of the window. Useful to browse small features such as SNV and indels. * :code:`-zo INT` Zoom out INT times after having found the next feature. Ignored if the `-start` flag is set. If <= 0 the window spans exactly the feature coordinates. Default 5. * :code:`track` Track to search for next feature. Default to the first annotation track found. `next` starts searching immediately after the current window and loops thourgh each chromosome until a feature is found. nextChrom +++++++++ :code:`nextChrom [-m] [-M] [regex]` Go to the start of the next chromosome or contig. * :code:`-min`: Go to next chrom having this minimum size. * :code:`-max`: Go to next chrom having this maximum size. * :code:`-s`: Sort order to decide what next is: :code:`s`: size ascending: go to next chrom larger than current (default) :code:`S`: size descending: go to next chrom smaller then current :code:`u`: unsorted, i.e. next in dictionary * :code:`regex`: Go to next chrom matching regex [.*]. Parameters using contig size are silently ignored. Find ---- find ++++ :code:`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. * :code:`-all`: Return the region containing **all** the regex matches. * :code:`-c` Match in CASE SENSITIVE mode. Default is case insensitive (changed in v1.12). * :code:`-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 ++++++++ :code:`seqRegex [-iupac] [-c] [regex]` Find regex in reference sequence and show matches as an additional track. Options: * :code:`regex` Regex to search. If missing the seq regex track is removed. * :code:`-iupac` Enable the interpretation of the IUPAC ambiguity code. NB: This option simply converts IUPAC chracters to the corresponding regex. * :code:`-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: :code:`search` for searching an aligning patterns with mismatches. search ++++++ :code:`search [-p|-f|-l pattern] [-k int]` Search sequence for *pattern* allowing up to *k* mismatches. `search` is useful for locating short sequences such as PCR primers, restriction sites, crispr targets. This command runs sassy under the hood. :code:`search` will try first to use :code:`sassy` on the user's search PATH and, if not found, use the sassy executable that ships with ASCIIGenome. Options: * :code:`-p` Comma separated patterns to search for (cannot be used with -f) * :code:`-l` Search each line of the file (cannot be used with -p) * :code:`-f` Search each record in the FASTA file (cannot be used with -p) * :code:`-k` Report matches up to (and including) this distance threshold [default = 1] * :code:`-a` The alphabet to use. DNA=ACTG, or default IUPAC=ACTG+NYR.... [default: iupac] [possible values: dna, iupac] * :code:`--overhang` Enable overhang alignment * :code:`--no-rc` Disable reverse complement search * :code:`--max-n-frac` Allow at most max_n_frac of N bases in the target sequence. Values must be in the range [0, 1]. A value of 0 will allow only hits where the target sequence contains no Ns. A value of 0.1-0.2 will allow for matches that include a small number of Ns [default: 0.2] * :code:`-j` Number of threads to use. All CPUs by default Examples:: search -p GCGGCCGC -k 1 -> NotI restriction site, 1 mismatch allowed search -p ACTG,AACC,GGCCTT -k 0 -> Search these patterns search -f patterns.fa -k 1 -> Get patterns from fasta file See also seqRegex for searching patterns as regex. bookmark ++++++++ :code:`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: * :code:`chrom:from-to` Bookmark this region. If chrom is omitted, use the current chromosome. * :code:`-d` Remove the bookmark at coordinates [chrom:from-to]. * :code:`-n name` Use name for this new bookmark. * :code:`-print` prints to screen the list of current bookmarks. * :code:`> 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 ++++ :code:`grep [-i = .*] [-e = ''] [-c] [-F] [-v] [track_regex = .*]...` Similar to grep command, filter for features including or excluding patterns. Options: * :code:`-i regex` Show features matching this regex. * :code:`-e regex` Exclude features matching this regex. * :code:`-c` Match in CASE SENSITIVE mode. Default is case insensitive (changed in v1.12). * :code:`-F` Interpret `regex` in `-i` and `-e` as a fixed, literal string instead of as a regex. * :code:`-v` Invert selection: apply changes to the tracks not selected by list of track_regex * :code:`track_regex` Apply to tracks matched by `track_regex`. *NOTES* * Use *single quotes* to delimit patterns containing spaces e.g. :code:`-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: :code:`grep -i .* -e ^$ .*` which means show everything, hide nothing, apply to all tracks. awk +++ :code:`awk [-off ...] [-F sep_re] [-v VAR=var] [-V] '