class_docstr: High-level API for creating images of pileups of reads and reference bases.
  
  This class provides a higher-level and more natural API for constructing
  images at a candidate variant call site. Given a DeepVariantCall, which
  contains the candidate variant call along with key supplementary information,
  this class provides create_pileup_images() that will do all of the necessary
  fetching of reads and reference bases from readers and pass those off to the
  lower-level PileupImageEncoder to construct the image Tensor.
  
  for dv_call in candidates:
    allele_and_images = pic.create_pileup_images(dv_call)
    ...
  
  A quick note on how we deal with multiple alt alleles:
  
  Suppose variant has ref and two alt alleles. Assuming the sample is diploid,
  we have the following six possible genotypes:
  
    ref/ref   => 0/0
    ref/alt1  => 0/1
    alt1/alt1 => 1/1
    ref/alt2  => 0/2
    alt1/alt2 => 1/2
    alt2/alt2 => 2/2
  
  In DeepVariant we predict the genotype count (0, 1, 2) for a specific set of
  alternate alleles. If we only had a single alt, we'd construct an image for
  ref vs. alt1:
  
    image1 => ref vs. alt1 => determine if we are 0/0, 0/1, 1/1
  
  If we add a second image for alt2, we get:
  
    image2 => ref vs. alt2 => determine if we are 0/0, 0/2, 2/2
  
  but the problem here is that we don't have a good estimate for the het-alt
  state 1/2. So we construct a third image contrasting ref vs. either alt1 or
  alt2:
  
    image3 => ref vs. alt1 or alt2 => determines 0/0, 0/{1,2}, {1,2}/{1,2}
  
  Given the predictions for each image:
  
    image1 => p00, p01, p11
    image2 => p00, p02, p22
    image3 => p00, p0x, pxx where x is {1,2}
  
  we calculate our six genotype likelihoods as:
  
    0/0 => p00 [from any image]
    0/1 => p01 [image1]
    1/1 => p11 [image1]
    0/2 => p02 [image2]
    2/2 => p22 [image2]
    1/2 => pxx [image3]
  
  The function create_pileup_images() returns all of the necessary images, along
  with the alt alleles used for each image.
