class_docstr: Sankey diagram.
  
    Sankey diagrams are a specific type of flow diagram, in which
    the width of the arrows is shown proportionally to the flow
    quantity.  They are typically used to visualize energy or
    material or cost transfers between processes.
    `Wikipedia (6/1/2011) <https://en.wikipedia.org/wiki/Sankey_diagram>`_
docstr: Create a new Sankey instance.
  
  The optional arguments listed below are applied to all subdiagrams so
  that there is consistent alignment and formatting.
  
  In order to draw a complex Sankey diagram, create an instance of
  `Sankey` by calling it without any kwargs::
  
      sankey = Sankey()
  
  Then add simple Sankey sub-diagrams::
  
      sankey.add() # 1
      sankey.add() # 2
      #...
      sankey.add() # n
  
  Finally, create the full diagram::
  
      sankey.finish()
  
  Or, instead, simply daisy-chain those calls::
  
      Sankey().add().add...  .add().finish()
  
  Other Parameters
  ----------------
  ax : `~matplotlib.axes.Axes`
      Axes onto which the data should be plotted.  If *ax* isn't
      provided, new Axes will be created.
  scale : float
      Scaling factor for the flows.  *scale* sizes the width of the paths
      in order to maintain proper layout.  The same scale is applied to
      all subdiagrams.  The value should be chosen such that the product
      of the scale and the sum of the inputs is approximately 1.0 (and
      the product of the scale and the sum of the outputs is
      approximately -1.0).
  unit : str
      The physical unit associated with the flow quantities.  If *unit*
      is None, then none of the quantities are labeled.
  format : str or callable
      A Python number formatting string or callable used to label the
      flows with their quantities (i.e., a number times a unit, where the
      unit is given). If a format string is given, the label will be
      ``format % quantity``. If a callable is given, it will be called
      with ``quantity`` as an argument.
  gap : float
      Space between paths that break in/break away to/from the top or
      bottom.
  radius : float
      Inner radius of the vertical paths.
  shoulder : float
      Size of the shoulders of output arrows.
  offset : float
      Text offset (from the dip or tip of the arrow).
  head_angle : float
      Angle, in degrees, of the arrow heads (and negative of the angle of
      the tails).
  margin : float
      Minimum space between Sankey outlines and the edge of the plot
      area.
  tolerance : float
      Acceptable maximum of the magnitude of the sum of flows.  The
      magnitude of the sum of connected flows cannot be greater than
      *tolerance*.
  **kwargs
      Any additional keyword arguments will be passed to `add`, which
      will create the first subdiagram.
  
  See Also
  --------
  Sankey.add
  Sankey.finish
  
  Examples
  --------
  .. plot:: gallery/specialty_plots/sankey_basics.py
