bio-ucsc-util 0.1.0

data/ext/ucsc-util/mkrf_conf.rb

@@ -0,0 +1,64 @@
+#(c) Copyright 2012 Nicholas A Thrower. All Rights Reserved.
+# create Rakefile for shared library compilation
+
+path = File.expand_path(File.dirname(__FILE__))
+
+path_external = File.join(path, "../../lib/bio/ucsc/src/")
+
+version = File.open(File.join(path_external,"Version"),'r')
+Version = version.read
+version.close
+
+Source = "ucsc-util-src-#{Version}.tgz"
+
+File.open(File.join(path,"Rakefile"),"w") do |rakefile|
+rakefile.write <<-RAKE
+require 'rbconfig'
+require 'fileutils'
+include FileUtils::Verbose
+require 'rake/clean'
+
+task :prepare do 
+  sh "tar xzvf #{Source}"
+  cp("makefile","ucsc-util-src-#{Version}/lib")
+end
+
+task :compile do
+  # build libraries
+  cd("ucsc-util-src-#{Version}/lib") do
+    sh "make"
+    case Config::CONFIG['host_os']
+      when /linux/
+        sh "make libucsc.so.1"
+        cp("libucsc.so.1","#{path_external}")
+      when /darwin/
+        sh "make libucsc.1.dylib"
+        cp("libucsc.1.dylib","#{path_external}")
+      else raise NotImplementedError, "ucsc-util not supported on your platform"
+    end
+    cp("libucsc.a","#{path_external}")
+  end
+end
+
+task :clobber do
+  rm_f("#{path_external}libucsc.a")
+  rm_f("#{path_external}libucsc.so.1")
+  rm_f("#{path_external}libucsc.1.dylib")
+end
+
+task :clean do
+  rm_rf("ucsc-util-src-#{Version}")
+end
+
+desc "clean compile"
+task :make_clean do
+  cd("ucsc-util-src-#{Version}") do
+    sh "make clean"
+  end
+end
+
+task :default => [:prepare,:compile,:clean]
+  
+RAKE
+  
+end

data/lib/bio-ucsc-util.rb

@@ -0,0 +1,3 @@
+require 'ffi'
+require 'bio/ucsc/util'
+require 'bio/ucsc/big_wig'

data/lib/bio/ucsc/big_wig.rb

