{"id":16618622,"url":"https://github.com/brentp/hts-nim","last_synced_at":"2025-03-11T05:45:52.314Z","repository":{"id":42084419,"uuid":"100417204","full_name":"brentp/hts-nim","owner":"brentp","description":"nim wrapper for htslib for parsing genomics data files","archived":false,"fork":false,"pushed_at":"2024-08-27T17:13:30.000Z","size":1796,"stargazers_count":155,"open_issues_count":6,"forks_count":26,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-01-17T20:46:24.682Z","etag":null,"topics":["bioinformatics","genomics","high-throughput-sequencing","htslib","nim","nim-lang"],"latest_commit_sha":null,"homepage":"https://brentp.github.io/hts-nim/","language":"Nim","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/brentp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2017-08-15T20:34:38.000Z","updated_at":"2024-08-27T17:13:34.000Z","dependencies_parsed_at":"2023-01-19T07:01:08.152Z","dependency_job_id":"6c960605-adf9-47bc-9fe0-4a34ef5220a4","html_url":"https://github.com/brentp/hts-nim","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brentp%2Fhts-nim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brentp%2Fhts-nim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brentp%2Fhts-nim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brentp%2Fhts-nim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brentp","download_url":"https://codeload.github.com/brentp/hts-nim/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242980782,"owners_count":20216285,"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","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":["bioinformatics","genomics","high-throughput-sequencing","htslib","nim","nim-lang"],"created_at":"2024-10-12T02:20:56.425Z","updated_at":"2025-03-11T05:45:52.283Z","avatar_url":"https://github.com/brentp.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"hts-nim\n=======\n\n\u003ch4\u003e\nv0.2.23 of hts-nim will be the last version that supports htslib below 1.10 (which was release in early december 2019).\nThe master branch requires htslib 1.10 and higher and will be backward incompatible with previous releases.\n\u003c/h4\u003e\n\n\n[![badge](https://img.shields.io/badge/docs-latest-blue.svg)](https://brentp.github.io/hts-nim/) [![Build Status](https://travis-ci.com/brentp/hts-nim.svg?branch=master)](https://travis-ci.com/brentp/hts-nim)\n\n\nThis is a wrapper for [htslib](https://github.com/samtools/htslib) in [nim](https://nim-lang.org). \n\nNim is a fast, garbage-collected language that compiles to C and has a syntax that's not\ntoo different to python.\n\nIf you use this library, please cite [the paper](https://academic.oup.com/bioinformatics/advance-article-abstract/doi/10.1093/bioinformatics/bty358/4990493)\n\nProjects using `hts-nim` are accumulating [in the wiki](https://github.com/brentp/hts-nim/wiki/Example-uses-of-hts-nim)\n\n## Installation\n\nSee Section Below\n\n# Usage\n\nExamples of `hts-nim` tools are available in the [hts-nim-tools repo](https://github.com/brentp/hts-nim-tools)\n\nbelow are examples of the syntax in this library see the [docs](https://brentp.github.io/hts-nim/) for more info:\n\nAlso see examples and other repos using hts-nim in the [wiki](https://github.com/brentp/hts-nim/wiki/Example-uses-of-hts-nim)\n\n## BAM / CRAM / SAM\n\n#### See API docs [here](https://brentp.github.io/hts-nim/hts/bam.html)\n\n```nim\nimport hts\n\n# open a bam/cram and look for the index.\nvar b:Bam\nopen(b, \"tests/HG02002.bam\", index=true, fai=\"/data/human/g1k_v37_decoy.fa\")\n\nfor record in b:\n  if record.mapping_quality \u003e 10u:\n    echo record.chrom, record.start, record.stop\n\n# regional queries:\nfor record in b.query(\"6\", 30816675, 32816675):\n  if record.flag.proper_pair and record.flag.reverse:\n    # cigar is an iterable of operations:\n    for op in record.cigar:\n      # $op gives the string repr of the operation, e.g. '151M'\n      echo $op, \" \", op.consumes.reference, \" \", op.consumes.query\n\n    # tags are pulled by type `ta`\n    var mismatches = tag[int](record, \"NM\")\n    if not mismatches.isNone and mismatches.get \u003c 3:\n      var rg = tag[string](record, \"RG\")\n      if not rg.isNone: echo rg.get\n```\n\n## VCF / BCF\n\n#### See API docs [here](https://brentp.github.io/hts-nim/hts/vcf.html)\n\n```nim\nimport hts\n\nvar tsamples = @[\"101976-101976\", \"100920-100920\", \"100231-100231\", \"100232-100232\", \"100919-100919\"]\n# VCF and BCF supported\nvar v:VCF\ndoAssert(open(v, \"tests/test.bcf\", samples=tsamples))\n\nvar afs = new_seq[float32](5) # size doesn't matter. this will be re-sized as needed\nvar acs = new_seq[int32](5) # size doesn't matter. this will be re-sized as needed\nvar csq = new_string_of_cap(20)\nfor rec in v:\n  echo rec, \" qual:\", rec.QUAL, \" filter:\", rec.FILTER\n  var info = rec.info\n  # accessing stuff from the INFO field is meant to be as fast as possible, allowing\n  # the user to re-use memory as needed.\n  doAssert info.get(\"CSQ\", csq) == Status.OK # string\n  doAssert info.get(\"AC\", acs) == Status.OK # ints\n  doAssert info.get(\"AF\", afs) == Status.OK # floats\n  echo acs, afs, csq, info.has_flag(\"IN_EXAC\")\n\n  # accessing format fields is similar\n  var dps = new_seq[int32](len(v.samples))\n  doAssert rec.format.get(\"DP\", dps) == Status.OK\n\n# open a VCF for writing\nvar wtr:VCF\ndoAssert(open(wtr, \"tests/outv.vcf\", mode=\"w\"))\nwtr.header = v.header\ndoAssert(wtr.write_header())\n\n# regional queries look for index. works for VCF and BCF\nfor rec in v.query(\"1:15600-18250\"):\n  echo rec.CHROM, \":\", $rec.POS\n  # adjust some values in the INFO\n  var val = 22.3\n  doAssert rec.info.set(\"VQSLOD\", val) == Status.OK\n  doAssert wtr.write_variant(rec)\n\n# Generate index files - .vcf.gz (tbi + csi ) \u0026 .bcf (csi)\nvar fnameInNew = \"tests/test.bcf\"\nvar fnameIndexCsi = \"tests/test00.bcf.csi\"\nbcfBuildIndex(fnameInNew, fnameIndexCsi, true) # `true` for csi and `false` for tbi\n\n```\n\n## TSV files\n\n```nim\nimport hts\n\nvar b: BGZI\ndoAssert b.open(\"ti.txt.gz\")  # Requires a CSI index: ti.txt.gz.csi\n\nfor reg in b.query(\"aaa\", 1, 5):\n  echo reg\n```\n\n\n## Setup / Installation\n\n`hts-nim` requires that [htslib](https://github.com/samtools/htslib) is installed and the shared library is available\n(use `LD_LIBRARY_PATH` if it is not in a standard location).\n\n\nIf you use docker, you can use one of [these images](https://hub.docker.com/r/nimlang/nim/) to get Nim installed.\n\nOr you can copy the [Dockerfile from this repo](https://github.com/brentp/hts-nim/blob/master/Dockerfile)\n\nIf you don't use docker, you can use [choosenim](https://github.com/dom96/choosenim) to quickly install Nim and nimble.\n\nUsers can also either follow or run [scripts/simple-install.sh](https://github.com/brentp/hts-nim/blob/master/scripts/simple-install.sh) which sets up Nim and nimble ready for use and shows the needed adjustments to `$PATH`.\n\nOnce Nim is set up, `hts-nim` can be installed with `nimble install -y` from the root of this repository.\n\nIn all cases, it's recommended to use nim version 0.18.0 or more recent.\n\nThen, from this repo you can run `nimble test` and `nimble install` and then you can save the above snippets into `some.nim`\nand run them with `nim c -d:release -r some.nim`. This will run them and save an executable named `some`.\n\n## Static Builds\n\n`hts-nim` is meant to simplify and speed development and distribution. To that end, there is some machinery to help create\ntruly static binaries for linux from nim-projects and for simple nim scripts. This means that there is no dependency on libhts.so. These builds only require docker and [this static binary](https://github.com/brentp/hts-nim/releases/download/v0.2.8/hts_nim_static_builder).\n\nFor a single file application that does not have a nimble file we can specify the dependencies using `--deps`:\n\n```\nhts_nim_static_builder -s vcf_cleaner.nim --deps \"hts@\u003e=0.2.7\" --deps \"binaryheap\"\n```\n\nThis will create a static binary at `./vcf_cleaner`.\n\n\n\nProjects with `.nimble` files can use that directly to indicate dependencies.\nFor example, to build [slivar](https://github.com/brentp/slivar), we can do:\n\n```\nhts_nim_static_builder -s ../slivar/src/slivar.nim -n ../slivar/slivar.nimble\n```\n\nAfter this finishes, a static `slivar` binary will appear in the current working directory.\n\nWe can verify that it is static using:\n\n```\n$ file ./slivar \n./slivar: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked, for GNU/Linux 2.6.18, BuildID[sha1]=c2b5b52cb7be7f81bf90355a4e44a08a08df91d8, not stripped\n```\n\nThe [docker image](https://hub.docker.com/r/brentp/musl-hts-nim) is based on alpine linux and uses musl to create truly static binaries.\nAt this time, libcurl is not supported so only binaries built using this method will only be able to access local files (no http/https/s3/gcs).\n\nThe docker images does use [libdeflate](https://github.com/ebiggers/libdeflate) by default. That provides,\nfor example, a 20% speed improvement when used to build [mosdepth](https://github.com/brentp/mosdepth).\n\n### Static binary with singularity\n\nThe default static build setup uses docker on linux. This is not possible on some clusters. To build a project using singularity, use something like this:\n\n```\nsingularity run \\\n\t    --bind $(pwd):/load \\\n\t    --bind /scratch \\\n\t    --bind /uufs \\\n            'docker://brentp/musl-hts-nim:latest' /usr/local/bin/nsb -n slivar.nimble -s src/slivar.nim -- -d:danger -d:release\n```\nwhere the first `bind` is required as-is. The other binds can be modified to adjust which paths on the machine need to be available to access all \nlocal source files. This command will create a `slivar` executable in `pwd`.\nThen, replace `slivar.nimble` with your nimble file and `src/slivar.nim` with your main source file.\nIt's also sometimes useful to replace `-d:danger -d:release` with `-d:debug` to get a debug build.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrentp%2Fhts-nim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrentp%2Fhts-nim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrentp%2Fhts-nim/lists"}