ulla 0.9.3

data/Manifest.txt

@@ -0,0 +1,90 @@
+.git/COMMIT_EDITMSG
+.git/HEAD
+.git/config
+.git/description
+.git/hooks/applypatch-msg.sample
+.git/hooks/commit-msg.sample
+.git/hooks/post-commit.sample
+.git/hooks/post-receive.sample
+.git/hooks/post-update.sample
+.git/hooks/pre-applypatch.sample
+.git/hooks/pre-commit.sample
+.git/hooks/pre-rebase.sample
+.git/hooks/prepare-commit-msg.sample
+.git/hooks/update.sample
+.git/index
+.git/info/exclude
+.git/logs/HEAD
+.git/logs/refs/heads/master
+.git/logs/refs/remotes/origin/HEAD
+.git/objects/06/9494e479f28b5751fb135b8e55e8fef3d3a02e
+.git/objects/22/0df784191ad94983ca1d943e49fe482c9d1069
+.git/objects/3b/b6f2b7f563175a13a0ccd723aab761552f448b
+.git/objects/41/f48aefb4d7a6a87eb423eaae77ae1e8a58dd6c
+.git/objects/44/d1f1782e3ea1d9fd2f9054784b53e8e810a8ca
+.git/objects/4f/364c2eac29f5c7fcbf06419c4f58074cd32ace
+.git/objects/57/1326145a7a4b3e58f3d3008ba343135f213b05
+.git/objects/6c/4f0844f62b7345f0651b0fb2829a8f157469fb
+.git/objects/73/8dc79450de050f12d48a32602f2ddbe6807029
+.git/objects/7b/4acb3aee6616d80e295ee21fe8bb7ee93ebe96
+.git/objects/9e/0a9235b0d70a8029098070007fb414cb52504e
+.git/objects/9e/bfcad2906aac4a23a7c9689a47b76723f5d152
+.git/objects/a6/578c95f2f474303464b572e9dac716432472b2
+.git/objects/a8/65ef5700ff04601c6fc40fa5ede3cc25534723
+.git/objects/aa/285cb176668c5e49c54c6e1d3cc27bd47fd4f4
+.git/objects/b8/e3828a1082137c4aa4595386bdfb73e3c75b9d
+.git/objects/c2/fb6afc000952b56354fe195682645000d2aea2
+.git/objects/c4/a0553ca0e3c4628e688ecb5e3304a8a8ac0c28
+.git/objects/c8/d49f83c4a32cff2d87dd4aa5f83eb7aac3a753
+.git/objects/ca/c25e8049075ed4bff993705acb4750b2b62ba9
+.git/objects/d2/ff2e939339eb3fb776e064c258e71dfa1cf396
+.git/objects/d7/cedf9e2a8ff35b5d7dafdc0f20daed9c65ce44
+.git/objects/e2/e81af59e3a6c4aa8daac62add62860ae776ba4
+.git/objects/e5/7c47d183ce5dda1a944c7ee1c19c8a0c4bb278
+.git/objects/eb/f4a4e1e50bb30731597f776e56b0ccb0c9959f
+.git/objects/f6/39d6f6cf883fde4b9052012919c1df3288c7da
+.git/objects/f8/2346f308f49053df108b7c31ac3089e8b4b4ac
+.git/objects/fb/4b193bb1cbe9041d2f00176f6caa6acfb1fc12
+.git/objects/pack/pack-aebf617a0b8e016433238d2f21f542bc5b21bd15.idx
+.git/objects/pack/pack-aebf617a0b8e016433238d2f21f542bc5b21bd15.pack
+.git/packed-refs
+.git/refs/heads/master
+.git/refs/remotes/origin/HEAD
+.gitignore
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+bin/ulla
+config/website.yml
+config/website.yml.sample
+lib/math_extensions.rb
+lib/narray_extensions.rb
+lib/nmatrix_extensions.rb
+lib/string_extensions.rb
+lib/ulla.rb
+lib/ulla/cli.rb
+lib/ulla/environment.rb
+lib/ulla/environment_class_hash.rb
+lib/ulla/environment_feature.rb
+lib/ulla/environment_feature_array.rb
+lib/ulla/heatmap_array.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+test/test_helper.rb
+test/test_math_extensions.rb
+test/test_narray_extensions.rb
+test/test_nmatrix_extensions.rb
+test/test_string_extensions.rb
+test/test_ulla.rb
+test/ulla/test_cli.rb
+test/ulla/test_environment_class_hash.rb
+test/ulla/test_environment_feature.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/PostInstall.txt

