API_CHANGES

API CHANGES in matplotlib-0.81


  pylab and artist "set" functions renamed to setp to avoid clash with
  python2.4 built-in set.  Current version will issue a deprecation
  warning which will be removed in future versions

  imshow interpolation arguments changes for advanced interpolation
  schemes.  See help imshow, particularly the interpolation,
  filternorm and filterrad kwargs

  Support for masked arrays has been added to the plot command and to
  the Line2D object.  Only the valid points are plotted.  A
  "valid_only" kwarg was added to the get_xdata() and get_ydata()
  methods of Line2D; by default it is False, so that the original data
  arrays are returned. Setting it to True returns the plottable
  points.

  contour changes:

   Masked arrays: contour and contourf now accept masked arrays as the
    variable to be contoured.  Masking works correctly for contour,
    but a bug remains to be fixed before it will work for contourf.
    The "badmask" kwarg has been removed from both functions.

   Level argument changes:

     Old version: a list of levels as one of the positional arguments
     specified the lower bound of each filled region; the upper bound
     of the last region was taken as a very large number.  Hence, it
     was not possible to specify that z values between 0 and 1, for
     example, be filled, and that values outside that range remain
     unfilled.

     New version: a list of N levels is taken as specifying the
     boundaries of N-1 z ranges.  Now the user has more control over
     what is colored and what is not.  Repeated calls to contourf
     (with different colormaps or color specifications, for example)
     can be used to color different ranges of z.  Values of z outside
     an expected range are left uncolored.

     Example:
       Old: contourf(z, [0, 1, 2]) would yield 3 regions: 0-1, 1-2, and >2.
       New: it would yield 2 regions: 0-1, 1-2.  If the same 3 regions were
       desired, the equivalent list of levels would be [0, 1, 2, 1e38].


API CHANGES in matplotlib-0.80

  xlim/ylim/axis always return the new limits regardless of arguments.
  They now take kwargs which allow you to selectively change the upper
  or lower limits while leaving unnamed limits unchanged.  See
  help(xlim) for example

API CHANGES in matplotlib-0.73

  Removed deprecated ColormapJet and friends

  Removed all error handling from the verbose object

  figure num of zero is now allowed

API CHANGES in matplotlib-0.72

  Line2D, Text, and Patch copy_properties renamed update_from and
  moved into artist base class

  LineCollecitons.color renamed to LineCollections.set_color for
  consistency with set/get introspection mechanism,

  pylab figure now defaults to num=None, which creates a new figure
  with a guaranteed unique number 

  contsour method syntax changed - now it is matlab compatible

    unchanged: contour(Z)
    old: contour(Z, x=Y, y=Y)
    new: contour(X, Y, Z)

   see http://matplotlib.sf.net/matplotlib.pylab.html#-contour


   Increased the default resolution for save command.

   Renamed the base attribute of the ticker classes to _base to avoid conflict
   with the base method.  Sitt for subs

   subs=none now does autosubbing in the tick locator.

   New subplots that overlap old will delete the old axes.  If you do
   not want this behavior, use fig.add_subplot or the axes command

API CHANGES in matplotlib-0.71   

   Significant numerix namespace changes, introduced to resolve
   namespace clashes between python built-ins and mlab names.
   Refactored numerix to maintain separate modules, rather than
   folding all these names into a single namespace.  See the following
   mailing list threads for more information and background

     http://sourceforge.net/mailarchive/forum.php?thread_id=6398890&forum_id=36187
     http://sourceforge.net/mailarchive/forum.php?thread_id=6323208&forum_id=36187


  OLD usage

   from matplotlib.numerix import array, mean, fft

  NEW usage

   from matplotlib.numerix import array
   from matplotlib.numerix.mlab import mean
   from matplotlib.numerix.fft import fft

  numerix dir structure mirrors numarray (though it is an incomplete
  implementation)

    numerix
    numerix/mlab
    numerix/linear_algebra
    numerix/fft
    numerix/random_array

  but of course you can use 'numerix : Numeric' and still get the
  symbols.

  pylab still imports most of the symbols from Numerix, MLab, fft,
  etc, but is more cautious.  For names that clash with python names
  (min, max, sum), pylab keeps the builtins and provides the numeric
  versions with an a* prefix, eg (amin, amax, asum)


API CHANGES in matplotlib-0.70

   MplEvent factored into a base class Event and derived classes
   MouseEvent and KeyEvent

   Removed definct set_measurement in wx toolbar

API CHANGES in matplotlib-0.65.1

  removed add_axes and add_subplot from backend_bases.  Use
  figure.add_axes and add_subplot instead.  The figure now manages the
  current axes with gca and sca for get and set current axe.  If you
  have code you are porting which called, eg, figmanager.add_axes, you
  can now simply do figmanager.canvas.figure.add_axes.

