README

= Molecules

A library of molecules for scientific calculations in Ruby.

== Description

Molecules provides libraries of commonly used molecules (currently just amino
acid residues and polypeptides).  Library classes inherit from EmpiricalFormula
which allows calculation of molecular composition and mass, as well as
adding/subtraction of other molecules.

I have attempted to use reputable sources and to adhere to standards when 
applicable.  Please notify me of any errors and send me suggestions!

* Rubyforge[http://rubyforge.org/projects/bioactive]
* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/13518-molecules/overview]
* Github[http://github.com/bahuvrihi/molecules/tree/master]

== Usage

  require 'molecules'
  include Molecules::Libraries
  
  # Residue predefines all common amino acids
  # as well as some uncommon ones.
  r = Residue::A
  r.name               # => "Alanine"
  r.abbr               # => "Ala"
  r.letter             # => "A"
  r.side_chain.to_s    # => "CH(3)"
  r.mass               # => 71.03711
  r.immonium_ion_mass  # => 44.0500
  
  # Polypeptide allows for creation of polypeptides
  # from residue sequences.
  p = Polypeptide.new("RPPGFSPFR")
  p.to_s               # => "C(50)H(71)N(15)O(10)"
  p.mass               # => 1041.5508
  
  # Generic molecules may be specified with EmpiricalFormula.
  caffeine = Molecules::EmpiricalFormula.parse("C8H10N4O2")
  coffee = Molecules::EmpiricalFormula.parse("C8H10N4O2 + H2O")

=== Mass Calculator (tap task)

Molecules provides a mass calculator tap task.  Tap[http://tap.rubyforge.org] 
is not required by molecules in general, but you get this bonus if you have tap
installed:

  % tap run -- molecules/calc H2O
    I[17:08:00]   18.0105646863 Da H2O

== Known Issues

* Polypeptide only allows common residues
* No 'Molecule' class is defined, pending the potential addition
  of more molecule data (ex: SMILES[http://en.wikipedia.org/wiki/Simplified_molecular_input_line_entry_specification]
  data)
* No mechanism for defining large libraries of molecules has been
  chosen.  A database solution may be adopted to this end.
  
== Installation

Molecules is available as a gem through RubyForge[http://rubyforge.org/projects/bioactive].  Use:

  % gem install molecules

== Info 

Copyright (c) 2006-2008, Regents of the University of Colorado.
Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com], {Biomolecular Structure Program}[http://biomol.uchsc.edu/], {Hansen Lab}[http://hsc-proteomics.uchsc.edu/hansenlab/] 
Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
Licence:: MIT-Style