{"id":42060205,"url":"https://github.com/statgen/savvy","last_synced_at":"2026-01-26T07:38:52.883Z","repository":{"id":21658799,"uuid":"63503479","full_name":"statgen/savvy","owner":"statgen","description":"Interface to various variant calling formats.","archived":false,"fork":false,"pushed_at":"2024-06-15T15:31:42.000Z","size":1298,"stargazers_count":31,"open_issues_count":10,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-12-08T11:52:35.868Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statgen.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2016-07-16T21:46:15.000Z","updated_at":"2025-12-04T14:10:18.000Z","dependencies_parsed_at":"2023-01-11T21:18:24.651Z","dependency_job_id":"adcb627e-821d-4a0c-b345-5bab83942fc6","html_url":"https://github.com/statgen/savvy","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/statgen/savvy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statgen%2Fsavvy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statgen%2Fsavvy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statgen%2Fsavvy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statgen%2Fsavvy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statgen","download_url":"https://codeload.github.com/statgen/savvy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statgen%2Fsavvy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28769853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T06:37:25.426Z","status":"ssl_error","status_checked_at":"2026-01-26T06:37:23.039Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-26T07:38:51.491Z","updated_at":"2026-01-26T07:38:52.877Z","avatar_url":"https://github.com/statgen.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Anaconda-Server Badge](https://anaconda.org/bioconda/savvy/badges/installer/conda.svg)](https://anaconda.org/bioconda/savvy)\n\n\nAll branches in this repository are development branches. The latest stable release can be found in the [releases](https://github.com/statgen/savvy/releases) section.\n\n# Savvy Library\nSavvy is the official C++ interface for the [SAV file format](sav_spec_v2.md) and offers seamless support for BCF and VCF files.\n\nSince the release of version 2.0, Savvy no longer supports writing of SAV 1.x files but will continue to support reading of existing 1.x files.  \n\n## Installing\nThe easiest way to install Savvy and its dependencies from source is to use [cget](http://cget.readthedocs.io/en/latest/src/intro.html#installing-cget).\n```shell\ncget install --prefix \u003cinstall_prefix\u003e statgen/savvy # default \u003cinstall_prefix\u003e is ./cget/\n```\n\nInstalling binaries of Savvy and its dependencies can be done with [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html).\n```shell\nconda install -c conda-forge -c bioconda savvy\n```\n\n## Including in Projects\nCMakeLists.txt:\n```cmake\n# Configure with cmake option: -DCMAKE_TOOLCHAIN_FILE=\u003cinstall_prefix\u003e/cget/cget.cmake\nfind_package(savvy REQUIRED)\nadd_executable(prog main.cpp)\ntarget_link_libraries(prog savvy)\n```\n\n## Reading Variants from File \n```c++\n#include \u003csavvy/reader.hpp\u003e\n\nsavvy::reader f(\"chr1.sav\");\nsavvy::variant var;\nstd::vector\u003cint\u003e geno;\n  \nwhile (f \u003e\u003e var)\n{\n  var.position();\n  var.chromosome();\n  var.ref();\n  var.alts();\n\n  int ac;\n  var.get_info(\"AC\", ac);\n  \n  var.get_format(\"GT\", geno);\n  for (int allele : geno)\n  {\n    ...\n  }\n}\n```\n\n## Random Access\nIn addition to the genomic region queries that CSI indices enable for VCF/BCF files, S1R indices also enable SAV files to be queried by record offset.  \n\n### Genomic Queries\n```c++\n#include \u003csavvy/reader.hpp\u003e\n\nsavvy::reader f(\"chrX.sav\");\nsavvy::variant var;\n\nf.reset_bounds(savvy::genomic_region(\"X\", 60001, 2699520));\nwhile (f \u003e\u003e var)\n{\n  ...\n}\n\n// Shorthand\nf.reset_bounds({\"X\", 154931044, 155260560});\nwhile (f \u003e\u003e var)\n{\n  ...\n}\n```\n\n### Slice Queries\n```c++\n#include \u003csavvy/reader.hpp\u003e\nsavvy::reader f(\"chr1.sav\");\n\n// Get the 10,000th record through the 19,999th record (0-based amd non-inclusive)\nf.reset_bounds(savvy::slice_bounds(10000, 20000));\n\n// Shorthand\nf.reset_bounds({20000, 30000});\n```\n\n## Subsetting Samples\n```c++\n#include \u003csavvy/reader.hpp\u003e\nsavvy::reader f(\"chr1.sav\");\nstd::vector\u003cstd::string\u003e requested = {\"ID001\",\"ID002\",\"ID003\"};\nstd::vector\u003cstd::string\u003e intersect = f.subset_samples({requested.begin(), requested.end()});\n\nsavvy::variant var;\nwhile (f.read(var))\n{\n  ...\n}\n```\n\n## Copying Files\n```c++\n#include \u003csavvy/reader.hpp\u003e\n#include \u003csavvy/writer.hpp\u003e\n\nsavvy::reader in(\"in.sav\");\nsavvy::writer out(\"out.bcf\", savvy::file::format::bcf, in.headers(), in.samples());\nsavvy::variant var;\nwhile (in \u003e\u003e var)\n  out \u003c\u003c var;\n```\n\n## Creating New Files\n```c++\n#include \u003csavvy/writer.hpp\u003e\n\nstd::vector\u003cstd::string\u003e sample_ids = {\"ID1\", \"ID2\", \"ID3\"};\n\nstd::vector\u003cstd::pair\u003cstd::string, std::string\u003e\u003e headers = {\n  {\"fileformat\", \"VCFv4.2\"},\n  {\"FILTER\", \"\u003cID=PASS,Description=\\\"All filters passed\\\"\u003e\"},\n  {\"contig\", \"\u003cID=chr1,length=248956422\u003e\"},\n  {\"INFO\",   \"\u003cID=AC,Number=A,Type=Integer,Description=\\\"Alternate Allele Counts\\\"\u003e\"},\n  {\"INFO\",   \"\u003cID=AN,Number=1,Type=Integer,Description=\\\"Total Number Allele Counts\\\"\u003e\"},\n  {\"FORMAT\", \"\u003cID=GT,Type=Integer,Description=\\\"Genotype\\\"\u003e\"} \n};\n\nsavvy::writer out(\"out.sav\", savvy::file::format::sav2, headers, sample_ids);\n\nstd::vector\u003cstd::int8_t\u003e geno = {0,0,1,0,0,1};\n\nsavvy::variant var(\"chr1\", 10000000, \"A\", {\"AC\"}); // chrom, pos, ref, alts\nvar.set_info(\"AC\", std::count(geno.begin(), geno.end(), 1));\nvar.set_info(\"AN\", geno.size());\nvar.set_format(\"GT\", geno);\n\nout.write(var);\n```\n\n# SAV Command Line Interface\nFile manipulation for SAV format.\n\n## Import\nThe `import` sub-command generates a SAV file from a BCF or VCF file. An S1R index is automatically generated and appended to the end of the resulting SAV file.\n```shell\nsav import file.bcf file.sav\n```\n\n## Export\nThe `export` sub-command can be used to manipulate SAV files and/or convert between file formats.\n```shell\nsav export --regions chr1,chr2:10000-20000 --sample-ids ID1,ID2,ID3 file.sav \u003e file.vcf\n```\n\n## Concatenate\nFast concatenation of SAV files (similar to `bcftools concat --naive`) can be achieved with the `concat` sub-command. This command avoids deserialization of variant data by performing a byte-for-byte copy of compressed variant blocks. The S1R index is also quickly concatenated without having to parse records in the SAV file. \n```shell\nsav concat file1.sav file2.sav \u003e concat.sav\n```\n\n## Slice Queries\nIn addition to querying genomic regions, S1R indices can be used to quickly subset records by their offset within a file.\n```shell\n# export first 1,000 records\nsav export --slice 0:1000 file.sav \u003e file.vcf\n\n# export second 1,000 records (1,000-1,999)\nsav export --slice 1000:2000 file.sav \u003e file.vcf\n```\n\n## Statistics\nThere are two sub-commands for gathering statistics on sav files. The `stat` command parses the entire file to calculate statistics. The `stat-index` sub-command only parsed the S1R index, making it a faster alternative for some statistics (e.g., number of variant records, chromosomes, etc.).\n```shell\nsav stat file.sav\nsav stat-index file.sav\n```\n\n## Sort\nThe `sort` sub-command sorts variant records by chromosome and position.  It can also be used to sort in descending order, which is supported by S1R indices.\n```shell\nsav sort unsorted.sav \u003e sorted.sav\nsav sort --direction desc unsorted.sav \u003e reversed.sav\n```\n\n## Header\nThe `head` and `rehead` sub-commands are used for retrieving and manipulating header information.\n```shell\nsav head file.sav \u003e header.txt\nsav head --sample-ids file.sav \u003e sample_ids.txt\nsav rehead --sample-ids new_ids_file.txt old.sav new.sav\n```\n\n## Parameter Trade-offs\n| Action | Pro | Con |\n|:-------|:----|:----|\n|Increasing block size|Smaller file size (especially with PBWT)|Reduces precision of random access|\n|Increasing compression level|Smaller file size|Slower compression speed (decompression not affected)|\n|Enabling PBWT|Smaller file size when used with some fields|Slower compression and decompression|\n\n# Packaging\n```shell\ndocker build -t savvy-packaging - \u003c packaging-dockerfile-ubuntu20\nmkdir -p packages\ndocker run -v $(pwd):/savvy-src -v $(pwd)/packages:/out savvy-packaging /savvy-src/package-linux.sh /savvy-src /out\n```\n\n# Optional Build Targets\n* `-DBUILD_TESTS=ON` allows running of tests with `make test`\n* `-DBUILD_EVAL=ON` enables building of sav-eval executable used to evaluate deserialization performance\n* `-DBUILD_SPARSE_REGRESSION=ON` enables building of sav-at executable\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatgen%2Fsavvy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatgen%2Fsavvy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatgen%2Fsavvy/lists"}