API CHANGES in matplotlib-0.65

  mpl_connect and mpl_disconnect in the matlab interface renamed to
  connect and disconnect

  Did away with the text methods for angle since they were ambiguous.
  fontangle could mean fontstyle (obligue, etc) or the rotation of the
  text.  Use style and rotation instead.


API CHANGES in matplotlib-0.63

  Dates are now represented internally as float days since 0001-01-01,
  UTC.

  All date tickers and formatters are now in matplotlib.dates, rather
  than matplotlib.tickers

  converters have been abolished from all functions and classes.
  num2date and date2num are now the converter functions for all date
  plots

  Most of the date tick locators have a different meaning in their
  constructors.  In the prior implementation, the first argument was a
  base and multiples of the base were ticked.  Eg 

    HourLocator(5)  # old: tick every 5 minutes

  In the new implementation, the explicit points you want to tick are
  provided as a number or sequence

     HourLocator(range(0,5,61))  # new: tick every 5 minutes

  This gives much greater flexibility.  I have tried to make the
  default constructors (no args) behave similarly, where possible.

  Note that YearLocator still works under the base/multiple scheme.
  The difference between the YearLocator and the other locators is
  that years are not recurrent.


  Financial functions: 

    matplotlib.finance.quotes_historical_yahoo(ticker, date1, date2)

     date1, date2 are now datetime instances.  Return value is a list
     of quotes where the quote time is a float - days since gregorian
     start, as returned by date2num

     See examples/finance_demo.py for example usage of new API


API CHANGES in matplotlib-0.61

  canvas.connect is now deprecated for event handling.  use
  mpl_connect and mpl_disconnect instead.  The callback signature is
  func(event) rather than func(widget, evet)

API CHANGES in matplotlib-0.60

ColormapJet and Grayscale are deprecated.  For backwards
compatibility, they can be obtained either by doing

  from matplotlib.cm import ColormapJet 

or

  from matplotlib.matlab import *

They are replaced by cm.jet and cm.grey


API CHANGES in matplotlib-0.54.3

removed the set_default_font / get_default_font scheme from the
font_manager to unify customization of font defaults with the rest of
the rc scheme.  See examples/font_properties_demo.py and help(rc) in
matplotlib.matlab.


API CHANGES in matplotlib-0.54

matlab interface
================

dpi
---

Several of the backends used a PIXELS_PER_INCH hack that I added to
try and make images render consistently across backends.  This just
complicated matters.  So you may find that some font sizes and line
widths appear different than before.  Apologies for the
inconvenience. You should set the dpi to an accurate value for your
screen to get true sizes.


pcolor and scatter
------------------

There are two changes to the matlab interface API, both involving the
patch drawing commands.  For efficiency, pcolor and scatter have been
rewritten to use polygon collections, which are a new set of objects
from matplotlib.collections designed to enable efficient handling of
large collections of objects.  These new collections make it possible
to build large scatter plots or pcolor plots with no loops at the
python level, and are significantly faster than their predecessors.
The original pcolor and scatter functions are retained as
pcolor_classic and scatter_classic.

The return value from pcolor is a PolyCollection.  Most of the
propertes that are available on rectangles or other patches are also
available on PolyCollections, eg you can say

  c = scatter(blah, blah)
  c.set_linewidth(1.0)
  c.set_facecolor('r')
  c.set_alpha(0.5)

or 

  c = scatter(blah, blah)
  set(c, 'linewidth', 1.0, 'facecolor', 'r', 'alpha', 0.5)


Because the collection is a single object, you no longer need to loop
over the return value of scatter or pcolor to set properties for the
entire list. 

If you want the different elements of a collection to vary on a
property, eg to have different line widths, see matplotlib.collections
for a discussion on how to set the properties as a sequence.

For scatter, the size argument is now in points^2 (the area of the
symbol in points) as in matlab and is not in data coords as before.
Using sizes in data coords caused several problems.  So you will need
to adjust your size arguments accordingly or use scatter_classic.

mathtext spacing
----------------

