class_docstr: Class for reading from native SAM/BAM/CRAM files.
  
  Most users will want to use SamReader instead, because it dynamically
  dispatches between reading native SAM/BAM/CRAM files and TFRecord files based
  on the filename's extensions.
class_docstr_tok: ["Class","for","reading","from","native","SAM\/BAM\/CRAM","files",".","Most","users","will","want","to","use","SamReader","instead",",","because","it","dynamically","dispatches","between","reading","native","SAM\/BAM\/CRAM","files","and","TFRecord","files","based","on","the","filename","'s","extensions","."]
docstr: Initializes a NativeSamReader.
  
  Args:
    input_path: str. A path to a resource containing SAM/BAM/CRAM records.
      Currently supports SAM text format, BAM binary format, and CRAM.
    ref_path: optional str or None. Only used for CRAM decoding, and only
      necessary if the UR encoded path in the CRAM itself needs to be
      overridden. If provided, we will tell the CRAM decoder to use this FASTA
      for the reference sequence.
    read_requirements: optional ReadRequirement proto. If not None, this proto
      is used to control which reads are filtered out by the reader before
      they are passed to the client.
    parse_aux_fields: optional bool, defaulting to False. If False, we do not
      parse the auxiliary fields of the SAM/BAM/CRAM records (see SAM spec for
      details). Parsing the aux fields is unnecessary for many applications,
      and adds a significant parsing cost to access. If you need these aux
      fields, set parse_aux_fields to True and these fields will be parsed and
      populate the appropriate Read proto fields (e.g., read.info).
    hts_block_size: int or None. If specified, this configures the block size
      of the underlying htslib file object. Larger values (e.g. 1M) may be
      beneficial for reading remote files. If None, the reader uses the
      default htslib block size.
    downsample_fraction: float in the interval [0.0, 1.0] or None. If
      specified as a positive float, the reader will only keep each read with
      probability downsample_fraction, randomly. If None or zero, all reads
      are kept.
    random_seed: None or int. The random seed to use with this sam reader, if
      needed. If None, a fixed random value will be assigned.
    use_original_base_quality_scores: optional bool, defaulting to False. If
      True, quality scores are read from OQ tag.
    aux_fields_to_keep: None or list[str]. If None, we keep all aux fields if
      they are parsed. If set, we only keep the aux fields with the names in
      this list.
  
  Raises:
    ValueError: If downsample_fraction is not None and not in the interval
      (0.0, 1.0].
    ImportError: If someone tries to load a tfbam file.