class_docstr_tok: ["High-level","API","for","creating","images","of","pileups","of","reads","and","reference","bases",".","This","class","provides","a","higher-level","and","more","natural","API","for","constructing","images","at","a","candidate","variant","call","site",".","Given","a","DeepVariantCall",",","which","contains","the","candidate","variant","call","along","with","key","supplementary","information",",","this","class","provides","create_pileup_images","(",")","that","will","do","all","of","the","necessary","fetching","of","reads","and","reference","bases","from","readers","and","pass","those","off","to","the","lower-level","PileupImageEncoder","to","construct","the","image","Tensor",".","for","dv_call","in","candidates",":","allele_and_images","=","pic.create_pileup_images","(","dv_call",")","...","A","quick","note","on","how","we","deal","with","multiple","alt","alleles",":","Suppose","variant","has","ref","and","two","alt","alleles",".","Assuming","the","sample","is","diploid",",","we","have","the","following","six","possible","genotypes",":","ref\/ref","=",">","0\/0","ref\/alt1","=",">","0\/1","alt1\/alt1","=",">","1\/1","ref\/alt2","=",">","0\/2","alt1\/alt2","=",">","1\/2","alt2\/alt2","=",">","2\/2","In","DeepVariant","we","predict","the","genotype","count","(","0",",","1",",","2",")","for","a","specific","set","of","alternate","alleles",".","If","we","only","had","a","single","alt",",","we","'d","construct","an","image","for","ref","vs.","alt1",":","image1","=",">","ref","vs.","alt1","=",">","determine","if","we","are","0\/0",",","0\/1",",","1\/1","If","we","add","a","second","image","for","alt2",",","we","get",":","image2","=",">","ref","vs.","alt2","=",">","determine","if","we","are","0\/0",",","0\/2",",","2\/2","but","the","problem","here","is","that","we","do","n't","have","a","good","estimate","for","the","het-alt","state","1\/2",".","So","we","construct","a","third","image","contrasting","ref","vs.","either","alt1","or","alt2",":","image3","=",">","ref","vs.","alt1","or","alt2","=",">","determines","0\/0",",","0\/","{","1,2","}",",","{","1,2","}","\/","{","1,2","}","Given","the","predictions","for","each","image",":","image1","=",">","p00",",","p01",",","p11","image2","=",">","p00",",","p02",",","p22","image3","=",">","p00",",","p0x",",","pxx","where","x","is","{","1,2","}","we","calculate","our","six","genotype","likelihoods","as",":","0\/0","=",">","p00","[","from","any","image","]","0\/1","=",">","p01","[","image1","]","1\/1","=",">","p11","[","image1","]","0\/2","=",">","p02","[","image2","]","2\/2","=",">","p22","[","image2","]","1\/2","=",">","pxx","[","image3","]","The","function","create_pileup_images","(",")","returns","all","of","the","necessary","images",",","along","with","the","alt","alleles","used","for","each","image","."]
docstr: Creates a DeepVariant TF.Example for the DeepVariant call dv_call.
  
  See class documents for more details.
  
  Args:
    dv_call: A learning.genomics.deepvariant.DeepVariantCall proto that we
      want to create a TF.Example pileup image of.
    reads_for_samples: list of read generators, one for each sample.
    sample_order: A list of indices representing the order in which samples
      should be represented in the pileup image. Example: [1,0,2] to swap the
      first two samples out of three. This is None by default which puts the
      samples in order.
    haplotype_alignments_for_samples: list with a dict for each sample of read
      alignments keyed by haplotype.
    haplotype_sequences: dict of sequences keyed by haplotype.
  
  Returns:
    A list of tuples. The first element of the tuple is a set of alternate
    alleles used as 'alt' when encoding this image. The second element is a
    [w, h, DEFAULT_NUM_CHANNEL] uint8 Tensor of the pileup image for those
    alt alleles.