docstr_tok: ["Create","a","new","Sankey","instance",".","The","optional","arguments","listed","below","are","applied","to","all","subdiagrams","so","that","there","is","consistent","alignment","and","formatting",".","In","order","to","draw","a","complex","Sankey","diagram",",","create","an","instance","of","`","Sankey","`","by","calling","it","without","any","kwargs",":",":","sankey","=","Sankey","(",")","Then","add","simple","Sankey","sub-diagrams",":",":","sankey.add","(",")","#","1","sankey.add","(",")","#","2","#","...","sankey.add","(",")","#","n","Finally",",","create","the","full","diagram",":",":","sankey.finish","(",")","Or",",","instead",",","simply","daisy-chain","those","calls",":",":","Sankey","(",")",".add","(",")",".add","...",".add","(",")",".finish","(",")","Other","Parameters","--","--","--","--","--","--","--","--","ax",":","`","~matplotlib.axes.Axes","`","Axes","onto","which","the","data","should","be","plotted",".","If","*","ax","*","isn't","provided",",","new","Axes","will","be","created",".","scale",":","float","Scaling","factor","for","the","flows",".","*","scale","*","sizes","the","width","of","the","paths","in","order","to","maintain","proper","layout",".","The","same","scale","is","applied","to","all","subdiagrams",".","The","value","should","be","chosen","such","that","the","product","of","the","scale","and","the","sum","of","the","inputs","is","approximately","1.0","(","and","the","product","of","the","scale","and","the","sum","of","the","outputs","is","approximately","-1.0",")",".","unit",":","str","The","physical","unit","associated","with","the","flow","quantities",".","If","*","unit","*","is","None",",","then","none","of","the","quantities","are","labeled",".","format",":","str","or","callable","A","Python","number","formatting","string","or","callable","used","to","label","the","flows","with","their","quantities","(","i.e.",",","a","number","times","a","unit",",","where","the","unit","is","given",")",".","If","a","format","string","is","given",",","the","label","will","be","``","format","%","quantity","``",".","If","a","callable","is","given",",","it","will","be","called","with","``","quantity","``","as","an","argument",".","gap",":","float","Space","between","paths","that","break","in\/break","away","to\/from","the","top","or","bottom",".","radius",":","float","Inner","radius","of","the","vertical","paths",".","shoulder",":","float","Size","of","the","shoulders","of","output","arrows",".","offset",":","float","Text","offset","(","from","the","dip","or","tip","of","the","arrow",")",".","head_angle",":","float","Angle",",","in","degrees",",","of","the","arrow","heads","(","and","negative","of","the","angle","of","the","tails",")",".","margin",":","float","Minimum","space","between","Sankey","outlines","and","the","edge","of","the","plot","area",".","tolerance",":","float","Acceptable","maximum","of","the","magnitude","of","the","sum","of","flows",".","The","magnitude","of","the","sum","of","connected","flows","can","not","be","greater","than","*","tolerance","*",".","*","*","kwargs","Any","additional","keyword","arguments","will","be","passed","to","`","add","`",",","which","will","create","the","first","subdiagram",".","See","Also","--","--","--","--","Sankey.add","Sankey.finish","Examples","--","--","--","--","..","plot",":",":","gallery\/specialty_plots\/sankey_basics.py"]
code: def __init__(
      self,
      ax=None,
      scale=1.0,
      unit="",
      format="%G",
      gap=0.25,
      radius=0.1,
      shoulder=0.03,
      offset=0.15,
      head_angle=100,
      margin=0.4,
      tolerance=1e-6,
      **kwargs,
  ):
      """
      Create a new Sankey instance.
  
      The optional arguments listed below are applied to all subdiagrams so
      that there is consistent alignment and formatting.
  
      In order to draw a complex Sankey diagram, create an instance of
      `Sankey` by calling it without any kwargs::
  
          sankey = Sankey()
  
      Then add simple Sankey sub-diagrams::
  
          sankey.add() # 1
          sankey.add() # 2
          #...
          sankey.add() # n
  
      Finally, create the full diagram::
  
          sankey.finish()
  
      Or, instead, simply daisy-chain those calls::
  
          Sankey().add().add...  .add().finish()
  
      Other Parameters
      ----------------
      ax : `~matplotlib.axes.Axes`
          Axes onto which the data should be plotted.  If *ax* isn't
          provided, new Axes will be created.
      scale : float
          Scaling factor for the flows.  *scale* sizes the width of the paths
          in order to maintain proper layout.  The same scale is applied to
          all subdiagrams.  The value should be chosen such that the product
          of the scale and the sum of the inputs is approximately 1.0 (and
          the product of the scale and the sum of the outputs is
          approximately -1.0).
      unit : str
          The physical unit associated with the flow quantities.  If *unit*
          is None, then none of the quantities are labeled.
      format : str or callable
          A Python number formatting string or callable used to label the
          flows with their quantities (i.e., a number times a unit, where the
          unit is given). If a format string is given, the label will be
          ``format % quantity``. If a callable is given, it will be called
          with ``quantity`` as an argument.
      gap : float
          Space between paths that break in/break away to/from the top or
          bottom.
      radius : float
          Inner radius of the vertical paths.
      shoulder : float
          Size of the shoulders of output arrows.
      offset : float
          Text offset (from the dip or tip of the arrow).
      head_angle : float
          Angle, in degrees, of the arrow heads (and negative of the angle of
          the tails).
      margin : float
          Minimum space between Sankey outlines and the edge of the plot
          area.
      tolerance : float
          Acceptable maximum of the magnitude of the sum of flows.  The
          magnitude of the sum of connected flows cannot be greater than
          *tolerance*.
      **kwargs
          Any additional keyword arguments will be passed to `add`, which
          will create the first subdiagram.
  
      See Also
      --------
      Sankey.add
      Sankey.finish
  
      Examples
      --------
      .. plot:: gallery/specialty_plots/sankey_basics.py
      """
      # Check the arguments.
      if gap < 0:
          raise ValueError(
              "'gap' is negative, which is not allowed because it would "
              "cause the paths to overlap"
          )
      if radius > gap:
          raise ValueError(
              "'radius' is greater than 'gap', which is not allowed because "
              "it would cause the paths to overlap"
          )
      if head_angle < 0:
          raise ValueError(
              "'head_angle' is negative, which is not allowed because it "
              "would cause inputs to look like outputs and vice versa"
          )
      if tolerance < 0:
          raise ValueError(
              "'tolerance' is negative, but it must be a magnitude"
          )
  
      # Create axes if necessary.
      if ax is None:
          import matplotlib.pyplot as plt
  
          fig = plt.figure()
          ax = fig.add_subplot(1, 1, 1, xticks=[], yticks=[])
  
      self.diagrams = []
  
      # Store the inputs.
      self.ax = ax
      self.unit = unit
      self.format = format
      self.scale = scale
      self.gap = gap
      self.radius = radius
      self.shoulder = shoulder
      self.offset = offset
      self.margin = margin
      self.pitch = np.tan(np.pi * (1 - head_angle / 180.0) / 2.0)
      self.tolerance = tolerance
  
      # Initialize the vertices of tight box around the diagram(s).
      self.extent = np.array((np.inf, -np.inf, np.inf, -np.inf))
  
      # If there are any kwargs, create the first subdiagram.
      if len(kwargs):
          self.add(**kwargs)
  
file_path: catboost/contrib/python/matplotlib/py3/matplotlib/sankey.py
imports: import logging
  from types import SimpleNamespace
  import numpy
  import matplotlib
  from matplotlib.path import Path
  from matplotlib.patches import PathPatch
  from matplotlib.transforms import Affine2D
  from matplotlib import _docstring
label_desc: Use image node_id 1 to create a new Sankey object  with example: obj = Sankey(ax, scale, unit, format, gap, radius, shoulder, offset, head_angle, margin, tolerance)