tools/bioawk/README.md

   1 ###Introduction
   2
   3 Bioawk is an extension to [Brian Kernighan's awk][1], adding the support of
   4 several common biological data formats, including optionally gzip'ed BED, GFF,
   5 SAM, VCF, FASTA/Q and TAB-delimited formats with column names. It also adds a
   6 few built-in functions and an command line option to use TAB as the
   7 input/output delimiter. When the new functionality is not used, bioawk is
   8 intended to behave exactly the same as the original BWK awk.
   9
  10 ###New functionality
  11
  12 #####Command line option `-t`
  13
  14 Using this option is equivalent to
  15
  16     bioawk -F'\t' -v OFS="\t"
  17
  18 #####Command line option `-c arg`
  19
  20 This option specifies the input format. When this option is in use, bioawk will
  21 seamlessly add variables that name the fields, based on either the format or
  22 the first line of the input, depending *arg*. This option also enables bioawk
  23 to read gzip'd files. The argument *arg* may take the following values:
  24
  25 * `help`. List the supported formats and the naming variables.
  26
  27 * `hdr` or `header`. Name each column based on the first line in the input.
  28   Special characters in the first are converted to underscore. For example:
  29
  30         grep -v ^## in.vcf | bioawk -tc hdr '{print $_CHROM,$POS}'
  31
  32   prints the `CHROM` and `POS` columns of the input VCF file.
  33
  34 * `sam`, `vcf`, `bed` and `gff`. SAM, VCF, BED and GFF formats.
  35
  36 * `fastx`. This option regards a FASTA or FASTQ as a TAB delimited file with
  37   four columns: sequence name, sequence, quality and FASTA/Q comment, such that
  38   various fields can be retrieved with column names. See also example 4 in the
  39   following.
  40
  41 #####New built-in functions
  42
  43 See `awk.1`.
  44
  45 ###Examples
  46
  47 1. List the supported formats:
  48
  49         bioawk -c help
  50
  51 2. Extract unmapped reads without header:
  52
  53         bioawk -c sam 'and($flag,4)' aln.sam.gz
  54
  55 3. Extract mapped reads with header:
  56
  57         bioawk -Hc sam '!and($flag,4)'
  58
  59 4. Reverse complement FASTA:
  60
  61         bioawk -c fastx '{print ">"$name;print revcomp($seq)}' seq.fa.gz
  62
  63 5. Create FASTA from SAM (uses revcomp if FLAG & 16)
  64
  65         samtools view aln.bam | \
  66             bioawk -c sam '{s=$seq; if(and($flag, 16)) {s=revcomp($seq)} print ">"$qname"\n"s}'
  67
  68 6. Print the genotypes of sample `foo` and `bar` from a VCF:
  69
  70         grep -v ^## in.vcf | bioawk -tc hdr '{print $foo,$bar}'
  71
  72
  73 ###Potential limitations
  74
  75 1. When option `-c` is in use, bioawk replaces the line reading module of awk.
  76    The new line reading function parses FASTA and FASTQ files and seamlessly
  77    reads gzip'ed files. However, the new code does not fully mimic the original
  78    code. It may fail in corner cases (though this has not happened yet). Thus
  79    when `-c` is not specified, awk falls back to the original line reading code
  80    and does not support gzip'ed input.
  81
  82 2. When `-c` is in use, several strings allocated in the new line reading
  83    module are not freed in the end. These will be reported by valgrind as
  84    "still reachable". To some extent, these are not memory leaks.
  85
  86
  87 [1]: http://www.cs.princeton.edu/~bwk/btl.mirror/