Ticket #4529: trac_4529-add_docs_eg_to_some_user_facing_functions.patch

File trac_4529-add_docs_eg_to_some_user_facing_functions.patch, 12.5 KB (added by ppurka, 9 years ago)

Apply to devel/sage

  • sage/plot/all.py

    # HG changeset patch
    # User Punarbasu Purkayastha <ppurka@gmail.com>
    # Date 1337533730 -28800
    # Node ID 16f61e53bcb1ecc5e88589f6970feb1dc99429b2
    # Parent  c0383ff651981be54fc02592b3412b9122b0099f
     - add some examples for log scale to other user facing functions
     - also add a minor check in parametric_plot
     - finally add loglog_*, semilogx_*, semilogy_* plots
    
    diff --git a/sage/plot/all.py b/sage/plot/all.py
    a b  
    11from graphics import show_default, Graphics, is_Graphics
    22from plot import plot, graphics_array, list_plot, parametric_plot, polar_plot
     3from plot import loglog_plot, semilogx_plot, semilogy_plot
     4from plot import loglog_list_plot, semilogx_list_plot, semilogy_list_plot
    35from line import line, line2d
    46from arrow import arrow, arrow2d
    57from bar_chart import bar_chart
  • sage/plot/contour_plot.py

    diff --git a/sage/plot/contour_plot.py b/sage/plot/contour_plot.py
    a b  
    526526
    527527    - ``legend_label`` -- the label for this item in the legend
    528528
     529    - ``base`` - (default: 10) the base of the logarithm if
     530      a logarithmic scale is set. This must be greater than 1. The base
     531      can be also given as a list or tuple ``(basex, basey)``.
     532      ``basex`` sets the base of the logarithm along the horizontal
     533      axis and ``basey`` sets the base along the vertical axis.
     534
     535    - ``scale`` -- (default: `linear`) string. The scale of the axes.
     536      Possible values are `linear`, `loglog`, `semilogx`, `semilogy`.
     537
     538      The scale can be also be given as single argument that is a list
     539      or tuple ``(scale, base)`` or ``(scale, basex, basey)``.
     540
     541      The `loglog` scale sets both the horizontal and vertical axes to
     542      logarithmic scale. The `semilogx` scale sets the horizontal axis
     543      to logarithmic scale. The `semilogy` scale sets the vertical axis
     544      to logarithmic scale. The `linear` scale is the default value
     545      when :class:`Graphics` is initialized.
     546
    529547    EXAMPLES:
    530548
    531549    A simple circle with a radius of 2. Note that
     
    605623
    606624        sage: implicit_plot(lambda x,y: x^2+y^2-2, (x,-3,3), (y,-3,3), fill=True, plot_points=500) # long time
    607625
     626    An example of an implicit plot on 'loglog' scale::
     627
     628        sage: implicit_plot(x^2+y^2 == 200, (x,1,200), (y,1,200), scale='loglog')
     629
    608630    TESTS::
    609631
    610632        sage: f(x,y) = x^2 + y^2 - 2
     
    683705 
    684706    - ``legend_label`` -- the label for this item in the legend
    685707
     708    - ``base`` - (default: 10) the base of the logarithm if
     709      a logarithmic scale is set. This must be greater than 1. The base
     710      can be also given as a list or tuple ``(basex, basey)``.
     711      ``basex`` sets the base of the logarithm along the horizontal
     712      axis and ``basey`` sets the base along the vertical axis.
     713
     714    - ``scale`` -- (default: `linear`) string. The scale of the axes.
     715      Possible values are `linear`, `loglog`, `semilogx`, `semilogy`.
     716
     717      The scale can be also be given as single argument that is a list
     718      or tuple ``(scale, base)`` or ``(scale, basex, basey)``.
     719
     720      The `loglog` scale sets both the horizontal and vertical axes to
     721      logarithmic scale. The `semilogx` scale sets the horizontal axis
     722      to logarithmic scale. The `semilogy` scale sets the vertical axis
     723      to logarithmic scale. The `linear` scale is the default value
     724      when :class:`Graphics` is initialized.
     725
    686726
    687727    EXAMPLES:
    688728
     
    742782
    743783        sage: region_plot(s>0,(s,-2,2),(t,-2,2))
    744784
     785    An example of a region plot in 'loglog' scale::
     786
     787        sage: region_plot(x^2+y^2<100, (x,1,10), (y,1,10), scale='loglog')
     788
    745789    """
    746790
    747791    from sage.plot.all import Graphics
  • sage/plot/plot.py

    diff --git a/sage/plot/plot.py b/sage/plot/plot.py
    a b  
    591591      documentation further below for more information, starting at "the
    592592      algorithm used to insert".
    593593   
     594    - ``base`` - (default: 10) the base of the logarithm if
     595      a logarithmic scale is set. This must be greater than 1. The base
     596      can be also given as a list or tuple ``(basex, basey)``.
     597      ``basex`` sets the base of the logarithm along the horizontal
     598      axis and ``basey`` sets the base along the vertical axis.
     599
     600    - ``scale`` -- (default: `linear`) string. The scale of the axes.
     601      Possible values are `linear`, `loglog`, `semilogx`, `semilogy`.
     602
     603      The scale can be also be given as single argument that is a list
     604      or tuple ``(scale, base)`` or ``(scale, basex, basey)``.
     605
     606      The `loglog` scale sets both the horizontal and vertical axes to
     607      logarithmic scale. The `semilogx` scale sets the horizontal axis
     608      to logarithmic scale. The `semilogy` scale sets the vertical axis
     609      to logarithmic scale. The `linear` scale is the default value
     610      when :class:`Graphics` is initialized.
     611
    594612    - ``xmin`` - starting x value
    595613
    596614    - ``xmax`` - ending x value
     
    778796    ambiguity::
    779797   
    780798        sage: plot(sin(1/x), (-1, 1))
    781    
     799
     800    Plotting in logarithmic scale is possible for 2D plots.::
     801
     802        sage: plot(exp, (1, 10), scale='semilogy') # log axis on vertical
     803
     804        sage: plot(exp, (1, 10), scale='loglog')   # both axes are log
     805
     806        sage: plot(exp, (1, 10), scale='loglog', base=2) # base of log is 2
     807
     808    We can also change the scale of the axes in the graphics just before
     809    displaying::
     810
     811        sage: G = plot(exp, 1, 10)
     812        sage: G.show(scale=('semilogy', 2))
     813
     814
    782815    The algorithm used to insert extra points is actually pretty
    783816    simple. On the picture drawn by the lines below::
    784817   
     
    13601393        sage: parametric_plot( vector((sin(t), sin(2*t))), (t, 0, 2*pi), color='green')
    13611394        sage: parametric_plot( vector([t, t+1, t^2]), (t, 0, 1))
    13621395
     1396    Plotting in logarithmic scale is possible with 2D plots. The keyword
     1397    ``aspect_ratio`` will be ignored if the scale is not `loglog` or
     1398    `linear`.::
     1399
     1400        sage: parametric_plot((x, x**2), (x, 1, 10), scale='loglog')
     1401
     1402    We can also change the scale of the axes in the graphics just before
     1403    displaying. In this case, the ``aspect_ratio`` must be specified as
     1404    `automatic` if the ``scale`` is set to `semilogx` or `semilogy`. For
     1405    other values of the ``scale`` parameter, any ``aspect_ratio`` can be
     1406    used, or the keyword need not be provided.::
     1407
     1408        sage: p = parametric_plot((x, x**2), (x, 1, 10))
     1409        sage: p.show(scale='semilogy', aspect_ratio='automatic')
     1410
    13631411    TESTS::
    13641412   
    13651413        sage: parametric_plot((x, t^2), (x, -4, 4))
     
    14061454    if num_vars>num_ranges:
    14071455        raise ValueError, "there are more variables than variable ranges"
    14081456
     1457    # Reset aspect_ratio to 'automatic' in case scale is 'semilog[xy]'.
     1458    # Otherwise matplotlib complains.
     1459    scale = kwargs.get('scale', None)
     1460    if scale == 'semilogy' or scale == 'semilogx':
     1461        kwargs['aspect_ratio'] = 'automatic'
     1462
    14091463    if num_funcs == 2 and num_ranges == 1:
    14101464        kwargs['parametric'] = True                   
    14111465        return plot(funcs, *args, **kwargs)
     
    15471601
    15481602        sage: list_plot({22: 3365, 27: 3295, 37: 3135, 42: 3020, 47: 2880, 52: 2735, 57: 2550})
    15491603
     1604    Plotting in logarithmic scale is possible for 2D plots.::
     1605
     1606        sage: yl = [2**k for k in range(10)]
     1607        sage: list_plot(yl, scale='semilogy')       # log axis on vertical
     1608
     1609        sage: list_plot(yl, scale='loglog')         # both axes are log
     1610
     1611        sage: list_plot(yl, scale='loglog', base=2) # base of log is 2
     1612
     1613    We can also change the scale of the axes in the graphics just before
     1614    displaying::
     1615
     1616        sage: G = list_plot(yl)
     1617        sage: G.show(scale=('semilogy', 2))
     1618
    15501619    TESTS:
    15511620
    15521621    We check to see that the x/y min/max data are set correctly.
     
    15921661        else:
    15931662            return point(data, **kwargs)
    15941663
     1664#------------------------ Graphs on log scale ---------------------------#
     1665@options(base=10)
     1666def loglog_plot(funcs, *args, **kwds):
     1667    """
     1668    Plot graphics in 'loglog' scale, that is, both the horizontal and the
     1669    vertical axes will be in logarithmic scale.
     1670
     1671    INPUTS:
     1672
     1673    - ``base`` -- (default: 10) the base of the logarithm. This must be
     1674      greater than 1. The base can be also given as a list or tuple
     1675      ``(basex, basey)``.  ``basex`` sets the base of the logarithm along the
     1676      horizontal axis and ``basey`` sets the base along the vertical axis.
     1677
     1678    - ``funcs`` -- any Sage object as is acceptable to the :func:`plot`.
     1679
     1680    For all other inputs, look at the documentation of :func:`plot`.
     1681
     1682    EXAMPLES::
     1683
     1684        sage: loglog_plot(exp, (1,10)) # plot in loglog scale with base 10
     1685
     1686        sage: loglog_plot(exp, (1,10), base=2) # with base 2 on both axes
     1687
     1688        sage: loglog_plot(exp, (1,10), base=(2,3))
     1689
     1690    """
     1691    return plot(funcs, *args, scale='loglog', **kwds)
     1692
     1693@options(base=10)
     1694def semilogx_plot(funcs, *args, **kwds):
     1695    """
     1696    Plot graphics in 'semilogx' scale, that is, the horizontal axis will be
     1697    in logarithmic scale.
     1698
     1699    INPUTS:
     1700
     1701    - ``base`` -- (default: 10) the base of the logarithm. This must be
     1702      greater than 1.
     1703
     1704    - ``funcs`` -- any Sage object as is acceptable to the :func:`plot`.
     1705
     1706    For all other inputs, look at the documentation of :func:`plot`.
     1707
     1708    EXAMPLES::
     1709
     1710        sage: semilogx_plot(exp, (1,10)) # plot in semilogx scale, base 10
     1711
     1712        sage: semilogx_plot(exp, (1,10), base=2) # with base 2
     1713
     1714    """
     1715    return plot(funcs, *args, scale='semilogx', **kwds)
     1716
     1717@options(base=10)
     1718def semilogy_plot(funcs, *args, **kwds):
     1719    """
     1720    Plot graphics in 'semilogy' scale, that is, the vertical axis will be
     1721    in logarithmic scale.
     1722
     1723    INPUTS:
     1724
     1725    - ``base`` -- (default: 10) the base of the logarithm. This must be
     1726      greater than 1.
     1727
     1728    - ``funcs`` -- any Sage object as is acceptable to the :func:`plot`.
     1729
     1730    For all other inputs, look at the documentation of :func:`plot`.
     1731
     1732    EXAMPLES::
     1733
     1734        sage: semilogy_plot(exp, (1,10)) # plot in semilogy scale, base 10
     1735
     1736        sage: semilogy_plot(exp, (1,10), base=2) # with base 2
     1737
     1738    """
     1739    return plot(funcs, *args, scale='semilogy', **kwds)
     1740
     1741@options(base=10)
     1742def loglog_list_plot(data, plotjoined=False, **kwds):
     1743    """
     1744    Plot the `data` in 'loglog' scale, that is, both the horizontal and the
     1745    vertical axes will be in logarithmic scale.
     1746
     1747    INPUTS:
     1748
     1749    - ``base`` -- (default: 10) the base of the logarithm. This must be
     1750      greater than 1. The base can be also given as a list or tuple
     1751      ``(basex, basey)``.  ``basex`` sets the base of the logarithm along the
     1752      horizontal axis and ``basey`` sets the base along the vertical axis.
     1753
     1754    For all other inputs, look at the documentation of :func:`list_plot`.
     1755
     1756    EXAMPLES::
     1757
     1758        sage: yl = [5**k for k in range(10)]; xl = [2**k for k in range(10)]
     1759        sage: loglog_list_plot(zip(xl, yl)) # plot in loglog scale with base 10
     1760
     1761        sage: loglog_list_plot(zip(xl, yl), base=2) # with base 2 on both axes
     1762
     1763        sage: loglog_list_plot(zip(xl, yl), base=(2,5))
     1764
     1765    """
     1766    return list_plot(data, plotjoined=plotjoined, scale='loglog', **kwds)
     1767
     1768@options(base=10)
     1769def semilogx_list_plot(data, plotjoined=False, **kwds):
     1770    """
     1771    Plot `data` in 'semilogx' scale, that is, the horizontal axis will be
     1772    in logarithmic scale.
     1773
     1774    INPUTS:
     1775
     1776    - ``base`` -- (default: 10) the base of the logarithm. This must be
     1777      greater than 1.
     1778
     1779    For all other inputs, look at the documentation of :func:`plot`.
     1780
     1781    EXAMPLES::
     1782
     1783        sage: yl = [5**k for k in range(10)]
     1784        sage: semilogx_list_plot(yl) # plot in semilogx scale, base 10
     1785
     1786        sage: semilogx_list_plot(yl, base=2) # with base 2
     1787
     1788    """
     1789    return list_plot(data, plotjoined=plotjoined, scale='semilogx', **kwds)
     1790
     1791@options(base=10)
     1792def semilogy_list_plot(data, plotjoined=False, **kwds):
     1793    """
     1794    Plot `data` in 'semilogy' scale, that is, the vertical axis will be
     1795    in logarithmic scale.
     1796
     1797    INPUTS:
     1798
     1799    - ``base`` -- (default: 10) the base of the logarithm. This must be
     1800      greater than 1.
     1801
     1802    For all other inputs, look at the documentation of :func:`plot`.
     1803
     1804    EXAMPLES::
     1805
     1806        sage: yl = [5**k for k in range(10)]
     1807        sage: semilogy_list_plot(yl) # plot in semilogy scale, base 10
     1808
     1809        sage: semilogy_list_plot(yl, base=5) # with base 5
     1810
     1811    """
     1812    return list_plot(data, plotjoined=plotjoined, scale='semilogy', **kwds)
     1813
    15951814def to_float_list(v):
    15961815    """
    15971816    Given a list or tuple or iterable v, coerce each element of v to a