Added documentaiton for CRAM usage

Author: IanSudbery

tests/README

@@ -1,3 +1,7 @@
 Command to make test files for umi_tools extract --either-read testing:
 
 cd tests; paste <(zcat indrop.fastq.1.gz) <(zcat indrop.fastq.2.gz)|paste - - - - - - - -| awk -F "\t" 'BEGIN{OFS="\n"; srand(0)} {if(rand()>0.5) {print $1,$3,$5,$7 > "delete_me"; print $2,$4,$6,$8 > "delete_me2"} else {print $2,$4,$6,$8 > "delete_me"; print $1,$3,$5,$7 > "delete_me2"}}'; gzip delete_me2 -c > indrop.fastq.2_either_read.gz; gzip delete_me -c > indrop.fastq.1_either_read.gz; rm delete_me delete_me2
+
+
+Note that CRAM outputs are tested at the string decoded level using pysam, and not at the binary level. This avoids differences due to differenly installed compression libraries. 
+ 

umi_tools/Documentation.py

@@ -420,6 +420,55 @@
 Input/Output Options
 ---------------------
 
+The following options deal with input and output format, and are useful for
+outputting CRAM format. In general UMI-tools will attempt to guess the input
+and output formats from the file names, but thing can be over-written using
+the ``out-format`` and ``input-format`` options. The location of  CRAM 
+reference files will be taken from the either the an input CRAM file 
+(if present) or from the ``--reference-filename`` option. Otherwise
+the reference will be embedded in the file. 
+
+"""""""""""""""""""""""""    
+``--in-format=IN_FORMAT``
+"""""""""""""""""""""""""
+      File format of the input file. Format is usually
+      implied from the extension of the filename, but maybe
+      overridden with this option. Default=bam
+
+""""""""""""""""""""""""""" 
+``--out-format=OUT_FORMAT``
+"""""""""""""""""""""""""""
+      File format of the input file. Format is usually
+      implied from the extension of the filename, but maybe
+      overridden with this option. Default=bam
+
+""""""""""""""""""""""""""""""""" 
+``--input-options=INPUT_OPTIONS``
+"""""""""""""""""""""""""""""""""
+
+      Format string provided to htslib for reading. Mostly
+      useful for CRAM formatted files. See samtools
+      documentation
+
+"""""""""""""""""""""""""""""""""""
+``--output-options=OUTPUT_OPTIONS``
+"""""""""""""""""""""""""""""""""""
+      Format string provided to htslib for writing. Mostly
+      useful for CRAM formatted files. See samtools
+      documentation
+
+""""""""""""""""""""""""""""""""""""""""""" 
+``--reference-filename=REFERENCE_FILENAME``
+"""""""""""""""""""""""""""""""""""""""""""
+      File path or URL to the genome reference to be used
+      when reading or writing CRAM files. Can be a path or
+      a URL. By default, when reading a CRAM file, the 
+      reference recorded in the input file will be used
+      unless this is specified. URL references cannot be read
+      from input files, however. When writing, specifying a
+      reference location is required unless specified in input.
+
+
 """""""""""""""""""""""
 ``--in-sam, --out-sam``
 """""""""""""""""""""""