@@ -0,0 +1,216 @@
+# == big_wig.rb
+# This file contains the BigWig class
+#
+# == Contact
+#
+# Author::    Nicholas A. Thrower
+# Copyright:: Copyright (c) 2012 Nicholas A Thrower
+# License::   See LICENSE.txt for more details
+#
+
+# :nodoc:
+module Bio
+  module Ucsc
+    # The BigWig class interacts with bigWig files
+    class BigWig
+      require 'bio/ucsc/binding'
+      # bigWig file name
+      attr_accessor :filename
+      # pointer to bbiFile
+      attr_accessor :bbi_file
+      # convenience method to create a new BigWig and open it.
+      def self.open(*args)
+        self.new(*args).open
+      end
+      # Returns a new BigWig.
+      def initialize(f=nil, opts={})
+        @filename = f
+        return self
+      end
+      # opens the file
+      def open
+        raise ArgumentError, "filename undefined" unless filename
+        raise NameError, "#{filename} not found" unless File.exist?(filename)
+        raise LoadError, "#{filename} bad format" unless Binding::isBigWig(filename)
+        @bbi_file = Binding::bigWigFileOpen(filename)
+        return self
+      end
+      # closes the file
+      def close
+        Binding::bbiFileClose(bbi_file) if bbi_file
+        @bbi_file = nil
+      end
+      # returns the caclulated standard deviation
+      def std_dev(chrom=nil,opts={})
+        if(chrom)
+          self.summary(chrom,0,self.chrom_length(chrom),1,{type:'std'}).first
+        else
+          bwf,bbi_sum = prepare_bwf(opts)
+          return Binding::calcStdFromSums(bbi_sum[:sumData], bbi_sum[:sumSquares], bbi_sum[:validCount])
+        end
+      end
+      # Percent of bases in region containing actual data
+      def coverage(chrom=nil,opts={})
+        if(chrom)
+          self.summary(chrom,0,self.chrom_length(chrom),1,{type:'coverage'}).first
+        else
+          bwf,bbi_sum = prepare_bwf(opts)          
+          return bbi_sum[:validCount] / chrom_length.to_f
+        end
+      end
+      # Returns the minimum value of items
+      def min(chrom=nil,opts={})
+        if(chrom)
+          self.summary(chrom,0,self.chrom_length(chrom),1,{type:'min'}).first
+        else
+          bwf,bbi_sum = prepare_bwf(opts)
+          return bbi_sum[:minVal]
+        end
+      end
+      # Returns the maximum value of items
+      def max(chrom=nil,opts={})
+        if(chrom)
+          self.summary(chrom,0,self.chrom_length(chrom),1,{type:'max'}).first
+        else
+          bwf,bbi_sum = prepare_bwf(opts)
+          return bbi_sum[:maxVal]
+        end
+      end
+      # Returns the mean value of items
+      def mean(chrom=nil,opts={})
+        if(chrom)
+          self.summary(chrom,0,self.chrom_length(chrom),1,{type:'mean'}).first
+        else
+          bwf,bbi_sum = prepare_bwf(opts)
+          return bbi_sum[:sumData]/bbi_sum[:validCount].to_f
+        end
+      end
+      # Total bases containing actual data
+      def bases_covered(opts={})
+        bwf,bbi_sum = prepare_bwf(opts)
+        return bbi_sum[:validCount]
+      end
+      # Returns size of given chromosome or the sum of all chromosomes
+      def chrom_length(chrom=nil)
+        chrom.nil? ? chrom_list.inject(0){|sum,chrom|sum+=chrom[:size]} : Binding::bbiChromSize(bbi_file,chrom)
+      end
+      # prints details about the file:
+      # - minMax/m => Only output the minimum and maximum values
+      # - zooms/z  => Display zoom level details
+      # - chroms/c => Display chrom details
+      # - udcDir/u => /dir/to/cache - place to put cache for remote bigBed/bigWigs
+      def info(opts={})
+        min_max =opts[:m] ||= opts[:minMax]
+        zooms =opts[:z] ||= opts[:zooms]
+        chroms =opts[:c] ||= opts[:chroms]
+        bwf,bbi_sum = prepare_bwf(opts)
+        # print min/max
+        if(min_max)
+          printf "%f %f\n", bbi_sum[:minVal], bbi_sum[:maxVal]
+          return
+        end
+        # start summary        
+        printf "version: %d\n", bwf[:version]
+        printf "isCompressed: %s\n", (bwf[:uncompressBufSize] > 0 ? "yes" : "no")
+        printf "isSwapped: %i\n", bwf[:isSwapped] ? 1 : 0
+        printf "primaryDataSize: %i\n",bwf[:unzoomedIndexOffset] - bwf[:unzoomedDataOffset]
+        unless(bwf[:levelList].null?)
+          list = Binding::BbiZoomLevel.new(bwf[:levelList])
+          printf "primaryIndexSize: %i\n", list[:dataOffset] - bwf[:unzoomedIndexOffset]
+        end
+        # print zoom level details
+        printf "zoomLevels: %d\n", bwf[:zoomLevels]
+        if(zooms)
+          zoom = Binding::BbiZoomLevel.new(bwf[:levelList])
+          while !zoom.null?
+            printf "\t%d\t%d\n", zoom[:reductionLevel], zoom[:indexOffset] - zoom[:dataOffset]
+            zoom = zoom[:next]
+          end
+        end
+        # print chrom details
+        
+        printf "chromCount: %d\n", chrom_list.size
+        if(chroms)
+          chrom_list.each do |chrom|
+            printf "\t%s %d %d\n", chrom[:name], chrom[:id], chrom[:size]
+          end
+        end
+        # finish summary
+        printf "basesCovered: %i\n", bbi_sum[:validCount]
+        printf "mean: %f\n", bbi_sum[:sumData]/bbi_sum[:validCount]
+        printf "min: %f\n", bbi_sum[:minVal]
+        printf "max: %f\n", bbi_sum[:maxVal]
+        printf "std: %f\n", Binding::calcStdFromSums(bbi_sum[:sumData], bbi_sum[:sumSquares], bbi_sum[:validCount])
+        return 
+      end
+      # retrieves summary information from the bigWig for the given range.
+      # - chrom  => Sequence name for summary
+      # - start  => Start of range (0 based)
+      # - stop  => End of range
+      # - count  => Number of datapoints to compute (1 for simple summary)
+      # hash Options:
+      # * :udcDir - /dir/to/cache - place to put cache for remote bigBed/bigWigs
+      # * :type => Summary type string
+      # * * mean - average value in region (default)
+      # * * min - minimum value in region
+      # * * max - maximum value in region
+      # * * std - standard deviation in region
+      # * * coverage - %% of region that is covered
+      def summary(chrom, start, stop, count, opts={})
+        type = opts[:type] || opts[:t] || 'mean'
+        udc_dir = opts[:u] ||= opts[:udcDir] ||= Binding::udcDefaultDir()
+        Binding::udcSetDefaultDir(udc_dir)
+        # allocate the array
+        summaryValues = FFI::MemoryPointer.new(:double,count)
+        # initialize to all 'NaN'
+        summaryValues.write_array_of_type(:double,:write_string,["NaN"]*count)
+        # fill in with Summary Data
+        Binding::bigWigSummaryArray(bbi_file, chrom, start, stop, Binding::bbiSummaryTypeFromString(type),count,summaryValues)
+        return summaryValues.read_array_of_double(count)
+      end      
+      # creates a new smoothed bigWig file at the supplied location. Smoothing options:
+      # - chrom => restrict smoothing to a given chromosome
+      # - cutoff => probe count cutoff[median]
+      # - window => rolling window size
+      # - type => smoothing algorithm [avg]
+      # * * 'avg' - average depth in window
+      # * * 'probe' - count of regions (probes) crossing 'cutoff' in window
+      # Big Wig options:
+      # - :blockSize => Number of items to bundle in r-tree [256]
+      # - :itemsPerSlot => Number of data points bundled at lowest level [1024]
+      # - :unc => If set, do not use compression
+      # - :udcDir => /dir/to/cache - place to put cache for remote bigBed/bigWigs
+      def smooth(out_file,opts={})
+        verb = opts[:v] || 0
+        window = opts[:window] || 250
+        cutoff = opts[:cutoff] || self.mean
+        block_size = opts[:block_size]||256
+        chrom = opts[:chrom]||nil
+        items_per_slot = opts[:items_per_slot]||1024
+        unc = opts[:unc]||false
+        do_compress = !unc
+        type = opts[:type]||'avg'
+        udc_dir = opts[:u] ||= opts[:udcDir] ||= Binding::udcDefaultDir()
+        Binding::bigWigFileSmooth(filename, chrom, block_size, items_per_slot, do_compress, window, verb, out_file, type, cutoff)
+      end
+      
+      private
+      # configures the temporary directory in case of remote files and returns a new BbiFile Struct and BbiSummaryElement
+      def prepare_bwf(opts)
+        udc_dir = opts[:u] ||= opts[:udcDir] ||= Binding::udcDefaultDir()
+        Binding::udcSetDefaultDir(udc_dir)     
+        return Binding::BbiFile.new(bbi_file), Binding::bbiTotalSummary(bbi_file)
+      end
+      # returns an array of BbiChromInfo items in file
+      def chrom_list
+        chrom = Binding::BbiChromInfo.new(Binding::bbiChromList(bbi_file))        
+        a = []
+        while !chrom.null?
+          a << chrom
+          chrom = chrom[:next]
+        end
+        return a
+      end
+    end
+  end
+end