docstr_tok: ["Initializes","a","NativeSamReader",".","Args",":","input_path",":","str",".","A","path","to","a","resource","containing","SAM\/BAM\/CRAM","records",".","Currently","supports","SAM","text","format",",","BAM","binary","format",",","and","CRAM",".","ref_path",":","optional","str","or","None",".","Only","used","for","CRAM","decoding",",","and","only","necessary","if","the","UR","encoded","path","in","the","CRAM","itself","needs","to","be","overridden",".","If","provided",",","we","will","tell","the","CRAM","decoder","to","use","this","FASTA","for","the","reference","sequence",".","read_requirements",":","optional","ReadRequirement","proto",".","If","not","None",",","this","proto","is","used","to","control","which","reads","are","filtered","out","by","the","reader","before","they","are","passed","to","the","client",".","parse_aux_fields",":","optional","bool",",","defaulting","to","False",".","If","False",",","we","do","not","parse","the","auxiliary","fields","of","the","SAM\/BAM\/CRAM","records","(","see","SAM","spec","for","details",")",".","Parsing","the","aux","fields","is","unnecessary","for","many","applications",",","and","adds","a","significant","parsing","cost","to","access",".","If","you","need","these","aux","fields",",","set","parse_aux_fields","to","True","and","these","fields","will","be","parsed","and","populate","the","appropriate","Read","proto","fields","(","e.g.",",","read.info",")",".","hts_block_size",":","int","or","None",".","If","specified",",","this","configures","the","block","size","of","the","underlying","htslib","file","object",".","Larger","values","(","e.g",".","1M",")","may","be","beneficial","for","reading","remote","files",".","If","None",",","the","reader","uses","the","default","htslib","block","size",".","downsample_fraction",":","float","in","the","interval","[","0.0",",","1.0","]","or","None",".","If","specified","as","a","positive","float",",","the","reader","will","only","keep","each","read","with","probability","downsample_fraction",",","randomly",".","If","None","or","zero",",","all","reads","are","kept",".","random_seed",":","None","or","int",".","The","random","seed","to","use","with","this","sam","reader",",","if","needed",".","If","None",",","a","fixed","random","value","will","be","assigned",".","use_original_base_quality_scores",":","optional","bool",",","defaulting","to","False",".","If","True",",","quality","scores","are","read","from","OQ","tag",".","aux_fields_to_keep",":","None","or","list","[","str","]",".","If","None",",","we","keep","all","aux","fields","if","they","are","parsed",".","If","set",",","we","only","keep","the","aux","fields","with","the","names","in","this","list",".","Raises",":","ValueError",":","If","downsample_fraction","is","not","None","and","not","in","the","interval","(","0.0",",","1.0","]",".","ImportError",":","If","someone","tries","to","load","a","tfbam","file","."]
code: def __init__(
      self,
      input_path,
      ref_path=None,
      read_requirements=None,
      parse_aux_fields=False,
      hts_block_size=None,
      downsample_fraction=None,
      random_seed=None,
      use_original_base_quality_scores=False,
      aux_fields_to_keep=None,
  ):
      """Initializes a NativeSamReader.
  
      Args:
        input_path: str. A path to a resource containing SAM/BAM/CRAM records.
          Currently supports SAM text format, BAM binary format, and CRAM.
        ref_path: optional str or None. Only used for CRAM decoding, and only
          necessary if the UR encoded path in the CRAM itself needs to be
          overridden. If provided, we will tell the CRAM decoder to use this FASTA
          for the reference sequence.
        read_requirements: optional ReadRequirement proto. If not None, this proto
          is used to control which reads are filtered out by the reader before
          they are passed to the client.
        parse_aux_fields: optional bool, defaulting to False. If False, we do not
          parse the auxiliary fields of the SAM/BAM/CRAM records (see SAM spec for
          details). Parsing the aux fields is unnecessary for many applications,
          and adds a significant parsing cost to access. If you need these aux
          fields, set parse_aux_fields to True and these fields will be parsed and
          populate the appropriate Read proto fields (e.g., read.info).
        hts_block_size: int or None. If specified, this configures the block size
          of the underlying htslib file object. Larger values (e.g. 1M) may be
          beneficial for reading remote files. If None, the reader uses the
          default htslib block size.
        downsample_fraction: float in the interval [0.0, 1.0] or None. If
          specified as a positive float, the reader will only keep each read with
          probability downsample_fraction, randomly. If None or zero, all reads
          are kept.
        random_seed: None or int. The random seed to use with this sam reader, if
          needed. If None, a fixed random value will be assigned.
        use_original_base_quality_scores: optional bool, defaulting to False. If
          True, quality scores are read from OQ tag.
        aux_fields_to_keep: None or list[str]. If None, we keep all aux fields if
          they are parsed. If set, we only keep the aux fields with the names in
          this list.
  
      Raises:
        ValueError: If downsample_fraction is not None and not in the interval
          (0.0, 1.0].
        ImportError: If someone tries to load a tfbam file.
      """
      if input_path.endswith(".tfbam"):
          # Delayed loading of tfbam_lib.
          try:
              from tfbam_lib import (
                  tfbam_reader,
              )  # pylint: disable=g-import-not-at-top
  
              self._reader = tfbam_reader.make_sam_reader(
                  input_path,
                  read_requirements=read_requirements,
                  unused_block_size=hts_block_size,
                  downsample_fraction=downsample_fraction,
                  random_seed=random_seed,
              )
          except ImportError:
              raise ImportError(
                  "tfbam_lib module not found, cannot read .tfbam files."
              )
      else:
          aux_field_handling = (
              reads_pb2.SamReaderOptions.SKIP_AUX_FIELDS
          )
          if parse_aux_fields:
              aux_field_handling = (
                  reads_pb2.SamReaderOptions.PARSE_ALL_AUX_FIELDS
              )
  
          # We make 0 be a valid value that means "keep all reads" so that proto
          # defaults (=0) do not omit all reads.
          if (
              downsample_fraction is not None
              and downsample_fraction != 0
          ):
              if not 0.0 < downsample_fraction <= 1.0:
                  raise ValueError(
                      "downsample_fraction must be in the interval (0.0, 1.0]",
                      downsample_fraction,
                  )
  
          if random_seed is None:
              # Fixed random seed produced with 'od -vAn -N4 -tu4 < /dev/urandom'.
              random_seed = 2928130004
  
          self._reader = sam_reader.SamReader.from_file(
              input_path.encode("utf8"),
              ref_path.encode("utf8") if ref_path is not None else "",
              reads_pb2.SamReaderOptions(
                  read_requirements=read_requirements,
                  aux_field_handling=aux_field_handling,
                  aux_fields_to_keep=aux_fields_to_keep,
                  hts_block_size=(hts_block_size or 0),
                  downsample_fraction=downsample_fraction,
                  random_seed=random_seed,
                  use_original_base_quality_scores=use_original_base_quality_scores,
              ),
          )
  
          self.header = self._reader.header
  
      super(NativeSamReader, self).__init__()
  
imports: from __future__ import absolute_import
  from __future__ import division
  from __future__ import print_function
  from third_party.nucleus.io import genomics_reader
  from third_party.nucleus.io import genomics_writer
  from third_party.nucleus.io.python import sam_reader
  from third_party.nucleus.io.python import sam_writer
  from third_party.nucleus.protos import reads_pb2
  from third_party.nucleus.util import ranges
  from third_party.nucleus.util import utils
label_desc: Use image node_id 1 to create a new NativeSamReader object from inherited base classes: genomics_reader with example: obj = NativeSamReader(input_path, ref_path, read_requirements, parse_aux_fields, hts_block_size, downsample_fraction, random_seed, use_original_base_quality_scores, aux_fields_to_keep)