{"id":35016040,"url":"https://github.com/martgro/bam-filtering-rust","last_synced_at":"2026-05-14T16:06:49.973Z","repository":{"id":321453287,"uuid":"1085910027","full_name":"MartGro/bam-filtering-rust","owner":"MartGro","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-24T18:33:33.000Z","size":6582,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T19:59:29.569Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/MartGro.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-29T17:16:18.000Z","updated_at":"2026-01-24T18:33:37.000Z","dependencies_parsed_at":"2025-10-29T19:33:10.477Z","dependency_job_id":"a03dbbdf-d9f2-4800-b267-be97ea19bf5f","html_url":"https://github.com/MartGro/bam-filtering-rust","commit_stats":null,"previous_names":["martgro/bam-filtering-rust"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MartGro/bam-filtering-rust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartGro%2Fbam-filtering-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartGro%2Fbam-filtering-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartGro%2Fbam-filtering-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartGro%2Fbam-filtering-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MartGro","download_url":"https://codeload.github.com/MartGro/bam-filtering-rust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartGro%2Fbam-filtering-rust/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33032638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"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":[],"created_at":"2025-12-27T05:19:59.418Z","updated_at":"2026-05-14T16:06:49.968Z","avatar_url":"https://github.com/MartGro.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BAM Pair Filter (Rust Version)\n\nA fast, portable Rust implementation for filtering paired-end BAM reads by kmer complexity, contiguous mapped bases, and mapping quality.\n\n## Key Features\n\n✅ **Truly Portable**: Single binary with no external dependencies\n✅ **Fast**: Compiled with LTO and full optimizations\n✅ **Safe**: Memory-safe Rust with no buffer overflows\n✅ **Small**: ~7.6MB statically-linked binary\n✅ **Same Features**: Identical to C version with same algorithms\n\n## Quick Start\n\n```bash\n# Build (requires Rust 1.82+)\ncargo build --release\n\n# Binary location\n./target/release/filter_bam_pairs\n\n# Run (filter by complexity and mapped bases only)\n./target/release/filter_bam_pairs \\\n    --input input.namesorted.bam \\\n    --output filtered.bam \\\n    --complexity 0.8 \\\n    --min-mapped 90\n\n# Or add mapping quality filter\n./target/release/filter_bam_pairs \\\n    --input input.namesorted.bam \\\n    --output filtered.bam \\\n    --complexity 0.8 \\\n    --min-mapped 90 \\\n    --min-mapq 20\n```\n\n## Installation\n\n### Option 1: Build from Source\n\n```bash\n# Install Rust (if not already installed)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# Build release binary\ncd fastq_kmer_filter_rust\ncargo build --release\n\n# Binary is at: target/release/filter_bam_pairs\n# Copy to PATH if desired:\nsudo cp target/release/filter_bam_pairs /usr/local/bin/\n```\n\n### Option 2: Use Pre-built Binary\n\nThe compiled binary is **fully portable** across Linux x86_64 systems:\n\n```bash\n# Just copy and run - no dependencies needed!\ncp target/release/filter_bam_pairs ~/bin/\n./filter_bam_pairs --help\n```\n\n## Usage\n\n```\nUsage: filter_bam_pairs [OPTIONS] --input \u003cFILE\u003e --output \u003cFILE\u003e\n\nOptions:\n  -i, --input \u003cFILE\u003e              Input BAM file (must be name-sorted)\n  -o, --output \u003cFILE\u003e             Output BAM file for passed reads\n  -r, --rejected \u003cFILE\u003e           Output BAM file for rejected reads (optional)\n  -c, --complexity \u003cCOMPLEXITY\u003e   Kmer complexity cutoff (0.0-1.0) [default: 0.8]\n  -m, --min-mapped \u003cMIN_MAPPED\u003e   Minimum contiguous mapped bases [default: 0]\n  -q, --min-mapq \u003cMIN_MAPQ\u003e       Minimum mapping quality [default: 0]\n  -h, --help                      Print help\n```\n\n### Examples\n\n```bash\n# Filter by complexity only (default 0.8)\n./filter_bam_pairs -i input.bam -o filtered.bam\n\n# Filter with separate output for passed and rejected reads\n./filter_bam_pairs \\\n    -i input.namesorted.bam \\\n    -o high_quality.bam \\\n    -r low_quality.bam \\\n    -c 0.8 \\\n    -m 90\n\n# Strict filtering with mapping quality\n./filter_bam_pairs \\\n    -i input.namesorted.bam \\\n    -o very_strict.bam \\\n    -r rejected.bam \\\n    -c 0.85 \\\n    -m 100 \\\n    -q 30\n\n# Filter by mapping quality only\n./filter_bam_pairs \\\n    -i input.namesorted.bam \\\n    -o high_mapq.bam \\\n    -c 0.0 \\\n    -q 20\n```\n\n## Output Files\n\nThe tool generates one or two output BAM files depending on your options:\n\n- **Passed reads** (`-o/--output`): Reads that pass all filtering criteria (required)\n- **Rejected reads** (`-r/--rejected`): Reads that fail filtering criteria (optional)\n\nBoth output files maintain the same BAM format and header as the input file. If the rejected output is not specified, rejected reads are simply discarded.\n\n## Important: BAM Requirements\n\n**Input BAM must be name-sorted:**\n\n```bash\n# Sort by read name\nsamtools sort -n input.bam -o input.namesorted.bam\n\n# Then filter\n./filter_bam_pairs -i input.namesorted.bam -o filtered.bam\n\n# Or with rejected output\n./filter_bam_pairs -i input.namesorted.bam -o passed.bam -r rejected.bam\n```\n\n## Portability\n\n### What Makes It Portable?\n\nThe Rust version:\n- **Statically links htslib**: No need to install htslib on target systems\n- **Only depends on libc/libm**: Standard libraries present on all Linux systems\n- **Single binary**: Just copy and run\n\n### Dependencies Check\n\n```bash\n$ ldd target/release/filter_bam_pairs\n    linux-vdso.so.1\n    libgcc_s.so.1 =\u003e /lib/x86_64-linux-gnu/libgcc_s.so.1\n    libm.so.6 =\u003e /lib/x86_64-linux-gnu/libm.so.6\n    libc.so.6 =\u003e /lib/x86_64-linux-gnu/libc.so.6\n    /lib64/ld-linux-x86-64.so.2\n```\n\n**No htslib dependency!** These are all standard libraries.\n\n### Cross-Platform Testing\n\n```bash\n# Test on different Linux distros\ndocker run --rm -v $(pwd):/work ubuntu:22.04 /work/target/release/filter_bam_pairs -h\ndocker run --rm -v $(pwd):/work debian:11 /work/target/release/filter_bam_pairs -h\ndocker run --rm -v $(pwd):/work centos:7 /work/target/release/filter_bam_pairs -h\n```\n\n## Performance\n\n### Compilation Optimizations\n\nThe binary is compiled with:\n- `-O3` (maximum optimization)\n- `LTO = true` (link-time optimization)\n- `codegen-units = 1` (better optimization, slower compile)\n- `strip = true` (remove debug symbols)\n\n### Benchmarks\n\nTypical performance on modern hardware:\n- **Throughput**: ~500k-1M paired reads/second\n- **Memory**: Minimal (\u003c100MB)\n- **I/O bound**: Performance limited by disk/BAM compression\n\n## Comparison: C vs Rust\n\n| Feature | C Version | Rust Version |\n|---------|-----------|--------------|\n| Speed | Fast | Fast (similar) |\n| Binary size | ~20KB | ~7.6MB |\n| Dependencies | Requires htslib installed | None (statically linked) |\n| Portability | Needs matching htslib | Runs anywhere |\n| Safety | Manual memory management | Memory safe |\n| Development | More code, error-prone | Less code, safer |\n\n**Recommendation**: Use Rust version for portability and safety.\n\n## Building for Different Targets\n\n### Static Binary (musl libc)\n\nFor maximum portability (works even on systems without glibc):\n\n```bash\n# Add musl target\nrustup target add x86_64-unknown-linux-musl\n\n# Build static binary\ncargo build --release --target x86_64-unknown-linux-musl\n\n# Truly static binary!\nldd target/x86_64-unknown-linux-musl/release/filter_bam_pairs\n# Output: not a dynamic executable\n```\n\n### Cross-Compilation\n\n```bash\n# For ARM64 (e.g., Apple Silicon)\nrustup target add aarch64-unknown-linux-gnu\ncargo build --release --target aarch64-unknown-linux-gnu\n\n# For macOS\nrustup target add x86_64-apple-darwin\ncargo build --release --target x86_64-apple-darwin\n```\n\n## Development\n\n### Run Tests\n\n```bash\ncargo test\n```\n\n### Run with Debug Logging\n\n```bash\nRUST_LOG=debug cargo run --release -- -i input.bam -o output.bam\n```\n\n### Format Code\n\n```bash\ncargo fmt\n```\n\n### Lint\n\n```bash\ncargo clippy\n```\n\n## Technical Details\n\n### Algorithm\n\nSame as C version:\n\n1. **Kmer Complexity**: `unique_kmers / total_kmers` (k=21)\n2. **Mapped Bases**: Longest contiguous M/= CIGAR stretch\n3. **Mapping Quality**: MAPQ score threshold\n4. **Filtering**: Both reads must pass all enabled thresholds\n5. **Pairing**: Maintains read pair integrity\n\n### Dependencies\n\n- `rust-htslib`: Rust bindings to htslib (statically linked)\n- `clap`: Command-line argument parsing\n- `anyhow`: Error handling\n\n### Rust Edition\n\nUses Rust 2021 edition with modern idioms.\n\n## Troubleshooting\n\n### \"cannot find -lbz2\" during build\n\nInstall bzip2 development files:\n\n```bash\nsudo apt-get install libbz2-dev\n```\n\n### \"cannot find -llzma\" during build\n\nInstall xz development files:\n\n```bash\nsudo apt-get install liblzma-dev\n```\n\n### Build takes long time\n\nFirst build compiles all dependencies. Subsequent builds are fast.\n\n### Binary too large\n\nThe binary includes:\n- htslib (BAM parsing)\n- Compression libraries (zlib, bzip2, lzma)\n- All statically linked for portability\n\nYou can reduce size with:\n```bash\ncargo build --release\nstrip target/release/filter_bam_pairs  # Already done automatically\nupx --best --lzma target/release/filter_bam_pairs  # Compress with UPX (optional)\n```\n\n## License\n\nSame as C version - Public domain\n\n## See Also\n\n- C version: `../fastq_kmer_filter/filter_bam_pairs`\n- FASTQ filter: `../fastq_kmer_filter/filter_paired_reads`\n\n## Why Rust?\n\nAdvantages over C:\n1. **No segfaults**: Memory safety guaranteed by compiler\n2. **No undefined behavior**: Strict type system\n3. **Easy distribution**: Statically linked by default\n4. **Modern tooling**: cargo, rustfmt, clippy\n5. **Maintainable**: Clearer code, better error handling\n\nThe Rust version provides the same functionality as C with better safety and easier deployment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartgro%2Fbam-filtering-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartgro%2Fbam-filtering-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartgro%2Fbam-filtering-rust/lists"}