barh: x and y args have been renamed to width and bottom

respectively, and their order has been swapped to maintain

a (position, value) order.

bar and barh: now accept kwarg 'edgecolor'.

bar and barh: The left, height, width and bottom args can

now all be scalars or sequences; see docstring.

barh: now defaults to edge aligned instead of center

aligned bars

bar, barh and hist: Added a keyword arg 'align' that

controls between edge or center bar alignment.

Collections: PolyCollection and LineCollection now accept

vertices or segments either in the original form [(x,y),

(x,y), ...] or as a 2D numerix array, with X as the first column

and Y as the second. Contour and quiver output the numerix

form. The transforms methods Bbox.update() and

Transformation.seq_xy_tups() now accept either form.

Collections: LineCollection is now a ScalarMappable like

PolyCollection, etc.

Specifying a grayscale color as a float is deprecated; use

a string instead, e.g., 0.75 -> '0.75'.

Collections: initializers now accept any mpl color arg, or

sequence of such args; previously only a sequence of rgba

tuples was accepted.

Colorbar: completely new version and api; see docstring. The

original version is still accessible as colorbar_classic, but

is deprecated.

Contourf: "extend" kwarg replaces "clip_ends"; see docstring.

Masked array support added to pcolormesh.

Modified aspect-ratio handling:

Removed aspect kwarg from imshow

Axes methods:

set_aspect(self, aspect, adjustable=None, anchor=None)

set_adjustable(self, adjustable)

set_anchor(self, anchor)

Pylab interface:

axis('image')

Backend developers: ft2font's load_char now takes a flags

argument, which you can OR together from the LOAD_XXX

constants.

API Changes in matplotlib-0.86

Matplotlib data is installed into the matplotlib module.

This is similar to package_data. This should get rid of

having to check for many possibilities in _get_data_path().

The MATPLOTLIBDATA env key is still checked first to allow

for flexibility.

1) Separated the color table data from cm.py out into

a new file, _cm.py, to make it easier to find the actual

code in cm.py and to add new colormaps. Everything

from _cm.py is imported by cm.py, so the split should be

transparent.

2) Enabled automatic generation of a colormap from

a list of colors in contour; see modified

examples/contour_demo.py.

3) Support for imshow of a masked array, with the

ability to specify colors (or no color at all) for

masked regions, and for regions that are above or

below the normally mapped region. See

examples/image_masked.py.

4) In support of the above, added two new classes,

ListedColormap, and no_norm, to colors.py, and modified

the Colormap class to include common functionality. Added

a clip kwarg to the normalize class.

API Changes in matplotlib-0.85

Made xtick and ytick separate props in rc

made pos=None the default for tick formatters rather than 0 to

indicate "not supplied"

Removed "feature" of minor ticks which prevents them from

overlapping major ticks. Often you want major and minor ticks at

the same place, and can offset the major ticks with the pad. This

could be made configurable

Changed the internal structure of contour.py to a more OO style.

Calls to contour or contourf in axes.py or pylab.py now return

a ContourSet object which contains references to the

LineCollections or PolyCollections created by the call,

as well as the configuration variables that were used.

The ContourSet object is a "mappable" if a colormap was used.

Added a clip_ends kwarg to contourf. From the docstring:

* clip_ends = True

If False, the limits for color scaling are set to the

minimum and maximum contour levels.

True (default) clips the scaling limits. Example:

if the contour boundaries are V = [-100, 2, 1, 0, 1, 2, 100],

then the scaling limits will be [-100, 100] if clip_ends

is False, and [-3, 3] if clip_ends is True.

Added kwargs linewidths, antialiased, and nchunk to contourf. These

are experimental; see the docstring.

Changed Figure.colorbar():

kw argument order changed;

if mappable arg is a non-filled ContourSet, colorbar() shows

lines instead hof polygons.

if mappable arg is a filled ContourSet with clip_ends=True,

the endpoints are not labelled, so as to give the

correct impression of open-endedness.

Changed LineCollection.get_linewidths to get_linewidth, for

consistency.

API Changes in matplotlib-0.84

Unified argument handling between hlines and vlines. Both now

take optionally a fmt argument (as in plot) and a keyword args

that can be passed onto Line2D.

Removed all references to "data clipping" in rc and lines.py since

these were not used and not optimized. I'm sure they'll be

resurrected later with a better implementation when needed.

'set' removed - no more deprecation warnings. Use 'setp' instead.

Backend developers: Added flipud method to image and removed it

from to_str. Removed origin kwarg from backend.draw_image.

origin is handled entirely by the frontend now.

API Changes in matplotlib-0.83

- Made HOME/.matplotlib the new config dir where the matplotlibrc

file, the ttf.cache, and the tex.cache live. The new default

filenames in .matplotlib have no leading dot and are not hidden.

Eg, the new names are matplotlibrc, tex.cache, and ttffont.cache.

This is how ipython does it so it must be right.

If old files are found, a warning is issued and they are moved to

the new location.

- backends/__init__.py no longer imports new_figure_manager,

draw_if_interactive and show from the default backend, but puts

these imports into a call to pylab_setup. Also, the Toolbar is no

longer imported from WX/WXAgg. New usage:

from backends import pylab_setup

new_figure_manager, draw_if_interactive, show = pylab_setup()

- Moved Figure.get_width_height() to FigureCanvasBase. It now

returns int instead of float.

API Changes in matplotlib-0.82

- toolbar import change in GTKAgg, GTKCairo and WXAgg

- Added subplot config tool to GTK* backends -- note you must now

import the NavigationToolbar2 from your backend of choice rather

than from backend_gtk because it needs to know about the backend

specific canvas -- see examples/embedding_in_gtk2.py. Ditto for

wx backend -- see examples/embedding_in_wxagg.py

- hist bin change

Sean Richards notes there was a problem in the way we created

the binning for histogram, which made the last bin

underrepresented. From his post:

I see that hist uses the linspace function to create the bins

and then uses searchsorted to put the values in their correct

bin. Thats all good but I am confused over the use of linspace

for the bin creation. I wouldn't have thought that it does

what is needed, to quote the docstring it creates a "Linear

spaced array from min to max". For it to work correctly

shouldn't the values in the bins array be the same bound for

each bin? (i.e. each value should be the lower bound of a

bin). To provide the correct bins for hist would it not be

something like

def bins(xmin, xmax, N):

if N==1: return xmax

dx = (xmax-xmin)/N # instead of N-1

return xmin + dx*arange(N)

This suggestion is implemented in 0.81. My test script with these

changes does not reveal any bias in the binning

from matplotlib.numerix.mlab import randn, rand, zeros, Float

from matplotlib.mlab import hist, mean

Nbins = 50

Ntests = 200

results = zeros((Ntests,Nbins), typecode=Float)

for i in range(Ntests):

print 'computing', i

x = rand(10000)

n, bins = hist(x, Nbins)

results[i] = n

print mean(results)

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

- contour 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.