@@ -0,0 +1,5 @@
+HELP/OPTIONS: ulla -h
+
+For more information on ulla, see http://ulla.rubyforge.org
+
+

data/README.rdoc

@@ -0,0 +1,259 @@
+= ulla
+
+http://www-cryst.bioc.cam.ac.uk/ulla
+
+
+== Description
+
+'ulla' is a program for calculating environment-specific substitution tables from user providing environmental class definitions and sequence alignments with the annotations of the environment classes.
+
+
+== Features
+
+* Environment-specific substitution table generation based on user providing environmental class definition
+* Entropy-based smoothing procedures to cope with sparse data problem
+* BLOSUM-like weighting procedures using PID threshold
+* Heat Map generation for substitution tables
+
+
+== Requirements
+
+* ruby 1.8.7 or above (http://www.ruby-lang.org)
+* rubygems 1.2.0 or above (http://rubyforge.org/projects/rubygems)
+
+Following RubyGems will be automatically installed if you have rubygems installed on your machine
+
+* narray (http://narray.rubyforge.org)
+* facets (http://facets.rubyforge.org)
+* bio (http://bioruby.open-bio.org)
+* RMagick (http://rmagick.rubyforge.org)
+
+
+== Installation
+
+    ~user $ sudo gem install ulla
+
+
+== Basic Usage
+
+It's pretty much the same as Kenji's subst (http://www-cryst.bioc.cam.ac.uk/~kenji/subst/), so in most cases, you can swap 'subst' with 'ulla'.
+
+    ~user $ ulla -l TEMLIST-file -c classdef.dat
+                or
+    ~user $ ulla -f TEM-file -c classdef.dat
+
+
+== Options
+    --tem-file (-f) FILE: a tem file
+    --tem-list (-l) FILE: a list for tem files
+    --classdef (-c) FILE: a file for the defintion of environments (default: 'classdef.dat')
+    --outfile (-o) FILE: output filename (default 'allmat.dat')
+    --weight (-w) INTEGER: clustering level (PID) for the BLOSUM-like weighting (default: 60)
+    --noweight: calculate substitution count with no weights
+    --smooth (-s) INTEGER:
+        0 for partial smoothing (default)
+        1 for full smoothing
+    --p1smooth: perform smoothing for p1 probability calculation when partial smoothing
+    --nosmooth: perform no smoothing operation
+    --cys (-y) INTEGER:
+        0 for using C and J only for structure (default)
+        1 for both structure and sequence
+        2 for using only C for both (must be set when you have no 'disulphide' or 'disulfide' annotation in templates)
+    --output INTEGER:
+        0 for raw count (no smoothing performed)
+        1 for probabilities
+        2 for log odds ratios (default)
+    --noroundoff: do not round off log odds ratio
+    --scale INTEGER: log odds ratio matrices in 1/n bit units (default 3)
+    --sigma DOUBLE: change the sigma value for smoothing (default 5.0)
+    --autosigma: automatically adjust the sigma value for smoothing
+    --add DOUBLE: add this value to raw count when deriving log odds ratios without smoothing (default 1/#classes)
+    --pidmin DOUBLE: count substitutions only for pairs with PID equal to or greater than this value (default none)
+    --pidmax DOUBLE: count substitutions only for pairs with PID smaller than this value (default none)
+    --heatmap INTEGER:
+        0 create a heat map file for each substitution table
+        1 create one big file containing all heat maps from substitution tables
+        2 do both 0 and 1
+    --heatmap-format INTEGER:
+        0 for Portable Network Graphics (PNG) Format (default)
+        1 for Graphics Interchange Format (GIF)
+        2 for Joint Photographic Experts Group (JPEG) Format
+        3 for Microsoft Windows bitmap (BMP) Format
+        4 for Portable Document Format (PDF)
+    --heatmap-columns INTEGER: number of tables to print in a row when --heatmap 1 or 2 set (default: sqrt(no. of tables))
+    --heatmap-stem STRING: stem for a file name when --heatmap 1 or 2 set (default: 'heatmap')
+    --heatmap-values: print values in the cells when generating heat maps
+    --verbose (-v) INTEGER
+        0 for ERROR level
+        1 for WARN or above level (default)
+        2 for INFO or above level
+        3 for DEBUG or above level
+    --version: print version
+    --help (-h): show help
+
+
+== Usage
+
+1. Prepare an environmental class definition file. For more details, please check this notes (http://www-cryst.bioc.cam.ac.uk/~kenji/subst/NOTES).
+
+        ~user $ cat classdef.dat
+        #
+        # name of feature (string); values adopted in .tem file (string); class labels assigned for each value (string);
+        # constrained or not (T or F); silent (used as masks)? (T or F)
+        #
+        secondary structure and phi angle;HEPC;HEPC;T;F
+        solvent accessibility;TF;Aa;F;F
+
+2. Prepare structural alignments and their annotations of above environmental classes in PIR format.
+
+        ~user $ cat sample1.tem
+        >P1;1mnma
+        sequence
+        QKERRKIEIKFIENKTRRHVTFSKRKHGIMKKAFELSVLTGTQVLLLVVSETGLVYTFSTPKFEPIVTQQEGRNL
+        IQACLNAPDD*
+        >P1;1egwa
+        sequence
+        --GRKKIQITRIMDERNRQVTFTKRKFGLMKKAYELSVLCDCEIALIIFNSSNKLFQYASTDMDKVLLKYTEY--
+        ----------*
+        >P1;1mnma
+        secondary structure and phi angle
+        CPCCCCCCCCCCCCHHHHHHHHHHHHHHHHHHHHHHHHHHPCCCEEEEECCCPCEEEEECCCCCHHHHCHHHHHH
+        HHHHHCCCCP*
+        >P1;1egwa
+        secondary structure and phi angle
+        --CCCCCCCCCCCCHHHHHHHHHHHHHHHHHHHHHHHHHCPCCCEEEEECCCPCEEEEECCCHHHHHHHHHHC--
+        ----------*
+        >P1;1mnma
+        solvent accessibility
+        TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTFTTTTTTTTTTTTTTTT
+        TTTTTTTTTT*
+        >P1;1egwa
+        solvent accessibility
+        --TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTFTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT--
+        ----------*
+        ... 
+
+3. When you have two or more alignment files, you should make a separate file containing all the paths for the alignment files.
+
+        ~user $ ls -1 *.tem > TEMLIST
+        ~user $ cat TEMLIST
+        sample1.tem
+        sample2.tem
+        ...
+
+4. To produce substitution count matrices, type
+
+        ~user $ ulla -l TEMLIST --output 0 -o substcount.mat
+
+5. To produce substitution probability matrices, type
+
+        ~user $ ulla -l TEMLIST --output 1 -o substprob.mat
+
+6. To produce log odds ratio matrices, type
+
+        ~user $ ulla -l TEMLIST --output 2 -o substlogo.mat
+
+7. To produce substitution data only from the sequence pairs within a given PID range, type (if you don't provide any name for output, 'allmat.dat' will be used.)
+
+        ~user $ ulla -l TEMLIST --pidmin 60 --pidmax 80 --output 1
+
+8. To change the clustering level (default 60), type
+
+        ~user $ ulla -l TEMLIST --weight 80 --output 2
+
+9. In case positions are masked with the character 'X' in any environmental features, all mutations from/to the position will be excluded from the calculation of substitution counts.
+
+10. Then, it will produce a file containing all the matrices, which will look like the one below. For more details, please check this notes (http://www-cryst.bioc.cam.ac.uk/~kenji/subst/NOTES).
+
+        # Environment-specific amino acid substitution matrices
+        # Creator: ulla version 0.0.5
+        # Creation Date: 05/02/2009 17:29
+        #
+        # Definitions for structural environments:
+        # 2 features used
+        #
+        # secondary structure and phi angle;HEPC;HEPC;F;F
+        # solvent accessibility;TF;Aa;F;F
+        # (read in from classdef.dat)
+        #
+        # Number of alignments: 1187
+        # (list of .tem files read in from TEMLIST)
+        #
+        # Total number of environments: 8
+        #
+        # There are 21 amino acids considered.
+        # ACDEFGHIKLMNPQRSTVWYJ
+        # 
+        # C: Cystine (the disulfide-bonded form)
+        # J: Cysteine (the free thiol form)
+        #
+        # Weighting scheme: clustering at PID 60 level
+        # ...
+        #
+        >HA 0
+        #        A      C      D      E      F      G      H      I      K      L      M      N      P      Q      R      S      T      V      W      Y      J
+        A        3     -5      0      0     -1      2      0      0      1      0      0      0      1      1      0      1      1      1     -1      0      2
+        C      -16     19    -16    -18    -11    -14    -13    -13    -14    -14    -14    -11    -17    -16    -13    -16    -14    -12    -12    -10     -4
+        D        1     -7      6      3     -3      1      0     -3      1     -3     -2      2      1      2      0      1      0     -2     -3     -2     -2
+        E        3     -7      5      7     -1      2      2      0      3      0      0      3      2      4      3      3      2      1     -1      0     -1
+        F       -4     -4     -6     -6      7     -5     -1      0     -4      1      0     -5     -5     -4     -4     -4     -3     -1      3      3      0
+        G       -2     -6     -3     -4     -5      5     -4     -5     -4     -5     -4     -2     -3     -4     -4     -2     -3     -5     -6     -4     -3
+        H        0     -6      0      0      1      0      8     -1      0      0      0      1     -2      1      1      0      0      0      1      3      0
+        I       -3     -7     -6     -5      0     -5     -3      4     -4      1      1     -5     -4     -4     -3     -5     -2      2     -2     -1      0
+        K        2     -6      2      2     -1      1      2      0      5      1      1      2      0      3      4      2      2      0     -2      0     -1
+        L       -2     -6     -5     -4      1     -4     -2      2     -3      4      2     -3     -4     -3     -2     -4     -2      1      0      0      1
+        M       -2     -7     -4     -3      1     -2     -1      2     -2      2      6     -3     -4     -2     -1     -2     -1      1      0      0      1
+        N        0     -5      1      0     -3      1      1     -3      0     -2     -2      6     -2      0      0      1      1     -2     -3     -1     -1
+        P       -1     -7     -1     -2     -4     -1     -3     -3     -2     -3     -4     -2      9     -2     -3      0     -1     -2     -4     -4     -4
+        Q        2     -7      2      2     -1      1      2     -1      2      0      0      2      0      5      2      1      1      0     -2     -1      0
+        R        1     -6      1      1     -1      0      2      0      3      0      1      1     -1      2      6      1      1      0     -1      0      0
+        S        0     -6     -1     -1     -3      0     -2     -3     -1     -3     -3      0      0     -1     -1      3      1     -2     -4     -3      0
+        T       -1     -7     -2     -2     -3     -2     -2     -2     -2     -2     -2     -1     -2     -2     -2      0      3     -1     -3     -3      0
+        V       -3     -6     -6     -5     -1     -4     -3      1     -4      0      0     -5     -3     -4     -4     -4     -2      2     -2     -2      0
+        W       -4     -6     -6     -5      2     -6     -2     -2     -5     -1     -2     -5     -5     -4     -4     -5     -4     -2     12      2     -3
+        Y       -3     -5     -5     -5      3     -4      1     -1     -3     -1     -1     -3     -5     -3     -3     -4     -3     -2      3      7     -1
+        J       -2      0     -4     -5      0     -2     -1      0     -3      0      0     -3     -6     -2     -2     -1     -1      0     -1      0      9
+        U       -5     16     -7     -8     -3     -5     -4     -3     -6     -3     -3     -5     -9     -6     -5     -4     -4     -3     -4     -3      6
+        ...
+
+11. To generate a heat map for each table with values in it,
+
+        ~user $ ulla -l TEMLIST --heatmap 0 --heatmap-values
+
+    which will look like this,
+
+    http://www-cryst.bioc.cam.ac.uk/~semin/images/0.HA.png
+
+12. To generate one big figure, 'myheatmaps.gif' containing all the heat maps (4 maps in a row),
+
+        ~user $ ulla -l TEMLIST --heatmap 1 --heatmap-stem myheatmaps --heatmap-format 1 --heatmap-columns 4
+
+    which will look like this,
+
+    http://www-cryst.bioc.cam.ac.uk/~semin/images/myheatmaps.gif
+
+== TODO
+
+* Substitution table generation considering both the source and the target environmental classes
+* Remove dependency on NMatrix package
+
+== Repository
+
+You can download a pre-built RubyGems package from
+
+* rubyforge: http://rubyforge.org/projects/ulla
+
+or, You can fetch the source from
+
+* github: http://github.com/semin/ulla/tree/master
+
+
+== Contact
+
+Comments are welcome, please send an email to me (seminlee at gmail dot com). 
+
+
+== License
+
+http://i.creativecommons.org/l/by-nc/2.0/uk/88x31.png
+This work is licensed under a {Creative Commons Attribution-Noncommercial 2.0 UK: England & Wales License}[http://creativecommons.org/licenses/by-nc/2.0/uk/].

data/Rakefile

@@ -0,0 +1,32 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/ulla'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('ulla', Ulla::VERSION) do |p|
+  p.developer('Semin Lee', 'seminlee@gmail.com')
+  p.changes               = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message  = 'PostInstall.txt' # TODO remove if post-install message not required
+  p.rubyforge_name        = p.name # TODO this is default value
+  p.extra_deps            = [
+    ['narray',  '>= 0.5.9.5'],
+    ['bio',     '>= 1.2.1'],
+    ['facets',  '>= 2.4.5'],
+    ['rmagick', '>= 2.9.1'],
+  ]
+
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+
+  p.clean_globs |= %w[**/.DS_Store tmp *.log *.swp]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]

data/bin/ulla

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+#
+#  Created on 2008-11-7.
+#  Copyright (c) 2008. All rights reserved.
+
+require File.expand_path(File.dirname(__FILE__) + "/../lib/ulla")
+
+require "ulla/cli"
+
+Ulla::CLI.execute(ARGV)

data/config/website.yml

@@ -0,0 +1,2 @@
+host: semin@rubyforge.org
+remote_dir: /var/www/gforge-projects/ulla

data/config/website.yml.sample

@@ -0,0 +1,2 @@
+host: unknown@rubyforge.org
+remote_dir: /var/www/gforge-projects/egor

data/lib/math_extensions.rb

@@ -0,0 +1,7 @@
+module MathExtensions
+  def log2(val)
+    log(val) / log(2)
+  end
+end
+
+Math.extend(MathExtensions)

data/lib/narray_extensions.rb

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'narray'
+require 'facets'
+
+module NArrayExtensions
+
+  def pretty_string(opts={})
+    { :col_header   => nil,
+      :row_header   => nil }.merge!(opts)
+
+    ("%-3s" % "#") + opts[:col_header].inject("") { |s, a| s + ("%7s" % a) } + "\n" +
+      self.to_a.inject("%-3s" % opts[:row_header]) { |s, v|
+      if v.is_a? Float
+        s + ("%7.2f" % v)
+      else
+        s + ("%7d" % v)
+      end
+    }
+  end
+end
+
+NArray.send(:include, NArrayExtensions)