{"id":15579344,"url":"https://github.com/davep/org-davep-2bit","last_synced_at":"2026-01-24T16:38:41.513Z","repository":{"id":66520600,"uuid":"286046582","full_name":"davep/org-davep-2bit","owner":"davep","description":"Common Lisp code to read data from 2bit files (work-in-progress personal play project)","archived":false,"fork":false,"pushed_at":"2020-08-22T12:59:31.000Z","size":89,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-06T18:15:46.144Z","etag":null,"topics":["2bit","common-lisp","file-format","lisp"],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2020-08-08T13:16:47.000Z","updated_at":"2024-02-12T04:42:02.000Z","dependencies_parsed_at":"2023-02-22T14:30:21.367Z","dependency_job_id":null,"html_url":"https://github.com/davep/org-davep-2bit","commit_stats":{"total_commits":53,"total_committers":1,"mean_commits":53.0,"dds":0.0,"last_synced_commit":"d2567fa0b523dc0150146fa580abb4bf3ded2e37"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davep%2Forg-davep-2bit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davep%2Forg-davep-2bit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davep%2Forg-davep-2bit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davep%2Forg-davep-2bit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davep","download_url":"https://codeload.github.com/davep/org-davep-2bit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253980062,"owners_count":21994042,"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":["2bit","common-lisp","file-format","lisp"],"created_at":"2024-10-02T19:14:37.652Z","updated_at":"2026-01-24T16:38:41.487Z","avatar_url":"https://github.com/davep.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# org-davep-2bit\n\n## Introduction\n\n`org-davep-2bit` is a small Common Lisp library that provides code for\nreading data from [`2bit` format\nfiles](https://genome.ucsc.edu/FAQ/FAQformat.html#format7). These are files\nthat can hold DNA sequences in a compressed format. You'll see examples of\nthis if you look at the [human genome\ndata](http://hgdownload.cse.ucsc.edu/goldenPath/hg38/bigZips/), for example.\nI believe there are other bodies of code out there for doing this, I wrote\nthis one with two main motivations in mind:\n\n1. To de-rust my rusty Common Lisp -- I'd not written anything in CL for a\n   while and wanted to refresh my memory about CL itself, and also using\n   [SLIME](https://common-lisp.net/project/slime/) in Emacs.\n2. I wanted to write a 2bit reader that could provide different routes to\n   reading the code. So, not just reading from a local file, but also\n   reading via HTTP(S) from a remote file (as you'll see happen in a\n   web-based genome browser such as\n   [Biodalliance](https://www.biodalliance.org/)).\n\nNote that, as of the time of writing, the code is designed such that the\nlatter can happen, but only reading from a local file has been implemented.\nAdding support for remote reading of 2bit files is left as an exercise for\nme to tinker with over time.\n\n## Usage\n\nThe library is broken up into two main classes, a reader class and a\nsequence class. The sequence class (called `2bit-sequence`) is what provides\naccess to the content of an actual sequence within the 2bit file, whereas\nthe reader class does the work of reading data from a 2bit source.\n\nNote that all code lives within a package called `org.davep.2bit`. See\n[`packages.lisp`](./packages.lisp) for a list of the exported symbols.\n\n### The reader class\n\nFor now the main reader class to use is `file-reader`. A helper function\ncalled `make-file-reader` is available to quickly and easily create an\ninstance of a `file-reader`. For example:\n\n```lisp\nCL-USER\u003e (in-package :2bit)\n#\u003cPACKAGE \"ORG.DAVEP.2BIT\"\u003e\n2BIT\u003e (make-file-reader \"hg38.2bit\")\n#\u003cFILE-READER \"hg38.2bit\" :masking T\u003e\n```\n\nThe reader class offers the following methods:\n\n#### open-reader\n\nGiven an instance of a reader, this method opens the connection to the\nsource data. For example:\n\n```lisp\nCL-USER\u003e (in-package :2bit)\n#\u003cPACKAGE \"ORG.DAVEP.2BIT\"\u003e\n2BIT\u003e (make-file-reader \"hg38.2bit\")\n#\u003cFILE-READER \"hg38.2bit\" :masking T\u003e\n2BIT\u003e (open-reader *)\n#\u003cFILE-READER \"hg38.2bit\" :masking T\u003e\n```\n\nOnce the reader is open the content can be accessed (see below).\n\n#### close-reader\n\nGiven an instance of a reader, this method closes the connection to the\nsource data. For example:\n\n```lisp\nCL-USER\u003e (in-package :2bit)\n#\u003cPACKAGE \"ORG.DAVEP.2BIT\"\u003e\n2BIT\u003e (make-file-reader \"hg38.2bit\")\n#\u003cFILE-READER \"hg38.2bit\" :masking T\u003e\n2BIT\u003e (open-reader *)\n#\u003cFILE-READER \"hg38.2bit\" :masking T\u003e\n2BIT\u003e (close-reader *)\nT\n2BIT\u003e\n```\n\n#### sequences\n\nGiven an open reader object, this method returns a list of all of names of\nall of the sequences held in the 2bit data. For example:\n\n```lisp\n2BIT\u003e (open-reader (make-file-reader \"hg38.2bit\"))\n#\u003cFILE-READER \"hg38.2bit\" :masking T\u003e\n2BIT\u003e (sequences *)\n(\"chr1\" \"chr10\" \"chr11\" \"chr11_KI270721v1_random\" \"chr12\" \"chr13\" \"chr14\"\n [...SNIP...] \"chrY_KI270740v1_random\")\n2BIT\u003e\n```\n\n#### seq\n\nGiven an open reader object, this method provides access to a particular\nnamed sequence. For example:\n\n```lisp\n2BIT\u003e (open-reader (make-file-reader \"hg38.2bit\"))\n#\u003cFILE-READER \"hg38.2bit\" :masking T\u003e\n2BIT\u003e (seq * \"chr1\")\n#\u003c2BIT-SEQUENCE \"chr1\" 10487\u003e\n2BIT\u003e\n```\n\n### The sequence class\n\nAs mentioned above, access to the actual sequence data is done via the\n`2bit-sequence` class -- this is what is returned by the call to `seq`\nmentioned above. Currently there is just one main method associated with\nthis class:\n\n#### bases\n\nThis method is used to get bases from the sequence. The parameters are the\nsequence to pull the bases from, the start location within the sequence, and\nthe end location within the sequence. Note that, as is the usual convention,\nwhat's returned is *inclusive* of the start location but *exclusive* of the\nend location.\n\nFor example:\n\n```lisp\n2BIT\u003e (open-reader (make-file-reader \"hg38.2bit\"))\n#\u003cFILE-READER \"hg38.2bit\" :masking T\u003e\n2BIT\u003e (seq * \"chr1\")\n#\u003c2BIT-SEQUENCE \"chr1\" 10487\u003e\n2BIT\u003e (bases * 10000 10010)\n\"taaccctaac\"\n2BIT\u003e\n```\n\n### Helper macro\n\nNote that, when creating and using a reader object yourself, it's very\nimportant that you open it, only use it while open, and then close it once\nyou're finished. No sequence access can happen on a reader that is no longer\nopen. Closing once you're finished is just good resource use.\n\nTo help with smaller calls to the data a `with-2bit-file` macro is made\navailable. For example:\n\n```lisp\n2BIT\u003e (with-2bit-file (human \"hg38.2bit\")\n        (format t \"~S\" (bases (seq human \"chr1\") 10000 10010)))\n\"taaccctaac\"\nNIL\n2BIT\u003e\n```\n\nThis takes care of opening the reader for you, and closing it again\nafterwards.\n\n[//]: # (README.md ends here)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavep%2Forg-davep-2bit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavep%2Forg-davep-2bit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavep%2Forg-davep-2bit/lists"}