The original project samtools-ruby belongs to Ricardo H. Ramirez @


Documentation and code come from that project and we'll adapt it for a better integration in BioRuby.

Binder of samtools for ruby, on the top of FFI.

This project was born from the need to add support of BAM files to the gee_fu genome browser (


'gem install bio-samtools'


See doc/tutorial.html or doc/tutorial.pdf for a walkthrough tutorial. The documentation in doc/index.html provides information on individual objects and methods.

The easiest way to see bio-samtools in action is to try the tests: rake test is all you should need to get the tests to run.

However on some systems (at least the one belonging to one of our developers on Mac OS X Lion, with the Apple provided Ruby) then you can get a LoadError: no such file to load 'ffi', despite it being installed. This is something to do with RubyGems and rake test that we haven't got to the bottom of yet. The workaround is to run the tests manually. 1) change into the directory bio-samtools installed into (you can find this with the command 'gem which bio-samtools') 2) run the tests as if they were any other ruby script eg ruby test/test_pileup.rb


-FFI (


I´m getting a segmentation Fault, what did I do wrong? -There are two known segmentation faults at the moment -When you try to load a text file as binary file -When you try to lad a binary file as a text file

I keep seeing this “Invalid gemspec in [some ruby gem path…]”, what is wrong?

  • This appears to be a bug in RubyGems that doesn't affect the running of the tools. It will keep happening until someone updates RubyGems. If it really bugs you, downgrade RubyGems.

To whom do I complain? -about bio-samtools? Try Ricardo dot Ramirez-Gonzalez at tgac dot ac dot uk


-Filter to the fetching algorithm (give a condition that has to be satisfied to add the alignment to the list)


-Libraries (libbam) are downloaded, compiled and installed inside the gem at install time on the host system

$ openssl dgst MD5( c45cfccfb41ffeb2730ee4b227d244c4

Contributing to bio-samtools

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it

  • Fork the project

  • Start a feature/bugfix branch

  • Commit and push until you are happy with your contribution

  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Important Notes for developers

Remember that you must compile and install the right libbam library for you host system. In order to do that there are three possible solutions:

  • download, compile and install the library in bioruby-samtools-your_clone/lib/bio/db/sam/external/libbam.xxxxx by yourself

  • install the gem and then grab the compiled library cp `locate libbam.1.dylib` bioruby-samtools-your_clone/lib/bio/db/sam/external (library name is an example)

  • in your bioruby-samtools-your_clone create the Rakefile typing “cd ext; ruby mkrf_conf.rb; rake -f Rakefile”

The latest I think is the easiest way, cause you are replicating the automatic process.

For testing just run `rake test`. Tests must be improved.


Copyright © 2011 Raoul J.P. Bonnal. See LICENSE.txt for further details.