UCSCBin 0.2.0

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2010 Hiroyuki MISHIMA 
+             (missy at be.to / hmishima at nagasaki-u.ac.jp)
+
+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.rdoc

@@ -0,0 +1,46 @@
+= UCSCBin
+Author:: Hiroyuki Mishima (missy at be.to / hmishima at nagasaki-u.ac.jp)
+Copyright:: Hiroyuki Mishima, 2010
+License:: the MIT/X11 license. See the LICENSE file.
+
+A library for handling BIN index and 0/1-based coordination of
+UCSC Bioinformatics Genome Browser ( http://genome.ucsc.edu/ )
+
+Original program in C by Jim Kent, 2002
+
+See also related materials:
+* http://genomewiki.ucsc.edu/index.php/Bin_indexing_system,
+* Kent, et. al. Genome Research 2002.12:996-1006, http://www.ncbi.nlm.nih.gov/pmc/articles/PMC186604/
+* src/lib/binRange.c in the kent source tree. http://hgdownload.cse.ucsc.edu/admin/jksrc.zip
+
+== UCSCBin::Util
+convert between 0-based half-open interval and
+1-based full-close intervals.
+
+== UCSCBin::BinRange
+Calculate Bin number from genomic physical position
+according to UCSC's Bin Indexing System. 
+note: Extended bin index for positions >= 512M is not supported yet.
+Do you need it? Please email the author.
+
+== sample/refseqgene.rb
+to run the sample (input interval is regular 1-based full-closed cordination) 
+ sudo gem install sequel
+ sample/refseqgene.rb chr1:234567-456789
+ 
+output:
+ chr1:234567-345678      LOC100133331; LOC100132287; LOC100132062
+
+== Note on Patches/Pull Requests 
+* github repository is git://github.com/misshie/UCSCBin.git
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches. 
+
+== Copyright
+
+Copyright (c) 2010 Hiroyuki MISHIMA. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "UCSCBin"
+    gem.summary =
+     %Q{Calculate BIN indexes on UCSC Bioinformatics's Genome Browser}
+    gem.description =
+     %Q{Utilities for UCSC Bioinfomatics's Genome Browser
+      ( http://g  enome.ucsc.edu ) including calculation of a BIN index
+       from a genomic interval to speed-up SQL queries, and conversion
+       between 1-based full-closed (for humans) and 0-based half-open 
+       (for machienes) intervals}
+    gem.email = "missy@be.to"
+    gem.homepage = "http://github.com/misshie/UCSCBin"
+    gem.authors = ["Hiroyuki MISHIMA"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "UCSCBin #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/UCSCBin.gemspec

@@ -0,0 +1,92 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{UCSCBin}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Hiroyuki MISHIMA"]
+  s.date = %q{2010-10-28}
+  s.description = %q{Utilities for UCSC Bioinfomatics's Genome Browser
+      ( http://g  enome.ucsc.edu ) including calculation of a BIN index
+       from a genomic interval to speed-up SQL queries, and conversion
+       between 1-based full-closed (for humans) and 0-based half-open 
+       (for machienes) intervals}
+  s.email = %q{missy@be.to}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "UCSCBin.gemspec",
+     "VERSION",
+     "lib/UCSCBin.rb",
+     "rdoc/README_rdoc.html",
+     "rdoc/UCSCBin.html",
+     "rdoc/UCSCBin/BinRange.html",
+     "rdoc/UCSCBin/Utils.html",
+     "rdoc/created.rid",
+     "rdoc/images/brick.png",
+     "rdoc/images/brick_link.png",
+     "rdoc/images/bug.png",
+     "rdoc/images/bullet_black.png",
+     "rdoc/images/bullet_toggle_minus.png",
+     "rdoc/images/bullet_toggle_plus.png",
+     "rdoc/images/date.png",
+     "rdoc/images/find.png",
+     "rdoc/images/loadingAnimation.gif",
+     "rdoc/images/macFFBgHack.png",
+     "rdoc/images/package.png",
+     "rdoc/images/page_green.png",
+     "rdoc/images/page_white_text.png",
+     "rdoc/images/page_white_width.png",
+     "rdoc/images/plugin.png",
+     "rdoc/images/ruby.png",
+     "rdoc/images/tag_green.png",
+     "rdoc/images/wrench.png",
+     "rdoc/images/wrench_orange.png",
+     "rdoc/images/zoom.png",
+     "rdoc/index.html",
+     "rdoc/js/darkfish.js",
+     "rdoc/js/jquery.js",
+     "rdoc/js/quicksearch.js",
+     "rdoc/js/thickbox-compressed.js",
+     "rdoc/lib/UCSCBin_rb.html",
+     "rdoc/rdoc.css",
+     "sample/refseqgene.rb",
+     "spec/UCSCBin_BinRange_spec.rb",
+     "spec/UCSCBin_Utils_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/misshie/UCSCBin}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Calculate BIN indexes on UCSC Bioinformatics's Genome Browser}
+  s.test_files = [
+    "spec/UCSCBin_Utils_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/UCSCBin_BinRange_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+  end
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/UCSCBin.rb

@@ -0,0 +1,144 @@
+# = UCSCBin
+# Author:: Hiroyuki Mishima
+# Copyright:: Hiroyuki Mishima, 2010
+# Licence:: the MIT/X11 licence. See the LICENCE file.
+#
+# Original program in C by Jim Kent, 2002
+#
+# Util:
+# convert between 0-based half-open interval and
+# 1-based full-close intervals.
+#
+# BinRange:
+# Calculate Bin number from genomic physical position
+# according to UCSC's Bin Indexing System. 
+#
+# See also http://genomewiki.ucsc.edu/index.php/Bin_indexing_system,
+# a paper Kent, et. al. Genome Research 2002.12:996-1006,
+# and src/lib/binRange.c in the kent source tree.
+#
+
+module UCSCBin
+# Version = "0.1.0" # 20100714
+Version = "0.2.0" # 20101028
+
+  class Utils
+    # 'zero_start' and 'zero_end' are 0-based half-open
+    # used in UCSC MySQL database and the BED format.
+    # the first one base in a chromosome is [0, 1)
+    # Positions must be start<end
+    def self.zero_to_one(zero_start, zero_end)
+      case
+      when (zero_start < 0 || zero_end < 0) 
+        raise ArgumentError, "positions must be >=0"
+      when zero_start >= zero_end
+        raise ArgumentError, "positions must be start<end"
+      end
+      
+      [zero_start + 1, zero_end]
+    end
+
+    # 'one_start' and 'one_end' are 1-based full-close
+    # used in UCSC genome browser's human interface and most of other formats
+    # the first one base in a chromosome is [1, 1]
+    # Positions must be start<=end
+    def self.one_to_zero(one_start, one_end)
+      case
+      when (one_start < 1 || one_end < 1) 
+        raise ArgumentError, "positions must be >=1"
+      when one_start > one_end
+        raise ArgumentError, "positions must be start<=end"
+      end
+
+      [one_start - 1 , one_end]
+    end
+  end
+
+  class BinRange
+    BINRANGE_MAXEND_512M       = (512*1024*1024)
+    BIN_OFFSETS_EXTENDED       = [4096+512+64+8+1, 512+64+8+1, 64+8+1, 8+1, 1, 0]
+    BIN_OFFSETS                = [512+64+8+1, 64+8+1, 8+1, 1, 0]
+    BIN_OFFSET_OLD_TO_EXTENDED = 4681
+    # How much to shift to get to finest bin.
+    BIN_FIRST_SHIFT            = 17 
+    # How much to shift to get to next larger bin.
+    BIN_NEXT_SHIFT             = 3 
+
+    # Return a Integer of a BIN which is the smallest/finest bin 
+    # containing whole the interval/range.
+    # 
+    # Extended bin index for positions >= 512M is not supported yet
+    # Do you need it? Please email me.
+    def self.bin_from_range(bin_start, bin_end)
+      if bin_end <= BINRANGE_MAXEND_512M
+        bin_from_range_standard(bin_start, bin_end)
+      else
+        bin_from_range_extended(bin_start, bin_end)
+      end
+    end
+
+    class << self;  alias bin bin_from_range; end
+
+    # Return an Array of BINs which are all bins containing whole the
+    # interval/range. Thus, it always contains "0" indicating a bin
+    # containing whole of a chromosome.
+    # 
+    # extended bin index for positions >= 512M is not supported yet
+    # Do you need it? Please email me.
+    #
+    def self.bin_all(p_start, p_end)
+      if p_end <= BINRANGE_MAXEND_512M
+        bin_all_standard(p_start, p_end)
+      else
+        bin_all_extended(p_start, p_end)
+      end
+    end
+
+    private
+
+    def self.bin_from_range_standard(bin_start, bin_end)
+      # Given start,end in chromosome coordinates assign it
+      # a bin.   There's a bin for each 128k segment, for each
+      # 1M segment, for each 8M segment, for each 64M segment,
+      # and for each chromosome (which is assumed to be less than
+      # 512M.)  A range goes into the smallest bin it will fit in.
+
+      bin_start >>= BIN_FIRST_SHIFT
+      bin_end -= 1
+      bin_end >>= BIN_FIRST_SHIFT
+
+      BIN_OFFSETS.each do |offset|
+        return offset + bin_start if bin_start == bin_end
+        bin_start >>= BIN_NEXT_SHIFT
+        bin_end   >>= BIN_NEXT_SHIFT
+      end
+      raise RangeError, \
+      "start #{bin_start}, end #{bin_end} out of range in findBin (max is 512M)"
+    end
+
+    def self.bin_from_range_extended(bin_start, bin_end)
+      raise NotImplementedError, "Extended bins are not supported yet"
+    end
+
+    def self.bin_all_standard(bin_start, bin_end)
+      bin_start_orig = bin_start
+      bin_end_orig   = bin_end 
+      results = Array.new
+
+      bin_start >>= BIN_FIRST_SHIFT
+      bin_end -= 1
+      bin_end >>= BIN_FIRST_SHIFT
+
+      BIN_OFFSETS.each do |offset|
+        results.concat(((offset + bin_start)..(offset + bin_end)).to_a)
+        bin_start >>= BIN_NEXT_SHIFT
+        bin_end   >>= BIN_NEXT_SHIFT
+      end
+      return results
+    end
+
+    def self.bin_all_extended(bin_start, bin_end)
+      raise NotImplementedError, "Extended bins are not supported yet"
+    end
+  end
+end

data/rdoc/README_rdoc.html

@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+	<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
+
+	<title>File: README.rdoc [UCSCBin 0.2.0
+]</title>
+
+	<link type="text/css" media="screen" href="./rdoc.css" rel="stylesheet" />
+
+	<script src="./js/jquery.js" type="text/javascript"
+		charset="utf-8"></script>
+	<script src="./js/thickbox-compressed.js" type="text/javascript"
+		charset="utf-8"></script>
+	<script src="./js/quicksearch.js" type="text/javascript"
+		charset="utf-8"></script>
+	<script src="./js/darkfish.js" type="text/javascript"
+		charset="utf-8"></script>
+</head>
+
+<body class="file">
+	<div id="metadata">
+		<div id="project-metadata">
+			
+			
+			<div id="fileindex-section" class="section project-section">
+				<h3 class="section-header">Files</h3>
+				<ul>
+				
+					<li class="file"><a href="./README_rdoc.html">README.rdoc</a></li>
+				
+				</ul>
+			</div>
+			
+
+			<div id="classindex-section" class="section project-section">
+				<h3 class="section-header">Class Index
+					<span class="search-toggle"><img src="./images/find.png"
+						height="16" width="16" alt="[+]"
+						title="show/hide quicksearch" /></span></h3>
+				<form action="#" method="get" accept-charset="utf-8" class="initially-hidden">
+				<fieldset>
+					<legend>Quicksearch</legend>
+					<input type="text" name="quicksearch" value=""
+						class="quicksearch-field" />
+				</fieldset>
+				</form>
+
+				<ul class="link-list">
+				
+					<li><a href="./UCSCBin.html">UCSCBin</a></li>
+				
+					<li><a href="./UCSCBin/BinRange.html">UCSCBin::BinRange</a></li>
+				
+					<li><a href="./UCSCBin/Utils.html">UCSCBin::Utils</a></li>
+				
+				</ul>
+				<div id="no-class-search-results" style="display: none;">No matching classes.</div>
+			</div>
+
+			
+		</div>
+	</div>
+
+	<div id="documentation">
+		<h1><a href="UCSCBin.html">UCSCBin</a></h1>
+<table>
+<tr><td valign="top">Author:</td><td>Hiroyuki Mishima (missy at be.to / hmishima at nagasaki-u.ac.jp)
+
+</td></tr>
+<tr><td valign="top">Copyright:</td><td>Hiroyuki Mishima, 2010
+
+</td></tr>
+<tr><td valign="top">License:</td><td>the MIT/X11 license. See the LICENSE file.
+
+</td></tr>
+</table>
+<p>
+A library for handling BIN index and 0/1-based coordination of UCSC
+Bioinformatics Genome Browser ( <a
+href="http://genome.ucsc.edu/">genome.ucsc.edu/</a> )
+</p>
+<p>
+Original program in C by Jim Kent, 2002
+</p>
+<p>
+See also related materials:
+</p>
+<ul>
+<li><a
+href="http://genomewiki.ucsc.edu/index.php/Bin_indexing_system">genomewiki.ucsc.edu/index.php/Bin_indexing_system</a>,
+
+</li>
+<li>Kent, et. al. Genome Research 2002.12:996-1006, <a
+href="http://www.ncbi.nlm.nih.gov/pmc/articles/PMC186604/">www.ncbi.nlm.nih.gov/pmc/articles/PMC186604/</a>
+
+</li>
+<li>src/lib/binRange.c in the kent source tree. <a
+href="http://hgdownload.cse.ucsc.edu/admin/jksrc.zip">hgdownload.cse.ucsc.edu/admin/jksrc.zip</a>
+
+</li>
+</ul>
+<h2>UCSCBin::Util</h2>
+<p>
+convert between 0-based half-open interval and 1-based full-close
+intervals.
+</p>
+<h2><a href="UCSCBin/BinRange.html">UCSCBin::BinRange</a></h2>
+<p>
+Calculate Bin number from genomic physical position according to
+UCSC&#8217;s Bin Indexing System. note: Extended bin index for positions >=
+512M is not supported yet. Do you need it? Please email the author.
+</p>
+<h2>sample/refseqgene.rb</h2>
+<p>
+to run the sample (input interval is regular 1-based full-closed
+cordination)
+</p>
+<pre>
+ sudo gem install sequel
+ sample/refseqgene.rb chr1:234567-456789
+</pre>
+<p>
+output:
+</p>
+<pre>
+ chr1:234567-345678      LOC100133331; LOC100132287; LOC100132062
+</pre>
+<h2>Note on Patches/Pull Requests</h2>
+<ul>
+<li>github repository is git://github.com/misshie/UCSCBin.git
+
+</li>
+<li>Fork the project.
+
+</li>
+<li>Make your feature addition or bug fix.
+
+</li>
+<li>Add tests for it. This is important so I don&#8217;t break it in a future
+version unintentionally.
+
+</li>
+<li>Commit, do not mess with rakefile, version, or history. (if you want to
+have your own version, that is fine but bump version in a commit by itself
+I can ignore when I pull)
+
+</li>
+<li>Send me a pull request. Bonus points for topic branches.
+
+</li>
+</ul>
+<h2>Copyright</h2>
+<p>
+Copyright &#169; 2010 Hiroyuki MISHIMA. See LICENSE for details.
+</p>
+
+	</div>
+
+	<div id="validator-badges">
+		<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+		<p><small>Generated with the <a href="http://deveiate.org/projects/Darkfish-Rdoc/">Darkfish
+			Rdoc Generator</a> 1.1.6</small>.</p>
+	</div>
+</body>
+</html>
+