class_docstr: Provides an interface to perform backpropagation.
  
  This class provids a way to calculate the gradients of a target class
  output w.r.t. an input image, by performing a single backprobagation.
  
  The gradients obtained can be used to visualise an image-specific class
  saliency map, which can gives some intuition on regions within the input
  image that contribute the most (and least) to the corresponding output.
  
  More details on saliency maps: `Deep Inside Convolutional Networks:
  Visualising Image Classification Models and Saliency Maps
  <https://arxiv.org/pdf/1312.6034.pdf>`_.
  
  Args:
      model: A neural network model from `torchvision.models
          <https://pytorch.org/docs/stable/torchvision/models.html>`_.
class_docstr_tok: ["Provides","an","interface","to","perform","backpropagation",".","This","class","provids","a","way","to","calculate","the","gradients","of","a","target","class","output","w.r.t",".","an","input","image",",","by","performing","a","single","backprobagation",".","The","gradients","obtained","can","be","used","to","visualise","an","image-specific","class","saliency","map",",","which","can","gives","some","intuition","on","regions","within","the","input","image","that","contribute","the","most","(","and","least",")","to","the","corresponding","output",".","More","details","on","saliency","maps",":","`","Deep","Inside","Convolutional","Networks",":","Visualising","Image","Classification","Models","and","Saliency","Maps","<","https",":","\/\/arxiv.org\/pdf\/1312.6034.pdf",">","`","_",".","Args",":","model",":","A","neural","network","model","from","`","torchvision.models","<","https",":","\/\/pytorch.org\/docs\/stable\/torchvision\/models.html",">","`","_","."]
docstr: Calculates gradients and visualizes the output.
  
  A method that combines the backprop operation and visualization.
  
  It also returns the gradients, if specified with `return_output=True`.
  
  Args:
      input_ (torch.Tensor): With shape :math:`(N, C, H, W)`.
      target_class (int, optional, default=None)
      take_max (bool, optional, default=False): If True, take the maximum
          gradients across colour channels for each pixel.
      guided (bool, optional, default=Fakse): If True, perform guided
          backpropagation. See `Striving for Simplicity: The All
          Convolutional Net <https://arxiv.org/pdf/1412.6806.pdf>`_.
      use_gpu (bool, optional, default=False): Use GPU if set to True and
          `torch.cuda.is_available()`.
      figsize (tuple, optional, default=(16, 4)): The size of the plot.
      cmap (str, optional, default='viridis): The color map of the
          gradients plots. See avaialable color maps `here <https://matplotlib.org/3.1.0/tutorials/colors/colormaps.html>`_.
      alpha (float, optional, default=.5): The alpha value of the max
          gradients to be jaxaposed on top of the input image.
      return_output (bool, optional, default=False): Returns the
          output(s) of optimization if set to True.
  
  Returns:
      gradients (torch.Tensor): With shape :math:`(C, H, W)`.
docstr_tok: ["Calculates","gradients","and","visualizes","the","output",".","A","method","that","combines","the","backprop","operation","and","visualization",".","It","also","returns","the","gradients",",","if","specified","with","`","return_output=True","`",".","Args",":","input_","(","torch.Tensor",")",":","With","shape",":","math",":","`","(","N",",","C",",","H",",","W",")","`",".","target_class","(","int",",","optional",",","default=None",")","take_max","(","bool",",","optional",",","default=False",")",":","If","True",",","take","the","maximum","gradients","across","colour","channels","for","each","pixel",".","guided","(","bool",",","optional",",","default=Fakse",")",":","If","True",",","perform","guided","backpropagation",".","See","`","Striving","for","Simplicity",":","The","All","Convolutional","Net","<","https",":","\/\/arxiv.org\/pdf\/1412.6806.pdf",">","`","_",".","use_gpu","(","bool",",","optional",",","default=False",")",":","Use","GPU","if","set","to","True","and","`","torch.cuda.is_available","(",")","`",".","figsize","(","tuple",",","optional",",","default=","(","16",",","4",")",")",":","The","size","of","the","plot",".","cmap","(","str",",","optional",",","default='viridis",")",":","The","color","map","of","the","gradients","plots",".","See","avaialable","color","maps","`","here","<","https",":","\/\/matplotlib.org\/3.1.0\/tutorials\/colors\/colormaps.html",">","`","_",".","alpha","(","float",",","optional",",","default=.5",")",":","The","alpha","value","of","the","max","gradients","to","be","jaxaposed","on","top","of","the","input","image",".","return_output","(","bool",",","optional",",","default=False",")",":","Returns","the","output","(","s",")","of","optimization","if","set","to","True",".","Returns",":","gradients","(","torch.Tensor",")",":","With","shape",":","math",":","`","(","C",",","H",",","W",")","`","."]
code: def visualize(
      self,
      input_,
      target_class,
      guided=False,
      use_gpu=False,
      figsize=(16, 4),
      cmap="viridis",
      alpha=0.5,
      return_output=False,
  ):
      """Calculates gradients and visualizes the output.
  
      A method that combines the backprop operation and visualization.
  
      It also returns the gradients, if specified with `return_output=True`.
  
      Args:
          input_ (torch.Tensor): With shape :math:`(N, C, H, W)`.
          target_class (int, optional, default=None)
          take_max (bool, optional, default=False): If True, take the maximum
              gradients across colour channels for each pixel.
          guided (bool, optional, default=Fakse): If True, perform guided
              backpropagation. See `Striving for Simplicity: The All
              Convolutional Net <https://arxiv.org/pdf/1412.6806.pdf>`_.
          use_gpu (bool, optional, default=False): Use GPU if set to True and
              `torch.cuda.is_available()`.
          figsize (tuple, optional, default=(16, 4)): The size of the plot.
          cmap (str, optional, default='viridis): The color map of the
              gradients plots. See avaialable color maps `here <https://matplotlib.org/3.1.0/tutorials/colors/colormaps.html>`_.
          alpha (float, optional, default=.5): The alpha value of the max
              gradients to be jaxaposed on top of the input image.
          return_output (bool, optional, default=False): Returns the
              output(s) of optimization if set to True.
  
      Returns:
          gradients (torch.Tensor): With shape :math:`(C, H, W)`.
      """  # noqa
  
      # Calculate gradients
  
      gradients = self.calculate_gradients(
          input_, target_class, guided=guided, use_gpu=use_gpu
      )
      max_gradients = self.calculate_gradients(
          input_,
          target_class,
          guided=guided,
          take_max=True,
          use_gpu=use_gpu,
      )
  
      # Setup subplots
  
      subplots = [
          # (title, [(image1, cmap, alpha), (image2, cmap, alpha)])
          (
              "Input image",
              [(format_for_plotting(denormalize(input_)), None, None)],
          ),
          (
              "Gradients across RGB channels",
              [
                  (
                      format_for_plotting(
                          standardize_and_clip(gradients)
                      ),
                      None,
                      None,
                  )
              ],
          ),
          (
              "Max gradients",
              [
                  (
                      format_for_plotting(
                          standardize_and_clip(max_gradients)
                      ),
                      cmap,
                      None,
                  )
              ],
          ),
          (
              "Overlay",
              [
                  (
                      format_for_plotting(denormalize(input_)),
                      None,
                      None,
                  ),
                  (
                      format_for_plotting(
                          standardize_and_clip(max_gradients)
                      ),
                      cmap,
                      alpha,
                  ),
              ],
          ),
      ]
  
      fig = plt.figure(figsize=figsize)
  
      for i, (title, images) in enumerate(subplots):
          ax = fig.add_subplot(1, len(subplots), i + 1)
          ax.set_axis_off()
          ax.set_title(title)
  
          for image, cmap, alpha in images:
              ax.imshow(image, cmap=cmap, alpha=alpha)
  
      if return_output:
          return gradients, max_gradients
  
file_path: flashtorch/flashtorch/saliency/backprop.py
imports: import warnings
  import matplotlib.pyplot
  import torch
  import torch.nn
  from flashtorch.utils import denormalize, format_for_plotting, standardize_and_clip
label_desc: Use image node_id 3 for calling the Backprop obj's underlying member method code with example usage: obj.visualize(input_, target_class, guided, use_gpu, figsize, cmap, alpha, return_output) and returns: gradients,  max_gradients