bel 0.2.1 → 0.3.0.beta1

data/INSTALL.md

@@ -0,0 +1,19 @@
+Install
+=======
+
+This library requires [Ruby](https://www.ruby-lang.org) (**>= 1.9.2**).  See [how to install ruby](https://github.com/OpenBEL/bel.rb/blob/master/INSTALL_RUBY.md).
+
+Install from [RubyGems.org](http://rubygems.org/gems/bel)
+
+```bash
+    gem install bel
+```
+
+Build from master branch
+
+1. Obtain source for master branch.
+  - `git clone git@github.com:OpenBEL/bel.rb.git`
+
+2. Build
+  - `gem build bel.gemspec`
+  - `gem install bel-[VERSION].gem`

data/INSTALL_RUBY.md

@@ -0,0 +1,107 @@
+# Install Ruby
+
+
+## Install Ruby (Windows)
+
+1. Download [RubyInstaller](http://rubyinstaller.org/downloads).
+   * Versions 1.9.3 and 2.x.x are supported.
+2. Install RubyInstaller version.
+   * Enable the _Add Ruby executables to your PATH_ option presented during installation.
+3. Open a command prompt (Windows Key + R then type `cmd`).
+   * Confirm installation by typing `ruby -v`.
+   * The output should show the ruby version (e.g. `ruby 2.0.0p451 (2014-02-24) [x64-mingw32]`).
+
+Continue with <a href="#install_bel_gem">Install the bel gem</a>.
+
+## Install Ruby (Mac OSX)
+
+_Option 1: Homebrew_
+
+1. Install with homebrew by typing `brew install ruby`.
+2. Add ruby commands to your PATH.
+   * Add to .bash_profile.
+     * `echo 'export PATH="/usr/local/Cellar/ruby/VERSION/bin:$PATH"' >> .bash_profile`
+   * Update environment by sourcing .bash_profile.
+     * `source ~/.bash_profile`
+3. Confirm installation by typing `ruby -v`.
+
+_Option 2: rbenv_
+
+* _Install with homebrew._
+   * `brew update`
+   * `brew install rbenv ruby-build`
+   * More details [here] (https://github.com/sstephenson/rbenv#homebrew-on-mac-os-x).
+
+* _Install with git._
+   * Clone rbenv repository.
+     * `git clone https://github.com/sstephenson/rbenv.git ~/.rbenv`
+   * Add to .bash_profile.
+     * `echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile`
+   * Enable shims and autocompletion from the terminal.
+     * `echo 'eval "$(rbenv init -)"' >> ~/.bash_profile`
+   * Clone ruby-build repository.
+     * `git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build`
+   * More details [here] (https://github.com/sstephenson/rbenv#installation).
+
+Continue with <a href="#install_bel_gem">Install the bel gem</a>.
+
+## Install Ruby (Linux)
+
+_Option 1: Install via package manager._
+
+* Example installation with Ubuntu.
+   * Type `sudo apt-get install ruby` in the terminal.
+
+_Option 2: rbenv_
+
+* _Install with git._
+   * Clone rbenv repository.
+     * `git clone https://github.com/sstephenson/rbenv.git ~/.rbenv`
+   * Add to .bash_profile.
+     * `echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile`
+   * Enable shims and autocompletion from the terminal.
+     * `echo 'eval "$(rbenv init -)"' >> ~/.bash_profile`
+   * Clone ruby-build repository.
+     * `git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build`
+   * More details [here] (https://github.com/sstephenson/rbenv#installation).
+
+Continue with <a href="#install_bel_gem">Install the bel gem</a>.
+
+<br><br>
+<div id="install_bel_gem"></div>
+## Install the _bel_ gem
+
+1. Open a terminal or command prompt.
+2. Use the `gem` command to install the `bel` gem.
+   * `gem install bel`
+3. You should see the following:
+
+<pre>
+    Fetching: bel-0.2.1.gem (100%)
+    Successfully installed bel-0.2.1
+    Parsing documentation for bel-0.2.1
+    Installing ri documentation for bel-0.2.1
+    1 gem installed
+</pre>
+4. Confirm you can access the `bel_upgrade` command.
+5. Continue with <a href="#upgrading_bel">Upgrading BEL</a>.
+
+<br><br>
+<div id="upgrading_bel"></div>
+## Upgrading BEL
+
+1. Type `bel_upgrade --help` for option details.
+2. Run command
+   * Example 1 - convert a BEL file
+     * `bel_upgrade --bel small_corpus.bel --changelog "http://resource.belframework.org/belframework/20131211/change_log.json"
+   * Example 2 - convert BEL from standard in
+     * `curl "http://resource.belframework.org/belframework/1.0/knowledge/small_corpus.bel" | bel_upgrade --changelog "http://resource.belframework.org/belframework/20131211/change_log.json"`
+   * More details [here] (https://github.com/OpenBEL/bel.rb).
+3. The upgraded BEL will be written to standard out.  Simply redirect to a file after that.
+   * `bel_upgrade ... > upgraded-version.bel`
+
+<br><br>
+## Issues
+
+* If you have questions with `bel_upgrade` or the `bel` gem please post to the [openbel-discuss] (https://groups.google.com/forum/#!forum/openbel-discuss) google group.
+* If you encounter errors please post an issue to [github issues] (https://github.com/OpenBEL/bel.rb/issues).

data/README.md

@@ -0,0 +1,319 @@
+bel ruby
+========
+
+[![Gem Version](https://badge.fury.io/rb/bel.svg)](http://badge.fury.io/rb/bel)
+
+The bel ruby gem allows the reading, writing, and processing of BEL (Biological Expression Language) with a natural DSL.
+
+Learn more on [BEL](http://www.openbel.org/content/bel-lang-language).
+
+License: [Apache License, Version 2.0](http://opensource.org/licenses/Apache-2.0)
+
+Dependencies
+
+- Required
+
+    - Ruby 1.9.2 or greater ([how to install ruby](INSTALL_RUBY.md))
+
+- Optional
+
+    - *rdf gem*, *addressable gem*, and *uuid gem* for RDF conversion
+    - *rdf-turtle gem* for serializing to RDF turtle format
+
+Install / Build: See [INSTALL](INSTALL.md).
+
+branches
+--------
+
+- master branch
+  - [![Travis CI Build](https://travis-ci.org/OpenBEL/bel.rb.svg?branch=master)](https://travis-ci.org/OpenBEL/bel.rb)
+
+- next branch
+  - [![Build Status for next branch](https://travis-ci.org/OpenBEL/bel.rb.svg?branch=next)](https://travis-ci.org/OpenBEL/bel.rb)
+
+
+executable commands
+-------------------
+
+**bel_upgrade**: Upgrade namespaces in BEL content to another version (i.e. *1.0* to *20131211*)
+
+```bash
+
+    # using BEL file and change log JSON file
+    bel_upgrade --bel small_corpus.bel --changelog change_log.json
+
+    # using BEL file and change log from a URL
+    bel_upgrade --bel small_corpus.bel --changelog http://resource.belframework.org/belframework/20131211/change_log.json
+
+    # using BEL from STDIN and change log from a URL
+    cat small_corpus.bel | bel_upgrade --changelog http://resource.belframework.org/belframework/20131211/change_log.json
+```
+
+**bel_upgrade_term**: Upgrade BEL terms to another version (e.g. *1.0* to *20131211*)
+
+```bash
+
+    # using BEL terms and change log JSON file
+    bel_upgrade_term -t "p(HGNC:A2LD1)\np(EGID:84)\n" -n "1.0" -c change_log.json
+
+    # using BEL terms and change log from a URL
+    bel_upgrade_term -t "p(HGNC:A2LD1)\np(EGID:84)\n" -n "1.0" -c http://resource.belframework.org/belframework/20131211/change_log.json
+
+    # using BEL from STDIN
+    echo -e "p(EGID:84)\np(HGNC:A2LD1)" | bel_upgrade_term -n "1.0" -c change_log.json
+    cat terms.bel | bel_upgrade_term -n "1.0" -c change_log.json
+```
+
+**bel_rdfschema**: Dumps the RDF Schema triples for BEL.
+
+```bash
+
+    # dumps schema in ntriples format (default)
+    bel_rdfschema
+
+    # dumps schema in turtle format
+    # note: requires the 'rdf-turtle' gem
+    bel_rdfschema --format turtle
+```
+
+**bel2rdf**: Converts BEL to RDF.
+
+```bash
+
+    # dumps RDF to standard out in ntriples format (default)
+    #   (from file)
+    bel2rdf --bel small_corpus.bel
+
+    #   (from standard in)
+    cat small_corpus.bel | bel2rdf
+
+    # dumps RDF to standard out in turtle format
+    #   (from file)
+    bel2rdf --bel small_corpus.bel --format turtle
+
+    #   (from standard in)
+    cat small_corpus.bel | bel2rdf --format turtle
+```
+
+**bel_parse**: Show parsed objects from BEL content for debugging purposes
+
+```bash
+
+    # ...from file
+    bel_parse --bel small_corpus.bel
+
+    # ...from standard in
+    cat small_corpus.bel | bel_parse
+```
+
+api examples
+------------
+
+**Use OpenBEL namespaces from the latest release.**
+
+```ruby
+
+    require 'bel'
+  
+    # reference namespace value using standard prefixes (HGNC, MGI, RGD, etc.)
+    HGNC['AKT1']
+    => #<BEL::Language::Parameter:0x00000004df5bc0
+      @enc=:GRP,
+      @ns_def="BEL::Namespace::HGNC",
+      @value=:AKT1>
+```
+
+**Load your own namespace**
+
+```ruby
+
+    require 'bel'
+
+    # define a NamespaceDefinition with prefix symbol and url
+    PUBCHEM = NamespaceDefinition.new(:PUBCHEM, 'http://your-url.org/pubchem.belns')
+
+    # reference caffeine compound, sip, and enjoy
+    PUBCHEM['2519']
+```
+
+**Load namespaces from a published OpenBEL version**
+
+```ruby
+
+    require 'bel'
+
+    ResourceIndex.openbel_published_index('1.0').namespaces.find { |x| x.prefix == :HGU133P2 }
+    ResourceIndex.openbel_published_index('20131211').namespaces.find { |x| x.prefix == :AFFX }
+    ResourceIndex.openbel_published_index('latest-release').namespaces.find { |x| x.prefix == :AFFX }
+```
+
+**Load namespaces from a custom resource index**
+
+```ruby
+
+    require 'bel'
+
+    ResourceIndex.new('/home/bel/index.xml').namespaces.map(&:prefix)
+    => ["AFFX", "CHEBIID", "CHEBI", "DOID", "DO", "EGID", "GOBPID", "GOBP",
+        "GOCCID", "GOCC", "HGNC", "MESHPP", "MESHCS", "MESHD", "MGI", "RGD",
+        "SCHEM", "SDIS", "SFAM", "SCOMP", "SPAC", "SP"]
+```
+
+**Validate BEL parameters**
+
+```ruby
+
+    require 'bel'
+
+    # AKT1 contained within HGNC NamespaceDefinition
+    HGNC[:AKT1].valid?
+    => true
+
+    # not_in_namespace is not contained with HGNC NamespaceDefinition
+    HGNC[:not_in_namespace].valid?
+    => false
+
+    # namespace is nil so :some_value MAY exist
+    Parameter.new(nil, :some_value).valid?
+    => true
+```
+
+**Validate BEL terms**
+
+```ruby
+
+    require 'bel'
+
+    tscript(g(HGNC['AKT1'])).valid?
+    => false
+    tscript(g(HGNC['AKT1'])).valid_signatures
+    => []
+    tscript(g(HGNC['AKT1'])).invalid_signatures.map(&:to_s)
+    => ["tscript(F:complex)a", "tscript(F:p)a"]
+
+    tscript(p(HGNC['AKT1'])).valid?
+    => true
+    tscript(p(HGNC['AKT1'])).valid_signatures.map(&:to_s)
+    => ["tscript(F:p)a"]
+    tscript(p(HGNC['AKT1'])).invalid_signatures.map(&:to_s)
+    => ["tscript(F:complex)a"]
+```
+
+**Write BEL in Ruby with a DSL**
+
+```ruby
+
+    require 'bel'
+    
+    # create BEL statements
+    p(HGNC['SKIL']).directlyDecreases tscript(p(HGNC['SMAD3']))
+    bp(GO['response to hypoxia']).increases tscript(p(EGID['7157']))
+```
+
+**Parse BEL input**
+
+```ruby
+
+    require 'bel'
+
+    # example BEL document
+    BEL_SCRIPT = <<-EOF
+    SET DOCUMENT Name = "Spec"
+    SET DOCUMENT Authors = User
+    SET Disease = "Atherosclerosis"
+    path(MESHD:Atherosclerosis)
+    path(Atherosclerosis)
+    bp(GO:"lipid oxidation")
+    p(MGI:Mapkap1) -> p(MGI:Akt1,pmod(P,S,473))
+    path(MESHD:Atherosclerosis) => bp(GO:"lipid oxidation")
+    path(MESHD:Atherosclerosis) =| (p(HGNC:MYC) -> bp(GO:"apoptotic process"))
+    EOF
+
+    # BEL::Script.parse returns BEL::Script::Parser
+    BEL::Script.parse('tscript(p(HGNC:AKT1))')
+    => #<BEL::Script::Parser:0x007f179261d270>
+
+    # BEL::Script::Parser is Enumerable so we can analyze as we parse
+    #   for example: count all function types into a hash
+    BEL::Script.parse('tscript(p(HGNC:AKT1))', {HGNC: HGNC}).find_all { |obj|
+      obj.is_a? Term
+    }.map { |term|
+      term.fx  
+    }.reduce(Hash.new {|h,k| h[k] = 0}) { |result, function|  
+      result[function.short_form] += 1  
+      result
+    }
+    => {:p=>1, :tscript=>1} 
+
+    # parse; yield each parsed object to the block
+    namespace_mapping = {GO: GOBP, HGNC: HGNC, MGI: MGI, MESHD: MESHD}
+    BEL::Script.parse(BEL_SCRIPT, namespace_mapping) do |obj|
+      puts "#{obj.class} #{obj}"  
+    end
+    => BEL::Script::DocumentProperty: SET DOCUMENT Name = "Spec"
+    => BEL::Script::DocumentProperty: SET DOCUMENT Authors = "User"
+    => BEL::Script::Annotation: SET Disease = "Atherosclerosis"
+    => BEL::Script::Parameter: MESHD:Atherosclerosis
+    => BEL::Script::Term: path(MESHD:Atherosclerosis)
+    => BEL::Script::Statement: path(MESHD:Atherosclerosis)
+    => BEL::Script::Parameter: Atherosclerosis
+    => BEL::Script::Term: path(Atherosclerosis)
+    => BEL::Script::Statement: path(Atherosclerosis)
+    => BEL::Script::Parameter: GO:"lipid oxidation"
+    => BEL::Script::Term: bp(GO:"lipid oxidation")
+    => BEL::Script::Statement: bp(GO:"lipid oxidation")
+    => BEL::Script::Parameter: MGI:Mapkap1
+    => BEL::Script::Term: p(MGI:Mapkap1)
+    => BEL::Script::Parameter: MGI:Akt1
+    => BEL::Script::Parameter: P
+    => BEL::Script::Parameter: S
+    => BEL::Script::Parameter: 473
+    => BEL::Script::Term: p(MGI:Akt1,pmod(P,S,473))
+    => BEL::Script::Statement: p(MGI:Mapkap1) -> p(MGI:Akt1,pmod(P,S,473))
+    => BEL::Script::Parameter: MESHD:Atherosclerosis
+    => BEL::Script::Term: path(MESHD:Atherosclerosis)
+    => BEL::Script::Parameter: GO:"lipid oxidation"
+    => BEL::Script::Term: bp(GO:"lipid oxidation")
+    => BEL::Script::Statement: path(MESHD:Atherosclerosis) => bp(GO:"lipid oxidation")
+    => BEL::Script::Parameter: MESHD:Atherosclerosis
+    => BEL::Script::Term: path(MESHD:Atherosclerosis)
+    => BEL::Script::Parameter: HGNC:MYC
+    => BEL::Script::Term: p(HGNC:MYC)
+    => BEL::Script::Parameter: GO:"apoptotic process"
+    => BEL::Script::Term: bp(GO:"apoptotic process")
+    => BEL::Script::Statement: path(MESHD:Atherosclerosis) =| (p(HGNC:MYC) -> bp(GO:"apoptotic process"))
+```
+
+**Iteratively parse BEL from file-like object**
+
+```ruby
+
+    require 'bel'
+    BEL::Script.parse(File.open('/home/user/small_corpus.bel')).find_all { |obj|
+      obj.is_a? Statement
+    }.to_a.size
+```
+
+**Parse BEL and convert to RDF (requires the *rdf*, *addressable*, and *uuid* gems)**
+
+```ruby
+
+    require 'bel'
+    parser = BEL::Script::Parser.new
+
+    rdf_statements = []
+
+    # parse term
+    parser.parse('p(HGNC:AKT1)') do |obj|
+      if obj.is_a? BEL::Language::Term  
+        rdf_statements += obj.to_rdf
+      end  
+    end
+
+    # parse statement
+    parser.parse("p(HGNC:AKT1) => tscript(g(HGNC:TNF))\n") do |obj|
+      if obj.is_a? BEL::Language::Statement
+        rdf_statements += obj.to_rdf
+      end  
+    end
+```

data/bel.gemspec

@@ -0,0 +1,67 @@
+Gem::Specification.new do |spec|
+  spec.name                     = 'bel'
+  spec.version                  = '0.3.0.beta1'
+  spec.summary                  = '''
+                                    Process BEL with ruby.
+                                  '''.gsub(%r{^\s+}, ' ').gsub(%r{\n}, '')
+  spec.description              = '''
+                                    The BEL gem allows the reading, writing,
+                                    and processing of BEL (Biological Expression
+                                    Language) with a natural DSL.
+                                  '''.gsub(%r{^\s+}, ' ').gsub(%r{\n}, '')
+  spec.license                  = 'Apache-2.0'
+  spec.authors                  = [
+                                    'Anthony Bargnesi',
+                                    'Natalie Catlett',
+                                    'Nick Bargnesi',
+                                    'William Hayes'
+                                  ]
+  spec.email                    = [
+                                    'abargnesi@selventa.com',
+                                    'ncatlett@selventa.com',
+                                    'nbargnesi@selventa.com',
+                                    'whayes@selventa.com'
+                                  ]
+  spec.files                    = [
+                                    Dir.glob("lib/**/*.rb"),
+                                    Dir.glob("ext/**/*.{c,h,def}"),
+                                    __FILE__,
+                                    'LICENSE',
+                                    'INSTALL.md',
+                                    'INSTALL_RUBY.md',
+                                    'README.md'
+                                  ].flatten!
+  spec.executables              = Dir.glob('bin/*').map(&File.method(:basename))
+  spec.homepage                 = 'https://github.com/OpenBEL/bel.rb'
+  spec.rdoc_options             = [
+                                    '--title', 'BEL Ruby Documentation',
+                                    '--main', 'README.md',
+                                    '--line-numbers',
+                                    '--exclude', 'lib/bel/script.rb',
+                                    'README.md',
+                                    'INSTALL.md',
+                                    'INSTALL_RUBY.md',
+                                    'LICENSE'
+                                  ]
+
+  spec.extensions              << 'ext/mri/extconf.rb'
+  spec.required_ruby_version    = '>= 1.9.2'
+
+  # runtime
+  spec.add_dependency             'ffi',           '~> 1.9'
+
+  # test rdf functionality
+  spec.add_development_dependency 'uuid',          '~> 2.3'
+  spec.add_development_dependency 'addressable',   '~> 2.3'
+  spec.add_development_dependency 'rdf',           '~> 1.1'
+
+  # development gems
+  spec.add_development_dependency 'bundler',       '~> 1.7'
+  spec.add_development_dependency 'rake',          '~> 10.4'
+  spec.add_development_dependency 'rake-compiler', '~> 0.9'
+  spec.add_development_dependency 'rspec',         '~> 3.2'
+  spec.add_development_dependency 'yard',          '~> 0.8'
+  spec.add_development_dependency 'rdoc',          '~> 4.2'
+end
+# vim: ts=2 sw=2:
+# encoding: utf-8