rubabel 0.2.0 → 0.2.1

data/README.md

@@ -0,0 +1,189 @@
+# rubabel
+
+Ruby interface to the openbabel ruby bindings (or the openbabel gem).  The
+interface attempts to be a ruby-ish analogue of
+[pybel](http://openbabel.org/docs/current/UseTheLibrary/Python_PybelAPI.html).
+
+## Examples
+
+The [Chemistry Toolkit Rosetta Wiki](http://ctr.wikia.com/wiki/Chemistry_Toolkit_Rosetta_Wiki) has a lot of examples you can check out.
+
+### Creating a molecule
+
+#### From a string
+
+    require 'rubabel'
+
+    # by default, reads in smiles strings
+    serine = Rubabel["C(C(C(=O)O)N)O"]
+    # more formally:
+    serine = Rubabel::Molecule.from_string("C(C(C(=O)O)N)O")
+
+    # also any other format openbabel supports, for example inchi
+    serine = Rubabel["InChI=1S/C3H7NO3/c4-2(1-5)3(6)7/h2,5H,1,4H2,(H,6,7)", :inchi]
+
+    # from the internet:
+    mol = Rubabel[some_molecule, Rubabel.format_from_mime(some_mime_type)]
+
+Find out all the formats Rubabel supports (hash is format key pointing to the description):
+
+    hash = Rubabel.in_formats
+    hash = Rubabel.out_formats
+
+#### From a file
+
+Reading multiple entries from a file:
+    
+    Rubabel.foreach("file.sdf") do |mol|
+      puts mol.exact_mass
+    end
+
+Foreach returns an enumerator that can be chained:
+
+    # return an array of every unique atom type in the file
+    uniq_atom_types = Rubabel.foreach("file.mol").flat_map {|mol| mol.map(&:type) }.uniq
+
+Read a single molecule from a file (reads only the first molecule)
+
+    mol = Rubabel::Molecule.from_file("file.sdf")
+    # handles gzipped files seamlessly:
+    mol = Rubabel::Molecule.from_file("file.sdf.gz") 
+    mol = Rubabel.molecule_from_file("file.sdf") # alternative
+
+    # explicit format for uninformative/wrong extensions:
+    mol = Rubabel::Molecule.from_file("file", :sdf)
+
+### Writing/Drawing
+
+#### create string output
+
+    mol = Rubabel["OCC"] # ethanol
+
+    mol.to_s       # canonical smiles -> "CCO"
+    mol.csmiles    # same thing
+
+    mol.to_s(:smi) # smiles -> "OCC"
+    mol.smiles     # same thing
+
+For inclusion in a file with standard smiles formatting (SMILES\tID\n):
+
+    can_smiles_string = mol.write_string # -> "CCO\t\n"
+    mol.title = "ethanol"
+    can_smiles_string = mol.write(:can)  # -> "CCO\tethanol\n"
+
+Other formats in the same manner:
+
+    pdb_string = mol.write(:pdb)
+
+Write to a file directly (single molecule only; depends on file extension for type):
+
+    # write to a smiles file
+    mol.write("file.smi")
+    mol.write_file("file.smi")
+
+Write multiple molecules to a file:
+
+    File.open("somefile.pdb", 'w') do |out|
+      molecules.each {|mol| out.print mol.write(:pdb) }
+    end
+
+#### Drawing
+
+If you write to svg or png (png uses mini_magick to convert from svg) then the
+molecule is automatically drawn in 2D:
+
+    mol = Rubabel["NCC(O)C(=O)O"]
+    mol.write("file.svg")
+
+    # must have imagemagick ('convert' command) and mini_magick gem installed
+    mol.write("file.png") 
+
+### Searching and Splitting
+
+*each_match*, *matches*, *matches?*, *smarts_indices* all take the same input (SMARTS
+string or object and optional boolean specifying uniqueness of results):
+
+    mol = Rubabel["NCC(O)C(=O)O"]
+    mol.each_match("CO") do |match|
+      # match is just an array of atoms that matched
+      match.first.el # => :c
+      match.last.el # => :o
+    end
+    
+    # matches returns all the matches in an array
+    all_matches = mol.matches("CO")
+    # all the match routines take a boolean to alter uniqueness
+    all_matches = mol.matches("CO", false) # some matches may not be uniq
+
+Have some bonds to break?, split makes new molecules split from that bond(s)
+    
+    bonds = mol.matches("CO").map {|c, o| c.get_bond(o) }
+    mol.split(*bonds)  # splits between every carbon single bonded to oxygen
+
+### Add & Delete atoms/bonds
+
+#### Adding
+
+    mol = Rubabel["OCC"]
+    # adds a carbon, then an oxygen to last indexed atom by atomic number
+    mol << 6 << 8    # #<Mol "OCCCO">
+    mol << :c << :o  # same thing
+
+    # add an ethyl group specifically to second carbon
+    mol = Rubabel["OCC"]
+    mol[1] << :c << :c
+
+    # add a vinyl group to second carbon (use method notation and parenthesis 
+    # because we are going to specify 2 arguments (the bond order):
+    ( mol[1] << :c).<<(:c, 2)
+
+#### Deleting
+
+    # delete an atom:
+    mol = Rubabel["NCO"]
+    mol.delete(mol[0])  # -> #<Mol CO>
+
+    # delete a bond:
+    bond = mol[0].get_bond(mol[1])
+    mol.delete(bond)  # ->  #<Mol C.O>
+
+## Installing
+
+First, many thanks to Andreas Maunz for packaging openbabel as a gem which makes this install quite painless.
+
+### Quick Install
+
+On a POSIX system, make sure you have openbabel (including header files), cmake, curl, tar, sed and make {see openbabel instructions}[https://github.com/amaunz/openbabel-gem].  On ubuntu/debian:
+
+    sudo apt-get install openbabel libopenbabel-dev cmake make curl
+
+Then install the gem (which should install the openbabel gem, too):
+
+    gem install rubabel
+
+### Building from Source
+
+1. download openbabel 
+2. swap out Init_OpenBabel for Init_openbabel in scripts/ruby/openbabel-ruby.cpp (see [here](http://forums.openbabel.org/Ruby-Open-Babel-in-2-1-1-td957640.html)).  Some versions have this fixed already, apparently.
+3. make sure you have the right [dependencies to compile](http://openbabel.org/docs/2.3.1/Installation/install.html#compiling-open-babel)
+
+Here's a complete example of compiling for a single user on Ubuntu 11.10 and probably will be generally forward compatible for some time.  This will compile bindings on whichever ruby comes up with '/usr/bin/env ruby':
+
+    # install the dependencies:
+    sudo apt-get install libeigen2-dev cmake libwxgtk2.8-dev libxml2-dev libcairo2-dev
+    # unpack it:
+    tar -xzvf openbabel-2.3.1.tar.gz
+    # swap out buggy lines in ruby bindings:
+    sed -i 's/Init_OpenBabel/Init_openbabel/g' openbabel-2.3.1/scripts/ruby/openbabel-ruby.cpp
+    # make a separate build directory for building in:
+    mkdir build-rvmruby1.9.3
+    cd build-rvmruby1.9.3
+    mkdir ~/tools
+    cmake ../openbabel-2.3.1 -DRUBY_BINDINGS=ON -DCMAKE_INSTALL_PREFIX=~/tools/openbabel-rvmruby1.9.3
+    make && make install
+
+[[Still need directions to install the gem on top of a build from source]]
+ 
+## Copyright
+
+MIT License.  See LICENSE for further details.

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/rubabel/atom.rb

@@ -14,14 +14,30 @@ module Rubabel
     include Enumerable
 
     class << self
-      # takes an element symbol and creates that atom.  If el_sym is set to
-      # nil or 0, then an atom of atomic number 0 is used
-      def [](el_sym=:h, id=nil)
-        ob_atom = OpenBabel::OBAtom.new
-        ob_atom.set_id(id) if id
-        ob_atom.set_atomic_num(Rubabel::EL_TO_NUM[el_sym] || 0)
-        self.new(ob_atom)
-      end
+      # I cannot figure out how to get the atom attached properly into a
+      # molecule.  Until I figure that out, no sense in having this method
+      # exposed:
+      #
+      # takes an atomic number or element symbol and creates that atom.  If
+      # arg is set to nil, then an atom of atomic number 0 is used
+      # (represented by '*' in smiles)
+      #def [](arg=:c)
+      #  ob_atom = OpenBabel::OBAtom.new
+      #  atomic_number = 
+      #    if arg.nil? then 0
+      #    elsif arg.is_a?(Symbol) 
+      #      Rubabel::EL_TO_NUM[arg]
+      #    else
+      #      arg
+      #    end
+      #  ob_atom.set_atomic_num(atomic_number)
+      #  self.new(ob_atom)
+      #end
+    end
+
+    # adds an atom and returns the added atom (allows chaining)
+    def <<(atom, bond_order=1)
+      add_atom!(atom, bond_order)
     end
 
     # returns the molecule that is parent of this atom
@@ -59,14 +75,14 @@ module Rubabel
       NUM_TO_ELEMENT[atomic_num]
     end
 
-    # creates a bond and adds it to both atoms
-    def add_atom!(other)
-      obbond = OpenBabel::OBBond.new
-      obbond.set_begin(self.ob)
-      obbond.set_end(other.ob)
-      @ob.add_bond(obbond)
-      other.ob.add_bond(obbond)
-      self
+    # creates a bond and adds it to both atoms.  Returns the passed in or
+    # newly created atom.
+    def add_atom!(arg, bond_order=1)
+      unless arg.is_a?(Rubabel::Atom)
+        arg = mol.add_atom!(arg)
+      end
+      @ob.get_parent.add_bond(self.ob.get_idx, arg.ob.get_idx, bond_order)
+      arg
     end
 
     def each_bond(&block)

data/lib/rubabel/molecule.rb

@@ -108,14 +108,28 @@ module Rubabel
       end
     end
 
-    # arg is an atomic number. returns the newly created atom
-    def add_atom!(atomic_num=1)
-      # jtp implementation:
-      # @ob.add_atom(atom.ob)
-      new_obatom = @ob.new_atom
-      new_obatom.set_atomic_num(atomic_num)
-      #@ob.add_atom(new_obatom)
-      Rubabel::Atom.new(new_obatom)
+    # returns the atom passed in or that was created.  arg is a pre-existing
+    # atom, an atomic number or an element symbol (e.g. :c).  default is to
+    # add carbon.
+    def add_atom!(arg=6, attach_to=nil, bond_order=1)
+      if attach_to
+        attach_to.add_atom!(arg, bond_order)
+      else
+        if arg.is_a?(Rubabel::Atom)
+          @ob.add_atom(arg.ob)
+          arg
+        else
+          new_obatom = @ob.new_atom
+          arg = Rubabel::EL_TO_NUM[arg] if arg.is_a?(Symbol)
+          new_obatom.set_atomic_num(arg)
+          Rubabel::Atom.new(new_obatom)
+        end
+      end
+    end
+
+    # retrieves the atom by index (accepts everything an array would)
+    def [](*args)
+      atoms[*args]
     end
 
     def delete_atom(atom)
@@ -145,8 +159,8 @@ module Rubabel
     # to add_h!
     def formula() @ob.get_formula end
 
-    def initialize(obmol)
-      @ob = obmol
+    def initialize(obmol=nil)
+      @ob = obmol.nil? ? OpenBabel::OBMol.new  : obmol
     end
 
     # returns a list of atom indices matching the patterns (corresponds to the
@@ -476,6 +490,18 @@ module Rubabel
       Rubabel::MoleculeData.new(@ob)
     end
 
+    # adds the atom (takes atomic number, element symbol or preexisting atom)
+    # and returns self
+    def <<(arg, bond_order=1)
+      last_atom = atoms[-1]
+      if last_atom
+        last_atom.add_atom!(arg, bond_order)
+      else
+        add_atom!(arg)
+      end
+      self
+    end
+
     # sensitive to add_h!
     def num_atoms() @ob.num_atoms  end
     def num_bonds() @ob.num_bonds  end
@@ -568,9 +594,9 @@ module Rubabel
       end
     end
 
-    # writes to the file based on the extension given.  If type is given
-    # explicitly, then it is used.  If png is the extension or format, the
-    # png is generated from an svg.
+    # writes to the file based on the extension given (must be recognized by
+    # OpenBabel).  If png is the extension or format, the png is generated
+    # from an svg.
     def write_file(filename, out_options={})
       type = Rubabel.filetype(filename)
       File.write(filename, write_string(type, out_options))

data/spec/rubabel/atom_spec.rb

@@ -5,7 +5,7 @@ require 'rubabel/atom'
 
 describe Rubabel::Atom do
 
-  it 'can be created given an element symbol' do
+  xit 'can be created given an element symbol' do
     hydrogen = Rubabel::Atom[:h]
     hydrogen.el.should == :h
 
@@ -17,6 +17,19 @@ describe Rubabel::Atom do
     chlorine.id.should == 3
   end
 
+  describe 'attaching another atom to itself (as part of a molecule)' do
+
+    it 'attaches preformed atom' do
+    end
+
+    it 'attaches given an atomic number' do
+    end
+
+    it 'attaches given an element symbol' do
+    end
+
+  end
+
   specify 'equality' do
     mol = Rubabel["CCO"]
     oxygen = mol.atoms[2]
@@ -76,13 +89,19 @@ describe Rubabel::Atom do
       end
     end
 
+    specify '#<<(atom) adds an atom and returns the added atom' do
+      mol = Rubabel["C"]
+      reply = (mol[0] << :n << :o)
+      reply.should be_a(Rubabel::Atom)
+      mol.csmiles.should == 'CNO'
+    end
 
     it '#mol retrieves the parent molecule' do
       @atom.mol.should == @mol
 
-      # no parent molecule 
-      h = Rubabel::Atom[:h]
-      h.mol.should be_nil
+      ## no parent molecule 
+      #h = Rubabel::Atom[:h]
+      #h.mol.should be_nil
     end
 
     it 'can get the bonds' do
@@ -92,8 +111,7 @@ describe Rubabel::Atom do
       @atom.bonds.size.should == 4
     end
 
-    it 'can add a bond' do
-    end
+    it 'can add a bond'
 
     it 'can get the neighboring atoms' do
       @atom.id.should == 0

data/spec/rubabel/molecule_spec.rb

@@ -8,6 +8,17 @@ describe Rubabel::Molecule do
       mol = Rubabel["CC(O)O"]
       mol.csmiles.should == "CC(O)O"
     end
+
+    it 'can be made with an existing obmol object' do
+      mol = Rubabel["CC(O)O"]
+      mol_dup = Rubabel::Molecule.new(mol.ob)
+    end
+
+    it 'can be made fresh' do
+      mol = Rubabel::Molecule.new
+      mol.atoms.size == 0
+      mol.title.should == ''
+    end
   end
 
   #xit 'can add a hydrogen to the formula' do
@@ -58,25 +69,59 @@ describe Rubabel::Molecule do
     mol1 = Rubabel["CCO"]
     mol2 = Rubabel["OCC"]
     (mol1 == mol2).should be_true
-    mol2.atoms[0].charge += 1
+    mol2[0].charge += 1
     (mol1 == mol2).should be_false
     mol3 = Rubabel["CCCO"]
     (mol1 == mol3).should be_false
   end
 
-  specify '#add_atom! adds an atom given an atomic number and returns it' do
-    mol = Rubabel["CCO"]
-    before_size = mol.atoms.size
-    atom = mol.add_atom!(6)
-    atom.el.should == :c
-    (mol.atoms.size - before_size).should == 1
-    mol.csmiles.should == "CCO.C"
+  specify '#[] retrieves atom by index' do
+    mol = Rubabel["NCO"]
+    mol[0].el.should == :n
+    mol[1].el.should == :c
+    mol[2].el.should == :o
+    mol[-1].el.should == :o
+    mol[-2].el.should == :c
+    ar = mol[1..-1]
+    ar.first.el.should == :c
+    ar.last.el.should == :o
+    ar.size.should == 2
+  end
+
+  describe 'adding an atom' do
+    it 'can be added but not attached' do
+      mol = Rubabel["CCO"]
+      atom = mol.add_atom!(:n)
+      atom.el.should == :n
+      atom = mol.add_atom!(8)
+      atom.el.should == :o
+      mol.csmiles.should == "CCO.N.O"
+    end
+
+    it "can be added and attached by el symbol or atomic number" do 
+      mol = Rubabel["CCO"]
+      first_carbon = mol[0]
+      mol.add_atom!(:n, first_carbon)
+      mol.csmiles.should == "NCCO"
+
+      mol.add_atom!(16, first_carbon)
+      mol.csmiles.should == "NC(CO)S"
+    end
+
+  end
+  
+  specify '#<< adds atom to the last atom and returns the mol' do
+    mol = Rubabel::Molecule.new
+    # by element symbol or atomic number
+    reply = (mol << :n << :c)
+    reply.should be_a(Rubabel::Molecule)
+    reply.csmiles.should == 'CN'
   end
 
   specify '#dup duplicates the molecule' do
     mol = Rubabel["CCO"]
     dup_mol = mol.dup
-    mol.atoms[0].ob.set_atomic_num(9)
+    mol[0].ob.set_atomic_num(9)
     mol.csmiles.should == "OCF"
     dup_mol.csmiles.should == "CCO"
   end
@@ -87,7 +132,7 @@ describe Rubabel::Molecule do
     specify 'given two atoms' do
       mol = Rubabel["CCO"]
       atom = mol.add_atom!(0)
-      mol.add_bond!(mol.atoms[1], atom)
+      mol.add_bond!(mol[1], atom)
       mol.csmiles.should == '*C(O)C'
     end
   end
@@ -148,7 +193,7 @@ describe Rubabel::Molecule do
     subject { mol = Rubabel["CC"] }
     it 'can be turned into a carbocation' do
       mol = subject
-      c = mol.atoms[0]
+      c = mol[0]
       c.ob.set_spin_multiplicity 2
       c.charge += 1
       mol.csmiles.should == "C[CH2+]"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubabel
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -116,12 +116,12 @@ executables:
 extensions: []
 extra_rdoc_files:
 - LICENSE
-- README.rdoc
+- README.md
 files:
 - .document
 - .rspec
 - LICENSE
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - bin/fragmenter.rb

data/README.rdoc

@@ -1,56 +0,0 @@
-= rubabel
-
-Ruby interface to the openbabel ruby bindings (or the openbabel gem).  The
-interface attempts to be a ruby-ish analogue of
-{pybel}[http://openbabel.org/docs/current/UseTheLibrary/Python_PybelAPI.html].
-
-== Examples
-
-    Rubabel.foreach("file.sdf") do |mol|
-      print mol.write  # -> canonical smiles: "smiles_string\tname\n"
-      puts mol  # .to_s -> canonical smiles string with no name or newline
-      puts mol.exact_mass
-    end
-
-    uniq_atom_types = Rubabel.foreach("file.mol").map(&:type).uniq
-
-== Installing
-
-First, many thanks to Andreas Maunz for packaging openbabel as a gem which makes this install quite painless.
-
-=== Quick Install
-
-On a POSIX system, make sure you have openbabel (including header files), cmake, curl, tar, sed and make {see openbabel instructions}[https://github.com/amaunz/openbabel-gem].  On ubuntu/debian:
-
-    sudo apt-get install openbabel libopenbabel-dev cmake make curl
-
-Then install the gem (which should install the openbabel gem, too):
-
-    gem install rubabel
-
-=== Building from Source
-
-1. download openbabel 
-2. swap out Init_OpenBabel for Init_openbabel in scripts/ruby/openbabel-ruby.cpp (see here[http://forums.openbabel.org/Ruby-Open-Babel-in-2-1-1-td957640.html]).  Some versions have this fixed already, apparently.
-3. make sure you have the right {dependencies to compile}(http://openbabel.org/docs/2.3.1/Installation/install.html#compiling-open-babel)
-
-Here's a complete example of compiling for a single user on Ubuntu 11.10 and probably will be generally forward compatible for some time.  This will compile bindings on whichever ruby comes up with '/usr/bin/env ruby':
-
-    # install the dependencies:
-    sudo apt-get install libeigen2-dev cmake libwxgtk2.8-dev libxml2-dev libcairo2-dev
-    # unpack it:
-    tar -xzvf openbabel-2.3.1.tar.gz
-    # swap out buggy lines in ruby bindings:
-    sed -i 's/Init_OpenBabel/Init_openbabel/g' openbabel-2.3.1/scripts/ruby/openbabel-ruby.cpp
-    # make a separate build directory for building in:
-    mkdir build-rvmruby1.9.3
-    cd build-rvmruby1.9.3
-    mkdir ~/tools
-    cmake ../openbabel-2.3.1 -DRUBY_BINDINGS=ON -DCMAKE_INSTALL_PREFIX=~/tools/openbabel-rvmruby1.9.3
-    make && make install
-
-[I still need to make directions to install the gem on top of a build from source]
- 
-== Copyright
-
-MIT License.  See LICENSE for further details.