github.com/Schaudge/hts@v0.0.0-20240223063651-737b4d69d68c/README.md (about)

     1  ![bíogo](https://raw.githubusercontent.com/biogo/biogo/master/biogo.png)
     2  
     3  # HTS
     4  
     5  [![Build Status](https://travis-ci.org/biogo/hts.svg?branch=master)](https://travis-ci.org/biogo/hts) [![GoDoc](https://godoc.org/github.com/biogo/hts?status.svg)](https://godoc.org/github.com/biogo/hts)
     6  
     7  ## Installation
     8  
     9          $ go get github.com/biogo/hts/...
    10  
    11  ## Overview
    12  
    13  SAM and BAM handling for the Go language.
    14  
    15  bíogo/hts provides a Go native implementation of the [SAM specification](https://samtools.github.io/hts-specs/SAMv1.pdf) for SAM and BAM alignment formats commonly used for representation of high throughput genomic data, the BAI, CSI and tabix indexing formats, and the BGZF blocked compression format.
    16  The bíogo/hts packages perform parallelized read and write operations and are able to cache recent reads according to user-specified caching methods.
    17  The bíogo/hts APIs have been constructed to provide a consistent interface to sequence alignment data and the underlying compression system in order to aid ease of use and tool development.
    18  
    19  ## Example usage
    20  
    21  The following code implements the equivalent of `samtools view -c -f n -F N file.bam`.
    22  
    23  ```
    24  package main
    25  
    26  import (
    27  	"flag"
    28  	"fmt"
    29  	"io"
    30  	"log"
    31  	"os"
    32  
    33  	"github.com/biogo/hts/bam"
    34  	"github.com/biogo/hts/bgzf"
    35  	"github.com/biogo/hts/sam"
    36  )
    37  
    38  var (
    39  	require = flag.Int("f", 0, "required flags")
    40  	exclude = flag.Int("F", 0, "excluded flags")
    41  	file    = flag.String("file", "", "input file (empty for stdin)")
    42  	conc    = flag.Int("threads", 0, "number of threads to use (0 = auto)")
    43  	help    = flag.Bool("help", false, "display help")
    44  )
    45  
    46  const maxFlag = int(^sam.Flags(0))
    47  
    48  func main() {
    49  	flag.Parse()
    50  	if *help {
    51  		flag.Usage()
    52  		os.Exit(0)
    53  	}
    54  
    55  	if *require > maxFlag {
    56  		flag.Usage()
    57  		log.Fatal("required flags (f) out of range")
    58  	}
    59  	reqFlag := sam.Flags(*require)
    60  
    61  	if *exclude > maxFlag {
    62  		flag.Usage()
    63  		log.Fatal("excluded flags (F) out of range")
    64  	}
    65  	excFlag := sam.Flags(*exclude)
    66  
    67  	var r io.Reader
    68  	if *file == "" {
    69  		r = os.Stdin
    70  	} else {
    71  		f, err := os.Open(*file)
    72  		if err != nil {
    73  			log.Fatalf("could not open file %q:", err)
    74  		}
    75  		defer f.Close()
    76  		ok, err := bgzf.HasEOF(f)
    77  		if err != nil {
    78  			log.Fatalf("could not open file %q:", err)
    79  		}
    80  		if !ok {
    81  			log.Printf("file %q has no bgzf magic block: may be truncated", *file)
    82  		}
    83  		r = f
    84  	}
    85  
    86  	b, err := bam.NewReader(r, *conc)
    87  	if err != nil {
    88  		log.Fatalf("could not read bam:", err)
    89  	}
    90  	defer b.Close()
    91  
    92  	// We only need flags, so skip variable length data.
    93  	b.Omit(bam.AllVariableLengthData)
    94  
    95  	var n int
    96  	for {
    97  		rec, err := b.Read()
    98  		if err == io.EOF {
    99  			break
   100  		}
   101  		if err != nil {
   102  			log.Fatalf("error reading bam: %v", err)
   103  		}
   104  		if rec.Flags&reqFlag == reqFlag && rec.Flags&excFlag == 0 {
   105  			n++
   106  		}
   107  	}
   108  
   109  	fmt.Println(n)
   110  }
   111  ```
   112  
   113  ## Getting help
   114  
   115  Help or similar requests are preferred on the biogo-user Google Group.
   116  
   117  https://groups.google.com/forum/#!forum/biogo-user
   118  
   119  ## Contributing
   120  
   121  If you find any bugs, feel free to file an issue on the github issue tracker.
   122  Pull requests are welcome, though if they involve changes to API or addition of features, please first open a discussion at the biogo-dev Google Group.
   123  
   124  https://groups.google.com/forum/#!forum/biogo-dev
   125  
   126  ## Citing
   127  
   128  If you use bíogo/hts, please cite Kortschak, Pedersen and Adelson "bíogo/hts: high throughput sequence handling for the Go language", doi:[10.21105/joss.00168](http://dx.doi.org/10.21105/joss.00168).
   129  
   130  ## Library Structure and Coding Style
   131  
   132  The coding style should be aligned with normal Go idioms as represented in the
   133  Go core libraries.
   134  
   135  ## Copyright and License
   136  
   137  Copyright ©2011-2013 The bíogo Authors except where otherwise noted. All rights
   138  reserved. Use of this source code is governed by a BSD-style license that can be
   139  found in the LICENSE file.
   140  
   141  The bíogo logo is derived from Bitstream Charter, Copyright ©1989-1992
   142  Bitstream Inc., Cambridge, MA.
   143  
   144  BITSTREAM CHARTER is a registered trademark of Bitstream Inc.