For reasons not clear to me (and which I'll eventually fix) spacing no
longer works in font groups.  However, I added three new spacing
commands which compensate for this '\ ' (regular space), '\/' (small
space) and '\hspace{frac}' where frac is a fraction of fontsize in
points.  You will need to quote spaces in font strings, is

  title(r'$\rm{Histogram\ of\ IQ:}\ \mu=100,\ \sigma=15$')


Object interface - Application programmers
==========================================

Autoscaling
------------

  The x and y axis instances no longer have autoscale view.  These are
  handled by axes.autoscale_view

Axes creation
--------------

    You should not instantiate your own Axes any more using the OO API.
    Rather, create a Figure as before and in place of

      f = Figure(figsize=(5,4), dpi=100)
      a = Subplot(f, 111)
      f.add_axis(a)

    use

      f = Figure(figsize=(5,4), dpi=100)
      a = f.add_subplot(111)

    That is, add_axis no longer exists and is replaced by 

      add_axes(rect, axisbg=defaultcolor, frameon=True)
      add_subplot(num, axisbg=defaultcolor, frameon=True)

Artist methods
---------------

  If you define your own Artists, you need to rename the _draw method
  to draw

Bounding boxes
--------------  

   matplotlib.transforms.Bound2D is replaced by
   matplotlib.transforms.Bbox.  If you want to construct a bbox from
   left, bottom, width, height (the signature for Bound2D), use
   matplotlib.transforms.lbwh_to_bbox, as in 

    bbox = clickBBox = lbwh_to_bbox(left, bottom, width, height)

   The Bbox has a different API than the Bound2D.  Eg, if you want to
   get the width and height of the bbox

     OLD
        width  = fig.bbox.x.interval()
        height = fig.bbox.y.interval()

     New
        width  = fig.bbox.width()
        height = fig.bbox.height()


Object constructors
-------------------

  You no longer pass the bbox, dpi, or transforms to the various
  Artist constructors.  The old way or creating lines and rectangles
  was cumbersome because you had to pass so many attributes to the
  Line2D and Rectangle classes not related directly to the gemoetry
  and properties of the object.  Now default values are added to the
  object when you call axes.add_line or axes.add_patch, so they are
  hidden from the user.

  If you want to define a custom transformation on these objects, call
  o.set_transform(trans) where trans is a Transformation instance.

  In prior versions of you wanted to add a custom line in data coords,
  you would have to do

        l =  Line2D(dpi, bbox, x, y,
                    color = color,
                    transx = transx,
                    transy = transy,	
                    )

  now all you need is

        l =  Line2D(x, y, color=color)

  and the axes will set the transformation for you (unless you have
  set your own already, in which case it will eave it unchanged)

Transformations
---------------

  The entire transformation architecture has been rewritten.
  Previously the x and y transformations where stored in the xaxis and
  yaxis insstances.  The problem with this approach is it only allows
  for separable transforms (where the x and y transformations don't
  depend on one another).  But for cases like polar, they do.  Now
  transformations operate on x,y together.  There is a new base class
  matplotlib.transforms.Transformation and two concrete
  implemetations, matplotlib.transforms.SeparableTransformation and
  matplotlib.transforms.Affine.  The SeparableTransformation is
  constructed with the bounding box of the input (this determines the
  rectangular coordinate system of the input, ie the x and y view
  limits), the bounding box of the display, and possibily nonlinear
  transformations of x and y.  The 2 most frequently used
  transformations, data cordinates -> display and axes coordinates ->
  display are available as ax.transData and ax.transAxes.  See
  alignment_demo.py which uses axes coords.

  Also, the transformations should be much faster now, for two reasons

   * they are written entirely in extension code

   * because they operate on x and y together, they can do the entire
     transformation in one loop.  Earlier I did something along the
     lines of 

       xt = sx*func(x) + tx
       yt = sy*func(y) + ty

     Although this was done in numerix, it still involves 6 length(x)
     for-loops (the multiply, add, and function evaluation each for x
     and y).  Now all of that is done in a single pass.


  If you are using transformations and bounding boxes to get the
  cursor position in data coordinates, the method calls are a little
  different now.  See the updated examples/coords_demo.py which shows
  you how to do this.

  Likewise, if you are using the artist bounding boxes to pick items
  on the canvas with the GUI, the bbox methods are somewhat
  different.  You will need to see the updated
  examples/object_picker.py. 
 
  See unit/transforms_unit.py for many examples using the new
  transformations.


API changes at 0.50

  * refactored Figure class so it is no longer backend dependent.
    FigureCanvasBackend takes over the backend specific duties of the
    Figure.  matplotlib.backend_bases.FigureBase moved to
    matplotlib.figure.Figure.

  * backends must implement FigureCanvasBackend (the thing that
    controls the figure and handles the events if any) and
    FigureManagerBackend (wraps the canvas and the window for matlab
    interface).  FigureCanvasBase implements a backend switching
    mechanism

  * Figure is now an Artist (like everything else in the figure) and
    is totally backend independent

  * GDFONTPATH renamed to TTFPATH

  * backend faceColor argument changed to rgbFace

  * colormap stuff moved to colors.py

  * arg_to_rgb in backend_bases moved to class ColorConverter in
    colors.py

  * GD users must upgrade to gd-2.0.22 and gdmodule-0.52 since new gd
    features (clipping, antialiased lines) are now used.

  * Renderer must implement points_to_pixels

Migrating code:

  Matlab interface: 

    The only API change for those using the matlab interface is in how
    you call figure redraws for dynamically updating figures.  In the
    old API, you did
   
      fig.draw()

    In the new API, you do

      manager = get_current_fig_manager()
      manager.canvas.draw()

    See the examples system_monitor.py, dynamic_demo.py, and anim.py

  API

    There is one important API change for application developers.
    Figure instances used subclass GUI widgets that enabled them to be
    placed directly into figures.  Eg, FigureGTK subclassed
    gtk.DrawingArea.  Now the Figure class is independent of the
    backend, and FigureCanvas takes over the functionality formerly
    handled by Figure.  In order to include figures into your apps,
    you now need to do, for example

      # gtk example
      fig = Figure(figsize=(5,4), dpi=100)
      canvas = FigureCanvasGTK(fig)  # a gtk.DrawingArea
      canvas.show()
      vbox.pack_start(canvas)

    If you use the NavigationToolbar, this in now intialized with a
    FigureCanvas, not a Figure.  The examples embedding_in_gtk.py,
    embedding_in_gtk2.py, and mpl_with_glade.py all reflect the new
    API so use these as a guide.
 
    All prior calls to 

     figure.draw()  and
     figure.print_figure(args) 

    should now be
 
     canvas.draw()  and
     canvas.print_figure(args) 

    Apologies for the inconvenience.  This refactorization brings
    significant more freedom in developing matplotlib and should bring
    better plotting capabilities, so I hope the inconvenience is worth
    it.

  
API changes at 0.42

  * Refactoring AxisText to be backend independent.  Text drawing and
    get_window_extent functionality will be moved to the Renderer.

  * backend_bases.AxisTextBase is now text.Text module

  * All the erase and reset functionality removed frmo AxisText - not
    needed with double buffered drawing.  Ditto with state change.
    Text instances have a get_prop_tup method that returns a hashable
    tuple of text properties which you can use to see if text props
    have changed, eg by caching a font or layout instance in a dict
    with the prop tup as a key -- see RendererGTK.get_pango_layout in
    backend_gtk for an example.

  * Text._get_xy_display renamed Text.get_xy_display
  
  * Artist set_renderer and wash_brushes methods removed

  * Moved Legend class from matplotlib.axes into matplotlib.legend

  * Moved Tick, XTick, YTick, Axis, XAxis, YAxis from matplotlib.axes
    to matplotlib.axis

  * moved process_text_args to matplotlib.text

  * After getting Text handled in a backend independent fashion, the
    import process is much cleaner since there are no longer cyclic
    dependencies

  * matplotlib.matlab._get_current_fig_manager renamed to
    matplotlib.matlab.get_current_fig_manager to allow user access to
    the GUI window attribute, eg figManager.window for GTK and
    figManager.frame for wx
  

API changes at 0.40

- Artist
    * __init__ takes a DPI instance and a Bound2D instance which is
      the bounding box of the artist in display coords
    * get_window_extent returns a Bound2D instance
    * set_size is removed; replaced by bbox and dpi
    * the clip_gc method is removed.  Artists now clip themselves with
      their box
    * added _clipOn boolean attribute.  If True, gc clip to bbox.
    
- AxisTextBase
    * Initialized with a transx, transy which are Transform instances
    * set_drawing_area removed
    * get_left_right and get_top_bottom are replaced by get_window_extent

- Line2D Patches now take transx, transy
    * Initialized with a transx, transy which are Transform instances

- Patches
   * Initialized with a transx, transy which are Transform instances

- FigureBase attributes dpi is a DPI intance rather than scalar and
  new attribute bbox is a Bound2D in display coords, and I got rid of
  the left, width, height, etc... attributes.  These are now
  accessible as, for example, bbox.x.min is left, bbox.x.interval() is
  width, bbox.y.max is top, etc...

- GcfBase attribute pagesize renamed to figsize

- Axes
    * removed figbg attribute
    * added fig instance to __init__
    * resizing is handled by figure call to resize.
     
- Subplot
    * added fig instance to __init__

- Renderer methods for patches now take gcEdge and gcFace instances.
  gcFace=None takes the place of filled=False

- True and False symbols provided by cbook in a python2.3 compatible
  way

- new module transforms supplies Bound1D, Bound2D and Transform
  instances and more

- Changes to the matlab helpers API

  * _matlab_helpers.GcfBase is renamed by Gcf.  Backends no longer
    need to derive from this class.  Instead, they provide a factory
    function new_figure_manager(num, figsize, dpi).  The destroy
    method of the GcfDerived from the backends is moved to the derived
    FigureManager.

  * FigureManagerBase moved to backend_bases

  * Gcf.get_all_figwins renamed to Gcf.get_all_fig_managers

Jeremy:

  Make sure to self._reset = False in AxisTextWX._set_font.  This was
  something missing in my backend code.