data/lib/bio/ucsc/binding.rb

@@ -0,0 +1,128 @@
+# == binding.rb
+# This file contains the ffi binding declarations for the ucsc api
+# See https://github.com/ffi/ffi
+#
+# == Contact
+#
+# Author::    Nicholas A. Thrower
+# Copyright:: Copyright (c) 2012 Nicholas A Thrower
+# License::   See LICENSE.txt for more details
+#
+
+# :nodoc:
+module Bio
+  # -
+  module Ucsc
+    # Ruby binding for the ucsc utils
+    module Binding # :nodoc: all
+      require 'bio/ucsc/library'
+      extend FFI::Library
+      ffi_lib Bio::Ucsc::Library.filename
+      
+      # CLASSES
+      
+      # A zoom level in bigWig file
+      class BbiZoomLevel < FFI::Struct
+        layout(
+          :next_ptr, :pointer,            # Next in list
+          :reductionLevel, :uint,         # How many bases per item
+          :reserved, :uint,               # Zero for Now
+          :dataOffset, :ulong_long,       # Offset of data for this level in file
+          :indexOffset, :ulong_long       # Offset of index for this level in file
+        )
+        # allow for nested self referential *next pointer
+        def [](value)
+          if value==:next
+            BbiZoomLevel.new(self[:next_ptr])
+          else
+            super(value)
+          end
+        end
+      end
+      
+      # An open binary file (BigWig/BigBed)
+      class BbiFile < FFI::Struct
+        layout(
+            :next, :pointer,                  # Next in list.
+            :fileName, :string,               # Name of file - for better error reporting.
+            :udc, :pointer,                   # Open UDC file handle.
+            :typeSig, :uint,                  # bigBedSig or bigWigSig for now.
+            :isSwapped, :bool,                # If TRUE need to byte swap everything.
+            :chromBpt, :pointer,              # Index of chromosomes.
+            :version, :ushort,                # Version number - initially 1.
+            :zoomLevels, :ushort,             # Number of zoom levels.
+            :chromTreeOffset, :ulong_long,    # Offset to chromosome index.
+            :unzoomedDataOffset, :ulong_long, # Start of unzoomed data.
+            :unzoomedIndexOffset, :ulong_long,# Start of unzoomed index.
+            :fieldCount, :ushort,             # Number of columns in bed version.
+            :definedFieldCount, :ushort,      # Number of columns using bed standard definitions.
+            :asOffset, :ulong_long,           # Offset to embedded null-terminated AutoSQL file.
+            :totalSummaryOffset, :ulong_long, # Offset to total summary information if any.  (On older files have to calculate)
+            :uncompressBufSize, :uint,        # Size of uncompression buffer, 0 if uncompressed
+            :unzoomedCir, :pointer,           # Unzoomed data index in memory - may be NULL.
+            :levelList, :pointer              # List of zoom levels.
+        )
+      end
+      
+      # A BbiFile summary element
+      class BbiSummaryElement < FFI::Struct
+        layout(
+        :validCount,:ulong_long,
+        :minVal, :double,
+        :maxVal, :double,
+        :sumData, :double,
+        :sumSquares, :double
+        )
+      end
+      
+      # Pair of a name and a 32-bit integer. Used to assign IDs to chromosomes.
+      class BbiChromInfo < FFI::Struct
+        layout(
+        :next_ptr, :pointer,
+        :name, :string,         # Chromosome name
+        :id, :uint,             # Chromosome ID - a small number usually
+        :size, :uint)           # Chromosome size in bases
+        # allow for nested self referential *next pointer
+        def [](value)
+          if value==:next
+            BbiChromInfo.new(self[:next_ptr])
+          else
+            super(value)
+          end
+        end
+      end
+      
+      ## ENUMS
+      
+      # bbiSummaryType - way to summarize data
+      BbiSummaryType = enum(:bbiSumMean, 0,
+        :bbiSumMax,
+        :bbiSumMin,
+        :bbiSumCoverage,
+        :bbiSumStandardDeviation
+      )
+
+      # FUNCTIONS
+      # bbi
+      attach_function :bbiChromList, [:pointer], :pointer                                                     # *bbiFile ; BbiChromInfo*
+      attach_function :bbiChromSize, [:pointer,:pointer], :int32                                              # *bbiFile, chrom ; size
+      attach_function :bbiFileClose, [:pointer], :void                                                        # *bbiFile
+      attach_function :bbiTotalSummary, [:pointer], BbiSummaryElement.by_value                                # **bbiFile
+      attach_function :bbiSummaryTypeFromString, [:string], BbiSummaryType                                    # summaryType
+      # bigwig
+      attach_function :bigWigFileCreate, [:string,:string,:int,:int,:bool,:bool,:string], :void                         # inName, chromSizes, blockSize, itemsPerSlot, clipDontDie, doCompress, outName      
+      attach_function :bigWigFileOpen, [:string], :pointer                                                              # filename
+      attach_function :bigWigFileSmooth, [:string, :string, :int, :int,:bool,:int,:int,:string,:string,:double], :void  # inName, chromSizes, blockSize, itemsPerSlot, doCompress, window, verbosity, outName, smoothType, Cutoff
+      attach_function :bigWigSummaryArray, [:pointer,:pointer,:uint32,:uint32,BbiSummaryType,:int,:pointer], :bool      # *bbiFile, chrom, start, end, type, size, &values
+      attach_function :isBigWig, [:string], :bool                                                                       # filename
+      # utils
+      attach_function :bedGraphToBigWig, [:string, :string, :int, :int, :bool, :string], :void                # inName, chromSizes, outName
+      # udc
+      attach_function :udcDefaultDir, [], :string
+      attach_function :udcSetDefaultDir, [:string], :void                                                     # path
+      # hmmstats
+      attach_function :calcStdFromSums, [:double, :double, :uint64], :double                                  # sum, sumSquares, n 
+      attach_function :slCount, [:pointer], :int                                                              # *bbiChromList
+    end
+  end
+end

data/lib/bio/ucsc/library.rb

@@ -0,0 +1,38 @@
+# == library.rb
+# This file contains the Library Class for retrieving platform specific library names
+#
+# == Contact
+#
+# Author::    Nicholas A. Thrower
+# Copyright:: Copyright (c) 2012 Nicholas A Thrower
+# License::   See LICENSE.txt for more details
+#
+
+# :nodoc: all
+module Bio
+  # -
+  module Ucsc
+    # Cross-platform library naming
+    class Library # :nodoc:
+      # return the platform specific library name
+      def self.filename
+        lib_os = case RUBY_PLATFORM
+        when /linux/
+          'so.1'
+        when /darwin/
+          '1.dylib'
+        else
+          case RUBY_DESCRIPTION
+          when /darwin.*java/
+            '1.dylib'
+          when /linux.*java/
+          'so.1'
+          else raise NotImplementedError, "UcscUtil not supported on your platform"
+          end
+        end
+
+        File.join(File.expand_path(File.dirname(__FILE__)),"src/libucsc.#{lib_os}")
+      end
+    end
+  end
+end