docstr_tok: ["Creates","a","DeepVariant","TF.Example","for","the","DeepVariant","call","dv_call",".","See","class","documents","for","more","details",".","Args",":","dv_call",":","A","learning.genomics.deepvariant.DeepVariantCall","proto","that","we","want","to","create","a","TF.Example","pileup","image","of",".","reads_for_samples",":","list","of","read","generators",",","one","for","each","sample",".","sample_order",":","A","list","of","indices","representing","the","order","in","which","samples","should","be","represented","in","the","pileup","image",".","Example",":","[","1,0,2","]","to","swap","the","first","two","samples","out","of","three",".","This","is","None","by","default","which","puts","the","samples","in","order",".","haplotype_alignments_for_samples",":","list","with","a","dict","for","each","sample","of","read","alignments","keyed","by","haplotype",".","haplotype_sequences",":","dict","of","sequences","keyed","by","haplotype",".","Returns",":","A","list","of","tuples",".","The","first","element","of","the","tuple","is","a","set","of","alternate","alleles","used","as","'alt","'","when","encoding","this","image",".","The","second","element","is","a","[","w",",","h",",","DEFAULT_NUM_CHANNEL","]","uint8","Tensor","of","the","pileup","image","for","those","alt","alleles","."]
code: def create_pileup_images(
      self,
      dv_call,
      reads_for_samples,
      sample_order=None,
      haplotype_alignments_for_samples=None,
      haplotype_sequences=None,
  ):
      """Creates a DeepVariant TF.Example for the DeepVariant call dv_call.
  
      See class documents for more details.
  
      Args:
        dv_call: A learning.genomics.deepvariant.DeepVariantCall proto that we
          want to create a TF.Example pileup image of.
        reads_for_samples: list of read generators, one for each sample.
        sample_order: A list of indices representing the order in which samples
          should be represented in the pileup image. Example: [1,0,2] to swap the
          first two samples out of three. This is None by default which puts the
          samples in order.
        haplotype_alignments_for_samples: list with a dict for each sample of read
          alignments keyed by haplotype.
        haplotype_sequences: dict of sequences keyed by haplotype.
  
      Returns:
        A list of tuples. The first element of the tuple is a set of alternate
        alleles used as 'alt' when encoding this image. The second element is a
        [w, h, DEFAULT_NUM_CHANNEL] uint8 Tensor of the pileup image for those
        alt alleles.
      """
      variant = dv_call.variant
      # Ref bases to show at the top of the pileup:
      ref_bases = self.get_reference_bases(variant)
      if not ref_bases:
          # This interval isn't valid => we are off the edge of the chromosome, so
          # return None to indicate we couldn't process this variant.
          return None
  
      alt_aligned_representation = self._options.alt_aligned_pileup
  
      def _pileup_for_pair_of_alts(alt_alleles):
          """Create pileup image for one combination of alt alleles."""
          # Always create the ref-aligned pileup image.
          ref_image = self.build_pileup(
              dv_call=dv_call,
              refbases=ref_bases,
              reads_for_samples=reads_for_samples,
              alt_alleles=alt_alleles,
              sample_order=sample_order,
          )
          # Optionally also create pileup images with reads aligned to alts.
          if alt_aligned_representation != "none":
              if (
                  haplotype_alignments_for_samples is None
                  or haplotype_sequences is None
              ):
                  # Use sample height or default to pic height.
                  sample_heights = [
                      sample.options.pileup_height
                      for sample in self._samples
                  ]
                  if None not in sample_heights:
                      pileup_height = sum(sample_heights)
                  else:
                      pileup_height = self.height
                  pileup_shape = (
                      pileup_height,
                      self.width,
                      self.num_channels,
                  )
                  alt_images = [
                      np.zeros(pileup_shape, dtype=np.uint8)
                      for alt in alt_alleles
                  ]
              else:
                  alt_images = []
                  for alt in alt_alleles:
                      if len(haplotype_sequences[alt]) != self.width:
                          logging.warning(
                              (
                                  "haplotype_sequences[alt] is %d long but pileup "
                                  "image width is %d. Giving up on this image"
                              ),
                              len(haplotype_sequences[alt]),
                              self.width,
                          )
                          return None
                      alt_image = self.build_pileup(
                          dv_call=dv_call,
                          refbases=haplotype_sequences[alt],
                          reads_for_samples=[
                              sample[alt]
                              for sample in haplotype_alignments_for_samples
                          ],
                          alt_alleles=alt_alleles,
                          sample_order=sample_order,
                          custom_ref=True,
                      )
                      alt_images.append(alt_image)
              composite_image = _represent_alt_aligned_pileups(
                  alt_aligned_representation, ref_image, alt_images
              )
              return composite_image
          else:
              return ref_image
  
      retval = []
      for alts in self._alt_allele_combinations(variant):
          pileup = _pileup_for_pair_of_alts(alts)
          # If the pileup is None, this can mean that we're near the edge of the
          # contig, so one pileup width is invalid.
          # Return None to indicate we couldn't process this variant.
          if pileup is None:
              return None
          retval.append((alts, pileup))
      return retval
  
imports: import itertools
  from typing import Iterable, List, Optional, Tuple
  from absl import logging
  import numpy
  from deepvariant import dv_constants
  from deepvariant import sample
  from deepvariant.protos import deepvariant_pb2
  from deepvariant.python import pileup_image_native
  from third_party.nucleus.io import fasta
  from third_party.nucleus.io import sam
  from third_party.nucleus.protos import reads_pb2
  from third_party.nucleus.protos import variants_pb2
  from third_party.nucleus.util import ranges
label_desc: Use image node_id 10 for calling the PileupImageCreator obj's underlying member method code with example usage: obj.create_pileup_images(dv_call, reads_for_samples, sample_order, haplotype_alignments_for_samples, haplotype_sequences) and returns: retval, None, composite_image, ref_image, None, None