bio-sam-mutation 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 89bbe12a6c812fdc4726e74a758d3243575875ea
+  data.tar.gz: 651ffa24264f666bf86740d7f7043845e3eae5a7
+SHA512:
+  metadata.gz: 3f27e36ba12e338179e310964e5867c3fdaedb8f799e50b49d06f65fe545d79223dc7f37ef6b88770d61d18b31b79c4edd4db58b5d77919f28c6587787db1a7b
+  data.tar.gz: 0904d6a55dd48f26ba20cbc9e11c65d00d1720e37b61cf9d15fe2f0b81afdf1c38b796ec265fc690f02b77abe6a39a6148da131dac9a42ed87e29424938875b1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 2.2.0
+  - 2.1.0
+
+# - rbx-19mode
+#  - 1.8.7
+#  - jruby-18mode # JRuby in 1.8 mode
+#  - rbx-18mode
+
+# uncomment this line if your project needs to run something other than `rake`:
+# script: bundle exec rspec spec

data/Gemfile

@@ -0,0 +1,21 @@
+source "http://rubygems.org"
+
+  gem "bio", ">= 1.4.2"
+  # Using edge version due to a problem with ruby >2.1 in biogems version at time of writing
+  gem "bio-samtools", "~>2.3.4", git: "https://github.com/helios/bioruby-samtools.git", ref: "2e77274"
+  # JSON serialisation:
+  gem "oj", "~>2.14"
+  # At the time of writing, the released version 0.2.0 does not include the variation#vep_hgvs method
+  # so use this specific commit:
+  gem "bio-ensembl-rest", "0.2.0", git: "https://github.com/ALTree/bio-ensembl-rest.git", ref: "c934fa0"
+  gem "trollop"
+  gem "rake", "~>0.9"
+
+group :development do
+  gem "shoulda", ">= 0"
+  gem "rdoc", "~> 3.12"
+  gem "simplecov", ">= 0"
+  gem "jeweler", "~> 2.0"
+  gem "bundler"
+  gem "test-unit", "~> 3.0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2015 stveep
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# bio-sam-mutation
+
+[![Build Status](https://secure.travis-ci.org/stveep/bioruby-sam-mutation.png)](http://travis-ci.org/stveep/bioruby-sam-mutation)
+
+*	Methods for calling mutations from SAM alignments, including CIGAR and MD tag parsers.
+
+*	Annotates mutations in HGVS format: http://www.hgvs.org/mutnomen/recs.html.
+
+*	Incorporates Ensembl VEP lookup.
+
+## Installation
+
+```sh
+gem install bio-sam-mutation
+```
+
+## Usage
+
+```ruby
+require 'bio-sam-mutation'
+
+  # NB must be tab-delimited
+  insertion_and_deletion = Bio::DB::Alignment.new("I2M5K:00253:00406\t0\t5\t112839854\t70\t63M2I138M1D27M7S\t*\t0\t0\tCAGTGATCTTCCAGATAGCCCTGGACAAACCATGCCACCAAGCAGAAGTAAAACACCTCCACCATACCTCCTCAAACAGCTCAAACCAAGCGAGAAGTACCTAAAAATAAAGCACCTACTGCTGAAAAGAGAGAGAGTGGACCTAAGCAAGCTGCAGTAAATGCTGCAGTTCAGAGGGTCCAGGTTCTTCCAGATGCTGATACTTATTACATTTTGCCACGGAAAGTACTGCTGAGG\t@CDDDCCCCACACCCCCCCC?CCACCCC>A6;;;;7;;6;6;BC;;6;;;;;.;;>ADDA??;;;;;?CCACCCD>C??@CCCC>C@C;>?CCCC@C=::@:::::+:::/:CCC?>>>>CCCCDDD9CCCC@AB????=AB>??;?BB>@@@AA???CC<@@?????BB>??;;;B<BC;??8;6:A=@=@BBB;;;?<77//*08*088888*8=9=?B7;;4;??????????<\tPG:Z:novoalign\tAS:i:183\tUQ:i:183\tNM:i:3\tMD:Z:201^T27")
+
+  insertion_and_deletion.mutations
+  #=> [#<Bio::Mutation:0x007fa20b5b4fc8 @position=112839916, @type=:insertion, @reference=nil, @mutant="AT", @seqname="5">, #<Bio::Mutation:0x007fa20b5b4960 @position=112840055, @type=:deletion, @reference="T", @mutant=nil, @seqname="5">]
+
+  insertion_and_deletion.mutations.first.to_hgvs("g")
+  #=> "5:g.112839916_112839917insAT"
+
+  puts YAML.dump(insertion_and_deletion.mutations.first.vep("human","g").first["transcript_consequences"].keep_if{|c| c["transcript_id"] == "ENST00000257430"})
+  #---
+  # - variant_allele: AT
+  #   cdna_end: 4379
+  #   codons: cca/ccATa
+  #   protein_end: 1441
+  #   strand: 1
+  #   hgnc_id: HGNC:583
+  #   amino_acids: P/PX
+  #   gene_symbol: APC
+  #   cdna_start: 4378
+  #   transcript_id: ENST00000257430
+  #   cds_start: 4322
+  #   gene_id: ENSG00000134982
+  #   protein_start: 1441
+  #   biotype: protein_coding
+  #   gene_symbol_source: HGNC
+  #   cds_end: 4323
+  #   consequence_terms:
+  #   - frameshift_variant
+  #   impact: HIGH
+  # => nil
+
+# E.g. of full request return
+# http://rest.ensembl.org/documentation/info/vep_hgvs_get
+insertion_and_deletion.mutations(112839854).first.vep("human","g")
+# => [{"assembly_name"=>"GRCh38", "end"=>112839917, "seq_region_name"=>"5", "transcript_consequences"=>[{"gene_id"=>"ENSG00000134982", "distance"=>46, "variant_allele"=>"AT", "biotype"=>"nonsense_mediated_decay", "gene_symbol_source"=>"HGNC", "consequence_terms"=>["downstream_gene_variant"], "strand"=>1, "hgnc_id"=>"HGNC:583", "gene_symbol"=>"APC", "transcript_id"=>"ENST00000502371", "impact"=>"MODIFIER"}, {"variant_allele"=>"AT", "cdna_end"=>4380, "codons"=>"-/AT", "protein_end"=>1442, "strand"=>1, "hgnc_id"=>"HGNC:583", "amino_acids"=>"-/X", "gene_symbol"=>"APC", "cdna_start"=>4379, "transcript_id"=>"ENST00000257430", "cds_start"=>4323, "gene_id"=>"ENSG00000134982", "protein_start"=>1441, "biotype"=>"protein_coding", "gene_symbol_source"=>"HGNC", "cds_end"=>4324, "consequence_terms"=>["frameshift_variant"], "impact"=>"HIGH"}, {"gene_id"=>"ENSG00000134982", "distance"=>863, "variant_allele"=>"AT", "biotype"=>"protein_coding", "gene_symbol_source"=>"HGNC", "consequence_terms"=>["downstream_gene_variant"], "strand"=>1, "hgnc_id"=>"HGNC:583", "gene_symbol"=>"APC", "transcript_id"=>"ENST00000507379", "impact"=>"MODIFIER"}, {"variant_allele"=>"AT", "cdna_end"=>4481, "codons"=>"-/AT", "protein_end"=>1442, "strand"=>1, "hgnc_id"=>"HGNC:583", "amino_acids"=>"-/X", "gene_symbol"=>"APC", "cdna_start"=>4480, "transcript_id"=>"ENST00000508376", "cds_start"=>4323, "gene_id"=>"ENSG00000134982", "protein_start"=>1441, "biotype"=>"protein_coding", "gene_symbol_source"=>"HGNC", "cds_end"=>4324, "consequence_terms"=>["frameshift_variant"], "impact"=>"HIGH"}, {"gene_id"=>"ENSG00000134982", "distance"=>409, "variant_allele"=>"AT", "biotype"=>"protein_coding", "gene_symbol_source"=>"HGNC", "consequence_terms"=>["downstream_gene_variant"], "strand"=>1, "hgnc_id"=>"HGNC:583", "gene_symbol"=>"APC", "transcript_id"=>"ENST00000512211", "impact"=>"MODIFIER"}, {"gene_id"=>"ENSG00000134982", "variant_allele"=>"AT", "cdna_end"=>4569, "biotype"=>"nonsense_mediated_decay", "gene_symbol_source"=>"HGNC", "consequence_terms"=>["3_prime_UTR_variant", "NMD_transcript_variant"], "strand"=>1, "hgnc_id"=>"HGNC:583", "gene_symbol"=>"APC", "cdna_start"=>4568, "transcript_id"=>"ENST00000508624", "impact"=>"MODIFIER"}, {"gene_id"=>"ENSG00000258864", "variant_allele"=>"AT", "biotype"=>"nonsense_mediated_decay", "gene_symbol_source"=>"Clone_based_vega_gene", "consequence_terms"=>["intron_variant", "NMD_transcript_variant"], "strand"=>1, "gene_symbol"=>"CTC-554D6.1", "transcript_id"=>"ENST00000520401", "impact"=>"MODIFIER"}, {"gene_id"=>"ENSG00000134982", "distance"=>2195, "variant_allele"=>"AT", "biotype"=>"protein_coding", "gene_symbol_source"=>"HGNC", "consequence_terms"=>["downstream_gene_variant"], "strand"=>1, "hgnc_id"=>"HGNC:583", "gene_symbol"=>"APC", "transcript_id"=>"ENST00000504915", "impact"=>"MODIFIER"}], "strand"=>1, "id"=>"5:g.112839917_112839918insAT", "allele_string"=>"-/AT", "most_severe_consequence"=>"frameshift_variant", "start"=>112839918}]
+
+
+
+```
+
+The API doc is online. For more code examples see the test files in
+the source tree.
+
+## Project home page
+
+Information on the source tree, documentation, examples, issues and
+how to contribute, see
+
+  http://github.com/stveep/bioruby-sam-mutation
+
+The BioRuby community is on IRC server: irc.freenode.org, channel: #bioruby.
+
+## Cite
+
+If you use this software, please cite one of
+
+* [BioRuby: bioinformatics software for the Ruby programming language](http://dx.doi.org/10.1093/bioinformatics/btq475)
+* [Biogem: an effective tool-based approach for scaling up open source software development in bioinformatics](http://dx.doi.org/10.1093/bioinformatics/bts080)
+
+## Biogems.info
+
+This Biogem is published at (http://biogems.info/index.html#bio-sam)
+
+## Copyright
+
+Copyright (c) 2015 stveep. See LICENSE.txt for further details.

data/README.rdoc

@@ -0,0 +1,48 @@
+= bio-sam
+
+{<img
+src="https://secure.travis-ci.org/stveep/bioruby-sam.png"
+/>}[http://travis-ci.org/#!/stveep/bioruby-sam]
+
+Full description goes here
+
+Note: this software is under active development!
+
+== Installation
+
+        gem install bio-sam
+
+== Usage
+
+== Developers
+
+To use the library 
+
+        require 'bio-sam'
+
+The API doc is online. For more code examples see also the test files in
+the source tree.
+        
+== Project home page
+
+Information on the source tree, documentation, issues and how to contribute, see
+
+  http://github.com/stveep/bioruby-sam
+
+The BioRuby community is on IRC server: irc.freenode.org, channel: #bioruby.
+
+== Cite
+
+  If you use this software, please cite one of
+ 
+* [BioRuby: bioinformatics software for the Ruby programming language](http://dx.doi.org/10.1093/bioinformatics/btq475)
+* [Biogem: an effective tool-based approach for scaling up open source software development in bioinformatics](http://dx.doi.org/10.1093/bioinformatics/bts080)
+
+== Biogems.info
+
+This Biogem is published at http://biogems.info/index.html#bio-sam
+
+== Copyright
+
+Copyright (c) 2015 stveep. See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+  gem.name = "bio-sam-mutation"
+  gem.version = '0.4.1'
+  gem.homepage = "http://github.com/stveep/bioruby-sam-mutation"
+  gem.license = "MIT"
+  gem.summary = %Q{Parsing and mutation calling from SAM, CIGAR and MD:Z.}
+  gem.description = %Q{Simple classes for parsing SAM, CIGAR and MD:Z strings, including slices. Methods for calling mutations in HGVS format and looking up consequences using Ensembl VEP REST API. Developed for calling mutations at an expected position in an alignment - e.g. Amplicon sequencing of CRISPR-induced mutations.}
+  gem.email = "spettitt@gmail.com"
+  gem.authors = ["Stephen Pettitt"]
+  # dependencies defined in Gemfile
+  # gem.required_ruby_version = '>= 1.9.3'
+  gem.executables << "mutations"
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+desc "Code coverage detail"
+task :simplecov do
+  ENV['COVERAGE'] = "true"
+  Rake::Task['test'].execute
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "bio-sam-mutation #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/bin/mutations

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(__dir__, '..', 'lib')
+require 'trollop'
+require 'bio-sam-mutation'
+require 'pry'
+
+opts = Trollop::options do
+  opt :config, "Configuration file in YAML format. Defaults to ./config.yml. Run with --example-config for example.", type: :string, default: "config.yml"
+  opt :example_config, "Show example configuration file."
+  opt :output, "Output file, works with single product only. Better to define in config file.", type: :string, default: "output.sam"
+  opt :tag, "Tag an input SAM file (or piped stream of SAM data) with mutation calls"
+  opt :report, "Produce a report by amplicon for each file given, including read counts and annotation for each allele. (does not work on a stream)"
+  opt :mincov, "Minimum fraction of reads to report a mutant allele.", default: 0.01
+  opt :flag, "Minimum reads to flag a potential mutant (= no wild type).", default: 20
+end
+
+raise "Cannot use report and tag simultaneously." if opts[:report] && opts[:tag]
+
+# Trollop removes and parses the options, leaving either input files or the incoming stream:
+config = opts[:config]? YAML.load_file(opts[:config]) : {}
+if opts[:tag]
+if config.keys.include? :products
+  config[:products].each do |product_name, config_hash|
+    config[product_name] = MutationsCLI.set_defaults(config_hash)
+  end
+  config = MutationsCLI.construct_products(config)
+else
+  config[:single_product] = true
+  config[:output] ||= opt[:output]
+  config[:outfile] = File.open(config[:output],'w')
+end
+
+  ARGF.each do |input|
+    MutationsCLI.tag input, config
+  end
+end
+
+if opts[:report]
+  config[:products].each do |product_name, config_hash|
+    config_hash = MutationsCLI.set_defaults(config_hash)
+    lookups = {}
+    out = File.open(product_name+"-report.txt",'w')
+    mutants = []
+    ARGV.each do |file|
+      calls = Hash.new{|h,k| h[k] = MutantAllele.new}
+      File.open(file).readlines.each do |input|
+        next if input.match /^@/ # skip sam headers
+        sam = Bio::DB::Alignment.new(input)
+        # Check correct start in case of file with mixed amplicons
+        if config_hash[:start]
+          next unless sam.seq.match Regexp.new("^"+config_hash[:start])
+        end
+        # Must be have sufficient mapped length to call mutations in the given interval:
+        next if sam.query_unmapped
+        next if config_hash[:length] > Bio::Alignment::CIGAR.new(sam.cigar).reference_length - config_hash[:offset]
+        key = "w.t."
+        muts = MutationsCLI.call_mutations_given_product sam, config_hash
+        if muts
+          key = muts.to_hgvs
+          calls[key].mutations ||= muts
+        end
+        calls[key].seq ||= sam.query(config_hash[:offset], config_hash[:length])
+        calls[key].example ||= sam
+        calls[key].count += 1
+      end
+      total_reads = calls.map{|k,v| v.count}.reduce(:+)
+      out.puts file
+      out.puts "Total reads: #{total_reads}"
+      threshold = total_reads ? opts[:mincov] * total_reads : 0
+      calls.keep_if{|k, v| v.count > threshold}
+      mutants << file unless calls.keys.include? "w.t." || total_reads < opts[:flag]
+      calls = calls.sort_by{|k,v| v.count}.reverse.to_h
+      calls.each do |key, allele|
+        hgvs, vep = ""
+        formatted = nil
+        if allele.mutations
+          hgvs = allele.mutations.to_hgvs
+          if allele.mutations.size == 1 # VEP lookup doesn't work for compound mutations
+            begin
+              vep = allele.lookup
+            rescue RuntimeError
+              result = nil
+            end
+            # TODO: sort out the cacheing - does it actually work?
+            if vep
+              result = lookups[hgvs] ? lookups[hgvs] : VepHgvs.consequences_for_transcript(vep,config_hash[:transcript]).first
+              if result
+                result.each
+                formatted = [[result["CDS position"].to_s,result["Allele"]].join(" "),[result["Protein start"].to_s,result["Mutation"]].join(" "),result["Consequence"]].join("\t")
+              end
+            else
+              formatted = "No VEP result"
+            end
+            lookups[hgvs] ||= result
+          else
+            formatted = "Compound mutant"
+          end
+        end
+        formatted ||= "No mutation"
+        out.puts ([allele.seq, allele.count, key, formatted]).join("\t")
+      end
+      out.puts "\n===================================="
+    end
+    out.puts "Files with wild type below threshold:"
+    out.puts mutants.join("\n")
+  end
+
+end

data/bin/sam-mutation

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+require 'bio-sam-mutation'
+require 'thor'
+
+class SamMutationCLI < Thor
+  desc "tag [--config=config.yml]", "Tag a SAM file with HGVS annotations."
+  option :config
+  def tag (file_name)
+    File.open(file_name).each do |line|
+      next if line.match(/^@/)
+      sam = Bio::DB::Alignment.new(line)
+      if sam.mutations
+        new_tag = Bio::DB::Tag.new("YH:m:"+sam.mutations.to_hgvs)
+        puts sam.add_tag(new_tag)
+      end
+    end
+  end
+end
+
+SamMutationCLI.start ARGV

data/lib/bio-sam-mutation.rb

@@ -0,0 +1,26 @@
+# Please require your code below, respecting the naming conventions in the
+# bioruby directory tree.
+#
+# For example, say you have a plugin named bio-plugin, the only uncommented
+# line in this file would be
+#
+#   require 'bio/bio-plugin/plugin'
+#
+# In this file only require other files. Avoid other source code.
+
+require 'bio'
+require 'bio-ensembl-rest'
+require 'bio-samtools'
+require 'oj'
+require 'yaml'
+require 'bio-sam-mutation/bio/db/alignment'
+require 'bio-sam-mutation/bio/alignment/iterate_pairs'
+require 'bio-sam-mutation/bio/alignment/cigar'
+require 'bio-sam-mutation/bio/db/tag'
+require 'bio-sam-mutation/bio/db/tag/md'
+require 'bio-sam-mutation/bio/vephgvs'
+require 'bio-sam-mutation/bio/mutation'
+require 'bio-sam-mutation/bio/mutation_array'
+require 'bio-sam-mutation/bio/mutantallele'
+
+require 'bio-sam-mutation/mutationscli'

data/lib/bio-sam-mutation/bio/alignment/cigar.rb

@@ -0,0 +1,239 @@
+# Parse a CIGAR string
+# An example from Exonerate output. Ideally will also allow SAM file input to be used.
+#   1 : CGGCTATGGGGTCGTGGGTCCCGCGTTG-CTCTGGGGCTCGGCACCCTGGGGCGGCACGGCCGT :  63
+#       | | || | ||||||||||||||||||| |||||||||||||||||||||||||||||||||||
+#   1 : CAG-TA-GTGGTCGTGGGTCCCGCGTTGTCTCTGGGGCTCGGCACCCTGGGGCGGCACGGCCGT :  62
+#
+# ref: CAGTAGTGGTCGTGGGTCCCGCGTTGTCTCTGG...
+# cigar: SP-A12_D02_2015-01-16.seq 0 611 + SP-A3_ref 0 621 + 2514  M 3 I 1 M 2 I 1 M 21 D 1 M 306 D 9 M 89 I 1 M 126 D 1 M 24 D 1 M 8 I 1 M 6 D 1 M 5 D 1 M 17
+# I are not counted in reference
+# Regexp (from SAM specification) - but in exonerate the number comes first: ([0-9]+[MIDNSHP])+|\*
+
+class Bio::Alignment::CIGAR
+	include Bio::Alignment::IteratePairs
+
+	class << self
+		attr_accessor :reference_operations, :query_operations, :subexp, :regexps
+	end
+
+	self.regexps = {"exonerate" => /([MIDNSHP]{1})(\d+)/, "sam" => /(\d+)([MIDNSHP]{1})/}
+	# Type of elements that count towards the reference length:
+	# TODO: add full support for other elements S, H etc.
+	self.reference_operations = /[MD]/
+	self.query_operations = /[MIS]/
+	self.subexp = /([atgcAGCT]+)>([atgcAGTC]+)/
+	attr_accessor :pairs, :reference
+
+	def initialize(string,ref=nil,source="")
+		# strip out whitespace
+		string.gsub!(/\s+/,"")
+
+		# Auto-detect source if not supplied
+		if !(Bio::Alignment::CIGAR.regexps.keys.include? source)
+		  Bio::Alignment::CIGAR.regexps.each do |k,v|
+				# Look for match at start of string
+				if m = string.match(v)
+				  source = k if m.offset(0)[0] == 0
+			  end
+			end
+			if source == ""
+				raise "Source (e.g. 'exonerate', 'sam') not given and failed to auto-detect."
+			end
+    end
+		# Make an array of pairs of of cigar elements:
+		@pairs = string.scan(Bio::Alignment::CIGAR.regexps[source])
+		if source == "exonerate"
+			@pairs.map!{|pair| [pair[0].to_s, pair[1].to_i]}
+		else
+			# Provision to have number and identifier the other way round
+			@pairs.map!{|pair| [pair[1].to_s, pair[0].to_i]}
+		end
+
+		# Include reference sequence if provided
+		@reference = ref
+		# Check length of reference = sum(M+D)?
+		#warn "Reference length is not equal to that implied by CIGAR string: #{@reference.length}, #{self.reference_length}." unless @reference.length == self.reference_length
+
+	end
+
+	# Given an offset in reference sequence and length, return an object corresponding to that subregion of the alignment
+	def subalignment(offset,length,regexp=Bio::Alignment::CIGAR.reference_operations)
+		new_array = iterate_pairs(@pairs,offset,length,regexp)
+		# Return a CIGAR instance with just the new alignment
+		new_string = new_array.join(" ")
+		# -1 from offset as ruby string starts at zero
+		new_cigar = Bio::Alignment::CIGAR.new(new_string,@reference[offset-1,length])
+		new_cigar.remove_empty!
+	end
+	alias_method :slice, :subalignment
+
+	# Given a CIGAR-based [not reference - use subalignment] offset and length, return a subregion
+	def subcigar(offset,length)
+		# No regexp - includes everything
+		self.subalignment(offset,length,//)
+	end
+
+	def unmasked(offset,length)
+		self.subalignment(offset,length,/[MDI]/)
+	end
+
+	def remove_small!(threshold=1)
+		# Deletions convert to matches, insertions just remove
+		deletions_to_matches(threshold)
+		remove_small_nonmatches(threshold)
+		self
+	end
+
+	def remove_empty!
+		self.pairs.keep_if{|pair| pair[1] != 0 }
+		self
+	end
+
+	def matched_length
+		count_type("M")
+	end
+
+	def deleted_length
+		count_type("D")
+	end
+
+	def inserted_length
+		count_type("I")
+	end
+
+	def masked_length
+		count_type(/[SH]/)
+	end
+
+	def reference_length
+		count_type(Bio::Alignment::CIGAR.reference_operations)
+	end
+
+	def query_length
+		count_type(Bio::Alignment::CIGAR.query_operations)
+	end
+
+	# Output a representation of the query: replace deleted portions with "-", flag insertions with "*" or sim. Optionally provide the sequence (or symbols to use) of insertions, in order of appearence.
+	# Should be able to accept an array
+	# TODO: Add support for substitution highlighting (e.g lowercasing)
+	def query(insertions=nil)
+		if (insertions && (insertions.is_a? String))
+			insertions = [insertions]
+		end
+		sequence = []
+		total = 0
+		@pairs.each do |pair|
+			if pair[0].match("M")
+				sequence << @reference[total..total+pair[1]-1].upcase
+				total += pair[1]
+			end
+			if pair[0].match("I")
+				if (insertions)
+					insertion = insertions.shift.to_s
+				else
+					insertion = '['+pair[1].to_s+']'
+				end
+				sequence << insertion
+			end
+			if pair[0].match("D")
+				pair[1].times{ sequence << "-" }
+				total += pair[1]
+			end
+		end
+		sequence.join("")
+	end
+
+	# Output hgnc variant format given reference position. Only deletions can be accurately annotated from the cigar string; insertions or wild type seqeunces return nil
+	# NB mutation calling and annotation now implemented as extension to Bio::DB::Alignment (SAM)
+	def hgnc(reference_pos=0,insertions=[],type="g",*subs)
+		if insertions
+			if insertions.is_a? String
+				insertions = [insertions]
+			end
+		end
+		first_match = true
+		total = 0
+		hgnc_format = []
+		@pairs.each do |pair|
+			case pair[0]
+				when "M"
+					#break if first_match == false
+					reference_pos += pair[1]
+					total += pair[1]
+					first_match = false
+				when "D"
+					deleted_bases = @reference[total,pair[1]].upcase
+					if (pair[1] == 1)
+						string = (reference_pos + 1).to_s
+					else
+						string = (reference_pos + 1).to_s + "_" + (reference_pos + pair[1]).to_s
+					end
+					string = string + "del" + deleted_bases
+					hgnc_format << string
+					total += pair[1]
+				when "I"
+					inserted_bases = (insertions.length == 0) ? "N" : insertions.shift
+
+					hgnc_format << (reference_pos).to_s + "_" + (reference_pos + 1).to_s + "ins" + inserted_bases.upcase
+			end
+		end
+		# Use for substitutions, but could also pass any other annotation to include in here, as an array of strings
+		subs = subs.first # >1 arguments discarded
+		if subs
+			if (subs.length > 0 && (subs.is_a? Array))
+				hgnc_format = hgnc_format + subs
+			end
+		end
+		if hgnc_format.length == 0
+			nil
+		elsif hgnc_format.length == 1
+			type.to_s + "." + hgnc_format[0]
+		else
+			type.to_s + "." + "[" + hgnc_format.join(";") + "]"
+		end
+
+	end
+
+  # TODO combine adjacent operations of the same type into a single pair
+	def combine_adjacent
+
+	end
+
+	# Returns a hash (keyed by operation type) of three element arrays: the start positions on the reference of operations of the given type(s) and the length of the operation,
+	# followed by query position (for e.g. retrieving inserted bases from SAM). A regexp can be used to specify multiple types e.g. /[ID]/.
+	def positions(type)
+		total = 0
+		qtotal = 0
+		hash = Hash.new{|h,k| h[k] = []}
+		@pairs.each do |pair|
+			if pair[0].match(type)
+				hash[$&] << [total, pair[1], qtotal]
+			end
+			total += pair[1] if pair[0].match Bio::Alignment::CIGAR.reference_operations
+			qtotal += pair[1] if pair[0].match Bio::Alignment::CIGAR.query_operations
+		end
+		hash
+	end
+
+
+	private
+
+	def deletions_to_matches(threshold)
+		self.pairs = @pairs.each{|pair| pair[0].sub!("D","M") if pair[1] <= threshold}
+	end
+
+	def remove_small_nonmatches(threshold)
+		self.pairs = @pairs.keep_if{|pair| pair[0] == "M" || pair[1] > threshold}
+	end
+
+	def count_type(type)
+		sum = 0
+		@pairs.each do |pair|
+			if pair[0].match(type)
+				sum += pair[1]
+			end
+		end
+		sum
+	end
+
+end #class