r'''
Added a label to the middle of a power-law annotation (see ``goosempl.plot_powerlaw``).

:arguments:

  **exp** (``float``)
    The power-law exponent.

  **startx, starty** (``float``)
    Start coordinates.

:options:

  **width, height, endx, endy** (``float``)
    Definition of the end coordinate (only on of these options is needed).

  **rx, ry** (``float``)
    Shift in x- and y-direction w.r.t. the default coordinates.

  **units** ([``'relative'``] | ``'absolute'``)
    The type of units in which the coordinates are specified. Relative coordinates correspond to a
    fraction of the relevant axis. If you use relative coordinates, be sure to set the limits and
    scale before calling this function!

  **axis** ([``plt.gca()``] | ...)
    Specify the axis to which to apply the limits.

  ...
    Any ``plt.text(...)`` option.

:returns:

  The handle of the ``plt.text(...)`` command.

def annotate_powerlaw(text, exp, startx, starty, width=None, rx=0.5, ry=0.5, **kwargs):
  r'''
Added a label to the middle of a power-law annotation (see ``goosempl.plot_powerlaw``).

:arguments:

  **exp** (``float``)
    The power-law exponent.

  **startx, starty** (``float``)
    Start coordinates.

:options:

  **width, height, endx, endy** (``float``)
    Definition of the end coordinate (only on of these options is needed).

  **rx, ry** (``float``)
    Shift in x- and y-direction w.r.t. the default coordinates.

  **units** ([``'relative'``] | ``'absolute'``)
    The type of units in which the coordinates are specified. Relative coordinates correspond to a
    fraction of the relevant axis. If you use relative coordinates, be sure to set the limits and
    scale before calling this function!

  **axis** ([``plt.gca()``] | ...)
    Specify the axis to which to apply the limits.

  ...
    Any ``plt.text(...)`` option.

:returns:

  The handle of the ``plt.text(...)`` command.
  '''

  # get options/defaults
  endx   = kwargs.pop('endx'  , None      )
  endy   = kwargs.pop('endy'  , None      )
  height = kwargs.pop('height', None      )
  units  = kwargs.pop('units' , 'relative')
  axis   = kwargs.pop('axis'  , plt.gca() )

  # check
  if axis.get_xscale() != 'log' or axis.get_yscale() != 'log':
    raise IOError('This function only works on a log-log scale, where the power-law is a straight line')

  # apply width/height
  if width is not None:

    endx = startx + width
    endy = None

  elif height is not None:

    if   exp >  0: endy = starty + height
    elif exp == 0: endy = starty
    else         : endy = starty - height

    endx = None

  # transform
  if units.lower() == 'relative':
    [startx, endx] = rel2abs_x([startx, endx], axis)
    [starty, endy] = rel2abs_y([starty, endy], axis)

  # determine multiplication constant
  const = starty / ( startx**exp )

  # get end x/y-coordinate
  if endx is not None: endy = const * endx**exp
  else               : endx = ( endy / const )**( 1/exp )

  # middle
  x = 10. ** ( np.log10(startx) + rx * ( np.log10(endx) - np.log10(startx) ) )
  y = 10. ** ( np.log10(starty) + ry * ( np.log10(endy) - np.log10(starty) ) )

  # plot
  return axis.text(x, y, text, **kwargs)