{"id":17220798,"url":"https://github.com/kojix2/ruby-htslib","last_synced_at":"2025-08-25T22:09:10.300Z","repository":{"id":42523781,"uuid":"247078205","full_name":"kojix2/ruby-htslib","owner":"kojix2","description":"HTSlib bindings for Ruby","archived":false,"fork":false,"pushed_at":"2025-08-11T07:16:20.000Z","size":3920,"stargazers_count":11,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-08-11T07:24:14.258Z","etag":null,"topics":["bam","bcf","bioinformatics","genomics","htslib","ruby","sam"],"latest_commit_sha":null,"homepage":"https://kojix2.github.io/ruby-htslib/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kojix2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"ko_fi":"kojix2"}},"created_at":"2020-03-13T13:31:20.000Z","updated_at":"2025-08-11T07:16:05.000Z","dependencies_parsed_at":"2024-02-10T01:29:05.716Z","dependency_job_id":"74a9edef-7be6-4e15-9916-bf7359b443c0","html_url":"https://github.com/kojix2/ruby-htslib","commit_stats":{"total_commits":769,"total_committers":1,"mean_commits":769.0,"dds":0.0,"last_synced_commit":"e7da178cfe5475907d252b22c8ec08753fcb4c1f"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/kojix2/ruby-htslib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kojix2%2Fruby-htslib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kojix2%2Fruby-htslib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kojix2%2Fruby-htslib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kojix2%2Fruby-htslib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kojix2","download_url":"https://codeload.github.com/kojix2/ruby-htslib/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kojix2%2Fruby-htslib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272139139,"owners_count":24880250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bam","bcf","bioinformatics","genomics","htslib","ruby","sam"],"created_at":"2024-10-15T03:53:13.043Z","updated_at":"2025-08-25T22:09:10.280Z","avatar_url":"https://github.com/kojix2.png","language":"Ruby","funding_links":["https://ko-fi.com/kojix2","https://github.com/sponsors/kojix2"],"categories":[],"sub_categories":[],"readme":"# ruby-htslib\n\n[![Gem Version](https://badge.fury.io/rb/htslib.svg)](https://badge.fury.io/rb/htslib)\n[![test](https://github.com/kojix2/ruby-htslib/actions/workflows/ci.yml/badge.svg)](https://github.com/kojix2/ruby-htslib/actions/workflows/ci.yml)\n[![The MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)\n[![DOI](https://zenodo.org/badge/247078205.svg)](https://zenodo.org/badge/latestdoi/247078205)\n[![Docs Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://rubydoc.info/gems/htslib)\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kojix2/ruby-htslib)\n[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Fruby-htslib%2Flines)](https://tokei.kojix2.net/github/kojix2/ruby-htslib)\n\nRuby-htslib is the [Ruby](https://www.ruby-lang.org) bindings to [HTSlib](https://github.com/samtools/htslib), a C library for high-throughput sequencing data formats. It allows you to read and write file formats commonly used in genomics, such as [SAM, BAM, VCF, and BCF](http://samtools.github.io/hts-specs/), in the Ruby language.\n\n:apple: Feel free to fork it!\n\n## Requirements\n\n- [Ruby](https://github.com/ruby/ruby) 3.1 or above.\n- [HTSlib](https://github.com/samtools/htslib)\n  - Ubuntu : `apt install libhts-dev`\n  - macOS : `brew install htslib`\n  - Windows : [mingw-w64-htslib](https://packages.msys2.org/base/mingw-w64-htslib) is automatically fetched when installing the gem ([RubyInstaller](https://rubyinstaller.org) only).\n  - Build from source code (see the Development section)\n\n## Installation\n\n```sh\ngem install htslib\n```\n\nIf you have installed htslib with apt on Ubuntu or homebrew on Mac, [pkg-config](https://github.com/ruby-gnome/pkg-config)\nwill automatically detect the location of the shared library. If pkg-config does not work well, set `PKG_CONFIG_PATH`.\nAlternatively, you can specify the directory of the shared library by setting the environment variable `HTSLIBDIR`.\n\n```sh\nexport HTSLIBDIR=\"/your/path/to/htslib\" # Directory where libhts.so is located\n```\n\nruby-htslib also works on Windows. If you use RubyInstaller, htslib will be prepared automatically.\n\n## Usage\n\n### HTS::Bam - SAM / BAM / CRAM - Sequence Alignment Map file\n\nReading fields\n\n```ruby\nrequire 'htslib'\n\nbam = HTS::Bam.open(\"test/fixtures/moo.bam\")\n\nbam.each do |r|\n  pp name: r.qname,\n     flag: r.flag,\n     chrm: r.chrom,\n     strt: r.pos + 1,\n     mapq: r.mapq,\n     cigr: r.cigar.to_s,\n     mchr: r.mate_chrom,\n     mpos: r.mpos + 1,\n     isiz: r.isize,\n     seqs: r.seq,\n     qual: r.qual_string,\n     MC:   r.aux(\"MC\")\nend\n\nbam.close\n```\n\nWith a block\n\n```ruby\nHTS::Bam.open(\"test/fixtures/moo.bam\") do |bam|\n  bam.each do |r|\n    puts r.to_s\n  end\nend\n```\n\n### HTS::Bcf - VCF / BCF - Variant Call Format file\n\nReading fields\n\n```ruby\nrequire 'htslib'\n\nbcf = HTS::Bcf.open(\"test/fixtures/test.bcf\")\n\nbcf.each do |r|\n  p chrom:  r.chrom,\n    pos:    r.pos,\n    id:     r.id,\n    qual:   r.qual.round(2),\n    ref:    r.ref,\n    alt:    r.alt,\n    filter: r.filter,\n    info:   r.info.to_h,\n    format: r.format.to_h\nend\n\nbcf.close\n```\n\nWith a block\n\n```ruby\nHTS::Bcf.open(\"test/fixtures/test.bcf\") do |bcf|\n  bcf.each do |r|\n    puts r.to_s\n  end\nend\n```\n\n### HTS::Faidx - FASTA / FASTQ - Nucleic acid sequence\n\n```ruby\nfa = HTS::Faidx.open(\"test/fixtures/moo.fa\")\nfa.seq(\"chr1:1-10\") # =\u003e CGCAACCCGA # 1-based\nfa.close\n```\n\n### HTS::Tabix - GFF / BED - TAB-delimited genome position file\n\n```ruby\ntb = HTS::Tabix.open(\"test/fixtures/test.vcf.gz\")\ntb.query(\"poo\", 2000, 3000) do |line|\n  puts line.join(\"\\t\")\nend\ntb.close\n```\n\n### Low-level API\n\nMiddle architectural layer between high-level Ruby code and low-level C code.\n`HTS::LibHTS` provides native C functions using [Ruby-FFI](https://github.com/ffi/ffi). \n\n```ruby\nrequire 'htslib'\n\na = HTS::LibHTS.hts_open(\"a.bam\", \"r\")\nb = HTS::LibHTS.hts_get_format(a)\np b[:category]\np b[:format]\n```\n\nThe low-level API makes it possible to perform detailed operations, such as calling CRAM-specific functions.\n\n#### Macro functions\n\nHTSlib is designed to improve performance with many macro functions. However, it is not possible to call C macro functions directly from Ruby-FFI. To overcome this, important macro functions have been re-implemented in Ruby, allowing them to be called in the same way as native functions.\n\n#### Garbage Collection and Memory Freeing\n\nA small number of commonly used structs, such as `Bam1` and `Bcf1`, are implemented using FFI's `ManagedStruct`. This allows for automatic memory release when Ruby's garbage collection is triggered. On the other hand, other structs are implemented using `FFI::Struct`, and they will require manual memory release.\n\n### Need more speed?\n\nTry Crystal. [HTS.cr](https://github.com/bio-cr/hts.cr) is implemented in Crystal language and provides an API compatible with ruby-htslib. \n\n## Documentation\n\n- [TUTORIAL.md](TUTORIAL.md)\n- [API Documentation (develop branch)](https://kojix2.github.io/ruby-htslib/)\n- [API Documentation (released gem)](https://rubydoc.info/gems/htslib)\n\n## Development\n\n#### Compile from source code\n\n[GNU Autotools](https://en.wikipedia.org/wiki/GNU_Autotools) is required to compile htslib.\nTo get started with development:\n\n```sh\ngit clone --recursive https://github.com/kojix2/ruby-htslib\ncd ruby-htslib\nbundle install\nbundle exec rake htslib:build\nbundle exec rake test\n```\n\n#### Macro functions are reimplemented\n\nHTSlib has many macro functions. These macro functions cannot be called from FFI and must be reimplemented in Ruby.\n\n#### Use the latest Ruby\n\nUse Ruby 3 or newer to take advantage of new features. This is possible because we have a small number of users.\n\n#### Keep compatibility with Crystal language\n\nCompatibility with Crystal language is important for Ruby-htslib development. \n\n- [HTS.cr](https://github.com/bio-cr/hts.cr) - HTSlib bindings for Crystal\n\nReturn value\n\nThe most challenging part is the return value. In the Crystal language, methods are expected to return only one type. On the other hand, in the Ruby language, methods that return multiple classes are very common. For example, in the Crystal language, the compiler gets confused if the return value is one of six types: Int32, Int64, Float32, Float64, Nil, or String. In fact Crystal allows you to do that. But the code gets a little messy. In Ruby, this is very common and doesn't cause any problems.\n\nMemory management\n\nRuby and Crystal are languages that use garbage collection. However, the memory release policy for allocated C structures is slightly different: in Ruby-FFI, you can define a `self.release` method in `FFI::Struct`. This method is called when GC. So you don't have to worry about memory in high-level APIs like Bam::Record or Bcf::Record, etc. Crystal requires you to define a finalize method on each class. So you need to define it in Bam::Record or Bcf::Record.\n\nMacro functions\n\nIn ruby-htslib, C macro functions are added to `LibHTS`, but in Crystal, `LibHTS` is a Lib, so methods cannot be added. methods are added to `LibHTS2`.\n\n#### Naming convention\n\nIf you are not sure about the naming of a method, follow the Rust-htslib API. This is a very weak rule. if a more appropriate name is found later in Ruby, it will replace it.\n\n#### Support for bitfields of structures\n\nSince Ruby-FFI does not support structure bit fields, the following extensions are used.\n\n- [ffi-bitfield](https://github.com/kojix2/ffi-bitfield) - Extension of Ruby-FFI to support bitfields.\n\n#### Automatic validation\n\nIn the `script` directory, there are several tools to help implement ruby-htslib. Scripts using c2ffi can check the coverage of htslib functions in Ruby-htslib. They are useful when new versions of htslib are released.\n\n- [c2ffi](https://github.com/rpav/c2ffi) is a tool to create JSON format metadata from C header files.\n\n## Contributing\n\nRuby-htslib is a library under development, so even minor improvements like typo fixes are welcome! Please feel free to send us your pull requests.\n\n- [Report bugs](https://github.com/kojix2/ruby-htslib/issues)\n- Fix bugs and [submit pull requests](https://github.com/kojix2/ruby-htslib/pulls)\n- Write, clarify, or fix documentation\n- Suggest or add new features\n- [financial contributions](https://github.com/sponsors/kojix2)\n\n```markdown\n# Ownership and Commit Rights\n\nDo you need commit rights to the ruby-htslib repository?\nDo you want to get admin rights and take over the project?\nIf so, please feel free to contact us @kojix2.\n```\n\n#### Why do you implement htslib in a language like Ruby, which is not widely used in bioinformatics?\n\nOne of the greatest joys of using a minor language like Ruby in bioinformatics is that nothing stops you from reinventing the wheel. Reinventing the wheel can be fun. But with languages like Python and R, where many bioinformatics masters work, there is no chance for beginners to create htslib bindings. Bioinformatics file formats, libraries, and tools are very complex, and I need to learn how to understand them. So I started to implement the HTSLib binding myself to better understand how the pioneers of bioinformatics felt when establishing the file format and how they created their tools. I hope one day we can work on bioinformatics using Ruby and Crystal languages, not to replace other languages such as Python and R, but to add new power and value to this advancing field.\n\n## Links\n\n- [samtools/hts-spec](https://github.com/samtools/hts-specs)\n- [bioruby](https://github.com/bioruby/bioruby)\n\n## Funding support\n\nThis work was supported partially by [Ruby Association Grant 2020](https://www.ruby.or.jp/en/news/20201022).\n\n## License\n\n[MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkojix2%2Fruby-htslib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkojix2%2Fruby-htslib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkojix2%2Fruby-htslib/lists"}