pylab0.99_manual

# pylab0.99_manual - Matplotlib Release 0.99.1.1 Darren Dale,...

This preview shows page 1. Sign up to view the full content.

This is the end of the preview. Sign up to access the rest of the document.

Unformatted text preview: Matplotlib Release 0.99.1.1 Darren Dale, Michael Droettboom, Eric Firing, John Hunter November 20, 2009 CONTENTS I User’s Guide 1 1 Introduction 3 2 Installing 2.1 OK, so you want to do it the hard way? 2.2 Installing from source . . . . . . . . . 2.3 Build requirements . . . . . . . . . . . 2.4 Building on OSX . . . . . . . . . . . . 3 Pyplot tutorial 9 3.1 Controlling line properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2 Working with multiple ﬁgures and axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.3 Working with text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4 Interactive navigation 19 4.1 Navigation Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5 Customizing matplotlib 23 5.1 The matplotlibrc ﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.2 Dynamic rc settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6 Using matplotlib in a python shell 33 6.1 Ipython to the rescue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.2 Other python interpreters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.3 Controlling interactive updating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 7 Working with text 7.1 Text introduction . . . . . . . . . 7.2 Basic text commands . . . . . . . 7.3 Text properties and layout . . . . 7.4 Writing mathematical expressions 7.5 Text rendering With LaTeX . . . 7.6 Annotating text . . . . . . . . . . 8 Image tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 6 6 7 37 37 37 39 42 52 56 61 i 8.1 8.2 8.3 9 Startup commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Importing image data into Numpy arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Plotting numpy arrays as images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Artist tutorial 9.1 Customizing your objects 9.2 Object containers . . . . . 9.3 Figure container . . . . . 9.4 Axes container . . . . . . 9.5 Axis containers . . . . . . 9.6 Tick containers . . . . . . 10 Legend guide 10.1 What to be displayed 10.2 Multicolumn Legend 10.3 Legend location . . 10.4 Multiple Legend . . . . . . 11 Event handling and picking 11.1 Event connections . . 11.2 Event attributes . . . . 11.3 Mouse enter and leave 11.4 Object picking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 77 79 79 81 83 86 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 89 91 91 92 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 95 96 100 101 12 Transformations Tutorial 12.1 Data coordinates . . . . . . . . . . . . . . . . . 12.2 Axes coordinates . . . . . . . . . . . . . . . . . 12.3 Blended transformations . . . . . . . . . . . . . 12.4 Using oﬀset transforms to create a shadow eﬀect 12.5 The transformation pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 105 108 110 111 113 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Path Tutorial 115 13.1 Bézier example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 13.2 Compound paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 14 Annotating Axes 14.1 Annotating with Text with Box . . . . . . . . . . 14.2 Annotating with Arrow . . . . . . . . . . . . . . . 14.3 Using ConnectorPatch . . . . . . . . . . . . . . . 14.4 Placing Artist at the anchored location of the Axes 14.5 Zoom eﬀect between Axes . . . . . . . . . . . . . 14.6 Deﬁne Custom BoxStyle . . . . . . . . . . . . . . 15 Toolkits 15.1 Basemap . 15.2 GTK Tools 15.3 Excel Tools 15.4 Natgrid . . 15.5 mplot3d . . ii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 121 123 128 129 131 132 . . . . . 137 137 137 137 137 137 15.6 AxesGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 16 Screenshots 16.1 Simple Plot . . . . . . 16.2 Subplot demo . . . . . 16.3 Histograms . . . . . . 16.4 Path demo . . . . . . 16.5 mplot3d . . . . . . . . 16.6 Ellipses . . . . . . . . 16.7 Bar charts . . . . . . . 16.8 Pie charts . . . . . . . 16.9 Table demo . . . . . . 16.10 Scatter demo . . . . . 16.11 Slider demo . . . . . . 16.12 Fill demo . . . . . . . 16.13 Date demo . . . . . . 16.14 Financial charts . . . . 16.15 Basemap demo . . . . 16.16 Log plots . . . . . . . 16.17 Polar plots . . . . . . 16.18 Legends . . . . . . . . 16.19 Mathtext_examples . . 16.20 Native TeX rendering 16.21 EEG demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 139 140 140 141 142 143 144 145 146 147 148 149 150 151 152 152 153 154 155 157 157 17 What’s new in matplotlib 159 17.1 new in matplotlib-0.99 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 17.2 new in 0.98.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 18 License 171 18.1 License agreement for matplotlib 0.99.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 19 Credits 173 II 177 The Matplotlib FAQ 20 Installation FAQ 20.1 Report a compilation problem . . . . . . . . . . . . . . 20.2 matplotlib compiled ﬁne, but nothing shows up with plot 20.3 Cleanly rebuild and reinstall everything . . . . . . . . . 20.4 Install from svn . . . . . . . . . . . . . . . . . . . . . . 20.5 Install from git . . . . . . . . . . . . . . . . . . . . . . 20.6 Backends . . . . . . . . . . . . . . . . . . . . . . . . . 20.7 OS-X questions . . . . . . . . . . . . . . . . . . . . . . 20.8 Windows questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 179 179 180 181 181 181 183 186 21 Usage 187 21.1 Matplotlib, pylab, and pyplot: how are they related? . . . . . . . . . . . . . . . . . . . . . 187 iii 22 Howto 22.1 Plotting: howto . . . . . . . . . . . . 22.2 Contributing: howto . . . . . . . . . 22.3 Matplotlib in a web application server 22.4 Search examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 190 199 201 202 23 Troubleshooting 23.1 Obtaining matplotlib version . . . 23.2 matplotlib install location . . . 23.3 .matplotlib directory location . 23.4 Report a problem . . . . . . . . . 23.5 Problems with recent svn versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 203 203 203 204 205 III . . . . . . . . . . The Matplotlib Developers’ Guide 24 Coding guide 24.1 Version control . . . . . . . . 24.2 Style guide . . . . . . . . . . 24.3 Documentation and docstrings 24.4 Developing a new backend . . 24.5 Licenses . . . . . . . . . . . 207 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 209 213 216 217 218 25 Documenting matplotlib 25.1 Getting started . . . . . . . . . . . . . . . 25.2 Organization of matplotlib’s documentation 25.3 Formatting . . . . . . . . . . . . . . . . . 25.4 Figures . . . . . . . . . . . . . . . . . . . 25.5 Referring to mpl documents . . . . . . . . 25.6 Internal section references . . . . . . . . . 25.7 Section names, etc . . . . . . . . . . . . . 25.8 Inheritance diagrams . . . . . . . . . . . . 25.9 Emacs helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 221 221 222 224 225 226 226 226 227 . . . . . . 229 229 229 229 230 230 231 26 Doing a matplolib release 26.1 Testing . . . . . . . . . . 26.2 Branching . . . . . . . . 26.3 Packaging . . . . . . . . 26.4 Release candidate testing: 26.5 Uploading . . . . . . . . 26.6 Announcing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Working with transformations 233 27.1 matplotlib.transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 28 Adding new scales and projections to matplotlib 253 28.1 Creating a new scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 28.2 Creating a new projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 28.3 API documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 iv 29 Docs outline 263 29.1 Reviewer notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 IV The Matplotlib API 269 30 API Changes 30.1 Changes in 0.99 . 30.2 Changes for 0.98.x 30.3 Changes for 0.98.1 30.4 Changes for 0.98.0 30.5 Changes for 0.91.2 30.6 Changes for 0.91.1 30.7 Changes for 0.91.0 30.8 Changes for 0.90.1 30.9 Changes for 0.90.0 30.10 Changes for 0.87.7 30.11 Changes for 0.86 . 30.12 Changes for 0.85 . 30.13 Changes for 0.84 . 30.14 Changes for 0.83 . 30.15 Changes for 0.82 . 30.16 Changes for 0.81 . 30.17 Changes for 0.80 . 30.18 Changes for 0.73 . 30.19 Changes for 0.72 . 30.20 Changes for 0.71 . 30.21 Changes for 0.70 . 30.22 Changes for 0.65.1 30.23 Changes for 0.65 . 30.24 Changes for 0.63 . 30.25 Changes for 0.61 . 30.26 Changes for 0.60 . 30.27 Changes for 0.54.3 30.28 Changes for 0.54 . 30.29 Changes for 0.50 . 30.30 Changes for 0.42 . 30.31 Changes for 0.40 . 271 271 271 273 273 278 278 278 279 280 281 283 283 284 285 285 286 287 287 287 288 289 289 289 289 290 290 291 291 294 296 297 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 matplotlib conﬁguration 299 31.1 matplotlib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 32 matplotlib afm 303 32.1 matplotlib.afm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 33 matplotlib artists 307 33.1 matplotlib.artist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 33.2 matplotlib.legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 v 33.3 matplotlib.lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 33.4 matplotlib.patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 33.5 matplotlib.text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 34 matplotlib axes 373 34.1 matplotlib.axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 35 matplotlib axis 517 35.1 matplotlib.axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 36 matplotlib cbook 525 36.1 matplotlib.cbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 37 matplotlib cm 535 37.1 matplotlib.cm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 38 matplotlib collections 537 38.1 matplotlib.collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 39 matplotlib colorbar 549 39.1 matplotlib.colorbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 40 matplotlib colors 551 40.1 matplotlib.colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 41 matplotlib dates 559 41.1 matplotlib.dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 42 matplotlib ﬁgure 567 42.1 matplotlib.figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 43 matplotlib font_manager 585 43.1 matplotlib.font_manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 43.2 matplotlib.fontconfig_pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 44 matplotlib nxutils 593 44.1 matplotlib.nxutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 45 matplotlib mathtext 595 45.1 matplotlib.mathtext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 46 matplotlib mlab 609 46.1 matplotlib.mlab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 47 matplotlib path 631 47.1 matplotlib.path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 48 matplotlib pyplot 637 48.1 matplotlib.pyplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 vi 49 matplotlib spine 785 49.1 matplotlib.spine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785 50 matplotlib ticker 789 50.1 matplotlib.ticker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789 51 matplotlib backends 51.1 matplotlib.backend_bases . . . . . . . 51.2 matplotlib.backends.backend_gtkagg 51.3 matplotlib.backends.backend_qt4agg 51.4 matplotlib.backends.backend_wxagg . 51.5 matplotlib.dviread . . . . . . . . . . . 51.6 matplotlib.type1font . . . . . . . . . . V Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 797 811 811 811 812 815 817 vii viii Part I User’s Guide 1 CHAPTER ONE INTRODUCTION matplotlib is a library for making 2D plots of arrays in Python. Although it has its origins in emulating the MATLAB™ graphics commands, it is independent of MATLAB, and can be used in a Pythonic, object oriented way. Although matplotlib is written primarily in pure Python, it makes heavy use of NumPy and other extension code to provide good performance even for large arrays. matplotlib is designed with the philosophy that you should be able to create simple plots with just a few commands, or just one! If you want to see a histogram of your data, you shouldn’t need to instantiate objects, call methods, set properties, and so on; it should just work. For years, I used to use MATLAB exclusively for data analysis and visualization. MATLAB excels at making nice looking plots easy. When I began working with EEG data, I found that I needed to write applications to interact with my data, and developed and EEG analysis application in MATLAB. As the application grew in complexity, interacting with databases, http servers, manipulating complex data structures, I began to strain against the limitations of MATLAB as a programming language, and decided to start over in Python. Python more than makes up for all of MATLAB’s deﬁciencies as a programming language, but I was having diﬃculty ﬁnding a 2D plotting package (for 3D VTK more than exceeds all of my needs). When I went searching for a Python plotting package, I had several requirements: • Plots should look great - publication quality. One important requirement for me is that the text looks good (antialiased, etc.) • Postscript output for inclusion with TeX documents • Embeddable in a graphical user interface for application development • Code should be easy enough that I can understand it and extend it • Making plots should be easy Finding no package that suited me just right, I did what any self-respecting Python programmer would do: rolled up my sleeves and dived in. Not having any real experience with computer graphics, I decided to emulate MATLAB’s plotting capabilities because that is something MATLAB does very well. This had the added advantage that many people have a lot of MATLAB experience, and thus they can quickly get up to steam plotting in python. From a developer’s perspective, having a ﬁxed user interface (the pylab interface) has been very useful, because the guts of the code base can be redesigned without aﬀecting user code. The matplotlib code is conceptually divided into three parts: the pylab interface is the set of functions provided by matplotlib.pylab which allow the user to create plots with code quite similar to MATLAB ﬁgure generating code (Pyplot tutorial). The matplotlib frontend or matplotlib API is the set of classes that 3 Matplotlib, Release 0.99.1.1 do the heavy lifting, creating and managing ﬁgures, text, lines, plots and so on (Artist tutorial). This is an abstract interface that knows nothing about output. The backends are device dependent drawing devices, aka renderers, that transform the frontend representation to hardcopy or a display device (What is a backend?). Example backends: PS creates PostScript® hardcopy, SVG creates Scalable Vector Graphics hardcopy, Agg creates PNG output using the high quality Anti-Grain Geometry library that ships with matplotlib, GTK embeds matplotlib in a Gtk+ application, GTKAgg uses the Anti-Grain renderer to create a ﬁgure and embed it a Gtk+ application, and so on for PDF, WxWidgets, Tkinter etc. matplotlib is used by many people in many diﬀerent contexts. Some people want to automatically generate PostScript ﬁles to send to a printer or publishers. Others deploy matplotlib on a web application server to generate PNG output for inclusion in dynamically-generated web pages. Some use matplotlib interactively from the Python shell in Tkinter on Windows™. My primary use is to embed matplotlib in a Gtk+ EEG application that runs on Windows, Linux and Macintosh OS X. 4 Chapter 1. Introduction CHAPTER TWO INSTALLING There are lots of diﬀerent ways to install matplotlib, and the best way depends on what operating system you are using, what you already have installed, and how you want to use it. To avoid wading through all the details (and potential complications) on this page, the easiest thing for you to do is use one of the prepackaged python distributions that already provide matplotlib built in. The Enthought Python Distribution (EPD) for Windows, OS X or Redhat is an excellent choice that “just works” out of the box. Another excellent alternative for Windows users is Python (x, y) which tends to be updated a bit more frequently. Both of these packages include matplotlib and pylab, and lots of other useful tools. matplotlib is also packaged for pretty much every major linux distribution, so if you are on linux your package manager will probably provide matplotlib prebuilt. One single click installer and you are done. 2.1 OK, so you want to do it the hard way? For some people, the prepackaged pythons discussed above are not an option. That’s OK, it’s usually pretty easy to get a custom install working. You will ﬁrst need to ﬁnd out if you have python installed on your machine, and if not, install it. The oﬃcial python builds are available for download here, but OS X users please read Which python for OS X?. Once you have python up and running, you will need to install numpy. numpy provides high performance array data structures and mathematical functions, and is a requirement for matplotlib. You can test your progress: >>> import numpy >>> print numpy.__version__ matplotlib requires numpy version 1.1 or later. Although it is not a requirement to use matplotlib, we strongly encourage you to install ipython, which is an interactive shell for python that is matplotlib aware. Once you have ipython, numpy and matplotlib installed, in ipython’s “pylab” mode you have a matlab-like environment that automatically handles most of the conﬁguration details for you, so you can get up and running quickly: [email protected]:~> ipython -pylab Python 2.4.5 (#4, Apr 12 2008, 09:09:16) IPython 0.9.0 -- An enhanced Interactive Python. 5 Matplotlib, Release 0.99.1.1 Welcome to pylab, a matplotlib-based Python environment. For more information, type ’help(pylab)’. In [1]: x = randn(10000) In [2]: hist(x, 100) And a voila, a ﬁgure pops up. But we are putting the cart ahead of the horse – ﬁrst we need to get matplotlib installed. We provide prebuilt binaries for OS X and Windows on the matplotlib download page. Click on the latest release of the “matplotlib” package, choose your python version (2.4 or 2.5) and your platform (macosx or win32) and you should be good to go. If you have any problems, please check the Installation FAQ, google around a little bit, and post a question the mailing list. Instructions for installing our OSX binaries are found in the FAQ ref:install_osx_binaries. Note that when testing matplotlib installations from the interactive python console, there are some issues relating to user interface toolkits and interactive settings that are discussed in Using matplotlib in a python shell. 2.2 Installing from source If you are interested perhaps in contributing to matplotlib development, or just like to build everything yourself, it is not diﬃcult to build matplotlib from source. Grab the latest tar.gz release ﬁle from sourceforge, or if you want to develop matplotlib or just need the latest bugﬁxed version, grab the latest svn version Install from svn. Once you have satisﬁed the requirements detailed below (mainly python, numpy, libpng and freetype), you build matplotlib in the usual way: cd matplotlib python setup.py build python setup.py install We provide a setup.cfg ﬁle that lives along setup.py which you can use to customize the build process, for example, which default backend to use, whether some of the optional libraries that matplotlib ships with are installed, and so on. This ﬁle will be particularly useful to those packaging matplotlib. 2.3 Build requirements These are external packages which you will need to install before installing matplotlib. Windows users only need the ﬁrst two (python and numpy) since the others are built into the matplotlib windows installers available for download at the sourceforge site. If you are building on OSX, see Building on OSX python 2.4 (or later but not python3) matplotlib requires python 2.4 or later (download) numpy 1.1 (or later) array support for python (download) 6 Chapter 2. Installing Matplotlib, Release 0.99.1.1 libpng 1.1 (or later) library for loading and saving PNG ﬁles (download). libpng requires zlib. If you are a windows user, you can ignore this since we build support into the matplotlib single click installer freetype 1.4 (or later) library for reading true type font ﬁles. If you are a windows user, you can ignore this since we build support into the matplotlib single click installer. Optional These are optional packages which you may want to install to use matplotlib with a user interface toolkit. See What is a backend? for more details on the optional matplotlib backends and the capabilities they provide tk 8.3 or later The TCL/Tk widgets library used by the TkAgg backend pyqt 3.1 or later The Qt3 widgets library python wrappers for the QtAgg backend pyqt 4.0 or later The Qt4 widgets library python wrappers for the Qt4Agg backend pygtk 2.2 or later The python wrappers for the GTK widgets library for use with the GTK or GTKAgg backend wxpython 2.6 or later The python wrappers for the wx widgets library for use with the WXAgg backend wxpython 2.8 or later The python wrappers for the wx widgets library for use with the WX backend pyﬂtk 1.0 or later The python wrappers of the FLTK widgets library for use with FLTKAgg Required libraries that ship with matplotlib agg 2.4 The antigrain C++ rendering engine. matplotlib links against the agg template source statically, so it will not aﬀect anything on your system outside of matplotlib. pytz 2007g or later timezone handling for python datetime objects. By default, matplotlib will install pytz if it isn’t already installed on your system. To override the default, use setup.cfg to force or prevent installation of pytz. dateutil 1.1 or later extensions to python datetime handling. By default, matplotlib will install dateutil if it isn’t already installed on your system. To override the default, use setup.cfg to force or prevent installation of dateutil. 2.4 Building on OSX The build situation on OSX is complicated by the various places one can get the png and freetype requirements from (darwinports, ﬁnk, /usr/X11R6) and the diﬀerent architectures (x86, ppc, universal) and the diﬀerent OSX version (10.4 and 10.5). We recommend that you build the way we do for the OSX release: by grabbing the tarbar or svn repository, cd-ing into the release/osx dir, and following the instruction in the README. This directory has a Makeﬁle which will automatically grab the zlib, png and freetype dependencies from the web, build them with the right ﬂags to make universal libraries, and then build the matplotlib source and binary installers. 2.4. Building on OSX 7 Matplotlib, Release 0.99.1.1 8 Chapter 2. Installing CHAPTER THREE PYPLOT TUTORIAL matplotlib.pyplot is a collection of command style functions that make matplotlib work like matlab. Each pyplot function makes some change to a ﬁgure: eg, create a ﬁgure, create a plotting area in a ﬁgure, plot some lines in a plotting area, decorate the plot with labels, etc.... matplotlib.pyplot is stateful, in that it keeps track of the current ﬁgure and plotting area, and the plotting functions are directed to the current axes import matplotlib.pyplot as plt plt.plot([1,2,3]) plt.ylabel(’some numbers’) plt.show() 9 Matplotlib, Release 0.99.1.1 You may be wondering why the x-axis ranges from 0-2 and the y-axis from 1-3. If you provide a single list or array to the plot() command, matplotlib assumes it is a sequence of y values, and automatically generates the x values for you. Since python ranges start with 0, the default x vector has the same length as y but starts with 0. Hence the x data are [0,1,2]. plot() is a versatile command, and will take an arbitrary number of arguments. For example, to plot x versus y, you can issue the command: plt.plot([1,2,3,4], [1,4,9,16]) For every x, y pair of arguments, there is a optional third argument which is the format string that indicates the color and line type of the plot. The letters and symbols of the format string are from matlab, and you concatenate a color string with a line style string. The default format string is ‘b-‘, which is a solid blue line. For example, to plot the above with red circles, you would issue import matplotlib.pyplot as plt plt.plot([1,2,3,4], [1,4,9,16], ’ro’) plt.axis([0, 6, 0, 20]) See the plot() documentation for a complete list of line styles and format strings. The axis() command in the example above takes a list of [xmin, xmax, ymin, ymax] and speciﬁes the viewport of the axes. If matplotlib were limited to working with lists, it would be fairly useless for numeric processing. Generally, you will use numpy arrays. In fact, all sequences are converted to numpy arrays internally. The example below illustrates a plotting several lines with diﬀerent format styles in one command using arrays. 10 Chapter 3. Pyplot tutorial Matplotlib, Release 0.99.1.1 import numpy as np import matplotlib.pyplot as plt # evenly sampled time at 200ms intervals t = np.arange(0., 5., 0.2) # red dashes, blue squares and green triangles plt.plot(t, t, ’r--’, t, t**2, ’bs’, t, t**3, ’g^’) 3.1 Controlling line properties Lines have many attributes that you can set: linewidth, dash style, antialiased, etc; matplotlib.lines.Line2D. There are several ways to set line properties see • Use keyword args: plt.plot(x, y, linewidth=2.0) • Use the setter methods of the Line2D instance. plot returns a list of lines; eg line1, line2 = plot(x1,y1,x2,x2). Below I have only one line so it is a list of length 1. I use tuple unpacking in the line, = plot(x, y, ’o’) to get the ﬁrst element of the list: 3.1. Controlling line properties 11 Matplotlib, Release 0.99.1.1 line, = plt.plot(x, y, ’-’) line.set_antialiased(False) # turn off antialising • Use the setp() command. The example below uses a Matlab-style command to set multiple properties on a list of lines. setp works transparently with a list of objects or a single object. You can either use python keyword arguments or Matlab-style string/value pairs: lines = plt.plot(x1, y1, x2, y2) # use keyword args plt.setp(lines, color=’r’, linewidth=2.0) # or matlab style string value pairs plt.setp(lines, ’color’, ’r’, ’linewidth’, 2.0) Here are the available Line2D properties. Property alpha animated antialiased or aa clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data ﬁgure label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius solid_capstyle solid_joinstyle transform visible xdata ydata 12 Value Type ﬂoat [True | False] [True | False] a matplotlib.transform.Bbox instance [True | False] a Path instance and a Transform instance, a Patch any matplotlib color the hit testing function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points (np.array xdata, np.array ydata) a matplotlib.ﬁgure.Figure instance any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘steps’ | ...] ﬂoat value in points [True | False] [ ‘+’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) used in interactive line selection the line pick selection radius [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance [True | False] np.array np.array Continued on next page Chapter 3. Pyplot tutorial Matplotlib, Release 0.99.1.1 zorder Table 3.1 – continued from previous page any number To get a list of settable line properties, call the setp() function with a line or lines as argument In [69]: lines = plt.plot([1,2,3]) In [70]: plt.setp(lines) alpha: float animated: [True | False] antialiased or aa: [True | False] ...snip 3.2 Working with multiple ﬁgures and axes Matlab, and pyplot, have the concept of the current ﬁgure and the current axes. All plotting commands apply to the current axes. The function gca() returns the current axes (a matplotlib.axes.Axes instance), and gcf() returns the current ﬁgure (matplotlib.figure.Figure instance). Normally, you don’t have to worry about this, because it is all taken care of behind the scenes. Below is a script to create two subplots. import numpy as np import matplotlib.pyplot as plt def f(t): return np.exp(-t) * np.cos(2*np.pi*t) t1 = np.arange(0.0, 5.0, 0.1) t2 = np.arange(0.0, 5.0, 0.02) plt.figure(1) plt.subplot(211) plt.plot(t1, f(t1), ’bo’, t2, f(t2), ’k’) plt.subplot(212) plt.plot(t2, np.cos(2*np.pi*t2), ’r--’) 3.2. Working with multiple ﬁgures and axes 13 Matplotlib, Release 0.99.1.1 The figure() command here is optional because figure(1) will be created by default, just as a subplot(111) will be created by default if you don’t manually specify an axes. The subplot() command speciﬁes numrows, numcols, fignum where fignum ranges from 1 to numrows*numcols. The commas in the subplot command are optional if numrows*numcols<10. So subplot(211) is identical to subplot(2,1,1). You can create an arbitrary number of subplots and axes. If you want to place an axes manually, ie, not on a rectangular grid, use the axes() command, which allows you to specify the location as axes([left, bottom, width, height]) where all values are in fractional (0 to 1) coordinates. See pylab_examples example code: axes_demo.py for an example of placing axes manually and pylab_examples example code: line_styles.py for an example with lots-o-subplots. You can create multiple ﬁgures by using multiple figure() calls with an increasing ﬁgure number. Of course, each ﬁgure can contain as many axes and subplots as your heart desires: import matplotlib.pyplot as plt plt.figure(1) # the first figure plt.subplot(211) # the first subplot in the first figure plt.plot([1,2,3]) plt.subplot(212) # the second subplot in the first figure plt.plot([4,5,6]) plt.figure(2) plt.plot([4,5,6]) 14 # a second figure # creates a subplot(111) by default Chapter 3. Pyplot tutorial Matplotlib, Release 0.99.1.1 plt.figure(1) plt.subplot(211) plt.title(’Easy as 1,2,3’) # figure 1 current; subplot(212) still current # make subplot(211) in figure1 current # subplot 211 title You can clear the current ﬁgure with clf() and the current axes with cla(). If you ﬁnd this statefulness, annoying, don’t despair, this is just a thin stateful wrapper around an object oriented API, which you can use instead (see Artist tutorial) 3.3 Working with text The text() command can be used to add text in an arbitrary location, and the xlabel(), ylabel() and title() are used to add text in the indicated locations (see Text introduction for a more detailed example) import numpy as np import matplotlib.pyplot as plt mu, sigma = 100, 15 x = mu + sigma * np.random.randn(10000) # the histogram of the data n, bins, patches = plt.hist(x, 50, normed=1, facecolor=’g’, alpha=0.75) plt.xlabel(’Smarts’) plt.ylabel(’Probability’) plt.title(’Histogram of IQ’) plt.text(60, .025, r’$\mu=100,\ \sigma=15$’) plt.axis([40, 160, 0, 0.03]) plt.grid(True) 3.3. Working with text 15 Matplotlib, Release 0.99.1.1 All of the text() commands return an matplotlib.text.Text instance. Just as with with lines above, you can customize the properties by passing keyword arguments into the text functions or using setp(): t = plt.xlabel(’my data’, fontsize=14, color=’red’) These properties are covered in more detail in Text properties and layout. 3.3.1 Using mathematical expressions in text matplotlib accepts TeX equation expressions in any text expression. For example to write the expression σi = 15 in the title, you can write a TeX expression surrounded by dollar signs: plt.title(r’$\sigma_i=15$’) The r preceeding the title string is important – it signiﬁes that the string is a raw string and not to treate backslashes and python escapes. matplotlib has a built-in TeX expression parser and layout engine, and ships its own math fonts – for details see Writing mathematical expressions. Thus you can use mathematical text across platforms without requiring a TeX installation. For those who have LaTeX and dvipng installed, you can also use LaTeX to format your text and incorporate the output directly into your display ﬁgures or saved postscript – see Text rendering With LaTeX . 16 Chapter 3. Pyplot tutorial Matplotlib, Release 0.99.1.1 3.3.2 Annotating text The uses of the basic text() command above place text at an arbitrary position on the Axes. A common use case of text is to annotate some feature of the plot, and the annotate() method provides helper functionality to make annotations easy. In an annotation, there are two points to consider: the location being annotated represented by the argument xy and the location of the text xytext. Both of these arguments are (x,y) tuples. import numpy as np import matplotlib.pyplot as plt ax = plt.subplot(111) t = np.arange(0.0, 5.0, 0.01) s = np.cos(2*np.pi*t) line, = plt.plot(t, s, lw=2) plt.annotate(’local max’, xy=(2, 1), xytext=(3, 1.5), arrowprops=dict(facecolor=’black’, shrink=0.05), ) plt.ylim(-2,2) plt.show() 3.3. Working with text 17 Matplotlib, Release 0.99.1.1 In this basic example, both the xy (arrow tip) and xytext locations (text location) are in data coordinates. There are a variety of other coordinate systems one can choose – see Annotating text and Annotating Axes for details. More examples can be found in pylab_examples example code: annotation_demo.py. 18 Chapter 3. Pyplot tutorial CHAPTER FOUR INTERACTIVE NAVIGATION All ﬁgure windows come with a navigation toolbar, which can be used to navigate through the data set. Here is a description of each of the buttons at the bottom of the toolbar The Forward and Back buttons These are akin to the web browser forward and back buttons. They are used to navigate back and forth between previously deﬁned views. They have no meaning unless you have already navigated somewhere else using the pan and zoom buttons. This is analogous to trying to click Back on your web browser before visiting a new page –nothing happens. Home always takes you to the ﬁrst, default view of your data. For Home, Forward and Back, think web browser where data views are web pages. Use the pan and zoom to rectangle to deﬁne new views. The Pan/Zoom button This button has two modes: pan and zoom. Click the toolbar button to activate panning and zooming, then put your mouse somewhere over an axes. Press the left mouse button and hold it to pan the ﬁgure, dragging it to a new position. When you release it, the data under the point where you pressed will be moved to the point where you released. If you press ‘x’ or ‘y’ while panning the motion will be constrained to the x or y axis, respectively. Press the right mouse button to zoom, dragging it to a new position. The x axis will be zoomed in proportionate to the rightward movement and zoomed out proportionate to the leftward movement. Ditto for the yaxis and up/down motions. The point under your mouse when you begin the zoom remains stationary, allowing you to zoom to an arbitrary point in the ﬁgure. You can use the modiﬁer keys ‘x’, ‘y’ or ‘CONTROL’ to constrain the zoom to the x axes, the y axes, or aspect ratio preserve, respectively. With polar plots, the pan and zoom functionality behaves diﬀerently. The radius axis labels can be dragged using the left mouse button. The radius scale can be zoomed in and out using the right mouse button. The Zoom-to-rectangle button Click this toolbar button to activate this mode. Put your mouse somewhere over and axes and press the left mouse button. Drag the mouse while holding the button to 19 Matplotlib, Release 0.99.1.1 a new location and release. The axes view limits will be zoomed to the rectangle you have deﬁned. There is also an experimental ‘zoom out to rectangle’ in this mode with the right button, which will place your entire axes in the region deﬁned by the zoom out rectangle. The Subplot-configuration button Use this tool to conﬁgure the parameters of the subplot: the left, right, top, bottom, space between the rows and space between the columns. The Save button Click this button to launch a ﬁle save dialog. You can save ﬁles with the following extensions: png, ps, eps, svg and pdf. 4.1 Navigation Keyboard Shortcuts Command Home/Reset Back Forward Pan/Zoom Zoom-to-rect Save Toggle fullscreen Constrain pan/zoom to x axis Constrain pan/zoom to y axis Preserve aspect ratio Toggle grid Toggle y axis scale (log/linear) Keyboard Shortcut(s) h or r or home c or left arrow or backspace v or right arrow p o s f hold x hold y hold CONTROL g l If you are using matplotlib.pyplot the toolbar will be created automatically for every ﬁgure. If you are writing your own user interface code, you can add the toolbar as a widget. The exact syntax depends on your UI, but we have examples for every supported UI in the matplotlib/examples/user_interfaces directory. Here is some example code for GTK: from matplotlib.figure import Figure from matplotlib.backends.backend_gtkagg import FigureCanvasGTKAgg as FigureCanvas from matplotlib.backends.backend_gtkagg import NavigationToolbar2GTKAgg as NavigationToolbar win = gtk.Window() win.connect("destroy", lambda x: gtk.main_quit()) win.set_default_size(400,300) win.set_title("Embedding in GTK") vbox = gtk.VBox() win.add(vbox) fig = Figure(figsize=(5,4), dpi=100) ax = fig.add_subplot(111) 20 Chapter 4. Interactive navigation Matplotlib, Release 0.99.1.1 ax.plot([1,2,3]) canvas = FigureCanvas(fig) # a gtk.DrawingArea vbox.pack_start(canvas) toolbar = NavigationToolbar(canvas, win) vbox.pack_start(toolbar, False, False) win.show_all() gtk.main() 4.1. Navigation Keyboard Shortcuts 21 Matplotlib, Release 0.99.1.1 22 Chapter 4. Interactive navigation CHAPTER FIVE CUSTOMIZING MATPLOTLIB 5.1 The matplotlibrc ﬁle matplotlib uses matplotlibrc conﬁguration ﬁles to customize all kinds of properties, which we call rc settings or rc parameters. You can control the defaults of almost every property in matplotlib: ﬁgure size and dpi, line width, color and style, axes, axis and grid properties, text and font properties and so on. matplotlib looks for matplotlibrc in three locations, in the following order: 1. matplotlibrc in the current working directory, usually used for speciﬁc customizations that you do not want to apply elsewhere. 2. .matplotlib/matplotlibrc, for the user’s default customizations. See .matplotlib directory location. 3. INSTALL/matplotlib/mpl-data/matplotlibrc, where INSTALL is something like /usr/lib/python2.5/site-packages on Linux, and maybe C:\Python25\Lib\site-packages on Windows. Every time you install matplotlib, this ﬁle will be overwritten, so if you want your customizations to be saved, please move this ﬁle to you .matplotlib directory. To display where the currently active matplotlibrc ﬁle was loaded from, one can do the following: >>> import matplotlib >>> matplotlib.matplotlib_fname() ’/home/foo/.matplotlib/matplotlibrc’ See below for a sample matplotlibrc ﬁle. 5.2 Dynamic rc settings You can also dynamically change the default rc settings in a python script or interactively from the python shell. All of the rc settings are stored in a dictionary-like variable called matplotlib.rcParams, which is global to the matplotlib package. rcParams can be modiﬁed directly, for example: 23 Matplotlib, Release 0.99.1.1 import matplotlib as mpl mpl.rcParams[’lines.linewidth’] = 2 mpl.rcParams[’lines.color’] = ’r’ Matplotlib also provides a couple of convenience functions for modifying rc settings. The matplotlib.rc() command can be used to modify multiple settings in a single group at once, using keyword arguments: import matplotlib as mpl mpl.rc(’lines’, linewidth=2, color=’r’) There matplotlib.rcdefaults() command will restore the standard matplotlib default settings. There is some degree of validation when setting the values of rcParams, see matplotlib.rcsetup for details. 5.2.1 A sample matplotlibrc ﬁle ### MATPLOTLIBRC FORMAT # # # # # # # # # # # # # # # # # # # # This is a sample matplotlib configuration file - you can find a copy of it on your system in site-packages/matplotlib/mpl-data/matplotlibrc. If you edit it there, please note that it will be overridden in your next install. If you want to keep a permanent local copy that will not be over-written, place it in HOME/.matplotlib/matplotlibrc (unix/linux like systems) and C:\Documents and Settings\yourname\.matplotlib (win32 systems). This file is best viewed in a editor which supports python mode syntax highlighting. Blank lines, or lines starting with a comment symbol, are ignored, as are trailing comments. Other lines must have the format key : val # optional comment Colors: for the color values below, you can either use - a matplotlib color string, such as r, k, or b - an rgb tuple, such as (1.0, 0.5, 0.0) - a hex string, such as ff00ff or #ff00ff - a scalar grayscale intensity such as 0.75 - a legal html color name, eg red, blue, darkslategray #### CONFIGURATION BEGINS HERE # the default backend; one of GTK GTKAgg GTKCairo CocoaAgg FltkAgg # MacOSX QtAgg Qt4Agg TkAgg WX WXAgg Agg Cairo GDK PS PDF SVG Template # You can also deploy your own backend outside of matplotlib by # referring to the module name (which must be in the PYTHONPATH) as # ’module://my_backend’ backend : GTKAgg 24 Chapter 5. Customizing matplotlib Matplotlib, Release 0.99.1.1 # if you are runing pyplot inside a GUI and your backend choice # conflicts, we will automatically try and find a compatible one for # you if backend_fallback is True #backend_fallback: True #interactive : False #toolbar : toolbar2 # None | classic | toolbar2 #timezone : UTC # a pytz timezone string, eg US/Central or Europe/Paris # Where your matplotlib data lives if you installed to a non-default # location. This is where the matplotlib fonts, bitmaps, etc reside #datapath : /home/jdhunter/mpldata ### LINES # See http://matplotlib.sourceforge.net/api/artist_api.html#module-matplotlib.lines for more # information on line properties. #lines.linewidth : 1.0 # line width in points #lines.linestyle :# solid line #lines.color : blue #lines.marker : None # the default marker #lines.markeredgewidth : 0.5 # the line width around the marker symbol #lines.markersize : 6 # markersize, in points #lines.dash_joinstyle : miter # miter|round|bevel #lines.dash_capstyle : butt # butt|round|projecting #lines.solid_joinstyle : miter # miter|round|bevel #lines.solid_capstyle : projecting # butt|round|projecting #lines.antialiased : True # render lines in antialised (no jaggies) ### PATCHES # Patches are graphical objects that fill 2D space, like polygons or # circles. See # http://matplotlib.sourceforge.net/api/artist_api.html#module-matplotlib.patches # information on patch properties #patch.linewidth : 1.0 # edge width in points #patch.facecolor : blue #patch.edgecolor : black #patch.antialiased : True # render patches in antialised (no jaggies) ### FONT # # font properties used by text.Text. See # http://matplotlib.sourceforge.net/api/font_manager_api.html for more # information on font properties. The 6 font properties used for font # matching are given below with their default values. # # The font.family property has five values: ’serif’ (e.g. Times), # ’sans-serif’ (e.g. Helvetica), ’cursive’ (e.g. Zapf-Chancery), # ’fantasy’ (e.g. Western), and ’monospace’ (e.g. Courier). Each of # these font families has a default list of font names in decreasing # order of priority associated with them. # # The font.style property has three values: normal (or roman), italic # or oblique. The oblique style will be used for italic, if it is not 5.2. Dynamic rc settings 25 Matplotlib, Release 0.99.1.1 # present. # # The font.variant property has two values: normal or small-caps. For # TrueType fonts, which are scalable fonts, small-caps is equivalent # to using a font size of ’smaller’, or about 83% of the current font # size. # # The font.weight property has effectively 13 values: normal, bold, # bolder, lighter, 100, 200, 300, ..., 900. Normal is the same as # 400, and bold is 700. bolder and lighter are relative values with # respect to the current weight. # # The font.stretch property has 11 values: ultra-condensed, # extra-condensed, condensed, semi-condensed, normal, semi-expanded, # expanded, extra-expanded, ultra-expanded, wider, and narrower. This # property is not currently implemented. # # The font.size property is the default font size for text, given in pts. # 12pt is the standard value. # #font.family : sans-serif #font.style : normal #font.variant : normal #font.weight : medium #font.stretch : normal # note that font.size controls default text sizes. To configure # special text sizes tick labels, axes, labels, title, etc, see the rc # settings for axes and ticks. Special text sizes can be defined # relative to font.size, using the following values: xx-small, x-small, # small, medium, large, x-large, xx-large, larger, or smaller #font.size : 12.0 #font.serif : Bitstream Vera Serif, New Century Schoolbook, Century Schoolbook L, Utopia, ITC B #font.sans-serif : Bitstream Vera Sans, Lucida Grande, Verdana, Geneva, Lucid, Arial, Helvetica, Ava #font.cursive : Apple Chancery, Textile, Zapf Chancery, Sand, cursive #font.fantasy : Comic Sans MS, Chicago, Charcoal, Impact, Western, fantasy #font.monospace : Bitstream Vera Sans Mono, Andale Mono, Nimbus Mono L, Courier New, Courier, Fixed ### TEXT # text properties used by text.Text. See # http://matplotlib.sourceforge.net/api/artist_api.html#module-matplotlib.text for more # information on text properties #text.color : black ### LaTeX customizations. See http://www.scipy.org/Wiki/Cookbook/Matplotlib/UsingTex #text.usetex : False # use latex for all text handling. The following fonts # are supported through the usual rc parameter settings: # new century schoolbook, bookman, times, palatino, # zapf chancery, charter, serif, sans-serif, helvetica, # avant garde, courier, monospace, computer modern roman, # computer modern sans serif, computer modern typewriter # If another font is desired which can loaded using the # LaTeX \usepackage command, please inquire at the 26 Chapter 5. Customizing matplotlib Matplotlib, Release 0.99.1.1 # matplotlib mailing list #text.latex.unicode : False # use "ucs" and "inputenc" LaTeX packages for handling # unicode strings. #text.latex.preamble : # IMPROPER USE OF THIS FEATURE WILL LEAD TO LATEX FAILURES # AND IS THEREFORE UNSUPPORTED. PLEASE DO NOT ASK FOR HELP # IF THIS FEATURE DOES NOT DO WHAT YOU EXPECT IT TO. # preamble is a comma separated list of LaTeX statements # that are included in the LaTeX document preamble. # An example: # text.latex.preamble : \usepackage{bm},\usepackage{euler} # The following packages are always loaded with usetex, so # beware of package collisions: color, geometry, graphicx, # type1cm, textcomp. Adobe Postscript (PSSNFS) font packages # may also be loaded, depending on your font settings #text.dvipnghack : None #text.markup # # # # # # : ’plain’ some versions of dvipng don’t handle alpha channel properly. Use True to correct and flush ~/.matplotlib/tex.cache before testing and False to force correction off. None will try and guess based on your dvipng version # # # # # # # # Affects how text, such as titles and labels, are interpreted by default. ’plain’: As plain, unformatted text ’tex’: As TeX-like text. Text between $’s will be formatted as a TeX math expression. This setting has no effect when text.usetex is True. In that case, all text will be sent to TeX for processing. # The following settings allow you to select the fonts in math mode. # They map from a TeX font name to a fontconfig font pattern. # These settings are only used if mathtext.fontset is ’custom’. # Note that this "custom" mode is unsupported and may go away in the # future. #mathtext.cal : cursive #mathtext.rm : serif #mathtext.tt : monospace #mathtext.it : serif:italic #mathtext.bf : serif:bold #mathtext.sf : sans #mathtext.fontset : cm # Should be ’cm’ (Computer Modern), ’stix’, # ’stixsans’ or ’custom’ #mathtext.fallback_to_cm : True # When True, use symbols from the Computer Modern # fonts when a symbol can not be found in one of # the custom math fonts. #mathtext.default : it # # # # 5.2. Dynamic rc settings The default font to use for math. Can be any of the LaTeX font names, including the special name "regular" for the same font used in regular text. 27 Matplotlib, Release 0.99.1.1 ### AXES # default face and edge color, default tick sizes, # default fontsizes for ticklabels, and so on. See # http://matplotlib.sourceforge.net/api/axes_api.html#module-matplotlib.axes #axes.hold : True # whether to clear the axes by default on #axes.facecolor : white # axes background color #axes.edgecolor : black # axes edge color #axes.linewidth : 1.0 # edge linewidth #axes.grid : False # display grid or not #axes.titlesize : large # fontsize of the axes title #axes.labelsize : medium # fontsize of the x any y labels #axes.labelcolor : black #axes.axisbelow : False # whether axis gridlines and ticks are below # the axes elements (lines, text, etc) #axes.formatter.limits : -7, 7 # use scientific notation if log10 # of the axis range is smaller than the # first or larger than the second #axes.unicode_minus : True # use unicode for the minus symbol # rather than hypen. See http://en.wikipedia.org/wiki/Plus_sign#Plus_sig #polaraxes.grid #axes3d.grid : True : True # display grid on polar axes # display grid on 3d axes ### TICKS # see http://matplotlib.sourceforge.net/api/axis_api.html#matplotlib.axis.Tick #xtick.major.size :4 # major tick size in points #xtick.minor.size :2 # minor tick size in points #xtick.major.pad :4 # distance to major tick label in points #xtick.minor.pad :4 # distance to the minor tick label in points #xtick.color :k # color of the tick labels #xtick.labelsize : medium # fontsize of the tick labels #xtick.direction : in # direction: in or out #ytick.major.size #ytick.minor.size #ytick.major.pad #ytick.minor.pad #ytick.color #ytick.labelsize #ytick.direction ### GRIDS #grid.color #grid.linestyle #grid.linewidth : : : : : : : : : : 4 2 4 4 k medium in black : 0.5 ### Legend #legend.fancybox : False #legend.isaxes #legend.numpoints #legend.fontsize : True :2 : large 28 # # # # # # # major tick size in points minor tick size in points distance to major tick label in points distance to the minor tick label in points color of the tick labels fontsize of the tick labels direction: in or out # grid color # dotted # in points # if True, use a rounded box for the # legend, else a rectangle # the number of points in the legend line Chapter 5. Customizing matplotlib Matplotlib, Release 0.99.1.1 #legend.pad : 0.0 #legend.borderpad : 0.5 #legend.markerscale : 1.0 # the following dimensions are #legend.labelsep : 0.010 #legend.handlelen : 0.05 #legend.handletextsep : 0.02 #legend.axespad : 0.02 #legend.shadow : False # deprecated; the fractional whitespace inside the legend border # border whitspace in fontsize units # the relative size of legend markers vs. original in axes coords # the vertical space between the legend entries # the length of the legend lines # the space between the legend line and legend text # the border between the axes and legend edge ### FIGURE # See http://matplotlib.sourceforge.net/api/figure_api.html#matplotlib.figure.Figure #figure.figsize : 8, 6 # figure size in inches #figure.dpi : 80 # figure dots per inch #figure.facecolor : 0.75 # figure facecolor; 0.75 is scalar gray #figure.edgecolor : white # figure edgecolor # The figure subplot parameters. All dimensions are fraction of the # figure width or height #figure.subplot.left : 0.125 # the left side of the subplots of the figure #figure.subplot.right : 0.9 # the right side of the subplots of the figure #figure.subplot.bottom : 0.1 # the bottom of the subplots of the figure #figure.subplot.top : 0.9 # the top of the subplots of the figure #figure.subplot.wspace : 0.2 # the amount of width reserved for blank space between subplots #figure.subplot.hspace : 0.2 # the amount of height reserved for white space between subplots ### IMAGES #image.aspect : equal #image.interpolation : bilinear #image.cmap : jet #image.lut : 256 #image.origin : upper #image.resample : False ### CONTOUR PLOTS #contour.negative_linestyle : # # # # # equal | auto | a number see help(imshow) for options gray | jet etc... the size of the colormap lookup table lower | upper dashed # dashed | solid ### Agg rendering ### Warning: experimental, 2008/10/10 #agg.path.chunksize : 0 # 0 to disable; values in the range # 10000 to 100000 can improve speed slightly # and prevent an Agg rendering failure # when plotting very large data sets, # especially if they are very gappy. # It may cause minor artifacts, though. # A value of 20000 is probably a good # starting point. ### SAVING FIGURES #path.simplify : False # When True, simplify paths by removing "invisible" # points to reduce file size and increase rendering # speed #path.simplify_threshold : 0.1 # The threshold of similarity below which # vertices will be removed in the simplification 5.2. Dynamic rc settings 29 Matplotlib, Release 0.99.1.1 # process # the default savefig params can be different from the display params # Eg, you may want a higher resolution, or to make the figure # background white #savefig.dpi : 100 # figure dots per inch #savefig.facecolor : white # figure facecolor when saving #savefig.edgecolor : white # figure edgecolor when saving #cairo.format : png # tk backend params #tk.window_focus : False #tk.pythoninspect : False # ps backend params #ps.papersize : letter #ps.useafm : False #ps.usedistiller : False #ps.distiller.res #ps.fonttype : 6000 :3 # png, ps, pdf, svg # Maintain shell focus for TkAgg # tk sets PYTHONINSEPCT # auto, letter, legal, ledger, A0-A10, B0-B10 # use of afm fonts, results in small files # can be: None, ghostscript or xpdf # Experimental: may produce smaller files. # xpdf intended for production of publication quality files, # but requires ghostscript, xpdf and ps2eps # dpi # Output Type 3 (Type3) or Type 42 (TrueType) # pdf backend params #pdf.compression : 6 # integer from 0 to 9 # 0 disables compression (good for debugging) #pdf.fonttype :3 # Output Type 3 (Type3) or Type 42 (TrueType) # svg backend params #svg.image_inline : True #svg.image_noscale : False #svg.embed_char_paths : True # write raster image data directly into the svg file # suppress scaling of raster data embedded in SVG # embed character outlines in the SVG file # docstring params #docstring.hardcopy = False # set this when you want to generate hardcopy docstring # # # # # # # # # # # # # # # Set the verbose flags. This controls how much information matplotlib gives you at runtime and where it goes. The verbosity levels are: silent, helpful, debug, debug-annoying. Any level is inclusive of all the levels below it. If your setting is "debug", you’ll get all the debug and helpful messages. When submitting problems to the mailing-list, please set verbose to "helpful" or "debug" and paste the output into your report. The "fileo" gives the destination for any calls to verbose.report. These objects can a filename, or a filehandle like sys.stdout. You can override the rc default verbosity from the command line by giving the flags --verbose-LEVEL where LEVEL is one of the legal levels, eg --verbose-helpful. 30 Chapter 5. Customizing matplotlib Matplotlib, Release 0.99.1.1 # You can access the verbose instance in your code # from matplotlib import verbose. #verbose.level : silent # one of silent, helpful, debug, debug-annoying #verbose.fileo : sys.stdout # a log filename, sys.stdout or sys.stderr 5.2. Dynamic rc settings 31 Matplotlib, Release 0.99.1.1 32 Chapter 5. Customizing matplotlib CHAPTER SIX USING MATPLOTLIB IN A PYTHON SHELL By default, matplotlib defers drawing until the end of the script because drawing can be an expensive operation, and you may not want to update the plot every time a single property is changed, only once after all the properties have changed. But when working from the python shell, you usually do want to update the plot with every command, eg, after changing the xlabel(), or the marker style of a line. While this is simple in concept, in practice it can be tricky, because matplotlib is a graphical user interface application under the hood, and there are some tricks to make the applications work right in a python shell. 6.1 Ipython to the rescue Fortunately, ipython, an enhanced interactive python shell, has ﬁgured out all of these tricks, and is matplotlib aware, so when you start ipython in the pylab mode. [email protected]:~> ipython -pylab Python 2.4.5 (#4, Apr 12 2008, 09:09:16) IPython 0.9.0 -- An enhanced Interactive Python. Welcome to pylab, a matplotlib-based Python environment. For more information, type ’help(pylab)’. In [1]: x = randn(10000) In [2]: hist(x, 100) it sets everything up for you so interactive plotting works as you would expect it to. Call figure() and a ﬁgure window pops up, call plot() and your data appears in the ﬁgure window. Note in the example above that we did not import any matplotlib names because in pylab mode, ipython will import them automatically. ipython also turns on interactive mode for you, which causes every pyplot command to trigger a ﬁgure update, and also provides a matplotlib aware run command to run matplotlib scripts eﬃciently. ipython will turn oﬀ interactive mode during a run command, and then restore the interactive state at the end of the run so you can continue tweaking the ﬁgure manually. 33 Matplotlib, Release 0.99.1.1 There has been a lot of recent work to embed ipython, with pylab support, into various GUI applications, so check on the ipython mailing list for the latest status. 6.2 Other python interpreters If you can’t use ipython, and still want to use matplotlib/pylab from an interactive python shell, eg the plainole standard python interactive interpreter, or the interpreter in your favorite IDE, you are going to need to understand what a matplotlib backend is What is a backend?. With the TkAgg backend, that uses the Tkinter user interface toolkit, you can use matplotlib from an arbitrary python shell. Just set your backend : TkAgg and interactive : True in your matplotlibrc ﬁle (see Customizing matplotlib) and ﬁre up python. Then: >>> from pylab import * >>> plot([1,2,3]) >>> xlabel(’hi mom’) should work out of the box. Note, in batch mode, ie when making ﬁgures from scripts, interactive mode can be slow since it redraws the ﬁgure with each command. So you may want to think carefully before making this the default behavior. For other user interface toolkits and their corresponding matplotlib backends, the situation is complicated by the GUI mainloop which takes over the entire process. The solution is to run the GUI in a separate thread, and this is the tricky part that ipython solves for all the major toolkits that matplotlib supports. There are reports that upcoming versions of pygtk will place nicely with the standard python shell, so stay tuned. 6.3 Controlling interactive updating The interactive property of the pyplot interface controls whether a ﬁgure canvas is drawn on every pyplot command. If interactive is False, then the ﬁgure state is updated on every plot command, but will only be drawn on explicit calls to draw(). When interactive is True, then every pyplot command triggers a draw. The pyplot interface provides 4 commands that are useful for interactive control. isinteractive() returns the interactive setting True|False ion() turns interactive mode on ioff() turns interactive mode oﬀ draw() forces a ﬁgure redraw When working with a big ﬁgure in which drawing is expensive, you may want to turn matplotlib’s interactive setting oﬀ temporarily to avoid the performance hit: >>> >>> >>> >>> 34 #create big-expensive-figure ioff() # turn updates off title(’now how much would you pay?’) xticklabels(fontsize=20, color=’green’) Chapter 6. Using matplotlib in a python shell Matplotlib, Release 0.99.1.1 >>> >>> >>> >>> >>> draw() # force a draw savefig(’alldone’, dpi=300) close() ion() # turn updating back on plot(rand(20), mfc=’g’, mec=’r’, ms=40, mew=4, ls=’--’, lw=3) 6.3. Controlling interactive updating 35 Matplotlib, Release 0.99.1.1 36 Chapter 6. Using matplotlib in a python shell CHAPTER SEVEN WORKING WITH TEXT 7.1 Text introduction matplotlib has excellent text support, including mathematical expressions, truetype support for raster and vector outputs, newline separated text with arbitrary rotations, and unicode support. Because we embed the fonts directly in the output documents, eg for postscript or PDF, what you see on the screen is what you get in the hardcopy. freetype2 support produces very nice, antialiased fonts, that look good even at small raster sizes. matplotlib includes its own matplotlib.font_manager, thanks to Paul Barrett, which implements a cross platform, W3C compliant font ﬁnding algorithm. You have total control over every text property (font size, font weight, text location and color, etc) with sensible defaults set in the rc ﬁle. And signiﬁcantly for those interested in mathematical or scientiﬁc ﬁgures, matplotlib implements a large number of TeX math symbols and commands, to support mathematical expressions anywhere in your ﬁgure. 7.2 Basic text commands The following commands are used to create text in the pyplot interface • text() - add text at an arbitrary location to the Axes; matplotlib.axes.Axes.text() in the API. • xlabel() - add an axis label to the x-axis; matplotlib.axes.Axes.set_xlabel() in the API. • ylabel() - add an axis label to the y-axis; matplotlib.axes.Axes.set_ylabel() in the API. • title() - add a title to the Axes; matplotlib.axes.Axes.set_title() in the API. • figtext() - add text at an arbitrary location to the Figure; matplotlib.figure.Figure.text() in the API. • suptitle() - add a title to the Figure; matplotlib.figure.Figure.suptitle() in the API. • annotate() - add an annotation, with optional arrow, matplotlib.axes.Axes.annotate() in the API. to the Axes ; All of these functions create and return a matplotlib.text.Text() instance, which can bew conﬁgured with a variety of font and other properties. The example below shows all of these commands in action. 37 Matplotlib, Release 0.99.1.1 # -*- coding: utf-8 -*import matplotlib.pyplot as plt fig = plt.figure() fig.suptitle(’bold figure suptitle’, fontsize=14, fontweight=’bold’) ax = fig.add_subplot(111) fig.subplots_adjust(top=0.85) ax.set_title(’axes title’) ax.set_xlabel(’xlabel’) ax.set_ylabel(’ylabel’) ax.text(3, 8, ’boxed italics text in data coords’, style=’italic’, bbox={’facecolor’:’red’, ’alpha’:0.5, ’pad’:10}) ax.text(2, 6, r’an equation:$E=mc^2’, fontsize=15) ax.text(3, 2, unicode(’unicode: Institut f\374r Festk\366rperphysik’, ’latin-1’)) ax.text(0.95, 0.01, ’colored text in axes coords’, verticalalignment=’bottom’, horizontalalignment=’right’, transform=ax.transAxes, color=’green’, fontsize=15) ax.plot([2], [1], ’o’) ax.annotate(’annotate’, xy=(2, 1), xytext=(3, 4), arrowprops=dict(facecolor=’black’, shrink=0.05)) ax.axis([0, 10, 0, 10]) plt.show() 38 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 7.3 Text properties and layout The matplotlib.text.Text instances have a variety of properties which can be conﬁgured via keyword arguments to the text commands (eg title(), xlabel() and text()). 7.3. Text properties and layout 39 Matplotlib, Release 0.99.1.1 Property alpha backgroundcolor bbox clip_box clip_on clip_path color family fontproperties horizontalalignment or ha label linespacing multialignment name or fontname picker position rotation size or fontsize style or fontstyle text transform variant verticalalignment or va visible weight or fontweight x y zorder Value Type ﬂoat any matplotlib color rectangle prop dict plus key ‘pad’ which is a pad in points a matplotlib.transform.Bbox instance [True | False] a Path instance and a Transform instance, a Patch any matplotlib color [ ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.font_manager.FontProperties instance [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat [’left’ | ‘right’ | ‘center’ ] string eg, [’Sans’ | ‘Courier’ | ‘Helvetica’ ...] [None|ﬂoat|boolean|callable] (x,y) [ angle in degrees ‘vertical’ | ‘horizontal’ [ size in points | relative size eg ‘smaller’, ‘x-large’ ] [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion a matplotlib.transform transformation instance [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ ‘normal’ | ‘bold’ | ‘heavy’ | ‘light’ | ‘ultrabold’ | ‘ultralight’] ﬂoat ﬂoat any number You can layout text with the alignment arguments horizontalalignment, verticalalignment, and multialignment. horizontalalignment controls whether the x positional argument for the text indicates the left, center or right side of the text bounding box. verticalalignment controls whether the y positional argument for the text indicates the bottom, center or top side of the text bounding box. multialignment, for newline separated strings only, controls whether the diﬀerent lines are left, center or right justiﬁed. Here is an example which uses the text() command to show the various alignment possibilities. The use of transform=ax.transAxes throughout the code indicates that the coordinates are given relative to the axes bounding box, with 0,0 being the lower left of the axes and 1,1 the upper right. import matplotlib.pyplot as plt import matplotlib.patches as patches # build a rectangle in axes coords left, width = .25, .5 bottom, height = .25, .5 right = left + width top = bottom + height fig = plt.figure() 40 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 ax = fig.add_axes([0,0,1,1]) # axes coordinates are 0,0 is bottom left and 1,1 is upper right p = patches.Rectangle( (left, bottom), width, height, fill=False, transform=ax.transAxes, clip_on=False ) ax.add_patch(p) ax.text(left, bottom, ’left top’, horizontalalignment=’left’, verticalalignment=’top’, transform=ax.transAxes) ax.text(left, bottom, ’left bottom’, horizontalalignment=’left’, verticalalignment=’bottom’, transform=ax.transAxes) ax.text(right, top, ’right bottom’, horizontalalignment=’right’, verticalalignment=’bottom’, transform=ax.transAxes) ax.text(right, top, ’right top’, horizontalalignment=’right’, verticalalignment=’top’, transform=ax.transAxes) ax.text(right, bottom, ’center top’, horizontalalignment=’center’, verticalalignment=’top’, transform=ax.transAxes) ax.text(left, 0.5*(bottom+top), ’right center’, horizontalalignment=’right’, verticalalignment=’center’, rotation=’vertical’, transform=ax.transAxes) ax.text(left, 0.5*(bottom+top), ’left center’, horizontalalignment=’left’, verticalalignment=’center’, rotation=’vertical’, transform=ax.transAxes) ax.text(0.5*(left+right), 0.5*(bottom+top), ’middle’, horizontalalignment=’center’, verticalalignment=’center’, fontsize=20, color=’red’, transform=ax.transAxes) 7.3. Text properties and layout 41 Matplotlib, Release 0.99.1.1 ax.text(right, 0.5*(bottom+top), ’centered’, horizontalalignment=’center’, verticalalignment=’center’, rotation=’vertical’, transform=ax.transAxes) ax.text(left, top, ’rotated\nwith newlines’, horizontalalignment=’center’, verticalalignment=’center’, rotation=45, transform=ax.transAxes) ax.set_axis_off() plt.show() 7.4 Writing mathematical expressions You can use a subset TeX markup in any matplotlib text string by placing it inside a pair of dollar signs (). Note that you do not need to have TeX installed, since matplotlib ships its own TeX expression parser, layout engine and fonts. The layout engine is a fairly direct adaptation of the layout algorithms in Donald Knuth’s TeX, so the quality is quite good (matplotlib also provides a usetex option for those who do want to call out to TeX to generate their text (see Text rendering With LaTeX ). 42 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 Any text element can use math text. You should use raw strings (preceed the quotes with an ’r’), and surround the math text with dollar signs ($), as in TeX. Regular text and mathtext can be interleaved within the same string. Mathtext can use the Computer Modern fonts (from (La)TeX), STIX fonts (with are designed to blend well with Times) or a Unicode font that you provide. The mathtext font can be selected with the customization variable mathtext.fontset (see Customizing matplotlib) Here is a simple example: # plain text plt.title(’alpha > beta’) produces “alpha > beta”. Whereas this: # math text plt.title(r’$\alpha > \beta$’) produces “α > β“. Note: Mathtext should be placed between a pair of dollar signs ($). To make it easy to display monetary values, e.g. “$100.00”, if a single dollar sign is present in the entire string, it will be displayed verbatim as a dollar sign. This is a small change from regular TeX, where the dollar sign in non-math text would have to be escaped (‘$’). Note: While the syntax inside the pair of dollar signs ($) aims to be TeX-like, the text outside does not. In particular, characters such as: #$ % & ~ _ ^ \ { }   have special meaning outside of math mode in TeX. Therefore, these characters will behave diﬀerently depending on the rcParam text.usetex ﬂag. See the usetex tutorial for more information. 7.4.1 Subscripts and superscripts To make subscripts and superscripts, use the ’_’ and ’^’ symbols: r’$\alpha_i > \beta_i$’ αi > βi (7.1) Some symbols automatically put their sub/superscripts under and over the operator. For example, to write the sum of xi from 0 to ∞, you could do: r’$\sum_{i=0}^\infty x_i$’ ∞ ￿ xi (7.2) i=0 7.4. Writing mathematical expressions 43 Matplotlib, Release 0.99.1.1 7.4.2 Fractions Fractions can be created with the \frac{}{} command: r’$\frac{3}{4}$’ produces 3 4 (7.3) Fractions can be arbitrarily nested: r’$\frac{5 - \frac{1}{x}}{4}$’ produces 5− 1 x (7.4) 4 Note that special care needs to be taken to place parentheses and brackets around fractions. Doing things the obvious way produces brackets that are too small: r’$(\frac{5 - \frac{1}{x}}{4})$’ 5− 1 x ( ) (7.5) 4 The solution is to precede the bracket with \left and \right to inform the parser that those brackets encompass the entire object: r’$\left(\frac{5 - \frac{1}{x}}{4}\right)$’ 7.4.3 Radicals 5 − 4 1 x (7.6) Radicals can be produced with the \sqrt{} command. For example: r’$\sqrt{2}$’ √ 2 (7.7) Any base can (optionally) be provided inside square brackets. Note that the base must be a simple expression, and can not contain layout commands such as fractions or sub/superscripts: r’$\sqrt[3]{x}$’ √ 3 44 x (7.8) Chapter 7. Working with text Matplotlib, Release 0.99.1.1 7.4.4 Fonts The default font is italics for mathematical symbols. Note: This default can be changed using the mathtext.default rcParam. This is useful, for example, to use the same font as regular non-math text for math text, by setting it to regular. To change fonts, eg, to write “sin” in a Roman font, enclose the text in a font command: r’$s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)$’ s(t) = Asin(2ωt) (7.9) More conveniently, many commonly used function names that are typeset in a Roman font have shortcuts. So the expression above could be written as follows: r’$s(t) = \mathcal{A}\sin(2 \omega t)$’ s(t) = A sin(2ωt) (7.10) s(t) = A sin(2ωt) (7.11) Here “s” and “t” are variable in italics font (default), “sin” is in Roman font, and the amplitude “A” is in calligraphy font. Note in the example above the caligraphy A is squished into the sin. You can use a spacing command to add a little whitespace between them: s(t) = \mathcal{A}\/\sin(2 \omega t) The choices available with all fonts are: Command \mathrm{Roman} \mathit{Italic} \mathtt{Typewriter} \mathcal{CALLIGRAPHY} Result Roman Italic Typewriter CALLIGRAPHY When using the STIX fonts, you also have the choice of: Command \mathbb{blackboard} \mathrm{\mathbb{blackboard}} \mathfrak{Fraktur} \mathsf{sansserif} \mathrm{\mathsf{sansserif}} Result ￿￿￿￿￿￿ ￿￿￿￿￿￿ Fraktur sansserif sansserif There are also three global “font sets” to choose from, which are selected using the mathtext.fontset parameter in matplotlibrc. cm: Computer Modern (TeX) 7.4. Writing mathematical expressions 45 Matplotlib, Release 0.99.1.1 stix: STIX (designed to blend well with Times) stixsans: STIX sans-serif Additionally, you can use \mathdefault{...} or its alias \mathregular{...} to use the font used for regular text outside of mathtext. There are a number of limitations to this approach, most notably that far fewer symbols will be available, but it can be useful to make math expressions blend well with other text in the plot. Custom fonts mathtext also provides a way to use custom fonts for math. This method is fairly tricky to use, and should be considered an experimental feature for patient users only. By setting the rcParam mathtext.fontset to custom, you can then set the following parameters, which control which font ﬁle to use for a particular set of math characters. Parameter mathtext.it mathtext.rm mathtext.tt mathtext.bf mathtext.cal mathtext.sf Corresponds to \mathit{} or default italic \mathrm{} Roman (upright) \mathtt{} Typewriter (monospace) \mathbf{} bold italic \mathcal{} calligraphic \mathsf{} sans-serif Each parameter should be set to a fontconﬁg font descriptor (as deﬁned in the yet-to-be-written font chapter). The fonts used should have a Unicode mapping in order to ﬁnd any non-Latin characters, such as Greek. If you want to use a math symbol that is not contained in your custom fonts, you can set the rcParam mathtext.fallback_to_cm to True which will cause the mathtext system to use characters from the default Computer Modern fonts whenever a particular character can not be found in the custom font. Note that the math glyphs speciﬁed in Unicode have evolved over time, and many fonts may not have glyphs in the correct place for mathtext. 7.4.5 Accents An accent command may precede any symbol to add an accent above it. There are long and short forms for some of them. 46 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 Command \acute a or \’a \bar a \breve a \ddot a or \"a \dot a or \.a \grave a or \‘a \hat a or \^a \tilde a or \~a \vec a Result a ´ a ¯ a ˘ a ¨ a ˙ a ` a ˆ a ˜ ￿ a In addition, there are two special accents that automatically adjust to the width of the symbols below: Command \widehat{xyz} \widetilde{xyz} Result ￿ xyz ￿ xyz Care should be taken when putting accents on lower-case i’s and j’s. Note that in the following \imath is used to avoid the extra dot over the i: r"$\hat i\ \ \hat \imath$" ˆı iˆ (7.12) 7.4.6 Symbols You can also use a large number of the TeX symbols, as in \infty, \leftarrow, \sum, \int. Lower-case Greek α \alpha ￿ \epsilon λ \lambda π \pi θ \theta ￿ \varpi ζ \zeta β \beta η \eta µ \mu ψ \psi υ \upsilon ￿ \varrho χ \chi γ \gamma ν \nu ρ \rho ε \varepsilon ς \varsigma δ \delta ι \iota ω \omega σ \sigma κ \varkappa ϑ \vartheta ￿ \digamma κ \kappa φ \phi τ \tau ϕ \varphi ξ \xi Upper-case Greek ∆ \Delta Ψ \Psi ∇ \nabla Γ \Gamma Σ \Sigma ℵ \aleph ￿ \beth Λ \Lambda Θ \Theta Ω \Omega Υ \Upsilon Φ \Phi Ξ \Xi Π \Pi ￿ \mho Hebrew ￿ \daleth ‫\ ג‬gimel Delimiters 7.4. Writing mathematical expressions 47 Matplotlib, Release 0.99.1.1 // ↓ \downarrow ￿ \rangle | \vert Big symbols ￿ \bigcap ￿ ￿ \biguplus \oint [[ ￿ \langle ￿ \rceil { \{ ⇓ \Downarrow ￿ \lceil ￿ \rfloor ￿ \| ￿ \bigcup ￿ \bigvee ￿ \prod ￿ \bigodot ￿ \bigwedge ￿ \sum Standard function names Pr \Pr arg \arg coth \coth dim \dim inf \inf lim inf \liminf max \max sinh \sinh arccos \arccos cos \cos csc \csc exp \exp ker \ker lim sup \limsup min \min sup \sup ⇑ \Uparrow ￿ \lfloor ￿ \ulcorner } \} ￿ \bigoplus ￿ \coprod arcsin \arcsin cosh \cosh deg \deg gcd \gcd lg \lg ln \ln sec \sec tan \tan ￿ \Vert ￿ \llcorner ↑ \uparrow] \ \backslash ￿ \lrcorner ￿ \urcorner || ￿ ￿ \bigotimes \int arctan \arctan cot \cot det \det hom \hom lim \lim log \log sin \sin tanh \tanh Binary operation and relation symbols ￿ \Bumpeq ￿ \Doteq ￿ \Supset ≈ \approx ￿ \asymp ￿ \backsimeq ￿ \between ￿ \bigtriangleup ⊥ \bot ￿ \boxminus • \bullet · \cdot ￿ \coloneq ￿ \curlyeqprec ￿ \curlywedge ‡ \ddag ￿ \divideontimes ￿ \dotplus ￿ \eqcolon ￿ \eqslantless 48 ￿ \Cap ￿ \Join ￿ \Vdash ￿ \approxeq ￿ \backepsilon ⊼ \barwedge ￿ \bigcirc ￿ \blacktriangleleft ￿￿ \bowtie ￿ \boxplus ￿ \bumpeq ◦ \circ ￿ \cong ￿ \curlyeqsucc † \dag ￿ \diamond ￿ \doteq ￿ \doublebarwedge ￿ \eqsim ≡ \equiv ￿ \Cup ￿ \Subset ￿ \Vvdash ∗ \ast ￿ \backsim ∵ \because ￿ \bigtriangledown ￿ \blacktriangleright ￿ \boxdot ￿ \boxtimes ∩ \cap ￿ \circeq ∪ \cup ￿ \curlyvee ￿ \dashv ÷ \div ￿ \doteqdot ￿ \eqcirc ￿ \eqslantgtr ￿ \fallingdotseq Chapter 7. Working with text Matplotlib, Release 0.99.1.1 ￿ \frown ￿ \geqslant ￿ \gnapprox ￿ \gtrapprox ￿ \gtreqqless ∈ \in ≤ \leq ￿ \lessapprox ￿ \lesseqqgtr ￿ \ll ￿ \lneqq | \mid ￿ \nVDash ￿ \ncong ￿ \neq ≯ \ngtr ≮ \nless ∦ \nparallel ￿ \nsubset ￿ \nsupset ≥ \geq ￿ \gg ￿ \gneqq ￿ \gtrdot ≷ \gtrless ￿ \intercal ￿ \leqq ￿ \lessdot ≶ \lessgtr ≪ \lll ￿ \lnsim |= \models ￿ \nVdash ￿ \ne ￿ \nequiv ￿ \ni ￿ \nmid ⊀ \nprec ￿ \nsubseteq ￿ \nsupseteq ￿ \geqq ≫ \ggg ￿ \gnsim ￿ \gtreqless ￿ \gtrsim ￿ \leftthreetimes ￿ \leqslant ￿ \lesseqgtr ￿ \lesssim ￿ \lnapprox ￿ \ltimes ∓ \mp ￿ \napprox ￿ \neq ￿ \ngeq ￿ \nleq ￿ \notin ￿ \nsim ￿ \nsucc ￿ \ntriangleleft ￿ \ntrianglelefteq ￿ \nvDash ￿ \ominus ⊗ \otimes ￿ \pitchfork ￿ \precapprox ￿ \precnapprox ∝ \propto ￿ \rtimes / \slash ￿ \sqcup ￿ \sqsubseteq ￿ \sqsupseteq ⊆ \subseteq ￿ \subsetneqq ￿ \succcurlyeq ￿ \succnsim ⊇ \supseteq ￿ \supsetneqq ￿ \top ￿ \ntriangleright ￿ \nvdash ⊕ \oplus ￿ \parallel ± \pm ￿ \preccurlyeq ￿ \precnsim ￿ \rightthreetimes ∼ \sim ￿ \smile ￿ \sqsubset ￿ \sqsupset ￿ \star ￿ \subseteqq ￿ \succ ￿ \succeq ￿ \succsim ￿ \supseteqq ∴ \therefore ￿ \triangleleft ￿ \ntrianglerighteq ⊙ \odot ￿ \oslash ⊥ \perp ≺ \prec ￿ \preceq ￿ \precsim ￿ \risingdotseq ￿ \simeq ￿ \sqcap ￿ \sqsubset ￿ \sqsupset ⊂ \subset ￿ \subsetneq ￿ \succapprox ￿ \succnapprox ⊃ \supset ￿ \supsetneq × \times ￿ \trianglelefteq ￿ \triangleq ￿ \uplus ￿ \vartriangleleft ∨ \vee ￿ \wr ￿ \triangleright ￿ \vDash ￿ \vartriangleright ￿ \veebar ￿ \trianglerighteq ∝ \varpropto ￿ \vdash ∧ \wedge Arrow symbols 7.4. Writing mathematical expressions 49 Matplotlib, Release 0.99.1.1 ⇓ \Downarrow ⇔ \Leftrightarrow ⇐= \Longleftarrow =⇒ \Longrightarrow ￿ \Nearrow ⇒ \Rightarrow ￿ \Rsh ￿ \Swarrow ￿ \Updownarrow ￿ \circlearrowright ￿ \curvearrowright ￿ \dashrightarrow ￿ \downdownarrows ￿ \downharpoonright ￿→ \hookrightarrow ← \leftarrow ￿ \leftharpoondown ⇔ \leftleftarrows ￿ \leftrightarrows ￿ \leftrightsquigarrow ←− \longleftarrow ￿−→ \longmapsto ￿ \looparrowleft ￿→ \mapsto ￿ \nLeftarrow ￿ \nRightarrow ￿ \nleftarrow ￿ \nrightarrow → \rightarrow ￿ \rightharpoondown ￿ \rightleftarrows ￿ \rightleftharpoons ⇒ \rightrightarrows ￿ \rightsquigarrow ￿ \swarrow ￿ \twoheadleftarrow ↑ \uparrow ￿ \updownarrow ￿ \upharpoonright ⇐ \Leftarrow ￿ \Lleftarrow ⇐⇒ \Longleftrightarrow ￿ \Lsh ￿ \Nwarrow ￿ \Rrightarrow ￿ \Searrow ⇑ \Uparrow ￿ \circlearrowleft ￿ \curvearrowleft ￿ \dashleftarrow ↓ \downarrow ￿ \downharpoonleft ←￿ \hookleftarrow ￿ \leadsto ￿ \leftarrowtail ￿ \leftharpoonup ↔ \leftrightarrow ￿ \leftrightharpoons ￿ \leftsquigarrow ←→ \longleftrightarrow −→ \longrightarrow ￿ \looparrowright ￿ \multimap ￿ \nLeftrightarrow ￿ \nearrow ￿ \nleftrightarrow ￿ \nwarrow ￿ \rightarrowtail ￿ \rightharpoonup ￿ \rightleftarrows ￿ \rightleftharpoons ⇒ \rightrightarrows ￿ \searrow → \to ￿ \twoheadrightarrow ￿ \updownarrow ￿ \upharpoonleft ⇑ \upuparrows Miscellaneous symbols 50 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 $\$ ￿ \Game ￿ \Re ￿ \backprime ￿ \blacktriangle ￿ \checkmark ♣ \clubsuit .. . \ddots Å \AA ￿ \Im § \S ￿ \bigstar ￿ \blacktriangledown ￿ \circledR ￿ \complement ￿ \Finv ¶ \P ∠ \angle ￿ \blacksquare · · · \cdots ￿ \circledS © \copyright ∅ \emptyset ￿ \flat ♥ \heartsuit ￿ \iint ∞ \infty ￿ \measuredangle ￿ \nexists ￿ \prime ￿ \sphericalangle ♦ \diamondsuit ð \eth ∀ \forall ￿ \hslash ￿ \iint \jmath ￿ \natural ￿ \oiiint ￿ \sharp \ss ∅ \varnothing ℘ \wp ￿ \vartriangle ￿ \yen ￿ \ell ∃ \exists ￿ \hbar ￿ \iiint ı \imath . . . \ldots ¬ \neg ∂ \partial ♠ \spadesuit ￿ \triangledown . . \vdots . If a particular symbol does not have a name (as is true of many of the more obscure symbols in the STIX fonts), Unicode characters can also be used: ur’$\u23ce$’ 7.4.7 Example Here is an example illustrating many of these features in context. import numpy as np import matplotlib.pyplot as plt t = np.arange(0.0, 2.0, 0.01) s = np.sin(2*np.pi*t) plt.plot(t,s) plt.title(r’$\alpha_i > \beta_i$’, fontsize=20) plt.text(1, -0.6, r’$\sum_{i=0}^\infty x_i$’, fontsize=20) plt.text(0.6, 0.6, r’$\mathcal{A}\mathrm{sin}(2 \omega t)$’, fontsize=20) plt.xlabel(’time (s)’) plt.ylabel(’volts (mV)’) 7.4. Writing mathematical expressions 51 Matplotlib, Release 0.99.1.1 7.5 Text rendering With LaTeX Matplotlib has the option to use LaTeX to manage all text layout. This option is available with the following backends: • Agg • PS • PDF The LaTeX option is activated by setting text.usetex : True in your rc settings. Text handling with matplotlib’s LaTeX support is slower than matplotlib’s very capable mathtext, but is more ﬂexible, since diﬀerent LaTeX packages (font packages, math packages, etc.) can be used. The results can be striking, especially when you take care to use the same fonts in your ﬁgures as in the main document. Matplotlib’s LaTeX support requires a working LaTeX installation, dvipng (which may be included with your LaTeX installation), and Ghostscript (GPL Ghostscript 8.60 or later is recommended). The executables for these external dependencies must all be located on your PATH. There are a couple of options to mention, which can be changed using rc settings. Here is an example matplotlibrc ﬁle: 52 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 font.family font.serif font.sans-serif font.cursive font.monospace : : : : : serif Times, Palatino, New Century Schoolbook, Bookman, Computer Modern Roman Helvetica, Avant Garde, Computer Modern Sans serif Zapf Chancery Courier, Computer Modern Typewriter text.usetex : true The ﬁrst valid font in each family is the one that will be loaded. If the fonts are not speciﬁed, the Computer Modern fonts are used by default. All of the other fonts are Adobe fonts. Times and Palatino each have their own accompanying math fonts, while the other Adobe serif fonts make use of the Computer Modern math fonts. See the PSNFSS documentation for more details. To use LaTeX and select Helvetica as the default font, without editing matplotlibrc use: from matplotlib import rc rc(’font’,**{’family’:’sans-serif’,’sans-serif’:[’Helvetica’]}) ## for Palatino and other serif fonts use: #rc(’font’,**{’family’:’serif’,’serif’:[’Palatino’])) rc(’text’, usetex=True) Here is the standard example, tex_demo.py: #!/usr/bin/env python """ You can use TeX to render all of your matplotlib text if the rc parameter text.usetex is set. This works currently on the agg and ps backends, and requires that you have tex and the other dependencies described at http://matplotlib.sf.net/matplotlib.texmanager.html properly installed on your system. The first time you run a script you will see a lot of output from tex and associated tools. The next time, the run may be silent, as a lot of the information is cached in ~/.tex.cache """ from matplotlib import rc from numpy import arange, cos, pi from matplotlib.pyplot import figure, axes, plot, xlabel, ylabel, title, \ grid, savefig, show rc(’text’, usetex=True) rc(’font’, family=’serif’) figure(1, figsize=(6,4)) ax = axes([0.1, 0.1, 0.8, 0.7]) t = arange(0.0, 1.0+0.01, 0.01) s = cos(2*2*pi*t)+2 plot(t, s) xlabel(r’\textbf{time (s)}’) ylabel(r’\textit{voltage (mV)}’,fontsize=16) title(r"\TeX\ is Number $\displaystyle\sum_{n=1}^\infty\frac{-e^{i\pi}}{2^n}$!", 7.5. Text rendering With LaTeX 53 Matplotlib, Release 0.99.1.1 fontsize=16, color=’r’) grid(True) savefig(’tex_demo’) show() TEX is Number voltage (mV) 3.0 ∞ ￿ −eiπ n=1 2n ! 2.5 2.0 1.5 1.0 0.0 0.2 0.4 time (s) 0.6 0.8 1.0 Note that display math mode ($$e=mc^2$$) is not supported, but adding the command \displaystyle, as in tex_demo.py, will produce the same results. Note: Certain characters require special escaping in TeX, such as: # $% & ~ _ ^ \ { }   Therefore, these characters will behave diﬀerently depending on the rcParam text.usetex ﬂag. 7.5.1 usetex with unicode It is also possible to use unicode strings with the LaTeX text manager, here is an example taken from tex_unicode_demo.py: #!/usr/bin/env python # -*- coding: utf-8 -*""" This demo is tex_demo.py modified to have unicode. See that file for more information. """ 54 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 from matplotlib import rcParams rcParams[’text.usetex’]=True rcParams[’text.latex.unicode’]=True from numpy import arange, cos, pi from matplotlib.pyplot import figure, axes, plot, xlabel, ylabel, title, \ grid, savefig, show figure(1, figsize=(6,4)) ax = axes([0.1, 0.1, 0.8, 0.7]) t = arange(0.0, 1.0+0.01, 0.01) s = cos(2*2*pi*t)+2 plot(t, s) xlabel(r’\textbf{time (s)}’) ylabel(ur’\textit{Velocity (\u00B0/sec)}’, fontsize=16) title(r"\TeX\ is Number$\displaystyle\sum_{n=1}^\infty\frac{-e^{i\pi}}{2^n}!", fontsize=16, color=’r’) grid(True) show() TEX is Number Velocity (° /sec) 3.0 ∞ ￿ −eiπ n=1 2n ! 2.5 2.0 1.5 1.0 0.0 0.2 0.4 time (s) 0.6 0.8 1.0 7.5.2 Postscript options In order to produce encapsulated postscript ﬁles that can be embedded in a new LaTeX document, the default behavior of matplotlib is to distill the output, which removes some postscript operators used by LaTeX that are illegal in an eps ﬁle. This step produces results which may be unacceptable to some users, because the text is coarsely rasterized and converted to bitmaps, which are not scalable like standard postscript, and the text is not searchable. One workaround is to to set ps.distiller.res to a higher value (perhaps 7.5. Text rendering With LaTeX 55 Matplotlib, Release 0.99.1.1 6000) in your rc settings, which will produce larger ﬁles but may look better and scale reasonably. A better workaround, which requires Poppler or Xpdf, can be activated by changing the ps.usedistiller rc setting to xpdf. This alternative produces postscript without rasterizing text, so it scales properly, can be edited in Adobe Illustrator, and searched text in pdf documents. 7.5.3 Possible hangups • On Windows, the PATH environment variable may need to be modiﬁed to include the directories containing the latex, dvipng and ghostscript executables. See Environment Variables and Setting environment variables in windows for details. • Using MiKTeX with Computer Modern fonts, if you get odd *Agg and PNG results, go to MiKTeX/Options and update your format ﬁles • The fonts look terrible on screen. You are probably running Mac OS, and there is some funny business with older versions of dvipng on the mac. Set text.dvipnghack : True in your matplotlibrc ﬁle. • On Ubuntu and Gentoo, the base texlive install does not ship with the type1cm package. You may need to install some of the extra packages to get all the goodies that come bundled with other latex distributions. • Some progress has been made so matplotlib uses the dvi ﬁles directly for text layout. This allows latex to be used for text layout with the pdf and svg backends, as well as the *Agg and PS backends. In the future, a latex installation may be the only external dependency. 7.5.4 Troubleshooting • Try deleting your .matplotlib/tex.cache directory. .matplotlib, see .matplotlib directory location. If you don’t know where to ﬁnd • Make sure LaTeX, dvipng and ghostscript are each working and on your PATH. • Make sure what you are trying to do is possible in a LaTeX document, that your LaTeX syntax is valid and that you are using raw strings if necessary to avoid unintended escape sequences. • Most problems reported on the mailing list have been cleared up by upgrading Ghostscript. If possible, please try upgrading to the latest release before reporting problems to the list. • The text.latex.preamble rc setting is not oﬃcially supported. This option provides lots of ﬂexibility, and lots of ways to cause problems. Please disable this option before reporting problems to the mailing list. • If you still need help, please see Report a problem 7.6 Annotating text For a more detailed introduction to annotations, see Annotating Axes. The uses of the basic text() command above place text at an arbitrary position on the Axes. A common use case of text is to annotate some feature of the plot, and the annotate() method provides helper functionality 56 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 to make annotations easy. In an annotation, there are two points to consider: the location being annotated represented by the argument xy and the location of the text xytext. Both of these arguments are (x,y) tuples. import numpy as np import matplotlib.pyplot as plt fig = plt.figure() ax = fig.add_subplot(111) t = np.arange(0.0, 5.0, 0.01) s = np.cos(2*np.pi*t) line, = ax.plot(t, s, lw=2) ax.annotate(’local max’, xy=(2, 1), xytext=(3, 1.5), arrowprops=dict(facecolor=’black’, shrink=0.05), ) ax.set_ylim(-2,2) plt.show() In this example, both the xy (arrow tip) and xytext locations (text location) are in data coordinates. There are a variety of other coordinate systems one can choose – you can specify the coordinate system of xy and xytext with one of the following strings for xycoords and textcoords (default is ‘data’) 7.6. Annotating text 57 Matplotlib, Release 0.99.1.1 argument ‘ﬁgure points’ ‘ﬁgure pixels’ ‘ﬁgure fraction’ ‘axes points’ ‘axes pixels’ ‘axes fraction’ ‘data’ coordinate system points from the lower left corner of the ﬁgure pixels from the lower left corner of the ﬁgure 0,0 is lower left of ﬁgure and 1,1 is upper, right points from lower left corner of axes pixels from lower left corner of axes 0,1 is lower left of axes and 1,1 is upper right use the axes data coordinate system For example to place the text coordinates in fractional axes coordinates, one could do: ax.annotate(’local max’, xy=(3, 1), xycoords=’data’, xytext=(0.8, 0.95), textcoords=’axes fraction’, arrowprops=dict(facecolor=’black’, shrink=0.05), horizontalalignment=’right’, verticalalignment=’top’, ) For physical coordinate systems (points or pixels) the origin is the (bottom, left) of the ﬁgure or axes. If the value is negative, however, the origin is from the (right, top) of the ﬁgure or axes, analogous to negative indexing of sequences. Optionally, you can specify arrow properties which draws an arrow from the text to the annotated point by giving a dictionary of arrow properties in the optional keyword argument arrowprops. arrowprops key width frac headwidth shrink **kwargs description the width of the arrow in points the fraction of the arrow length occupied by the head the width of the base of the arrow head in points move the tip and base some percent away from the annotated point and text any key for matplotlib.patches.Polygon, e.g. facecolor In the example below, the xy point is in native coordinates (xycoords defaults to ‘data’). For a polar axes, this is in (theta, radius) space. The text in this example is placed in the fractional ﬁgure coordinate system. matplotlib.text.Text keyword args like horizontalalignment, verticalalignment and fontsize are passed from the ‘~matplotlib.Axes.annotate‘ to the ‘‘Text instance import numpy as np import matplotlib.pyplot as plt fig = plt.figure() ax = fig.add_subplot(111, polar=True) r = np.arange(0,1,0.001) theta = 2*2*np.pi*r line, = ax.plot(theta, r, color=’#ee8d18’, lw=3) ind = 800 thisr, thistheta = r[ind], theta[ind] ax.plot([thistheta], [thisr], ’o’) ax.annotate(’a polar annotation’, xy=(thistheta, thisr), # theta, radius xytext=(0.05, 0.05), # fraction, fraction textcoords=’figure fraction’, 58 Chapter 7. Working with text Matplotlib, Release 0.99.1.1 arrowprops=dict(facecolor=’black’, shrink=0.05), horizontalalignment=’left’, verticalalignment=’bottom’, ) plt.show() For more on all the wild and wonderful things you can do with annotations, including fancy arrows, see Annotating Axes and pylab_examples example code: annotation_demo.py. 7.6. Annotating text 59 Matplotlib, Release 0.99.1.1 60 Chapter 7. Working with text CHAPTER EIGHT IMAGE TUTORIAL 8.1 Startup commands At the very least, you’ll need to have access to the imshow() function. There are a couple of ways to do it. The easy way for an interactive environment:ipython -pylab The imshow function is now directly accessible (it’s in your namespace). See also Pyplot tutorial. The more expressive, easier to understand later method (use this in your scripts to make it easier for others (including your future self) to read) is to use the matplotlib API (see Artist tutorial) where you use explicit namespaces and control object creation, etc... In [1]: import matplotlib.pyplot as plt In [2]: import matplotlib.image as mpimg In [3]: import numpy as np Examples below will use the latter method, for clarity. In these examples, if you use the -pylab method, you can skip the “mpimg.” and “plt.” preﬁxes. 8.2 Importing image data into Numpy arrays Plotting image data is supported by the Python Image Library (PIL), . Natively, matplotlib only supports PNG images. The commands shown below fall back on PIL if the native read fails. The image used in this example is a PNG ﬁle, but keep that PIL requirement in mind for your own data. Here’s the image we’re going to play with: 61 Matplotlib, Release 0.99.1.1 It’s a 24-bit RGB PNG image (8 bits for each of R, G, B). Depending on where you get your data, the other kinds of image that you’ll most likely encounter are RGBA images, which allow for transparency, or singlechannel grayscale (luminosity) images. You can right click on it and choose “Save image as” to download it to your computer for the rest of this tutorial. And here we go... In [4]: img=mpimg.imread(’stinkbug.png’) Out[4]: array([[[ 0.40784314, 0.40784314, 0.40784314], [ 0.40784314, 0.40784314, 0.40784314], [ 0.40784314, 0.40784314, 0.40784314], ..., [ 0.42745098, 0.42745098, 0.42745098], [ 0.42745098, 0.42745098, 0.42745098], [ 0.42745098, 0.42745098, 0.42745098]], [[ 0.41176471, [ 0.41176471, [ 0.41176471, ..., [ 0.42745098, [ 0.42745098, 62 0.41176471, 0.41176471, 0.41176471, 0.41176471], 0.41176471], 0.41176471], 0.42745098, 0.42745098, 0.42745098], 0.42745098], Chapter 8. Image tutorial Matplotlib, Release 0.99.1.1 [ 0.42745098, 0.42745098, 0.42745098]], [[ 0.41960785, [ 0.41568628, [ 0.41568628, ..., [ 0.43137255, [ 0.43137255, [ 0.43137255, 0.41960785, 0.41568628, 0.41568628, 0.41960785], 0.41568628], 0.41568628], 0.43137255, 0.43137255, 0.43137255, 0.43137255], 0.43137255], 0.43137255]], 0.43921569, 0.43529412, 0.43137255, 0.43921569], 0.43529412], 0.43137255], 0.45490196, 0.4509804 , 0.4509804 , 0.45490196], 0.4509804 ], 0.4509804 ]], [[ 0.44313726, [ 0.44313726, [ 0.43921569, ..., [ 0.4509804 , [ 0.44705883, [ 0.44705883, 0.44313726, 0.44313726, 0.43921569, 0.44313726], 0.44313726], 0.43921569], 0.4509804 , 0.44705883, 0.44705883, 0.4509804 ], 0.44705883], 0.44705883]], [[ 0.44313726, [ 0.4509804 , [ 0.4509804 , ..., [ 0.44705883, [ 0.44705883, [ 0.44313726, 0.44313726, 0.4509804 , 0.4509804 , 0.44313726], 0.4509804 ], 0.4509804 ], 0.44705883, 0.44705883, 0.44313726, 0.44705883], 0.44705883], 0.44313726]]], dtype=float32) ..., [[ 0.43921569, [ 0.43529412, [ 0.43137255, ..., [ 0.45490196, [ 0.4509804 , [ 0.4509804 , Note the dtype there - ﬂoat32. Matplotlib has rescaled the 8 bit data from each channel to ﬂoating point data between 0.0 and 1.0. As a side note, the only datatype that PIL can work with is uint8. Matplotlib plotting can handle ﬂoat32 and uint8, but image reading/writing for any format other than PNG is limited to uint8 data. Why 8 bits? Most displays can only render 8 bits per channel worth of color gradation. Why can they only render 8 bits/channel? Because that’s about all the human eye can see. More here (from a photography standpoint): Luminous Landscape bit depth tutorial. Each inner list represents a pixel. Here, with an RGB image, there are 3 values. Since it’s a black and white image, R, G, and B are all similar. An RGBA (where A is alpha, or transparency), has 4 values per inner list, and a simple luminance image just has one value (and is thus only a 2-D array, not a 3-D array). For RGB and RGBA images, matplotlib supports ﬂoat32 and uint8 data types. For grayscale, matplotlib supports only ﬂoat32. If your array data does not meet one of these descriptions, you need to rescale it. 8.2. Importing image data into Numpy arrays 63 Matplotlib, Release 0.99.1.1 8.3 Plotting numpy arrays as images So, you have your data in a numpy array (either by importing it, or by generating it). Let’s render it. In Matplotlib, this is performed using the imshow() function. Here we’ll grab the plot object. This object gives you an easy way to manipulate the plot from the prompt. In [5]: imgplot = plt.imshow(img) You can also plot any numpy array - just remember that the datatype must be ﬂoat32 (and range from 0.0 to 1.0) or uint8. 8.3.1 Applying pseudocolor schemes to image plots Pseudocolor can be a useful tool for enhancing contrast and visualizing your data more easily. This is especially useful when making presentations of your data using projectors - their contrast is typically quite poor. Pseudocolor is only relevant to single-channel, grayscale, luminosity images. We currently have an RGB image. Since R, G, and B are all similar (see for yourself above or in your data), we can just pick on channel of our data: In [6]: lum_img = img[:,:,0] 64 Chapter 8. Image tutorial Matplotlib, Release 0.99.1.1 This is array slicing. You can read more in the Numpy tutorial. In [7]: imgplot = mpimg.imshow(lum_img) Now, with a luminosity image, the default colormap (aka lookup table, LUT), is applied. The default is called jet. There are plenty of others to choose from. Let’s set some others using the set_cmap() method on our image plot object: In [8]: imgplot.set_cmap(’hot’) 8.3. Plotting numpy arrays as images 65 Matplotlib, Release 0.99.1.1 In [9]: imgplot.set_cmap(’spectral’) 66 Chapter 8. Image tutorial Matplotlib, Release 0.99.1.1 There are many other colormap schemes available. See the list and images of the colormaps. 8.3.2 Color scale reference It’s helpful to have an idea of what value a color represents. We can do that by adding color bars. It’s as easy as one line: In [10]: plt.colorbar() 8.3. Plotting numpy arrays as images 67 Matplotlib, Release 0.99.1.1 This adds a colorbar to your existing ﬁgure. This won’t automatically change if you change you switch to a diﬀerent colormap - you have to re-create your plot, and add in the colorbar again. 8.3.3 Examining a speciﬁc data range Sometimes you want to enhance the contrast in your image, or expand the contrast in a particular region while sacriﬁcing the detail in colors that don’t vary much, or don’t matter. A good tool to ﬁnd interesting regions is the histogram. To create a histogram of our image data, we use the hist() function. In[10]: plt.hist(lum_img.flatten(), 256, range=(0.0,1.0), fc=’k’, ec=’k’) 68 Chapter 8. Image tutorial Matplotlib, Release 0.99.1.1 Most often, the “interesting” part of the image is around the peak, and you can get extra contrast by clipping the regions above and/or below the peak. In our histogram, it looks like there’s not much useful information in the high end (not many white things in the image). Let’s adjust the upper limit, so that we eﬀectively “zoom in on” part of the histogram. We do this by calling the set_clim() method of the image plot object. In[11]: imgplot.set_clim=(0.0,0.7) 8.3. Plotting numpy arrays as images 69 Matplotlib, Release 0.99.1.1 8.3.4 Array Interpolation schemes Interpolation calculates what the color or value of a pixel “should” be, according to diﬀerent mathematical schemes. One common place that this happens is when you resize an image. The number of pixels change, but you want the same information. Since pixels are discrete, there’s missing space. Interpolation is how you ﬁll that space. This is why your images sometimes come out looking pixelated when you blow them up. The eﬀect is more pronounced when the diﬀerence between the original image and the expanded image is greater. Let’s take our image and shrink it. We’re eﬀectively discarding pixels, only keeping a select few. Now when we plot it, that data gets blown up to the size on your screen. The old pixels aren’t there anymore, and the computer has to draw in pixels to ﬁll that space. In In In In In 70 [8]: import Image [9]: img = Image.open(’stinkbug.png’) # Open image as PIL image object [10]: rsize = img.resize((img.size[0]/10,img.size[1]/10)) # Use PIL to resize [11]: rsizeArr = np.asarray(rsize) # Get array back [12]: imgplot = mpimg.imshow(rsizeArr) Chapter 8. Image tutorial Matplotlib, Release 0.99.1.1 Here we have the default interpolation, bilinear, since we did not give imshow() any interpolation argument. Let’s try some others: In [10]: imgplot.set_interpolation(’nearest’) 8.3. Plotting numpy arrays as images 71 Matplotlib, Release 0.99.1.1 In [10]: imgplot.set_interpolation(’bicubic’) 72 Chapter 8. Image tutorial Matplotlib, Release 0.99.1.1 Bicubic interpolation is often used when blowing up photos - people tend to prefer blurry over pixelated. 8.3. Plotting numpy arrays as images 73 Matplotlib, Release 0.99.1.1 74 Chapter 8. Image tutorial CHAPTER NINE ARTIST TUTORIAL There are three layers to the matplotlib API. The matplotlib.backend_bases.FigureCanvas is the area onto which the ﬁgure is drawn, the matplotlib.backend_bases.Renderer is the object which knows how to draw on the FigureCanvas, and the matplotlib.artist.Artist is the object that knows how to use a renderer to paint onto the canvas. The FigureCanvas and Renderer handle all the details of talking to user interface toolkits like wxPython or drawing languages like PostScript®, and the Artist handles all the high level constructs like representing and laying out the ﬁgure, text, and lines. The typical user will spend 95% of his time working with the Artists. There are two types of Artists: primitives and containers. The primitives represent the standard graphical objects we want to paint onto our canvas: Line2D, Rectangle, Text, AxesImage, etc., and the containers are places to put them (Axis, Axes and Figure). The standard use is to create a Figure instance, use the Figure to create one or more Axes or Subplot instances, and use the Axes instance helper methods to create the primitives. In the example below, we create a Figure instance using matplotlib.pyplot.figure(), which is a convenience method for instantiating Figure instances and connecting them with your user interface or drawing toolkit FigureCanvas. As we will discuss below, this is not necessary – you can work directly with PostScript, PDF Gtk+, or wxPython FigureCanvas instances, instantiate your Figures directly and connect them yourselves – but since we are focusing here on the Artist API we’ll let pyplot handle some of those details for us: import matplotlib.pyplot as plt fig = plt.figure() ax = fig.add_subplot(2,1,1) # two rows, one column, first plot The Axes is probably the most important class in the matplotlib API, and the one you will be working with most of the time. This is because the Axes is the plotting area into which most of the objects go, and the Axes has many special helper methods (plot(), text(), hist(), imshow()) to create the most common graphics primitives (Line2D, Text, Rectangle, Image, respectively). These helper methods will take your data (eg. numpy arrays and strings) and create primitive Artist instances as needed (eg. Line2D), add them to the relevant containers, and draw them when requested. Most of you are probably familiar with the Subplot, which is just a special case of an Axes that lives on a regular rows by columns grid of Subplot instances. If you want to create an Axes at an arbitrary location, simply use the add_axes() method which takes a list of [left, bottom, width, height] values in 0-1 relative ﬁgure coordinates: fig2 = plt.figure() ax2 = fig2.add_axes([0.15, 0.1, 0.7, 0.3]) 75 Matplotlib, Release 0.99.1.1 Continuing with our example: import numpy as np t = np.arange(0.0, 1.0, 0.01) s = np.sin(2*np.pi*t) line, = ax.plot(t, s, color=’blue’, lw=2) In this example, ax is the Axes instance created by the fig.add_subplot call above (remember Subplot is just a subclass of Axes) and when you call ax.plot, it creates a Line2D instance and adds it to the Axes.lines list. In the interactive ipython session below, you can see that the Axes.lines list is length one and contains the same line that was returned by the line, = ax.plot... call: In [101]: ax.lines[0] Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710> In [102]: line Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710> If you make subsequent calls to ax.plot (and the hold state is “on” which is the default) then additional lines will be added to the list. You can remove lines later simply by calling the list methods; either of these will work: del ax.lines[0] ax.lines.remove(line) # one or the other, not both! The Axes also has helper methods to conﬁgure and decorate the x-axis and y-axis tick, tick labels and axis labels: xtext = ax.set_xlabel(’my xdata’) # returns a Text instance ytext = ax.set_ylabel(’my xdata’) When you call ax.set_xlabel, it passes the information on the Text instance of the XAxis. Each Axes instance contains an XAxis and a YAxis instance, which handle the layout and drawing of the ticks, tick labels and axis labels. Try creating the ﬁgure below. 76 Chapter 9. Artist tutorial Matplotlib, Release 0.99.1.1 9.1 Customizing your objects Every element in the ﬁgure is represented by a matplotlib Artist, and each has an extensive list of properties to conﬁgure its appearance. The ﬁgure itself contains a Rectangle exactly the size of the ﬁgure, which you can use to set the background color and transparency of the ﬁgures. Likewise, each Axes bounding box (the standard white box with black edges in the typical matplotlib plot, has a Rectangle instance that determines the color, transparency, and other properties of the Axes. These instances are stored as member variables Figure.patch and Axes.patch (“Patch” is a name inherited from MATLAB™, and is a 2D “patch” of color on the ﬁgure, eg. rectangles, circles and polygons). Every matplotlib Artist has the following properties 9.1. Customizing your objects 77 Matplotlib, Release 0.99.1.1 Property alpha animated axes clip_box clip_on clip_path contains ﬁgure label picker transform visible zorder Description The transparency - a scalar from 0-1 A boolean that is used to facilitate animated drawing The axes that the Artist lives in, possibly None The bounding box that clips the Artist Whether clipping is enabled The path the artist is clipped to A picking function to test whether the artist contains the pick point The ﬁgure instance the artist lives in, possibly None A text label (eg. for auto-labeling) A python object that controls object picking The transformation A boolean whether the artist should be drawn A number which determines the drawing order Each of the properties is accessed with an old-fashioned setter or getter (yes we know this irritates Pythonistas and we plan to support direct access via properties or traits but it hasn’t been done yet). For example, to multiply the current alpha by a half: a = o.get_alpha() o.set_alpha(0.5*a) If you want to set a number of properties at once, you can also use the set method with keyword arguments. For example: o.set(alpha=0.5, zorder=2) If you are working interactively at the python shell, a handy way to inspect the Artist properties is to use the matplotlib.artist.getp() function (simply getp() in pylab), which lists the properties and their values. This works for classes derived from Artist as well, eg. Figure and Rectangle. Here are the Figure rectangle properties mentioned above: In [149]: matplotlib.artist.getp(fig.patch) alpha = 1.0 animated = False antialiased or aa = True axes = None clip_box = None clip_on = False clip_path = None contains = None edgecolor or ec = w facecolor or fc = 0.75 figure = Figure(8.125x6.125) fill = 1 hatch = None height = 1 label = linewidth or lw = 1.0 picker = None 78 Chapter 9. Artist tutorial Matplotlib, Release 0.99.1.1 transform = <Affine object at 0x134cca84> verts = ((0, 0), (0, 1), (1, 1), (1, 0)) visible = True width = 1 window_extent = <Bbox object at 0x134acbcc> x=0 y=0 zorder = 1 The docstrings for all of the classes also contain the Artist properties, so you can consult the interactive “help” or the matplotlib artists for a listing of properties for a given object. 9.2 Object containers Now that we know how to inspect and set the properties of a given object we want to conﬁgure, we need to now how to get at that object. As mentioned in the introduction, there are two kinds of objects: primitives and containers. The primitives are usually the things you want to conﬁgure (the font of a Text instance, the width of a Line2D) although the containers also have some properties as well – for example the Axes Artist is a container that contains many of the primitives in your plot, but it also has properties like the xscale to control whether the xaxis is ‘linear’ or ‘log’. In this section we’ll review where the various container objects store the Artists that you want to get at. 9.3 Figure container The top level container Artist is the matplotlib.figure.Figure, and it contains everything in the ﬁgure. The background of the ﬁgure is a Rectangle which is stored in Figure.patch. As you add subplots (add_subplot()) and axes (add_axes()) to the ﬁgure these will be appended to the Figure.axes. These are also returned by the methods that create them: In [156]: fig = plt.figure() In [157]: ax1 = fig.add_subplot(211) In [158]: ax2 = fig.add_axes([0.1, 0.1, 0.7, 0.3]) In [159]: ax1 Out[159]: <matplotlib.axes.Subplot instance at 0xd54b26c> In [160]: print fig.axes [<matplotlib.axes.Subplot instance at 0xd54b26c>, <matplotlib.axes.Axes instance at 0xd3f0b2c>] Because the ﬁgure maintains the concept of the “current axes” (see Figure.gca and Figure.sca) to support the pylab/pyplot state machine, you should not insert or remove axes directly from the axes list, but rather use the add_subplot() and add_axes() methods to insert, and the delaxes() method to delete. You are free however, to iterate over the list of axes or index into it to get access to Axes instances you want to customize. Here is an example which turns all the axes grids on: 9.2. Object containers 79 Matplotlib, Release 0.99.1.1 for ax in fig.axes: ax.grid(True) The ﬁgure also has its own text, lines, patches and images, which you can use to add primitives directly. The default coordinate system for the Figure will simply be in pixels (which is not usually what you want) but you can control this by setting the transform property of the Artist you are adding to the ﬁgure. More useful is “ﬁgure coordinates” where (0, 0) is the bottom-left of the ﬁgure and (1, 1) is the top-right of the ﬁgure which you can obtain by setting the Artist transform to fig.transFigure: In [191]: fig = plt.figure() In [192]: l1 = matplotlib.lines.Line2D([0, 1], [0, 1], transform=fig.transFigure, figure=fig) In [193]: l2 = matplotlib.lines.Line2D([0, 1], [1, 0], transform=fig.transFigure, figure=fig) In [194]: fig.lines.extend([l1, l2]) In [195]: fig.canvas.draw() Here is a summary of the Artists the ﬁgure contains 80 Chapter 9. Artist tutorial Matplotlib, Release 0.99.1.1 Figure attribute axes patch images legends lines patches texts Description A list of Axes instances (includes Subplot) The Rectangle background A list of FigureImages patches - useful for raw pixel display A list of Figure Legend instances (diﬀerent from Axes.legends) A list of Figure Line2D instances (rarely used, see Axes.lines) A list of Figure patches (rarely used, see Axes.patches) A list Figure Text instances 9.4 Axes container The matplotlib.axes.Axes is the center of the matplotlib universe – it contains the vast majority of all the Artists used in a ﬁgure with many helper methods to create and add these Artists to itself, as well as helper methods to access and customize the Artists it contains. Like the Figure, it contains a Patch patch which is a Rectangle for Cartesian coordinates and a Circle for polar coordinates; this patch determines the shape, background and border of the plotting region: ax = fig.add_subplot(111) rect = ax.patch # a Rectangle instance rect.set_facecolor(’green’) When you call a plotting method, eg. the canonical plot() and pass in arrays or lists of values, the method will create a matplotlib.lines.Line2D() instance, update the line with all the Line2D properties passed as keyword arguments, add the line to the Axes.lines container, and returns it to you: In [213]: x, y = np.random.rand(2, 100) In [214]: line, = ax.plot(x, y, ’-’, color=’blue’, linewidth=2) plot returns a list of lines because you can pass in multiple x, y pairs to plot, and we are unpacking the ﬁrst element of the length one list into the line variable. The line has been added to the Axes.lines list: In [229]: print ax.lines [<matplotlib.lines.Line2D instance at 0xd378b0c>] Similarly, methods that create patches, like bar() creates a list of rectangles, will add the patches to the Axes.patches list: In [233]: n, bins, rectangles = ax.hist(np.random.randn(1000), 50, facecolor=’yellow’) In [234]: rectangles Out[234]: <a list of 50 Patch objects> In [235]: print len(ax.patches) You should not add objects directly to the Axes.lines or Axes.patches lists unless you know exactly what you are doing, because the Axes needs to do a few things when it creates and adds an object. It sets the ﬁgure and axes property of the Artist, as well as the default Axes transformation (unless a transformation is 9.4. Axes container 81 Matplotlib, Release 0.99.1.1 set). It also inspects the data contained in the Artist to update the data structures controlling auto-scaling, so that the view limits can be adjusted to contain the plotted data. You can, nonetheless, create objects yourself and add them directly to the Axes using helper methods like add_line() and add_patch(). Here is an annotated interactive session illustrating what is going on: In [261]: fig = plt.figure() In [262]: ax = fig.add_subplot(111) # create a rectangle instance In [263]: rect = matplotlib.patches.Rectangle( (1,1), width=5, height=12) # by default the axes instance is None In [264]: print rect.get_axes() None # and the transformation instance is set to the "identity transform" In [265]: print rect.get_transform() <Affine object at 0x13695544> # now we add the Rectangle to the Axes In [266]: ax.add_patch(rect) # and notice that the ax.add_patch method has set the axes # instance In [267]: print rect.get_axes() Subplot(49,81.25) # and the transformation has been set too In [268]: print rect.get_transform() <Affine object at 0x15009ca4> # the default axes transformation is ax.transData In [269]: print ax.transData <Affine object at 0x15009ca4> # notice that the xlimits of the Axes have not been changed In [270]: print ax.get_xlim() (0.0, 1.0) # but the data limits have been updated to encompass the rectangle In [271]: print ax.dataLim.get_bounds() (1.0, 1.0, 5.0, 12.0) # we can manually invoke the auto-scaling machinery In [272]: ax.autoscale_view() # and now the xlim are updated to encompass the rectangle In [273]: print ax.get_xlim() (1.0, 6.0) # we have to manually force a figure draw In [274]: ax.figure.canvas.draw() 82 Chapter 9. Artist tutorial Matplotlib, Release 0.99.1.1 There are many, many Axes helper methods for creating primitive Artists and adding them to their respective containers. The table below summarizes a small sampling of them, the kinds of Artist they create, and where they store them Helper method ax.annotate - text annotations ax.bar - bar charts ax.errorbar - error bar plots ax.ﬁll - shared area ax.hist - histograms ax.imshow - image data ax.legend - axes legends ax.plot - xy plots ax.scatter - scatter charts ax.text - text Artist Annotate Rectangle Line2D and Rectangle Polygon Rectangle AxesImage Legend Line2D PolygonCollection Text Container ax.texts ax.patches ax.lines and ax.patches ax.patches ax.patches ax.images ax.legends ax.lines ax.collections ax.texts In addition to all of these Artists, the Axes contains two important Artist containers: the XAxis and YAxis, which handle the drawing of the ticks and labels. These are stored as instance variables xaxis and yaxis. The XAxis and YAxis containers will be detailed below, but note that the Axes contains many helper methods which forward calls on to the Axis instances so you often do not need to work with them directly unless you want to. For example, you can set the font size of the XAxis ticklabels using the Axes helper method: for label in ax.get_xticklabels(): label.set_color(’orange’) Below is a summary of the Artists that the Axes contains Axes attribute artists patch collections images legends lines patches texts xaxis yaxis Description A list of Artist instances Rectangle instance for Axes background A list of Collection instances A list of AxesImage A list of Legend instances A list of Line2D instances A list of Patch instances A list of Text instances matplotlib.axis.XAxis instance matplotlib.axis.YAxis instance 9.5 Axis containers The matplotlib.axis.Axis instances handle the drawing of the tick lines, the grid lines, the tick labels and the axis label. You can conﬁgure the left and right ticks separately for the y-axis, and the upper and lower ticks separately for the x-axis. The Axis also stores the data and view intervals used in auto-scaling, panning and zooming, as well as the Locator and Formatter instances which control where the ticks are placed and how they are represented as strings. 9.5. Axis containers 83 Matplotlib, Release 0.99.1.1 Each Axis object contains a label attribute (this is what pylab modiﬁes in calls to xlabel() and ylabel()) as well as a list of major and minor ticks. The ticks are XTick and YTick instances, which contain the actual line and text primitives that render the ticks and ticklabels. Because the ticks are dynamically created as needed (eg. when panning and zooming), you should access the lists of major and minor ticks through their accessor methods get_major_ticks() and get_minor_ticks(). Although the ticks contain all the primitives and will be covered below, the Axis methods contain accessor methods to return the tick lines, tick labels, tick locations etc.: In [285]: axis = ax.xaxis In [286]: axis.get_ticklocs() Out[286]: array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.]) In [287]: axis.get_ticklabels() Out[287]: <a list of 10 Text major ticklabel objects> # note there are twice as many ticklines as labels because by # default there are tick lines at the top and bottom but only tick # labels below the xaxis; this can be customized In [288]: axis.get_ticklines() Out[288]: <a list of 20 Line2D ticklines objects> # by default you get the major ticks back In [291]: axis.get_ticklines() Out[291]: <a list of 20 Line2D ticklines objects> # but you can also ask for the minor ticks In [292]: axis.get_ticklines(minor=True) Out[292]: <a list of 0 Line2D ticklines objects> Here is a summary of some of the useful accessor methods of the Axis (these have corresponding setters where useful, such as set_major_formatter) Accessor method get_scale get_view_interval get_data_interval get_gridlines get_label get_ticklabels get_ticklines get_ticklocs get_major_locator get_major_formatter get_minor_locator get_minor_formatter get_major_ticks get_minor_ticks grid Description The scale of the axis, eg ‘log’ or ‘linear’ The interval instance of the axis view limits The interval instance of the axis data limits A list of grid lines for the Axis The axis label - a Text instance A list of Text instances - keyword minor=True|False A list of Line2D instances - keyword minor=True|False A list of Tick locations - keyword minor=True|False The matplotlib.ticker.Locator instance for major ticks The matplotlib.ticker.Formatter instance for major ticks The matplotlib.ticker.Locator instance for minor ticks The matplotlib.ticker.Formatter instance for minor ticks A list of Tick instances for major ticks A list of Tick instances for minor ticks Turn the grid on or oﬀ for the major or minor ticks Here is an example, not recommended for its beauty, which customizes the axes and tick properties 84 Chapter 9. Artist tutorial Matplotlib, Release 0.99.1.1 import numpy as np import matplotlib.pyplot as plt # plt.figure creates a matplotlib.figure.Figure instance fig = plt.figure() rect = fig.patch # a rectangle instance rect.set_facecolor(’lightgoldenrodyellow’) ax1 = fig.add_axes([0.1, 0.3, 0.4, 0.4]) rect = ax1.patch rect.set_facecolor(’lightslategray’) for label in ax1.xaxis.get_ticklabels(): # label is a Text instance label.set_color(’red’) label.set_rotation(45) label.set_fontsize(16) for line in ax1.yaxis.get_ticklines(): # line is a Line2D instance line.set_color(’green’) line.set_markersize(25) line.set_markeredgewidth(3) 9.5. Axis containers 85 Matplotlib, Release 0.99.1.1 9.6 Tick containers The matplotlib.axis.Tick is the ﬁnal container object in our descent from the Figure to the Axes to the Axis to the Tick. The Tick contains the tick and grid line instances, as well as the label instances for the upper and lower ticks. Each of these is accessible directly as an attribute of the Tick. In addition, there are boolean variables that determine whether the upper labels and ticks are on for the x-axis and whether the right labels and ticks are on for the y-axis. Tick attribute tick1line tick2line gridline label1 label2 gridOn tick1On tick2On label1On label2On Description Line2D instance Line2D instance Line2D instance Text instance Text instance boolean which determines whether to draw the tickline boolean which determines whether to draw the 1st tickline boolean which determines whether to draw the 2nd tickline boolean which determines whether to draw tick label boolean which determines whether to draw tick label Here is an example which sets the formatter for the right side ticks with dollar signs and colors them green on the right side of the yaxis import numpy as np import matplotlib.pyplot as plt import matplotlib.ticker as ticker fig = plt.figure() ax = fig.add_subplot(111) ax.plot(100*np.random.rand(20)) formatter = ticker.FormatStrFormatter(’$%1.2f ’) ax.yaxis.set_major_formatter(formatter) for tick in ax.yaxis.get_major_ticks(): tick.label1On = False tick.label2On = True tick.label2.set_color(’green’) 86 Chapter 9. Artist tutorial Matplotlib, Release 0.99.1.1 9.6. Tick containers 87 Matplotlib, Release 0.99.1.1 88 Chapter 9. Artist tutorial CHAPTER TEN LEGEND GUIDE Do not proceed unless you already have read legend() and matplotlib.legend.Legend! 10.1 What to be displayed The legend command has a following call signature: legend(*args, **kwargs) If len(args) is 2, the ﬁrst argument should be a list of artist to be labeled, and the second argument should a list of string labels. If len(args) is 0, it automatically generate the legend from label properties of the child artists by calling get_legend_handles_labels() method. For example, ax.legend() is equivalent to: handles, labels = ax.get_legend_handles_labels() ax.legend(handles, labels) The get_legend_handles_labels() method returns a tuple of two lists, i.e., list of artists and list of labels (python string). However, it does not return all of its child artists. It returns all artists in ax.lines and ax.patches and some artists in ax.collection which are instance of LineCollection or RegularPolyCollection. The label attributes (returned by get_label() method) of collected artists are used as text labels. If label attribute is empty string or starts with “_”, that artist will be ignored. • Note that not all kind of artists are supported by the legend. The following is the list of artists that are currently supported. – Line2D – Patch – LineCollection – RegularPolyCollection Unfortunately, there is no easy workaround when you need legend for an artist not in the above list (You may use one of the supported artist as a proxy. See below), or customize it beyond what is supported by matplotlib.legend.Legend. 89 Matplotlib, Release 0.99.1.1 • Remember that some pyplot commands return artist not supported by legend, e.g., fill_between() returns PolyCollection that is not supported. Or some return multiple artists. For example, plot() returns list of Line2D instances, and errorbar() returns a length 3 tuple of Line2D instances. • The legend does not care about the axes that given artists belongs, i.e., the artists may belong to other axes or even none. 10.1.1 Adjusting the Order of Legend items When you want to customize the list of artists to be displayed in the legend, or their order of appearance. There are a two options. First, you can keep lists of artists and labels, and explicitly use these for the ﬁrst two argument of the legend call.: p1, = plot([1,2,3]) p2, = plot([3,2,1]) p3, = plot([2,3,1]) legend([p2, p1], ["line 2", "line 1"]) Or you may use get_legend_handles_labels() to retrieve list of artist and labels and manipulate them before feeding them to legend call.: ax = subplot(1,1,1) p1, = ax.plot([1,2,3], label="line 1") p2, = ax.plot([3,2,1], label="line 2") p3, = ax.plot([2,3,1], label="line 3") handles, labels = ax.get_legend_handles_labels() # reverse the order ax.legend(handles[::-1], labels[::-1]) # or sort them by labels import operator hl = sorted(zip(handles, labels), key=operator.itemgetter(1)) handles2, labels2 = zip(*hl) ax.legend(handles2, labels2) 10.1.2 Using Proxy Artist When you want to display legend for an artist not supported by the matplotlib, you may use other supported artist as a proxy. For example, you may creates an proxy artist without adding it to the axes (so the proxy artist will not be drawn in the main axes) and feet it to the legend function.: p = Rectangle((0, 0), 1, 1, fc="r") legend([p], ["Red Rectangle"]) 90 Chapter 10. Legend guide Matplotlib, Release 0.99.1.1 10.2 Multicolumn Legend By specifying the keyword argument ncol, you can have a multi-column legend. Also, mode=”expand” horizontally expand the legend to ﬁll the axes area. See legend_demo3.py for example. 10.3 Legend location The location of the legend can be speciﬁed by the keyword argument loc, either by string or a integer number. String upper right upper left lower left lower right right center left center right lower center upper center center Number 1 2 3 4 5 6 7 8 9 10 By default, the legend will anchor to the bbox of the axes (for legend) or the bbox of the ﬁgure (ﬁglegend). You can specify your own bbox using bbox_to_anchor argument. bbox_to_anchor can be an instance of BboxBase, a tuple of 4 ﬂoats (x, y, width, height of the bbox), or a tuple of 2 ﬂoats (x, y with width=height=0). Unless bbox_transform argument is given, the coordinates (even for the bbox instance) are considered as normalized axes coordinates. For example, if you want your axes legend located at the ﬁgure corner (instead of the axes corner): l = legend(bbox_to_anchor=(0, 0, 1, 1), transform=gcf().transFigure) Also, you can place above or outer right-hand side of the axes, from matplotlib.pyplot import * subplot(211) plot([1,2,3], label="test1") plot([3,2,1], label="test2") legend(bbox_to_anchor=(0., 1.02, 1., .102), loc=3, ncol=2, mode="expand", borderaxespad=0.) subplot(223) plot([1,2,3], label="test1") plot([3,2,1], label="test2") legend(bbox_to_anchor=(1.05, 1), loc=2, borderaxespad=0.) show() 10.2. Multicolumn Legend 91 Matplotlib, Release 0.99.1.1 10.4 Multiple Legend Sometime, you want to split the legend into multiple ones.: p1, = plot([1,2,3]) p2, = plot([3,2,1]) legend([p1], ["Test1"], loc=1) legend([p2], ["Test2"], loc=4) However, the above code only shows the second legend. When the legend command is called, a new legend instance is created and old ones are removed from the axes. Thus, you need to manually add the removed legend. from matplotlib.pyplot import * p1, = plot([1,2,3], label="test1") p2, = plot([3,2,1], label="test2") l1 = legend([p1], ["Label 1"], loc=1) l2 = legend([p2], ["Label 2"], loc=4) # this removes l1 from the axes. gca().add_artist(l1) # add l1 as a separate artist to the axes 92 Chapter 10. Legend guide Matplotlib, Release 0.99.1.1 show() 10.4. Multiple Legend 93 Matplotlib, Release 0.99.1.1 94 Chapter 10. Legend guide CHAPTER ELEVEN EVENT HANDLING AND PICKING matplotlib works with 6 user interface toolkits (wxpython, tkinter, qt, gtk, ﬂtk and macosx) and in order to support features like interactive panning and zooming of ﬁgures, it is helpful to the developers to have an API for interacting with the ﬁgure via key presses and mouse movements that is “GUI neutral” so we don’t have to repeat a lot of code across the diﬀerent user interfaces. Although the event handling API is GUI neutral, it is based on the GTK model, which was the ﬁrst user interface matplotlib supported. The events that are triggered are also a bit richer vis-a-vis matplotlib than standard GUI events, including information like which matplotlib.axes.Axes the event occurred in. The events also understand the matplotlib coordinate system, and report event locations in both pixel and data coordinates. 11.1 Event connections To receive events, you need to write a callback function and then connect your function to the event manager, which is part of the FigureCanvasBase. Here is a simple example that prints the location of the mouse click and which button was pressed: fig = plt.figure() ax = fig.add_subplot(111) ax.plot(np.random.rand(10)) def onclick(event): print ’button=%d , x=%d , y=%d , xdata=%f , ydata=%f ’%( event.button, event.x, event.y, event.xdata, event.ydata) cid = fig.canvas.mpl_connect(’button_press_event’, onclick) The FigureCanvas method mpl_connect() returns a connection id which is simply an integer. When you want to disconnect the callback, just call: fig.canvas.mpl_disconnect(cid) Here are the events that you can connect to, the class instances that are sent back to you when the event occurs, and the event descriptions 95 Matplotlib, Release 0.99.1.1 Event name ‘button_press_event’ ‘button_release_event’ ‘draw_event’ ‘key_press_event’ ‘key_release_event’ ‘motion_notify_event’ ‘pick_event’ ‘resize_event’ ‘scroll_event’ ‘ﬁgure_enter_event’ ‘ﬁgure_leave_event’ ‘axes_enter_event’ ‘axes_leave_event’ Class and description MouseEvent - mouse button is pressed MouseEvent - mouse button is released DrawEvent - canvas draw KeyEvent - key is pressed KeyEvent - key is released MouseEvent - mouse motion PickEvent - an object in the canvas is selected ResizeEvent - ﬁgure canvas is resized MouseEvent - mouse scroll wheel is rolled LocationEvent - mouse enters a new ﬁgure LocationEvent - mouse leaves a ﬁgure LocationEvent - mouse enters a new axes LocationEvent - mouse leaves an axes 11.2 Event attributes All matplotlib events inherit from the base class matplotlib.backend_bases.Event, which store the attributes: name the event name canvas the FigureCanvas instance generating the event guiEvent the GUI event that triggered the matplotlib event The most common events that are the bread and butter of event handling are key press/release events and mouse press/release and movement events. The KeyEvent and MouseEvent classes that handle these events are both derived from the LocationEvent, which has the following attributes x x position - pixels from left of canvas y y position - pixels from bottom of canvas inaxes the Axes instance if mouse is over axes xdata x coord of mouse in data coords ydata y coord of mouse in data coords Let’s look a simple example of a canvas, where a simple line segment is created every time a mouse is pressed: class LineBuilder: def __init__(self, line): self.line = line self.xs = list(line.get_xdata()) self.ys = list(line.get_ydata()) self.cid = line.figure.canvas.mpl_connect(’button_press_event’, self) def __call__(self, event): print ’click’, event 96 Chapter 11. Event handling and picking Matplotlib, Release 0.99.1.1 if event.inaxes!=self.line.axes: return self.xs.append(event.xdata) self.ys.append(event.ydata) self.line.set_data(self.xs, self.ys) self.line.figure.canvas.draw() fig = plt.figure() ax = fig.add_subplot(111) ax.set_title(’click to build line segments’) line, = ax.plot([0], [0]) # empty line linebuilder = LineBuilder(line) The MouseEvent that we just used is a LocationEvent, so we have access to the data and pixel coordinates in event.x and event.xdata. In addition to the LocationEvent attributes, it has button button pressed None, 1, 2, 3, ‘up’, ‘down’ (up and down are used for scroll events) key the key pressed: None, any character, ‘shift’, ‘win’, or ‘control’ 11.2.1 Draggable rectangle exercise Write draggable rectangle class that is initialized with a Rectangle instance but will move its x,y location when dragged. Hint: you will need to store the original xy location of the rectangle which is stored as rect.xy and connect to the press, motion and release mouse events. When the mouse is pressed, check to see if the click occurs over your rectangle (see matplotlib.patches.Rectangle.contains()) and if it does, store the rectangle xy and the location of the mouse click in data coords. In the motion event callback, compute the deltax and deltay of the mouse movement, and add those deltas to the origin of the rectangle you stored. The redraw the ﬁgure. On the button release event, just reset all the button press data you stored as None. Here is the solution: import numpy as np import matplotlib.pyplot as plt class DraggableRectangle: def __init__(self, rect): self.rect = rect self.press = None def connect(self): ’connect to all the events we need’ self.cidpress = self.rect.figure.canvas.mpl_connect( ’button_press_event’, self.on_press) self.cidrelease = self.rect.figure.canvas.mpl_connect( ’button_release_event’, self.on_release) self.cidmotion = self.rect.figure.canvas.mpl_connect( ’motion_notify_event’, self.on_motion) def on_press(self, event): ’on button press we will see if the mouse is over us and store some data’ 11.2. Event attributes 97 Matplotlib, Release 0.99.1.1 if event.inaxes != self.rect.axes: return contains, attrd = self.rect.contains(event) if not contains: return print ’event contains’, self.rect.xy x0, y0 = self.rect.xy self.press = x0, y0, event.xdata, event.ydata def on_motion(self, event): ’on motion we will move the rect if the mouse is over us’ if self.press is None: return if event.inaxes != self.rect.axes: return x0, y0, xpress, ypress = self.press dx = event.xdata - xpress dy = event.ydata - ypress #print ’x0=%f, xpress=%f, event.xdata=%f, dx=%f, x0+dx=%f’%(x0, xpress, event.xdata, dx, x0+dx) self.rect.set_x(x0+dx) self.rect.set_y(y0+dy) self.rect.figure.canvas.draw() def on_release(self, event): ’on release we reset the press data’ self.press = None self.rect.figure.canvas.draw() def disconnect(self): ’disconnect all the stored connection ids’ self.rect.figure.canvas.mpl_disconnect(self.cidpress) self.rect.figure.canvas.mpl_disconnect(self.cidrelease) self.rect.figure.canvas.mpl_disconnect(self.cidmotion) fig = plt.figure() ax = fig.add_subplot(111) rects = ax.bar(range(10), 20*np.random.rand(10)) drs = for rect in rects: dr = DraggableRectangle(rect) dr.connect() drs.append(dr) plt.show() Extra credit: use the animation blit techniques discussed in the animations recipe to make the animated drawing faster and smoother. Extra credit solution: # draggable rectangle with the animation blit techniques; see # http://www.scipy.org/Cookbook/Matplotlib/Animations import numpy as np import matplotlib.pyplot as plt 98 Chapter 11. Event handling and picking Matplotlib, Release 0.99.1.1 class DraggableRectangle: lock = None # only one can be animated at a time def __init__(self, rect): self.rect = rect self.press = None self.background = None def connect(self): ’connect to all the events we need’ self.cidpress = self.rect.figure.canvas.mpl_connect( ’button_press_event’, self.on_press) self.cidrelease = self.rect.figure.canvas.mpl_connect( ’button_release_event’, self.on_release) self.cidmotion = self.rect.figure.canvas.mpl_connect( ’motion_notify_event’, self.on_motion) def on_press(self, event): ’on button press we will see if the mouse is over us and store some data’ if event.inaxes != self.rect.axes: return if DraggableRectangle.lock is not None: return contains, attrd = self.rect.contains(event) if not contains: return print ’event contains’, self.rect.xy x0, y0 = self.rect.xy self.press = x0, y0, event.xdata, event.ydata DraggableRectangle.lock = self # draw everything but the selected rectangle and store the pixel buffer canvas = self.rect.figure.canvas axes = self.rect.axes self.rect.set_animated(True) canvas.draw() self.background = canvas.copy_from_bbox(self.rect.axes.bbox) # now redraw just the rectangle axes.draw_artist(self.rect) # and blit just the redrawn area canvas.blit(axes.bbox) def on_motion(self, event): ’on motion we will move the rect if the mouse is over us’ if DraggableRectangle.lock is not self: return if event.inaxes != self.rect.axes: return x0, y0, xpress, ypress = self.press dx = event.xdata - xpress dy = event.ydata - ypress self.rect.set_x(x0+dx) self.rect.set_y(y0+dy) canvas = self.rect.figure.canvas 11.2. Event attributes 99 Matplotlib, Release 0.99.1.1 axes = self.rect.axes # restore the background region canvas.restore_region(self.background) # redraw just the current rectangle axes.draw_artist(self.rect) # blit just the redrawn area canvas.blit(axes.bbox) def on_release(self, event): ’on release we reset the press data’ if DraggableRectangle.lock is not self: return self.press = None DraggableRectangle.lock = None # turn off the rect animation property and reset the background self.rect.set_animated(False) self.background = None # redraw the full figure self.rect.figure.canvas.draw() def disconnect(self): ’disconnect all the stored connection ids’ self.rect.figure.canvas.mpl_disconnect(self.cidpress) self.rect.figure.canvas.mpl_disconnect(self.cidrelease) self.rect.figure.canvas.mpl_disconnect(self.cidmotion) fig = plt.figure() ax = fig.add_subplot(111) rects = ax.bar(range(10), 20*np.random.rand(10)) drs = for rect in rects: dr = DraggableRectangle(rect) dr.connect() drs.append(dr) plt.show() 11.3 Mouse enter and leave If you want to be notiﬁed when the mouse enters or leaves a ﬁgure or axes, you can connect to the ﬁgure/axes enter/leave events. Here is a simple example that changes the colors of the axes and ﬁgure background that the mouse is over: """ Illustrate the figure and axes enter and leave events by changing the 100 Chapter 11. Event handling and picking Matplotlib, Release 0.99.1.1 frame colors on enter and leave """ import matplotlib.pyplot as plt def enter_axes(event): print ’enter_axes’, event.inaxes event.inaxes.patch.set_facecolor(’yellow’) event.canvas.draw() def leave_axes(event): print ’leave_axes’, event.inaxes event.inaxes.patch.set_facecolor(’white’) event.canvas.draw() def enter_figure(event): print ’enter_figure’, event.canvas.figure event.canvas.figure.patch.set_facecolor(’red’) event.canvas.draw() def leave_figure(event): print ’leave_figure’, event.canvas.figure event.canvas.figure.patch.set_facecolor(’grey’) event.canvas.draw() fig1 = plt.figure() fig1.suptitle(’mouse hover over figure or axes to trigger events’) ax1 = fig1.add_subplot(211) ax2 = fig1.add_subplot(212) fig1.canvas.mpl_connect(’figure_enter_event’, enter_figure) fig1.canvas.mpl_connect(’figure_leave_event’, leave_figure) fig1.canvas.mpl_connect(’axes_enter_event’, enter_axes) fig1.canvas.mpl_connect(’axes_leave_event’, leave_axes) fig2 = plt.figure() fig2.suptitle(’mouse hover over figure or axes to trigger events’) ax1 = fig2.add_subplot(211) ax2 = fig2.add_subplot(212) fig2.canvas.mpl_connect(’figure_enter_event’, enter_figure) fig2.canvas.mpl_connect(’figure_leave_event’, leave_figure) fig2.canvas.mpl_connect(’axes_enter_event’, enter_axes) fig2.canvas.mpl_connect(’axes_leave_event’, leave_axes) plt.show() 11.4 Object picking You can enable picking by setting the picker property of an Artist (eg a matplotlib Line2D, Text, Patch, Polygon, AxesImage, etc...) 11.4. Object picking 101 Matplotlib, Release 0.99.1.1 There are a variety of meanings of the picker property: None picking is disabled for this artist (default) boolean if True then picking will be enabled and the artist will ﬁre a pick event if the mouse event is over the artist float if picker is a number it is interpreted as an epsilon tolerance in points and the the artist will ﬁre oﬀ an event if its data is within epsilon of the mouse event. For some artists like lines and patch collections, the artist may provide additional data to the pick event that is generated, eg the indices of the data within epsilon of the pick event. function if picker is callable, it is a user supplied function which determines whether the artist is hit by the mouse event. The signature is hit, props = picker(artist, mouseevent) to determine the hit test. If the mouse event is over the artist, return hit=True and props is a dictionary of properties you want added to the PickEvent attributes After you have enabled an artist for picking by setting the picker property, you need to connect to the ﬁgure canvas pick_event to get pick callbacks on mouse press events. Eg: def pick_handler(event): mouseevent = event.mouseevent artist = event.artist # now do something with this... The PickEvent which is passed to your callback is always ﬁred with two attributes: mouseevent the mouse event that generate the pick event. The mouse event in turn has attributes like x and y (the coords in display space, eg pixels from left, bottom) and xdata, ydata (the coords in data space). Additionally, you can get information about which buttons were pressed, which keys were pressed, which Axes the mouse is over, etc. See matplotlib.backend_bases.MouseEvent for details. artist the Artist that generated the pick event. Additionally, certain artists like Line2D and PatchCollection may attach additional meta data like the indices into the data that meet the picker criteria (eg all the points in the line that are within the speciﬁed epsilon tolerance) 11.4.1 Simple picking example In the example below, we set the line picker property to a scalar, so it represents a tolerance in points (72 points per inch). The onpick callback function will be called when the pick event it within the tolerance distance from the line, and has the indices of the data vertices that are within the pick distance tolerance. Our onpick callback function simply prints the data that are under the pick location. Diﬀerent matplotlib Artists can attach diﬀerent data to the PickEvent. For example, Line2D attaches the ind property, which are the indices into the line data under the pick point. See pick() for details on the PickEvent properties of the line. Here is the code: 102 Chapter 11. Event handling and picking Matplotlib, Release 0.99.1.1 import numpy as np import matplotlib.pyplot as plt fig = plt.figure() ax = fig.add_subplot(111) ax.set_title(’click on points’) line, = ax.plot(np.random.rand(100), ’o’, picker=5) # 5 points tolerance def onpick(event): thisline = event.artist xdata = thisline.get_xdata() ydata = thisline.get_ydata() ind = event.ind print ’onpick points:’, zip(xdata[ind], ydata[ind]) fig.canvas.mpl_connect(’pick_event’, onpick) plt.show() 11.4.2 Picking exercise Create a data set of 100 arrays of 1000 Gaussian random numbers and compute the sample mean and standard deviation of each of them (hint: numpy arrays have a mean and std method) and make a xy marker plot of the 100 means vs the 100 standard deviations. Connect the line created by the plot command to the pick event, and plot the original time series of the data that generated the clicked on points. If more than one point is within the tolerance of the clicked on point, you can use multiple subplots to plot the multiple time series. Exercise solution: """ compute the mean and stddev of 100 data sets and plot mean vs stddev. When you click on one of the mu, sigma points, plot the raw data from the dataset that generated the mean and stddev """ import numpy as np import matplotlib.pyplot as plt X = np.random.rand(100, 1000) xs = np.mean(X, axis=1) ys = np.std(X, axis=1) fig = plt.figure() ax = fig.add_subplot(111) ax.set_title(’click on point to plot time series’) line, = ax.plot(xs, ys, ’o’, picker=5) # 5 points tolerance def onpick(event): 11.4. Object picking 103 Matplotlib, Release 0.99.1.1 if event.artist!=line: return True N = len(event.ind) if not N: return True figi = plt.figure() for subplotnum, dataind in enumerate(event.ind): ax = figi.add_subplot(N,1,subplotnum+1) ax.plot(X[dataind]) ax.text(0.05, 0.9, ’mu=%1.3f \nsigma=%1.3f ’%(xs[dataind], ys[dataind]), transform=ax.transAxes, va=’top’) ax.set_ylim(-0.5, 1.5) figi.show() return True fig.canvas.mpl_connect(’pick_event’, onpick) plt.show() 104 Chapter 11. Event handling and picking CHAPTER TWELVE TRANSFORMATIONS TUTORIAL Like any graphics packages, matplotlib is built on top of a transformation framework to easily move between coordinate systems, the userland data coordinate system, the axes coordinate system, the ﬁgure coordinate system, and the display coordinate system. In 95% of your plotting, you won’t need to think about this, as it happens under the hood, but as you push the limits of custom ﬁgure generation, it helps to have an understanding of these objects so you can reuse the existing transformations matplotlib makes available to you, or create your own (see matplotlib.transforms). The table below summarizes the existing coordinate systems, the transformation object you should use to work in that coordinate system, and the description of that system. In the Transformation Object column, ax is a Axes instance, and fig is a Figure instance. Coordinate data axes ﬁgure display TransforDescription mation Object ax.transData The userland data coordinate system, controlled by the xlim and ylim ax.transAxes The coordinate system of the Axes; (0,0) is bottom left of the axes, and (1,1) is top right of the axes fig.transFigure coordinate system of the Figure; (0,0) is bottom left of the ﬁgure, and The (1,1) is top right of the ﬁgure None This is the pixel coordinate system of the display; (0,0) is the bottom left of the display, and (width, height) is the top right of the display in pixels All of the transformation objects in the table above take inputs in their coordinate system, and transform the input to the display coordinate system. That is why the display coordinate system has None for the Transformation Object column – it already is in display coordinates. The transformations also know how to invert themselves, to go from display back to the native coordinate system. This is particularly useful when processing events from the user interface, which typically occur in display space, and you want to know where the mouse click or key-press occurred in your data coordinate system. 12.1 Data coordinates Let’s start with the most commonly used coordinate, the data coordinate system. Whenever you add data to the axes, matplotlib updates the datalimits, most commonly updated with the set_xlim() and set_ylim() methods. For example, in the ﬁgure below, the data limits stretch from 0 to 10 on the x-axis, and -1 to 1 on the y-axis. 105 Matplotlib, Release 0.99.1.1 import numpy as np import matplotlib.pyplot as plt x = np.arange(0, 10, 0.005) y = np.exp(-x/2.) * np.sin(2*np.pi*x) fig = plt.figure() ax = fig.add_subplot(111) ax.plot(x, y) ax.set_xlim(0, 10) ax.set_ylim(-1, 1) plt.show() You can use the ax.transData instance to transform from your data to your display coordinate system, either a single point or a sequence of points as shown below: In [14]: type(ax.transData) Out[14]: <class ’ matplotlib.transforms.CompositeGenericTransform’> In [15]: ax.transData.transform((5, 0)) Out[15]: array([ 335.175, 247.) In [16]: ax.transData.transform([(5, 0), (1,2)]) Out[16]: 106 Chapter 12. Transformations Tutorial Matplotlib, Release 0.99.1.1 array([[ 335.175, [ 132.435, 247. 642.2 ,]) You can use the inverted() method to create a transform which will take you from display to data coordinates: In [41]: inv = ax.transData.inverted() In [42]: type(inv) Out[42]: <class ’ matplotlib.transforms.CompositeGenericTransform’> In [43]: inv.transform((335.175, Out[43]: array([ 5., 0.]) 247.)) If your are typing along with this tutorial, the exact values of the display coordinates may diﬀer if you have a diﬀerent window size or dpi setting. Likewise, in the ﬁgure below, the display labeled points are probably not the same as in the ipython session because the documentation ﬁgure size defaults are diﬀerent. Note: If you run the source code in the example above in a GUI backend, you may also ﬁnd that the two arrows for the data and display annotations do not point to exactly the same point. This is because the display point was computed before the ﬁgure was displayed, and the GUI backend may slightly resize the ﬁgure when it is created. The eﬀect is more pronounced if you resize the ﬁgure yourself. This is one good reason why you rarely want to work in display space, but you can connect to the ’on_draw’ Event to update ﬁgure coordinates on ﬁgure draws; see Event handling and picking. 12.1. Data coordinates 107 Matplotlib, Release 0.99.1.1 When you change the x or y limits of your axes, the data limits are updated so the transformation yields a new display point. Note that when we just change the ylim, only the y-display coordinate is altered, and when we change the xlim too, both are altered. More on this later when we talk about the Bbox. In [54]: ax.transData.transform((5, 0)) Out[54]: array([ 335.175, 247.) In [55]: ax.set_ylim(-1,2) Out[55]: (-1, 2) In [56]: ax.transData.transform((5, 0)) Out[56]: array([ 335.175 , 181.13333333]) In [57]: ax.set_xlim(10,20) Out[57]: (10, 20) In [58]: ax.transData.transform((5, 0)) Out[58]: array([-171.675 , 181.13333333]) 12.2 Axes coordinates After the data coordinate system, axes is probably the second most useful coordinate system. Here the point (0,0) is the bottom left of your axes or subplot, (0.5, 0.5) is the center, and (1.0, 1.0) is the top right. You can also refer to points outside the range, so (-0.1, 1.1) is to the left and above your axes. This coordinate system is extremely useful when placing text in your axes, because you often want a text bubble in a ﬁxed, location, eg. the upper left of the axes pane, and have that location remain ﬁxed when you pan or zoom. Here is a simple example that creates four panels and labels them ‘A’, ‘B’, ‘C’, ‘D’ as you often see in journals. import numpy as np import matplotlib.pyplot as plt fig = plt.figure() for i, label in enumerate((’A’, ’B’, ’C’, ’D’)): ax = fig.add_subplot(2,2,i+1) ax.text(0.05, 0.95, label, transform=ax.transAxes, fontsize=16, fontweight=’bold’, va=’top’) plt.show() 108 Chapter 12. Transformations Tutorial Matplotlib, Release 0.99.1.1 You can also make lines or patches in the axes coordinate system, but this is less useful in my experience than using ax.transAxes for placing text. Nonetheless, here is a silly example which plots some random dots in data space, and overlays a semi-transparent Circle centered in the middle of the axes with a radius one quarter of the axes – if your axes does not preserve aspect ratio (see set_aspect()), this will look like an ellipse. Use the pan/zoom tool to move around, or manually change the data xlim and ylim, and you will see the data move, but the circle will remain ﬁxed because it is not in data coordinates and will always remain at the center of the axes. import numpy as np import matplotlib.pyplot as plt import matplotlib.patches as patches fig = plt.figure() ax = fig.add_subplot(111) x, y = 10*np.random.rand(2, 1000) ax.plot(x, y, ’go’) # plot some data in data coordinates circ = patches.Circle((0.5, 0.5), 0.25, transform=ax.transAxes, facecolor=’yellow’, alpha=0.5) ax.add_patch(circ) plt.show() 12.2. Axes coordinates 109 Matplotlib, Release 0.99.1.1 12.3 Blended transformations Drawing in blended coordinate spaces which mix axes with data coordinates is extremely useful, for example to create a horizontal span which highlights some region of the y-data but spans across the x-axis regardless of the data limits, pan or zoom level, etc. In fact these blended lines and spans are so useful, we have built in functions to make them easy to plot (see axhline(), axvline(), axhspan(), axvspan()) but for didactic purposes we will implement the horizontal span here using a blended transformation. This trick only works for separable transformations, like you see in normal Cartesian coordinate systems, but not on inseparable transformations like the PolarTransform. import import import import numpy as np matplotlib.pyplot as plt matplotlib.patches as patches matplotlib.transforms as transforms fig = plt.figure() ax = fig.add_subplot(111) x = np.random.randn(1000) ax.hist(x, 30) ax.set_title(r’$\sigma=1 \/ \dots \/ \sigma=2’, fontsize=16) 110 Chapter 12. Transformations Tutorial Matplotlib, Release 0.99.1.1 # the x coords of this transformation are data, and the # y coord are axes trans = transforms.blended_transform_factory( ax.transData, ax.transAxes) # highlight the 1..2 stddev region with a span. # We want x to be in data coordinates and y to # span from 0..1 in axes coords rect = patches.Rectangle((1,0), width=1, height=1, transform=trans, color=’yellow’, alpha=0.5) ax.add_patch(rect) plt.show() 12.4 Using offset transforms to create a shadow effect One use of transformations is to create a new transformation that is oﬀset from another annotation, eg to place one object shifted a bit relative to another object. Typically you want the shift to be in some physical dimension, like points or inches rather than in data coordinates, so that the shift eﬀect is constant at diﬀerent zoom levels and dpi settings. 12.4. Using offset transforms to create a shadow effect 111 Matplotlib, Release 0.99.1.1 One use for an oﬀset is to create a shadow eﬀect, where you draw one object identical to the ﬁrst just to the right of it, and just below it, adjusting the zorder to make sure the shadow is drawn ﬁrst and then the object it is shadowing above it. The transforms module has a helper transformation ScaledTranslation. It is instantiated with: trans = ScaledTranslation(xt, yt, scale_trans) where xt and yt are the translation oﬀsets, and scale_trans is a transformation which scales xt and yt at transformation time before applying the oﬀsets. A typical use case is to use the ﬁgure fig.dpi_scale_trans transformation for the scale_trans argument, to ﬁrst scale xt and yt speciﬁed in points to display space before doing the ﬁnal oﬀset. The dpi and inches oﬀset is a common-enough use case that we have a special helper function to create it in matplotlib.transforms.offset_copy(), which returns a new transform with an added oﬀset. But in the example below, we’ll create the oﬀset transform ourselves. Note the use of the plus operator in: offset = transforms.ScaledTranslation(dx, dy, fig.dpi_scale_trans) shadow_transform = ax.transData + offset showing that can chain transformations using the addition operator. This code says: ﬁrst apply the data transformation ax.transData and then translate the data by dx and dy points. import import import import numpy as np matplotlib.pyplot as plt matplotlib.patches as patches matplotlib.transforms as transforms fig = plt.figure() ax = fig.add_subplot(111) # make a simple sine wave x = np.arange(0., 2., 0.01) y = np.sin(2*np.pi*x) line, = ax.plot(x, y, lw=3, color=’blue’) # shift the object over 2 points, and down 2 points dx, dy = 2/72., -2/72. offset = transforms.ScaledTranslation(dx, dy, fig.dpi_scale_trans) shadow_transform = ax.transData + offset # now plot the same data with our offset transform; # use the zorder to make sure we are below the line ax.plot(x, y, lw=3, color=’gray’, transform=shadow_transform, zorder=0.5*line.get_zorder()) ax.set_title(’creating a shadow effect with an offset transform’) plt.show() 112 Chapter 12. Transformations Tutorial Matplotlib, Release 0.99.1.1 12.5 The transformation pipeline The ax.transData transform we have been working with in this tutorial is a composite of three diﬀerent transformations that comprise the transformation pipeline from data -> display coordinates. Michael Droettboom implemented the transformations framework, taking care to provide a clean API that segregated the nonlinear projections and scales that happen in polar and logarithmic plots, from the linear aﬃne transformations that happen when you pan and zoom. There is an eﬃciency here, because you can pan and zoom in your axes which aﬀects the aﬃne transformation, but you may not need to compute the potentially expensive nonlinear scales or projections on simple navigation events. It is also possible to multiply aﬃne transformation matrices together, and then apply them to coordinates in one step. This is not true of all possible transformations. Here is how the ax.transData instance is deﬁned in the basic separable axis Axes class: self.transData = self.transScale + (self.transLimits + self.transAxes) We’ve been introduced to the transAxes instance above in Axes coordinates, which maps the (0,0), (1,1) corners of the axes or subplot bounding box to display space, so let’s look at these other two pieces. self.transLimits is the transformation that takes you from data to axes coordinates; i.e., it maps your view xlim and ylim to the unit space of the axes (and transAxes then takes that unit space to display space). We can see this in action here 12.5. The transformation pipeline 113 Matplotlib, Release 0.99.1.1 In [80]: ax = subplot(111) In [81]: ax.set_xlim(0, 10) Out[81]: (0, 10) In [82]: ax.set_ylim(-1,1) Out[82]: (-1, 1) In [84]: ax.transLimits.transform((0,-1)) Out[84]: array([ 0., 0.]) In [85]: ax.transLimits.transform((10,-1)) Out[85]: array([ 1., 0.]) In [86]: ax.transLimits.transform((10,1)) Out[86]: array([ 1., 1.]) In [87]: ax.transLimits.transform((5,0)) Out[87]: array([ 0.5, 0.5]) and we can use this same inverted transformation to go from the unit axes coordinates back to data coordinates. In [90]: inv.transform((0.25, 0.25)) Out[90]: array([ 2.5, -0.5]) The ﬁnal piece is the self.transScale attribute, which is responsible for the optional non-linear scaling of the data, eg. for logarithmic axes. When an Axes is initially setup, this is just set to the identity transform, since the basic matplotlib axes has linear scale, but when you call a logarithmic scaling function like semilogx() or explicitly set the scale to logarithmic with set_xscale(), then the ax.transScale attribute is set to handle the nonlinear projection. The scales transforms are properties of the respective xaxis and yaxis Axis instances. For example, when you call ax.set_xscale(’log’), the xaxis updates its scale to a matplotlib.scale.LogScale instance. For non-separable axes the PolarAxes, there is one more piece to consider, the projection transformation. The transData matplotlib.projections.polar.PolarAxes is similar to that for the typical separable matplotlib Axes, with one additional piece transProjection: self.transData = self.transScale + self.transProjection + \ (self.transProjectionAffine + self.transAxes) transProjection handles the projection from the space, eg. latitude and longitude for map data, or radius and theta for polar data, to a separable Cartesian coordinate system. There are several projection examples in the matplotlib.projections package, and the best way to learn more is to open the source for those packages and see how to make your own, since matplotlib supports extensible axes and projections. Michael Droettboom has provided a nice tutorial example of creating a hammer projection axes; see api example code: custom_projection_example.py. 114 Chapter 12. Transformations Tutorial CHAPTER THIRTEEN PATH TUTORIAL The object underlying all of the matplotlib.patch objects is the Path, which supports the standard set of moveto, lineto, curveto commands to draw simple and compound outlines consisting of line segments and splines. The Path is instantiated with a (N,2) array of (x,y) vertices, and a N-length array of path codes. For example to draw the unit rectangle from (0,0) to (1,1), we could use this code import matplotlib.pyplot as plt from matplotlib.path import Path import matplotlib.patches as patches verts = [ (0., 0.), (0., 1.), (1., 1.), (1., 0.), (0., 0.), # # # # # left, bottom left, top right, top right, bottom ignored codes = [Path.MOVETO, Path.LINETO, Path.LINETO, Path.LINETO, Path.CLOSEPOLY, path = Path(verts, codes) fig = plt.figure() ax = fig.add_subplot(111) patch = patches.PathPatch(path, facecolor=’orange’, lw=2) ax.add_patch(patch) ax.set_xlim(-2,2) ax.set_ylim(-2,2) plt.show() 115 Matplotlib, Release 0.99.1.1 The following path codes are recognized Code STOP Vertices 1 (ignored) 1 1 2 (1 control point, 1 endpoint) CURVE4 3 (2 control points, 1 endpoint) CLOSEPOLY (point itself is 1 ignored) MOVETO LINETO CURVE3 Description A marker for the end of the entire path (currently not required and ignored) Pick up the pen and move to the given vertex. Draw a line from the current position to the given vertex. Draw a quadratic Bézier curve from the current position, with the given control point, to the given end point. Draw a cubic Bézier curve from the current position, with the given control points, to the given end point. Draw a line segment to the start point of the current polyline. 13.1 Bézier example Some of the path components require multiple vertices to specify them: for example CURVE 3 is a bézier curve with one control point and one end point, and CURVE4 has three vertices for the two control points and the end point. The example below shows a CURVE4 Bézier spline – the bézier curve will be contained in the convex hull of the start point, the two control points, and the end point 116 Chapter 13. Path Tutorial Matplotlib, Release 0.99.1.1 import matplotlib.pyplot as plt from matplotlib.path import Path import matplotlib.patches as patches verts = [ (0., 0.), (0.2, 1.), (1., 0.8), (0.8, 0.), # # # # P0 P1 P2 P3 codes = [Path.MOVETO, Path.CURVE4, Path.CURVE4, Path.CURVE4, path = Path(verts, codes) fig = plt.figure() ax = fig.add_subplot(111) patch = patches.PathPatch(path, facecolor=’none’, lw=2) ax.add_patch(patch) xs, ys = zip(*verts) ax.plot(xs, ys, ’x--’, lw=2, color=’black’, ms=10) ax.text(-0.05, -0.05, ’P0’) ax.text(0.15, 1.05, ’P1’) ax.text(1.05, 0.85, ’P2’) ax.text(0.85, -0.05, ’P3’) ax.set_xlim(-0.1, 1.1) ax.set_ylim(-0.1, 1.1) plt.show() 13.1. Bézier example 117 Matplotlib, Release 0.99.1.1 13.2 Compound paths All of the simple patch primitives in matplotlib, Rectangle, Circle, Polygon, etc, are implemented with simple path. Plotting functions like hist() and bar(), which create a number of primitives, eg a bunch of Rectangles, can usually be implemented more eﬃciently using a compound path. The reason bar creates a list of rectangles and not a compound path is largely historical: the Path code is comparatively new and bar predates it. While we could change it now, it would break old code, so here we will cover how to create compound paths, replacing the functionality in bar, in case you need to do so in your own code for eﬃciency reasons, eg you are creating an animated bar plot. We will make the histogram chart by creating a series of rectangles for each histogram bar: the rectangle width is the bin width and the rectangle height is the number of datapoints in that bin. First we’ll create some random normally distributed data and compute the histogram. Because numpy returns the bin edges and not centers, the length of bins is 1 greater than the length of n in the example below: # histogram our data with numpy data = np.random.randn(1000) n, bins = np.histogram(data, 100) We’ll now extract the corners of the rectangles. Each of the left, bottom, etc, arrays below is len(n), where n is the array of counts for each histogram bar: 118 Chapter 13. Path Tutorial Matplotlib, Release 0.99.1.1 # get the corners of the rectangles for the histogram left = np.array(bins[:-1]) right = np.array(bins[1:]) bottom = np.zeros(len(left)) top = bottom + n Now we have to construct our compound path, which will consist of a series of MOVETO, LINETO and CLOSEPOLY for each rectangle. For each rectangle, we need 5 vertices: 1 for the MOVETO, 3 for the LINETO, and 1 for the CLOSEPOLY. As indicated in the table above, the vertex for the closepoly is ignored but we still need it to keep the codes aligned with the vertices: nverts = nrects*(1+3+1) verts = np.zeros((nverts, 2)) codes = np.ones(nverts, int) * path.Path.LINETO codes[0::5] = path.Path.MOVETO codes[4::5] = path.Path.CLOSEPOLY verts[0::5,0] = left verts[0::5,1] = bottom verts[1::5,0] = left verts[1::5,1] = top verts[2::5,0] = right verts[2::5,1] = top verts[3::5,0] = right verts[3::5,1] = bottom All that remains is to create the path, attach it to a PathPatch, and add it to our axes: barpath = path.Path(verts, codes) patch = patches.PathPatch(barpath, facecolor=green’, edgecolor=’yellow’, alpha=0.5) ax.add_patch(patch) Here is the result 13.2. Compound paths 119 Matplotlib, Release 0.99.1.1 120 Chapter 13. Path Tutorial CHAPTER FOURTEEN ANNOTATING AXES Do not proceed unless you already have read text() and annotate()! 14.1 Annotating with Text with Box Let’s start with a simple example. 121 Matplotlib, Release 0.99.1.1 The text() function in the pyplot module (or text method of the Axes class) takes bbox keyword argument, and when given, a box around the text is drawn. bbox_props = dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2) t = ax.text(0, 0, "Direction", ha="center", va="center", rotation=45, size=15, bbox=bbox_props) The patch object associated with the text can be accessed by: bb = t.get_bbox_patch() The return value is an instance of FancyBboxPatch and the patch properties like facecolor, edgewidth, etc. can be accessed and modiﬁed as usual. To change the shape of the box, use set_boxstyle method. bb.set_boxstyle("rarrow", pad=0.6) The arguments are the name of the box style with its attributes as keyword arguments. Currently, following box styles are implemented. Class LArrow RArrow Round Round4 Roundtooth Sawtooth Square 122 Name larrow rarrow round round4 roundtooth sawtooth square Attrs pad=0.3 pad=0.3 pad=0.3,rounding_size=None pad=0.3,rounding_size=None pad=0.3,tooth_size=None pad=0.3,tooth_size=None pad=0.3 Chapter 14. Annotating Axes Matplotlib, Release 0.99.1.1 Note that the attributes arguments can be speciﬁed within the style name with separating comma (this form can be used as “boxstyle” value of bbox argument when initializing the text instance) bb.set_boxstyle("rarrow,pad=0.6") 14.2 Annotating with Arrow The annotate() function in the pyplot module (or annotate method of the Axes class) is used to draw an arrow connecting two points on the plot. ax.annotate("Annotation", xy=(x1, y1), xycoords=’data’, xytext=(x2, y2), textcoords=’offset points’, ) This annotates a point at xy in the given coordinate (xycoords) with the text at xytext given in textcoords. Often, the annotated point is speciﬁed in the data coordinate and the annotating text in oﬀset points. See annotate() for available coordinate systems. 14.2. Annotating with Arrow 123 Matplotlib, Release 0.99.1.1 An arrow connecting two point (xy & xytext) can be optionally drawn by specifying the arrowprops argument. To draw only an arrow, use empty string as the ﬁrst argument. ax.annotate("", xy=(0.2, 0.2), xycoords=’data’, xytext=(0.8, 0.8), textcoords=’data’, arrowprops=dict(arrowstyle="->", connectionstyle="arc3"), ) The arrow drawing takes a few steps. 1. a connecting path between two points are created. This is controlled by connectionstyle key value. 2. If patch object is given (patchA & patchB), the path is clipped to avoid the patch. 3. The path is further shrunk by given amount of pixels (shirnkA & shrinkB) 4. The path is transmuted to arrow patch, which is controlled by the arrowstyle key value. The creation of the connecting path between two points is controlled by connectionstyle key and following styles are available. 124 Chapter 14. Annotating Axes Matplotlib, Release 0.99.1.1 Name angle angle3 arc arc3 bar Attrs angleA=90,angleB=0,rad=0.0 angleA=90,angleB=0 angleA=0,angleB=0,armA=None,armB=None,rad=0.0 rad=0.0 armA=0.0,armB=0.0,fraction=0.3,angle=None Note that “3” in angle3 and arc3 is meant to indicate that the resulting path is a quadratic spline segment (three control points). As will be discussed below, some arrow style option only can be used when the connecting path is a quadratic spline. The behavior of each connection style is (limitedly) demonstrated in the example below. (Warning : The behavior of the bar style is currently not well deﬁned, it may be changed in the future). The connecting path (after clipping and shrinking) is then mutated to an arrow patch, according to the given arrowstyle. 14.2. Annotating with Arrow 125 Matplotlib, Release 0.99.1.1 Name -> -[ -|> <<-> <|<|-|> fancy simple wedge Attrs None head_length=0.4,head_width=0.2 widthB=1.0,lengthB=0.2,angleB=None head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.4,tail_width=0.4 head_length=0.5,head_width=0.5,tail_width=0.2 tail_width=0.3,shrink_factor=0.5 Some arrowstyles only work with connection style that generates a quadratic-spline segment. They are fancy, simple, and wedge. For these arrow styles, you must use “angle3” or “arc3” connection style. If the annotation string is given, the patchA is set to the bbox patch of the text by default. 126 Chapter 14. Annotating Axes Matplotlib, Release 0.99.1.1 As in the text command, a box around the text can be drawn using the bbox argument. By default, the starting point is set to the center of the text extent. This can be adjusted with relpos key value. The values are normalized to the extent of the text. For example, (0,0) means lower-left corner and (1,1) means top-right. 14.2. Annotating with Arrow 127 Matplotlib, Release 0.99.1.1 14.3 Using ConnectorPatch The ConnectorPatch is like an annotation without a text. While the annotate function is recommended in most of situation, the ConnectorPatch is useful when you want to connect points in diﬀerent axes. from matplotlib.patches import ConnectionPatch xy = (0.2, 0.2) con = ConnectionPatch(xyA=xy, xyB=xy, coordsA="data", coordsB="data", axesA=ax1, axesB=ax2) ax2.add_artist(con) The above code connects point xy in data coordinate of ax1 to point xy int data coordinate of ax2. Here is a simple example. 128 Chapter 14. Annotating Axes Matplotlib, Release 0.99.1.1 While the ConnectorPatch instance can be added to any axes, but you may want it to be added to the axes in the latter (?) of the axes drawing order to prevent overlap (?) by other axes. 14.4 Placing Artist at the anchored location of the Axes There are class of artist that can be placed at the anchored location of the Axes. A common example is the legend. This type of artists can be created by using the OﬀsetBox class. A few predeﬁned classes are available in mpl_toolkits.axes_grid.anchored_artists. from mpl_toolkits.axes_grid.anchored_artists import AnchoredText at = AnchoredText("Figure 1a", prop=dict(size=8), frameon=True, loc=2, ) at.patch.set_boxstyle("round,pad=0.,rounding_size=0.2") ax.add_artist(at) The loc keyword has same meaning as in the legend command. A simple application is when the size of the artist (or collection of artists) is known in pixel size during the time of creation. For example, If you want to draw a circle with ﬁxed size of 20 pixel x 20 pixel (radius = 10 pixel), you can utilize AnchoredDrawingArea. The instance is created with a size of the drawing area (in pixel). And user can add arbitrary artist to the drawing area. Note that the extents of the artists that are added to the drawing area has nothing to do with the placement of the drawing area itself. The initial size only matters. from mpl_toolkits.axes_grid.anchored_artists import AnchoredDrawingArea ada = AnchoredDrawingArea(20, 20, 0, 0, loc=1, pad=0., frameon=False) p1 = Circle((10, 10), 10) ada.drawing_area.add_artist(p1) 14.4. Placing Artist at the anchored location of the Axes 129 Matplotlib, Release 0.99.1.1 p2 = Circle((30, 10), 5, fc="r") ada.drawing_area.add_artist(p2) The artists that are added to the drawing area should not have transform set (they will be overridden) and the dimension of those artists are interpreted as a pixel coordinate, i.e., the radius of the circles in above example are 10 pixel and 5 pixel, respectively. Sometimes, you want to your artists scale with data coordinate (or other coordinate than canvas pixel). You can use AnchoredAuxTransformBox class. This is similar to AnchoredDrawingArea except that the extent of the artist is determined during the drawing time respecting the speciﬁed transform. from mpl_toolkits.axes_grid.anchored_artists import AnchoredAuxTransformBox box = AnchoredAuxTransformBox(ax.transData, loc=2) el = Ellipse((0,0), width=0.1, height=0.4, angle=30) # in data coordinates! box.drawing_area.add_artist(el) The ellipse in the above example will have width and height corresponds to 0.1 and 0.4 in data coordinate and will be automatically scaled when the view limits of the axes change. 130 Chapter 14. Annotating Axes Matplotlib, Release 0.99.1.1 As in the legend, the bbox_to_anchor argument can be set. Using the HPacker and VPacker, you can have an arrangement(?) of artist as in the legend (as a matter of fact, this is how the legend is created). Note that unlike the legend, the bbox_transform is set to IdentityTransform by default. 14.4.1 Advanced Topics 14.5 Zoom effect between Axes mpl_toolkits.axes_grid.inset_locator deﬁnes some patch classes useful for interconnect two axes. Understanding the code requires some knowledge of how mpl’s transform works. But, utilizing it will be straight forward. 14.5. Zoom effect between Axes 131 Matplotlib, Release 0.99.1.1 14.6 Deﬁne Custom BoxStyle You can use a custom box style. The value for the boxstyle can be a callable object in following forms.: def __call__(self, x0, y0, width, height, mutation_size, aspect_ratio=1.): """ Given the location and size of the box, return the path of the box around it. - *x0*, *y0*, *width*, *height* : location and size of the box - *mutation_size* : a reference scale for the mutation. - *aspect_ratio* : aspect-ration for the mutation. """ path = ... return path Here is a complete example. 132 Chapter 14. Annotating Axes Matplotlib, Release 0.99.1.1 However, it is recommended that you derive from the matplotlib.patches.BoxStyle._Base as demonstrated below. from matplotlib.path import Path from matplotlib.patches import BoxStyle import matplotlib.pyplot as plt # we may derive from matplotlib.patches.BoxStyle._Base class. # You need to overide transmute method in this case. class MyStyle(BoxStyle._Base): """ A simple box. """ def __init__(self, pad=0.3): """ The arguments need to be floating numbers and need to have default values. *pad* amount of padding """ self.pad = pad super(MyStyle, self).__init__() def transmute(self, x0, y0, width, height, mutation_size): """ Given the location and size of the box, return the path of the box around it. - *x0*, *y0*, *width*, *height* : location and size of the box - *mutation_size* : a reference scale for the mutation. 14.6. Deﬁne Custom BoxStyle 133 Matplotlib, Release 0.99.1.1 Often, the *mutation_size* is the font size of the text. You don’t need to worry about the rotation as it is automatically taken care of. """ # padding pad = mutation_size * self.pad # width and height with padding added. width, height = width + 2.*pad, \ height + 2.*pad, # boundary of the padded box x0, y0 = x0-pad, y0-pad, x1, y1 = x0+width, y0 + height cp = [(x0, y0), (x1, y0), (x1, y1), (x0, y1), (x0-pad, (y0+y1)/2.), (x0, y0), (x0, y0)] com = [Path.MOVETO, Path.LINETO, Path.LINETO, Path.LINETO, Path.LINETO, Path.LINETO, Path.CLOSEPOLY] path = Path(cp, com) return path # register the custom style BoxStyle._style_list["angled"] = MyStyle plt.figure(1, figsize=(3,3)) ax = plt.subplot(111) ax.text(0.5, 0.5, "Test", size=30, va="center", ha="center", rotation=30, bbox=dict(boxstyle="angled,pad=0.5", alpha=0.2)) del BoxStyle._style_list["angled"] plt.show() 134 Chapter 14. Annotating Axes Matplotlib, Release 0.99.1.1 Similarly, you can deﬁne custom ConnectionStyle and custom ArrowStyle. lib/matplotlib/patches.py and check how each style class is deﬁned. 14.6. Deﬁne Custom BoxStyle See the source code of 135 Matplotlib, Release 0.99.1.1 136 Chapter 14. Annotating Axes CHAPTER FIFTEEN TOOLKITS Toolkits are collections of application-speciﬁc functions that extend matplotlib. 15.1 Basemap Plots data on map projections, with continental and political boundaries, see basemap docs. 15.2 GTK Tools mpl_toolkits.gtktools provides some utilities for working with GTK. This toolkit ships with matplotlib, but requires pygtk. 15.3 Excel Tools mpl_toolkits.exceltools provides some utilities for working with Excel. This toolkit ships with matplotlib, but requires pyExcelerator 15.4 Natgrid mpl_toolkits.natgrid is an interface to natgrid C library for gridding irregularly spaced data. This requires a separate installation of the natgrid toolkit from the sourceforge download page. 15.5 mplot3d mpl_toolkits.mplot3d provides some basic 3D plotting (scatter, surf, line, mesh) tools. Not the fastest or feature complete 3D library out there, but ships with matplotlib and thus may be a lighter weight solution for some use cases. See mplot3d for more documentation and examples. 137 Matplotlib, Release 0.99.1.1 15.6 AxesGrid The matplotlib AxesGrid toolkit is a collection of helper classes to ease displaying multiple images in matplotlib. The AxesGrid toolkit is distributed with matplotlib source. See Matplotlib AxesGrid Toolkit for documentations. 138 Chapter 15. Toolkits CHAPTER SIXTEEN SCREENSHOTS Here you will ﬁnd a host of example ﬁgures with the code that generated them 16.1 Simple Plot The most basic plot(), with text labels 139 Matplotlib, Release 0.99.1.1 16.2 Subplot demo Multiple regular axes (numrows by numcolumns) are created with the subplot() command. 16.3 Histograms The hist() command automatically generates histograms and will return the bin counts or probabilities 140 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.4 Path demo You can add aribitrary paths in matplotlib as of release 0.98. See the matplotlib.path. 16.4. Path demo 141 Matplotlib, Release 0.99.1.1 16.5 mplot3d The mplot3d toolkit (see mplot3d tutorial and mplot3d Examples) has support for simple 3d graphs including surface, wireframe, scatter, and bar charts (added in matlpotlib-0.99). Thanks to John Porter, Jonathon Taylor and Reinier Heeres for the mplot3d toolkit. The toolkit is included with all standard matplotlib installs. 142 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.6 Ellipses In support of the Phoenix mission to Mars, which used matplotlib in ground tracking of the spacecraft, Michael Droettboom built on work by Charlie Moad to provide an extremely accurate 8-spline approximation to elliptical arcs (see Arc) in the viewport. This provides a scale free, accurate graph of the arc regardless of zoom level 16.6. Ellipses 143 Matplotlib, Release 0.99.1.1 16.7 Bar charts The bar() command takes error bars as an optional argument. You can also use up and down bars, stacked bars, candlestick bars, etc, ... See bar_stacked.py for another example. You can make horizontal bar charts with the barh() command. 144 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.8 Pie charts The pie() command uses a matlab(TM) compatible syntax to produce pie charts. Optional features include auto-labeling the percentage of area, exploding one or more wedges out from the center of the pie, and a shadow eﬀect. Take a close look at the attached code that produced this ﬁgure; nine lines of code. 16.8. Pie charts 145 Matplotlib, Release 0.99.1.1 16.9 Table demo The table() command will place a text table on the axes 146 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.10 Scatter demo The scatter() command makes a scatter plot with (optional) size and color arguments. This example plots changes in Google stock price from one day to the next with the sizes coding trading volume and the colors coding price change in day i. Here the alpha attribute is used to make semitransparent circle markers with the Agg backend (see What is a backend?) 16.10. Scatter demo 147 Matplotlib, Release 0.99.1.1 16.11 Slider demo Matplotlib has basic GUI widgets that are independent of the graphical user interface you are using, allowing you to write cross GUI ﬁgures and widgets. See matplotlib.widgets and the widget examples <examples/widgets> 148 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.12 Fill demo The fill() command lets you plot ﬁlled polygons. Thanks to Andrew Straw for providing this function 16.12. Fill demo 149 Matplotlib, Release 0.99.1.1 16.13 Date demo You can plot date data with major and minor ticks and custom tick formatters for both the major and minor ticks; see matplotlib.ticker and matplotlib.dates for details and usage. 150 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.14 Financial charts You can make much more sophisticated ﬁnancial plots. This example emulates one of the ChartDirector ﬁnancial plots. Some of the data in the plot, are real ﬁnancial data, some are random traces that I used since the goal was to illustrate plotting techniques, not market analysis! 16.14. Financial charts 151 Matplotlib, Release 0.99.1.1 16.15 Basemap demo Jeﬀ Whitaker provided this example showing how to eﬃciently plot a collection of lines over a colormap image using the Basemap . Many map projections are handled via the proj4 library: cylindrical equidistant, mercator, lambert conformal conic, lambert azimuthal equal area, albers equal area conic and stereographic. See the tutorial entry on the wiki. Exception occurred rendering plot. 16.16 Log plots The semilogx(), semilogy() and loglog() functions generate log scaling on the respective axes. The lower subplot uses a base10 log on the xaxis and a base 4 log on the yaxis. Thanks to Andrew Straw, Darren Dale and Gregory Lielens for contributions to the log scaling infrastructure. 152 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.17 Polar plots The polar() command generates polar plots. 16.17. Polar plots 153 Matplotlib, Release 0.99.1.1 16.18 Legends The legend() command automatically generates ﬁgure legends, with Matlab compatible legend placement commands. Thanks to Charles Twardy for input on the legend command 154 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.19 Mathtext_examples A sampling of the many TeX expressions now supported by matplotlib’s internal mathtext engine. The mathtext module provides TeX style mathematical expressions using freetype2 and the BaKoMa computer modern or STIX fonts. See the matplotlib.mathtext module for additional. matplotlib mathtext is an independent implementation, and does not required TeX or any external packages installed on your computer. See the tutorial at Writing mathematical expressions. 16.19. Mathtext_examples 155 Matplotlib, Release 0.99.1.1 156 Chapter 16. Screenshots Matplotlib, Release 0.99.1.1 16.20 Native TeX rendering Although matplotlib’s internal math rendering engine is quite powerful, sometimes you need TeX, and matplotlib supports external TeX rendering of strings with the usetex option. TEX is Number voltage (mV) 3.0 ∞ ￿ −eiπ n=1 2n ! 2.5 2.0 1.5 1.0 0.0 0.2 0.4 time (s) 0.6 0.8 1.0 16.21 EEG demo You can embed matplotlib into pygtk, wxpython, Tk, FLTK or Qt applications. Here is a screenshot of an eeg viewer called pbrain which is part of the NeuroImaging in Python suite NIPY. Pbrain is written in pygtk using matplotlib. The lower axes uses specgram() to plot the spectrogram of one of the EEG channels. For an example of how to use the navigation toolbar in your applications, see user_interfaces example code: embedding_in_gtk2.py. If you want to use matplotlib in a wx application, see user_interfaces example code: embedding_in_wx2.py. If you want to work with glade, see user_interfaces example code: mpl_with_glade.py. 16.20. Native TeX rendering 157 Matplotlib, Release 0.99.1.1 158 Chapter 16. Screenshots CHAPTER SEVENTEEN WHAT’S NEW IN MATPLOTLIB This page just covers the highlights – for the full story, see the CHANGELOG 17.1 new in matplotlib-0.99 17.1.1 New documentation Jae-Joon Lee has written two new guides Legend guide and Annotating Axes. Michael Sarahan has written Image tutorial. John Hunter has written two new tutorials on working with paths and transformations: Path Tutorial and Transformations Tutorial. 17.1.2 mplot3d Reinier Heeres has ported John Porter’s mplot3d over to the new matplotlib transformations framework, and it is now available as a toolkit mpl_toolkits.mplot3d (which now comes standard with all mpl installs). See mplot3d Examples and mplot3d tutorial 159 Matplotlib, Release 0.99.1.1 17.1.3 axes grid toolkit Jae-Joon Lee has added a new toolkit to ease displaying multiple images in matplotlib, as well as some support for curvilinear grids to support the world coordinate system. The toolkit is included standard with all new mpl installs. See axes_grid Examples and The Matplotlib AxesGrid Toolkit User’s Guide. 160 Chapter 17. What’s new in matplotlib Matplotlib, Release 0.99.1.1 17.1.4 Axis spine placement Andrew Straw has added the ability to place “axis spines” – the lines that denote the data limits – in various arbitrary locations. No longer are your axis lines constrained to be a simple rectangle around the ﬁgure – you can turn on or oﬀ left, bottom, right and top, as well as “detach” the spine to oﬀset it away from the data. See pylab_examples example code: spine_placement_demo.py and matplotlib.spines.Spine. 17.1. new in matplotlib-0.99 161 Matplotlib, Release 0.99.1.1 17.2 new in 0.98.4 It’s been four months since the last matplotlib release, and there are a lot of new features and bug-ﬁxes. Thanks to Charlie Moad for testing and preparing the source release, including binaries for OS X and Windows for python 2.4 and 2.5 (2.6 and 3.0 will not be available until numpy is available on those releases). Thanks to the many developers who contributed to this release, with contributions from Jae-Joon Lee, Michael Droettboom, Ryan May, Eric Firing, Manuel Metz, Jouni K. Seppaenen, Jeﬀ Whitaker, Darren Dale, David Kaplan, Michiel de Hoon and many others who submitted patches 17.2.1 Legend enhancements Jae-Joon has rewritten the legend class, and added support for multiple columns and rows, as well as fancy box drawing. See legend() and matplotlib.legend.Legend. 162 Chapter 17. What’s new in matplotlib Matplotlib, Release 0.99.1.1 17.2.2 Fancy annotations and arrows Jae-Joon has added lot’s of support to annotations for drawing fancy boxes and connectors in annotations. See annotate() and BoxStyle, ArrowStyle, and ConnectionStyle. 17.2. new in 0.98.4 163 Matplotlib, Release 0.99.1.1 17.2.3 Native OS X backend Michiel de Hoon has provided a native Mac OSX backend that is almost completely implemented in C. The backend can therefore use Quartz directly and, depending on the application, can be orders of magnitude faster than the existing backends. In addition, no third-party libraries are needed other than Python and NumPy. The backend is interactive from the usual terminal application on Mac using regular Python. It hasn’t been tested with ipython yet, but in principle it should to work there as well. Set ‘backend : macosx’ in your matplotlibrc ﬁle, or run your script with: > python myfile.py -dmacosx 164 Chapter 17. What’s new in matplotlib Matplotlib, Release 0.99.1.1 17.2.4 psd amplitude scaling Ryan May did a lot of work to rationalize the amplitude scaling of psd() and friends. See pylab_examples example code: psd_demo2.py. and pylab_examples example code: psd_demo3.py. The changes should increase MATLAB™ compatabililty and increase scaling options. 17.2.5 Fill between Added a fill_between() function to make it easier to do shaded region plots in the presence of masked data. You can pass an x array and a ylower and yupper array to ﬁll betweem, and an optional where argument which is a logical mask where you want to do the ﬁlling. 17.2.6 Lots more Here are the 0.98.4 notes from the CHANGELOG: Added mdehoon’s native macosx backend from sf patch 2179017 - JDH Removed the prints in the set_*style commands. pprinted strings instead - JDH Return the list of Some of the changes Michael made to improve the output of the 17.2. new in 0.98.4 165 Matplotlib, Release 0.99.1.1 property tables in the rest docs broke of made difficult to use some of the interactive doc helpers, eg setp and getp. Having all the rest markup in the ipython shell also confused the docstrings. I added a new rc param docstring.harcopy, to format the docstrings differently for hardcopy and other use. Ther ArtistInspector could use a little refactoring now since there is duplication of effort between the rest out put and the non-rest output - JDH Updated spectral methods (psd, csd, etc.) to scale one-sided densities by a factor of 2 and, optionally, scale all densities by the sampling frequency. This gives better MatLab compatibility. -RM Fixed alignment of ticks in colorbars. -MGD drop the deprecated "new" keyword of np.histogram() for numpy 1.2 or later. -JJL Fixed a bug in svg backend that new_figure_manager() ignores keywords arguments such as figsize, etc. -JJL Fixed a bug that the handlelength of the new legend class set too short when numpoints=1 -JJL Added support for data with units (e.g. dates) to Axes.fill_between. -RM Added fancybox keyword to legend. Also applied some changes for better look, including baseline adjustment of the multiline texts so that it is center aligned. -JJL The transmuter classes in the patches.py are reorganized as subclasses of the Style classes. A few more box and arrow styles are added. -JJL Fixed a bug in the new legend class that didn’t allowed a tuple of coordinate vlaues as loc. -JJL Improve checks for external dependencies, using subprocess (instead of deprecated popen*) and distutils (for version checking) - DSD Reimplementaion of the legend which supports baseline alignement, multi-column, and expand mode. - JJL Fixed histogram autoscaling bug when bins or range are given explicitly (fixes Debian bug 503148) - MM Added rcParam axes.unicode_minus which allows plain hypen for minus when False - JDH Added scatterpoints support in Legend. patch by Erik Tollerud JJL 166 Chapter 17. What’s new in matplotlib Matplotlib, Release 0.99.1.1 Fix crash in log ticking. - MGD Added static helper method BrokenHBarCollection.span_where and Axes/pyplot method fill_between. See examples/pylab/fill_between.py - JDH Add x_isdata and y_isdata attributes to Artist instances, and use them to determine whether either or both coordinates are used when updating dataLim. This is used to fix autoscaling problems that had been triggered by axhline, axhspan, axvline, axvspan. - EF Update the psd(), csd(), cohere(), and specgram() methods of Axes and the csd() cohere(), and specgram() functions in mlab to be in sync with the changes to psd(). In fact, under the hood, these all call the same core to do computations. - RM Add ’pad_to’ and ’sides’ parameters to mlab.psd() to allow controlling of zero padding and returning of negative frequency components, respecitively. These are added in a way that does not change the API. - RM Fix handling of c kwarg by scatter; generalize is_string_like to accept numpy and numpy.ma string array scalars. - RM and EF Fix a possible EINTR problem in dviread, which might help when saving pdf files from the qt backend. - JKS Fix bug with zoom to rectangle and twin axes - MGD Added Jae Joon’s fancy arrow, box and annotation enhancements -see examples/pylab_examples/annotation_demo2.py Autoscaling is now supported with shared axes - EF Fixed exception in dviread that happened with Minion - JKS set_xlim, ylim now return a copy of the viewlim array to avoid modify inplace surprises Added image thumbnail generating function matplotlib.image.thumbnail. See examples/misc/image_thumbnail.py - JDH Applied scatleg patch based on ideas and work by Erik Tollerud and Jae-Joon Lee. - MM Fixed bug in pdf backend: if you pass a file object for output instead of a filename, e.g. in a wep app, we now flush the object at the end. - JKS Add path simplification support to paths with gaps. - EF 17.2. new in 0.98.4 167 Matplotlib, Release 0.99.1.1 Fix problem with AFM files that don’t specify the font’s full name or family name. - JKS Added ’scilimits’ kwarg to Axes.ticklabel_format() method, for easy access to the set_powerlimits method of the major ScalarFormatter. - EF Experimental new kwarg borderpad to replace pad in legend, based on suggestion by Jae-Joon Lee. - EF Allow spy to ignore zero values in sparse arrays, based on patch by Tony Yu. Also fixed plot to handle empty data arrays, and fixed handling of markers in figlegend. - EF Introduce drawstyles for lines. Transparently split linestyles like ’steps--’ into drawstyle ’steps’ and linestyle ’--’. Legends always use drawstyle ’default’. - MM Fixed quiver and quiverkey bugs (failure to scale properly when resizing) and added additional methods for determining the arrow angles - EF Fix polar interpolation to handle negative values of theta - MGD Reorganized cbook and mlab methods related to numerical calculations that have little to do with the goals of those two modules into a separate module numerical_methods.py Also, added ability to select points and stop point selection with keyboard in ginput and manual contour labeling code. Finally, fixed contour labeling bug. - DMK Fix backtick in Postscript output. - MGD [ 2089958 ] Path simplification for vector output backends Leverage the simplification code exposed through path_to_polygons to simplify certain well-behaved paths in the vector backends (PDF, PS and SVG). "path.simplify" must be set to True in matplotlibrc for this to work. - MGD Add "filled" kwarg to Path.intersects_path and Path.intersects_bbox. - MGD Changed full arrows slightly to avoid an xpdf rendering problem reported by Friedrich Hagedorn. - JKS Fix conversion of quadratic to cubic Bezier curves in PDF and PS backends. Patch by Jae-Joon Lee. - JKS Added 5-point star marker to plot command q- EF Fix hatching in PS backend - MGD Fix log with base 2 - MGD 168 Chapter 17. What’s new in matplotlib Matplotlib, Release 0.99.1.1 Added support for bilinear interpolation in NonUniformImage; patch by Gregory Lielens. - EF Added support for multiple histograms with data of different length - MM Fix step plots with log scale - MGD Fix masked arrays with markers in non-Agg backends - MGD Fix clip_on kwarg so it actually works correctly - MGD Fix locale problems in SVG backend - MGD fix quiver so masked values are not plotted - JSW improve interactive pan/zoom in qt4 backend on windows - DSD Fix more bugs in NaN/inf handling. In particular, path simplification (which does not handle NaNs or infs) will be turned off automatically when infs or NaNs are present. Also masked arrays are now converted to arrays with NaNs for consistent handling of masks and NaNs - MGD and EF 17.2. new in 0.98.4 169 Matplotlib, Release 0.99.1.1 170 Chapter 17. What’s new in matplotlib CHAPTER EIGHTEEN LICENSE Matplotlib only uses BSD compatible code, and its license is based on the PSF license. See the Open Source Initiative licenses page for details on individual licenses. Non-BSD compatible licenses (eg LGPL) are acceptable in matplotlib Toolkits. For a discussion of the motivations behind the licencing choice, see Licenses. 18.1 License agreement for matplotlib 0.99.1.1 1. This LICENSE AGREEMENT is between John D. Hunter (“JDH”), and the Individual or Organization (“Licensee”) accessing and otherwise using matplotlib software in source or binary form and its associated documentation. 2. Subject to the terms and conditions of this License Agreement, JDH hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use matplotlib 0.99.1.1 alone or in any derivative version, provided, however, that JDH’s License Agreement and JDH’s notice of copyright, i.e., “Copyright (c) 20022009 John D. Hunter; All Rights Reserved” are retained in matplotlib 0.99.1.1 alone or in any derivative version prepared by Licensee. 3. In the event Licensee prepares a derivative work that is based on or incorporates matplotlib 0.99.1.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to matplotlib 0.99.1.1. 4. JDH is making matplotlib 0.99.1.1 available to Licensee on an “AS IS” basis. JDH MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, JDH MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF MATPLOTLIB 0.99.1.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. 5. JDH SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF MATPLOTLIB 0.99.1.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING MATPLOTLIB 0.99.1.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. 6. This License Agreement will automatically terminate upon a material breach of its terms and conditions. 171 Matplotlib, Release 0.99.1.1 7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between JDH and Licensee. This License Agreement does not grant permission to use JDH trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party. 8. By copying, installing or otherwise using matplotlib 0.99.1.1, Licensee agrees to be bound by the terms and conditions of this License Agreement. 172 Chapter 18. License CHAPTER NINETEEN CREDITS matplotlib was written by John Hunter and is now developed and maintained by a number of active developers. Special thanks to those who have made valuable contributions (roughly in order of ﬁrst contribution by date) Jeremy O’Donoghue wrote the wx backend Andrew Straw provided much of the log scaling architecture, the ﬁll command, PIL support for imshow, and provided many examples. He also wrote the support for dropped axis spines and the buildbot unit testing infrastructure which triggers the JPL/James Evans platform speciﬁc builds and regression test image comparisons from svn matplotlib across platforms on svn commits. Charles Twardy provided the impetus code for the legend class and has made countless bug reports and suggestions for improvement. Gary Ruben made many enhancements to errorbar to support x and y errorbar plots, and added a number of new marker types to plot. John Gill wrote the table class and examples, helped with support for auto-legend placement, and added support for legending scatter plots. David Moore wrote the paint backend (no longer used) Todd Miller supported by STSCI contributed the TkAgg backend and the numerix module, which allows matplotlib to work with either numeric or numarray. He also ported image support to the postscript backend, with much pain and suﬀering. Paul Barrett supported by STSCI overhauled font management to provide an improved, free-standing, platform independent font manager with a WC3 compliant font ﬁnder and cache mechanism and ported truetype and mathtext to PS. Perry Greenﬁeld supported by STSCI overhauled and modernized the goals and priorities page, implemented an improved colormap framework, and has provided many suggestions and a lot of insight to the overall design and organization of matplotlib. Jared Wahlstrand wrote the initial SVG backend. Steve Chaplin served as the GTK maintainer and wrote the Cairo and GTKCairo backends. Jim Benson provided the patch to handle vertical mathttext. 173 Matplotlib, Release 0.99.1.1 Gregory Lielens provided the FltkAgg backend and several patches for the frontend, including contributions to toolbar2, and support for log ticking with alternate bases and major and minor log ticking. Darren Dale did the work to do mathtext exponential labeling for log plots, added improved support for scalar formatting, and did the lions share of the psfrag LaTeX support for postscript. He has made substantial contributions to extending and maintaining the PS and Qt backends, and wrote the site.cfg and matplotlib.conf build and runtime conﬁguration support. He setup the infrastructure for the sphinx documentation that powers the mpl docs. Paul Mcguire provided the pyparsing module on which mathtext relies, and made a number of optimizations to the matplotlib mathtext grammar. Fernando Perez has provided numerous bug reports and patches for cleaning up backend imports and expanding pylab functionality, and provided matplotlib support in the pylab mode for ipython. He also provided the matshow() command, and wrote TConﬁg, which is the basis for the experimental traited mpl conﬁguration. Andrew Dalke of Dalke Scientiﬁc Software contributed the strftime formatting code to handle years earlier than 1900. Jochen Voss served as PS backend maintainer and has contributed several bugﬁxes. Nadia Dencheva supported by STSCI provided the contouring and contour labeling code. Baptiste Carvello provided the key ideas in a patch for proper shared axes support that underlies ganged plots and multiscale plots. Jeﬀrey Whitaker at NOAA wrote the Basemap tookit Sigve Tjoraand, Ted Drain, James Evans and colleagues at the JPL collaborated on the QtAgg backend and sponsored development of a number of features including custom unit types, datetime support, scale free ellipses, broken bar plots and more. The JPL team wrote the unit testing image comparison infrastructure for regression test image comparisons. James Amundson did the initial work porting the qt backend to qt4 Eric Firing has contributed signiﬁcantly to contouring, masked array, pcolor, image and quiver support, in addition to ongoing support and enhancements in performance, design and code quality in most aspects of matplotlib. Daishi Harada added support for “Dashed Text”. See dashpointlabel.py and TextWithDash. Nicolas Young added support for byte images to imshow, which are more eﬃcient in CPU and memory, and added support for irregularly sampled images. The brainvisa Orsay team and Fernando Perez added Qt support to ipython in pylab mode. Charlie Moad contributed work to matplotlib’s Cocoa support and has done a lot of work on the OSX and win32 binary releases. Jouni K. Seppaenen wrote the PDF backend and contributed numerous ﬁxes to the code, to tex support and to the get_sample_data handler 174 Chapter 19. Credits Matplotlib, Release 0.99.1.1 Paul Kienzle improved the picking infrastruture for interactive plots, and with Alex Mont contributed fast rendering code for quadrilateral meshes. Michael Droettboom supported by STSCI wrote the enhanced mathtext support, implementing Knuth’s box layout algorithms, saving to ﬁle-like objects across backends, and is responsible for numerous bug-ﬁxes, much better font and unicode support, and feature and performance enhancements across the matplotlib code base. He also rewrote the transformation infrastructure to support custom projections and scales. John Porter, Jonathon Taylor and Reinier Heeres John Porter wrote the mplot3d module for basic 3D plotting in matplotlib, and Jonathon Taylor and Reinier Heeres ported it to the refactored transform trunk. Jae-Joon Lee implemented fancy arrows and boxes, rewrote the legend support to handle multiple columns and fancy text boxes, wrote the axes grid toolkit, and has made numerous contributions to the code and documentation 175 Matplotlib, Release 0.99.1.1 176 Chapter 19. Credits Part II The Matplotlib FAQ 177 CHAPTER TWENTY INSTALLATION FAQ Contents • Installation FAQ – Report a compilation problem – matplotlib compiled ﬁne, but nothing shows up with plot – Cleanly rebuild and reinstall everything * Easy Install * Windows installer * Source install – Install from svn – Install from git – Backends * What is a backend? * Compile matplotlib with PyGTK-2.4 – OS-X questions * Which python for OS X? * Installing OSX binaries * easy_install from egg * Building and installing from source on OSX with EPD – Windows questions * Binary installers for windows 20.1 Report a compilation problem See Report a problem. 20.2 matplotlib compiled ﬁne, but nothing shows up with plot The ﬁrst thing to try is a clean install and see if that helps. If not, the best way to test your install is by running a script, rather than working interactively from a python shell or an integrated development environment such as IDLE which add additional complexities. Open up a UNIX shell or a DOS command 179 Matplotlib, Release 0.99.1.1 prompt and cd into a directory containing a minimal example in a ﬁle. Something like simple_plot.py, or for example: from pylab import * plot([1,2,3]) show() and run it with: python simple_plot.py --verbose-helpful This will give you additional information about which backends matplotlib is loading, version information, and more. At this point you might want to make sure you understand matplotlib’s conﬁguration process, governed by the matplotlibrc conﬁguration ﬁle which contains instructions within and the concept of the matplotlib backend. If you are still having trouble, see Report a problem. 20.3 Cleanly rebuild and reinstall everything The steps depend on your platform and installation method. 20.3.1 Easy Install 1. Delete the caches from your .matplotlib conﬁguration directory. 2. Run: easy_install -m PackageName 3. Delete any .egg ﬁles or directories from your installation directory. 20.3.2 Windows installer 1. Delete the caches from your .matplotlib conﬁguration directory. 2. Use Start → Control Panel to start the Add and Remove Software utility. 20.3.3 Source install Unfortunately: python setup.py clean does not properly clean the build directory, and does nothing to the install directory. To cleanly rebuild: 1. Delete the caches from your .matplotlib conﬁguration directory. 180 Chapter 20. Installation FAQ Matplotlib, Release 0.99.1.1 2. Delete the build directory in the source tree 3. Delete any matplotlib directories or eggs from your installation directory <locating-matplotlibinstall> 20.4 Install from svn Checking out the main source: svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/matplotlib matplotlib and build and install as usual with: > cd matplotlib > python setup.py install If you want to be able to follow the development branch as it changes just replace the last step with (Make sure you have setuptools installed): > python setupegg.py develop This creates links in the right places and installs the command line script to the appropriate places. Then, if you want to update your matplotlib at any time, just do: > svn update When you run svn update, if the output shows that only Python ﬁles have been updated, you are all set. If C ﬁles have changed, you need to run the python setupegg develop command again to compile them. There is more information on using Subversion in the developer docs. 20.5 Install from git See Using git. 20.6 Backends 20.6.1 What is a backend? A lot of documentation on the website and in the mailing lists refers to the “backend” and many new users are confused by this term. matplotlib targets many diﬀerent use cases and output formats. Some people use matplotlib interactively from the python shell and have plotting windows pop up when they type commands. Some people embed matplotlib into graphical user interfaces like wxpython or pygtk to build rich applications. Others use matplotlib in batch scripts to generate postscript images from some numerical simulations, and still others in web application servers to dynamically serve up graphs. 20.4. Install from svn 181 Matplotlib, Release 0.99.1.1 To support all of these use cases, matplotlib can target diﬀerent outputs, and each of these capabililities is called a backend (the “frontend” is the user facing code, ie the plotting code, whereas the “backend” does all the dirty work behind the scenes to make the ﬁgure. There are two types of backends: user interface backends (for use in pygtk, wxpython, tkinter, qt or ﬂtk) and hardcopy backends to make image ﬁles (PNG, SVG, PDF, PS). There are a two primary ways to conﬁgure your backend. One is to set the backend parameter in you matplotlibrc ﬁle (see Customizing matplotlib): backend : WXAgg # use wxpython with antigrain (agg) rendering The other is to use the matplotlib use() directive: import matplotlib matplotlib.use(’PS’) # generate postscript output by default If you use the use directive, this must be done before importing matplotlib.pyplot or matplotlib.pylab. If you are unsure what to do, and just want to get cranking, just set your backend to TkAgg. This will do the right thing for 95% of the users. It gives you the option of running your scripts in batch or working interactively from the python shell, with the least amount of hassles, and is smart enough to do the right thing when you ask for postscript, or pdf, or other image formats. If however, you want to write graphical user interfaces, or a web application server (Matplotlib in a web application server), or need a better understanding of what is going on, read on. To make things a little more customizable for graphical user interfaces, matplotlib separates the concept of the renderer (the thing that actually does the drawing) from the canvas (the place where the drawing goes). The canonical renderer for user interfaces is Agg which uses the antigrain C++ library to make a raster (pixel) image of the ﬁgure. All of the user interfaces can be used with agg rendering, eg WXAgg, GTKAgg, QTAgg, TkAgg. In addition, some of the user interfaces support other rendering engines. For example, with GTK, you can also select GDK rendering (backend GTK) or Cairo rendering (backend GTKCairo). For the rendering engines, one can also distinguish between vector or raster renderers. Vector graphics languages issue drawing commands like “draw a line from this point to this point” and hence are scale free, and raster backends generate a pixel represenation of the line whose accuracy depends on a DPI setting. Here is a summary of the matplotlib renderers (there is an eponymous backed for each): Renderer AGG PS PDF SVG Cairo GDK Filetypes png ps eps pdf svg png ps pdf svg ... png jpg tiﬀ ... Description raster graphics – high quality images using the Anti-Grain Geometry engine vector graphics – Postscript output vector graphics – Portable Document Format vector graphics – Scalable Vector Graphics vector graphics – Cairo graphics raster graphics – the Gimp Drawing Kit And here are the user interfaces and renderer combinations supported: 182 Chapter 20. Installation FAQ Matplotlib, Release 0.99.1.1 Backend GTKAgg GTK GTKCairo WXAgg WX TkAgg QtAgg Qt4Agg FLTKAgg Description Agg rendering to a GTK canvas (requires PyGTK) GDK rendering to a GTK canvas (not recommended) (requires PyGTK) Cairo rendering to a GTK Canvas (requires PyGTK) Agg rendering to to a wxWidgets canvas (requires wxPython) Native wxWidgets drawing to a wxWidgets Canvas (not recommended) (requires wxPython) Agg rendering to a Tk canvas (requires TkInter) Agg rendering to a Qt canvas (requires PyQt) Agg rendering to a Qt4 canvas (requires PyQt4) Agg rendering to a FLTK canvas (requires pyFLTK) 20.6.2 Compile matplotlib with PyGTK-2.4 There is a bug in PyGTK-2.4. You need to edit pygobject.h to add the G_BEGIN_DECLS and G_END_DECLS macros, and rename typename parameter to typename_: + const char *typename, const char *typename_, 20.7 OS-X questions 20.7.1 Which python for OS X? Apple ships with its own python, many users have had trouble with it so there are alternatives. If it is feasible for you, we recommend the enthought python distribution EPD for OS X (which comes with matplotlib and much more) or the MacPython or the oﬃcial OS X version from python.org. 20.7.2 Installing OSX binaries If you want to install matplotlib from one of the binary installers we build, you have two choices: a dmg installer, which is a typical Installer.app, or an binary OSX egg, which you can install via setuptools easy_install. The mkpg installer will have a “dmg” extension, and will have a name like matplotlib-0.99.0-py2.5-macosx10.5.dmg depending on the python, matplotlib, and OSX versions. Save this ﬁle and double click it, which will open up a folder with a ﬁle in it that has the mpkg extension. Double click this to run the Installer.app, which will prompt you for a password if you need system wide installation privileges, and install to a directory like /Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages, again depedending on your python version. This directory should be in your python path, so you can test your installation with: > python -c ’import matplotlib; print matplotlib.__version__, matplotlib.__file__’ If you get an error like: 20.7. OS-X questions 183 Matplotlib, Release 0.99.1.1 Traceback (most recent call last): File "<string>", line 1, in <module> ImportError: No module named matplotlib then you will need to set your PYTHONPATH, eg: export PYTHONPATH=/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/site-packages:PYTHONP See also Environment Variables. If you are upgrading your matplotlib using the dmg installer over an Enthought Python Distribution, you may get an error like “You must use a framework install of python”. EPD puts their python in a directory like :ﬁle://Library/Frameworks/Python.framework/Versions/4.3.0 where 4.3.0 is an EPD version number. The mpl installer needs the python version number, so you need to create a symlink pointing your python version to the EPS version before installing matplotlib. For example, for python veersion 2.5 and EPD version 4.3.0: > cd /Library/Frameworks/Python.framework/Versions > ln -s 4.3.0 2.5 20.7.3 easy_install from egg You can also us the eggs we build for OSX (see the installation instructions for easy_install if you do not have it on your system already). You can try: > easy_install matplotlib which should grab the latest egg from the sourceforge site, but the naming conventions for OSX eggs appear to be broken (see below) so there is no guarantee the right egg will be found. We recommend you download the latest egg from our download site directly to your harddrive, and manually install it with > easy_install –install-dir=~/dev/lib/python2.5/site-packages/ matplotlib-0.99.0.rc1-py2.5macosx-10.5-i386.egg Some users have reported problems with the egg for 0.98 from the matplotlib download site, with easy_install, getting an error: > easy_install ./matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg Processing matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg removing ’/Library/Python/2.5/site-packages/matplotlib-0.98.0-py2.5...snip... Reading http://matplotlib.sourceforge.net Reading http://cheeseshop.python.org/pypi/matplotlib/0.91.3 No local packages or download links found for matplotlib==0.98.0 error: Could not find suitable distribution for Requirement.parse(’matplotlib==0.98.0’) 184 Chapter 20. Installation FAQ Matplotlib, Release 0.99.1.1 If you rename matplotlib-0.98.0-py2.5-macosx-10.3-fat.egg to matplotlib-0.98.0-py2.5.egg, easy_install will install it from the disk. Many Mac OS X eggs with cruft at the end of the ﬁlename, which prevents their installation through easy_install. Renaming is all it takes to install them; still, it’s annoying. 20.7.4 Building and installing from source on OSX with EPD If you have the EPD installed (Which python for OS X?), it might turn out to be rather tricky to install a new version of matplotlib from source on the Mac OS 10.5 . Here’s a procedure that seems to work, at least sometimes: 1. Remove the ~/.matplotlib folder (“rm -rf ~/.matplotlib”). 1. Edit the ﬁle (make a backup before you start, just in case): /Library/Frameworks/Python.framework/Versions/Current/lib/python2.5/config/Makefile, removing all occurrences of the string -arch ppc, changing the line MACOSX_DEPLOYMENT_TARGET=10.3 to MACOSX_DEPLOYMENT_TARGET=10.5 and changing the occurrences of MacOSX10.4u.sdk into MacOSX10.5.sdk 2. In /Library/Frameworks/Python.framework/Versions/Current/lib/pythonX.Y/site-packages/easy-inst (where X.Y is the version of Python you are building against) Comment out the line containing the name of the directory in which the previous version of MPL was installed (Looks something like ./matplotlib-0.98.5.2n2-py2.5-macosx-10.3-fat.egg). 1. Save the following as a shell script , for example ./install-matplotlib-epd-osx.sh NAME=matplotlib VERSION=0_99 PREFIX=$HOME #branch="release" branch="trunk" if [$branch = "trunk" ] then echo getting the trunk svn co https://matplotlib.svn.sourceforge.net/svnroot/$NAME/trunk/$NAME $NAME cd$NAME fi if [ $branch = "release" ] then echo getting the maintenance branch svn co https://matplotlib.svn.sf.net/svnroot/matplotlib/branches/v${VERSION}_maint $NAME$VERSIO cd $NAME$VERSION fi export CFLAGS="-Os -arch i386" export LDFLAGS="-Os -arch i386" export PKG_CONFIG_PATH="/usr/x11/lib/pkgconfig" export ARCHFLAGS="-arch i386" python setup.py build python setup.py install #--prefix=PREFIX #Use this if you don’t want it installed into your defau cd .. 20.7. OS-X questions 185 Matplotlib, Release 0.99.1.1 Run this script (for example sh ./install-matplotlib-epd-osx.sh) in the directory in which you want the source code to be placed, or simply type the commands in the terminal command line. This script sets some local variable (CFLAGS, LDFLAGS, PKG_CONFIG_PATH, ARCHFLAGS), removes previous installations, checks out the source from svn, builds and installs it. The backend seems to be set to MacOSX. 20.8 Windows questions 20.8.1 Binary installers for windows If you have already installed python, you can use one of the matplotlib binary installers for windows – you can get these from the sourceforge download site. Choose the ﬁles that match your version of python (eg py2.5 if you installed Python 2.5) which have the exe extension. If you haven’t already installed python, you can get the oﬃcial version from the python web site. There are also two packaged distributions of python that come preloaded with matplotlib and many other tools like ipython, numpy, scipy, vtk and user interface toolkits. These packages are quite large because they come with so much, but you get everything with a single click installer. • the enthought python distribution EPD • python (x, y) 186 Chapter 20. Installation FAQ CHAPTER TWENTYONE USAGE Contents • Usage – Matplotlib, pylab, and pyplot: how are they related? 21.1 Matplotlib, pylab, and pyplot: how are they related? Matplotlib is the whole package; pylab is a module in matplotlib that gets installed alongside matplotlib; and matplotlib.pyplot is a module in matplotlib. Pyplot provides a Matlab-style state-machine interface to the underlying object-oriented plotting library in matplotlib. Pylab combines the pyplot functionality (for plotting) with the numpy functionality (for mathematics and for working with arrays) in a single namespace, making that namespace (or environment) even more Matlablike. This is what you get if you use the ipython shell with the -pylab option, which imports everything from pylab and makes plotting fully interactive. We have been gradually converting the matplotlib examples from pure Matlab-style, using “from pylab import *”, to a preferred style in which pyplot is used for some convenience functions, either pyplot or the object-oriented style is used for the remainder of the plotting code, and numpy is used explicitly for numeric array operations. In this preferred style, the imports at the top are: import matplotlib.pyplot as plt import numpy as np Then one calls, for example, np.arange, np.zeros, np.pi, plt.ﬁgure, plt.plot, plt.show, etc. Example, pure Matlab-style: from pylab import * x = arange(0, 10, 0.2) y = sin(x) 187 Matplotlib, Release 0.99.1.1 plot(x, y) show() Now in preferred style, but still using pyplot interface: import matplotlib.pyplot as plt import numpy as np x = np.arange(0, 10, 0.2) y = np.sin(x) plt.plot(x, y) plt.show() And using pyplot convenience functions, but object-orientation for the rest: import matplotlib.pyplot as plt import numpy as np x = np.arange(0, 10, 0.2) y = np.sin(x) fig = plt.figure() ax = fig.add_subplot(111) ax.plot(x, y) plt.show() So, why do all the extra typing required as one moves away from the pure matlab-style? For very simple things like this example, the only advantage is educational: the wordier styles are more explicit, more clear as to where things come from and what is going on. For more complicated applications, the explicitness and clarity become increasingly valuable, and the richer and more complete object-oriented interface will likely make the program easier to write and maintain. 188 Chapter 21. Usage CHAPTER TWENTYTWO HOWTO Contents • Howto – Plotting: howto * Find all objects in ﬁgure of a certain type * Save transparent ﬁgures * Move the edge of an axes to make room for tick labels * Automatically make room for tick labels * Conﬁgure the tick linewidths * Align my ylabels across multiple subplots * Skip dates where there is no data * Test whether a point is inside a polygon * Control the depth of plot elements * Make the aspect ratio for plots equal * Make a movie * Multiple y-axis scales * Generate images without having a window popup * Use show() – Contributing: howto * Submit a patch * Contribute to matplotlib documentation – Matplotlib in a web application server * matplotlib with apache * matplotlib with django * matplotlib with zope * Clickable images for HTML – Search examples 189 Matplotlib, Release 0.99.1.1 22.1 Plotting: howto 22.1.1 Find all objects in ﬁgure of a certain type Every matplotlib artist (see Artist tutorial) has a method called findobj() that can be used to recursively search the artist for any artists it may contain that meet some criteria (eg match all Line2D instances or match some arbitrary ﬁlter function). For example, the following snippet ﬁnds every object in the ﬁgure which has a set_color property and makes the object blue: def myfunc(x): return hasattr(x, ’set_color’) for o in fig.findobj(myfunc): o.set_color(’blue’) You can also ﬁlter on class instances: import matplotlib.text as text for o in fig.findobj(text.Text): o.set_fontstyle(’italic’) 22.1.2 Save transparent ﬁgures The savefig() command has a keyword argument transparent which, if True, will make the ﬁgure and axes backgrounds transparent when saving, but will not aﬀect the displayed image on the screen. If you need ﬁner grained control, eg you do not want full transparency or you to aﬀect the screen displayed version as well, you can set the alpha properties directly. The ﬁgure has a matplotlib.patches.Rectangle instance called patch and the axes has a Rectangle instance called patch. You can set any property on them directly (facecolor, edgecolor, linewidth, linestyle, alpha). Eg: fig = plt.figure() fig.patch.set_alpha(0.5) ax = fig.add_subplot(111) ax.patch.set_alpha(0.5) If you need all the ﬁgure elements to be transparent, there is currently no global alpha setting, but you can set the alpha channel on individual elements, eg: ax.plot(x, y, alpha=0.5) ax.set_xlabel(’volts’, alpha=0.5) 22.1.3 Move the edge of an axes to make room for tick labels For subplots, you can control the default spacing on the left, right, bottom, and top as well as the horizontal and vertical spacing between multiple rows and columns using the 190 Chapter 22. Howto Matplotlib, Release 0.99.1.1 matplotlib.figure.Figure.subplots_adjust() method (in pyplot it is subplots_adjust()). For example, to move the bottom of the subplots up to make room for some rotated x tick labels: fig = plt.figure() fig.subplots_adjust(bottom=0.2) ax = fig.add_subplot(111) You can control the defaults for these parameters in your matplotlibrc ﬁle; see Customizing matplotlib. For example, to make the above setting permanent, you would set: figure.subplot.bottom : 0.2 # the bottom of the subplots of the figure The other parameters you can conﬁgure are, with their defaults left = 0.125 the left side of the subplots of the ﬁgure right = 0.9 the right side of the subplots of the ﬁgure bottom = 0.1 the bottom of the subplots of the ﬁgure top = 0.9 the top of the subplots of the ﬁgure wspace = 0.2 the amount of width reserved for blank space between subplots hspace = 0.2 the amount of height reserved for white space between subplots If you want additional control, you can create an Axes using the axes() command (or equivalently the ﬁgure matplotlib.figure.Figure.add_axes() method), which allows you to specify the location explicitly: ax = fig.add_axes([left, bottom, width, height]) where all values are in fractional (0 to 1) coordinates. See axes_demo.py for an example of placing axes manually. 22.1.4 Automatically make room for tick labels In most use cases, it is enough to simpy change the subplots adjust parameters as described in Move the edge of an axes to make room for tick labels. But in some cases, you don’t know ahead of time what your tick labels will be, or how large they will be (data and labels outside your control may be being fed into your graphing application), and you may need to automatically adjust your subplot parameters based on the size of the tick labels. Any matplotlib.text.Text instance can report its extent in window coordinates (a negative x coordinate is outside the window), but there is a rub. The matplotlib.backend_bases.RendererBase instance, which is used to calculate the text size, is not known until the ﬁgure is drawn (matplotlib.figure.Figure.draw()). After the window is drawn and the text instance knows its renderer, you can call matplotlib.text.Text.get_window_extent(). One way to solve this chicken and egg problem is to wait until the ﬁgure is draw by connecting (matplotlib.backend_bases.FigureCanvasBase.mpl_connect()) to the “on_draw” signal (DrawEvent) and get the window extent there, and then do something with it, eg move the left of the canvas over; see Event handling and picking. 22.1. Plotting: howto 191 Matplotlib, Release 0.99.1.1 Here is that gets a bounding box in relative ﬁgure coordinates (0..1) of each of the labels and uses it to move the left of the subplots over so that the tick labels ﬁt in the ﬁgure import matplotlib.pyplot as plt import matplotlib.transforms as mtransforms fig = plt.figure() ax = fig.add_subplot(111) ax.plot(range(10)) ax.set_yticks((2,5,7)) labels = ax.set_yticklabels((’really, really, really’, ’long’, ’labels’)) def on_draw(event): bboxes = for label in labels: bbox = label.get_window_extent() # the figure transform goes from relative coords->pixels and we # want the inverse of that bboxi = bbox.inverse_transformed(fig.transFigure) bboxes.append(bboxi) # this is the bbox that bounds all the bboxes, again in relative # figure coords bbox = mtransforms.Bbox.union(bboxes) if fig.subplotpars.left < bbox.width: # we need to move it over fig.subplots_adjust(left=1.1*bbox.width) # pad a little fig.canvas.draw() return False fig.canvas.mpl_connect(’draw_event’, on_draw) plt.show() 192 Chapter 22. Howto Matplotlib, Release 0.99.1.1 22.1.5 Conﬁgure the tick linewidths In matplotlib, the ticks are markers. All Line2D objects support a line (solid, dashed, etc) and a marker (circle, square, tick). The tick linewidth is controlled by the “markeredgewidth” property: import matplotlib.pyplot as plt fig = plt.figure() ax = fig.add_subplot(111) ax.plot(range(10)) for line in ax.get_xticklines() + ax.get_yticklines(): line.set_markersize(10) plt.show() The other properties that control the tick marker, and all markers, are markerfacecolor, markeredgecolor, markeredgewidth, markersize. For more information on conﬁguring ticks, see Axis containers and Tick containers. 22.1. Plotting: howto 193 Matplotlib, Release 0.99.1.1 22.1.6 Align my ylabels across multiple subplots If you have multiple subplots over one another, and the y data have diﬀerent scales, you can often get ylabels that do not align vertically across the multiple subplots, which can be unattractive. By default, matplotlib positions the x location of the ylabel so that it does not overlap any of the y ticks. You can override this default behavior by specifying the coordinates of the label. The example below shows the default behavior in the left subplots, and the manual setting in the right subplots. import numpy as np import matplotlib.pyplot as plt box = dict(facecolor=’yellow’, pad=5, alpha=0.2) fig = plt.figure() fig.subplots_adjust(left=0.2, wspace=0.6) ax1 = fig.add_subplot(221) ax1.plot(2000*np.random.rand(10)) ax1.set_title(’ylabels not aligned) ax1.set_ylabel(’misaligned 1’, bbox=box) ax1.set_ylim(0, 2000) ax3 = fig.add_subplot(223) ax3.set_ylabel(’misaligned 2’,bbox=box) ax3.plot(np.random.rand(10)) labelx = -0.3 # axes coords ax2 = fig.add_subplot(222) ax2.set_title(’ylabels aligned’) ax2.plot(2000*np.random.rand(10)) ax2.set_ylabel(’aligned 1’, bbox=box) ax2.yaxis.set_label_coords(labelx, 0.5) ax2.set_ylim(0, 2000) ax4 = fig.add_subplot(224) ax4.plot(np.random.rand(10)) ax4.set_ylabel(’aligned 2’, bbox=box) ax4.yaxis.set_label_coords(labelx, 0.5) plt.show() 194 Chapter 22. Howto Matplotlib, Release 0.99.1.1 22.1.7 Skip dates where there is no data When plotting time series, eg ﬁnancial time series, one often wants to leave out days on which there is no data, eg weekends. By passing in dates on the x-xaxis, you get large horizontal gaps on periods when there is not data. The solution is to pass in some proxy x-data, eg evenly sampled indicies, and then use a custom formatter to format these as dates. The example below shows how to use an ‘index formatter’ to achieve the desired plot: import import import import numpy as np matplotlib.pyplot as plt matplotlib.mlab as mlab matplotlib.ticker as ticker r = mlab.csv2rec(’../data/aapl.csv’) r.sort() r = r[-30:] # get the last 30 days N = len(r) ind = np.arange(N) # the evenly spaced plot indices def format_date(x, pos=None): thisind = np.clip(int(x+0.5), 0, N-1) return r.date[thisind].strftime(’%Y-%m-%d ’) 22.1. Plotting: howto 195 Matplotlib, Release 0.99.1.1 fig = plt.figure() ax = fig.add_subplot(111) ax.plot(ind, r.adj_close, ’o-’) ax.xaxis.set_major_formatter(ticker.FuncFormatter(format_date)) fig.autofmt_xdate() plt.show() 22.1.8 Test whether a point is inside a polygon The matplotlib.nxutils provides two high performance methods: for a single point use pnpoly() and for an array of points use points_inside_poly(). For a discussion of the implementation see pnpoly. In [25]: import numpy as np In [26]: import matplotlib.nxutils as nx In [27]: verts = np.array([ [0,0], [0, 1], [1, 1], [1,0]], float) In [28]: nx.pnpoly( 0.5, 0.5, verts) Out[28]: 1 In [29]: nx.pnpoly( 0.5, 1.5, verts) Out[29]: 0 In [30]: points = np.random.rand(10,2)*2 In [31]: Out[31]: array([[ [ [ [ [ [ [ [ [ [ points 1.03597426, 1.94061056, 1.08593748, 0.9255139 , 1.54564936, 1.71514397, 1.19133536, 0.40939549, 1.8944715 , 0.03128518, 0.61029911], 0.65233947], 1.16010789], 1.79098751], 1.15604046], 1.26147554], 0.56787764], 0.35190339], 0.61785408], 0.48144145]]) In [32]: nx.points_inside_poly(points, verts) Out[32]: array([False, False, False, False, False, False, False, True, False, True], dtype=bool) 22.1.9 Control the depth of plot elements Within an axes, the order that the various lines, markers, text, collections, etc appear is determined by the matplotlib.artist.Artist.set_zorder() property. The default order is patches, lines, text, with collections of lines and collections of patches appearing at the same level as regular lines and patches, respectively: 196 Chapter 22. Howto Matplotlib, Release 0.99.1.1 line, = ax.plot(x, y, zorder=10) You can also use the Axes property matplotlib.axes.Axes.set_axisbelow() to control whether the grid lines are placed above or below your other plot elements. 22.1.10 Make the aspect ratio for plots equal The Axes property matplotlib.axes.Axes.set_aspect() controls the aspect ratio of the axes. You can set it to be ‘auto’, ‘equal’, or some ratio which controls the ratio: ax = fig.add_subplot(111, aspect=’equal’) 22.1.11 Make a movie If you want to take an animated plot and turn it into a movie, the best approach is to save a series of image ﬁles (eg PNG) and use an external tool to convert them to a movie. You can use mencoder, which is part of the mplayer suite for this: #fps (frames per second) controls the play speed mencoder ’mf://*.png’ -mf type=png:fps=10 -ovc \\ lavc -lavcopts vcodec=wmv2 -oac copy -o animation.avi The swiss army knife of image tools, ImageMagick’s convert works for this as well. Here is a simple example script that saves some PNGs, makes them into a movie, and then cleans up: import os, sys import matplotlib.pyplot as plt files = fig = plt.figure(figsize=(5,5)) ax = fig.add_subplot(111) for i in range(50): # 50 frames ax.cla() ax.imshow(rand(5,5), interpolation=’nearest’) fname = ’_tmp%03d.png’%i print ’Saving frame’, fname fig.savefig(fname) files.append(fname) print ’Making movie animation.mpg - this make take a while’ os.system("mencoder ’mf://_tmp*.png’ -mf type=png:fps=10 \\ -ovc lavc -lavcopts vcodec=wmv2 -oac copy -o animation.mpg") 22.1. Plotting: howto 197 Matplotlib, Release 0.99.1.1 22.1.12 Multiple y-axis scales A frequent request is to have two scales for the left and right y-axis, which is possible using twinx() (more than two scales are not currently supported, though it is on the wish list). This works pretty well, though there are some quirks when you are trying to interactively pan and zoom, since both scales do not get the signals. The approach twinx() (and its sister twiny()) uses is to use 2 diﬀerent axes, turning the axes rectangular frame oﬀ on the 2nd axes to keep it from obscuring the ﬁrst, and manually setting the tick locs and labels as desired. You can use separate matplotlib.ticker formatters and locators as desired since the two axes are independent: import numpy as np import matplotlib.pyplot as plt fig = plt.figure() ax1 = fig.add_subplot(111) t = np.arange(0.01, 10.0, 0.01) s1 = np.exp(t) ax1.plot(t, s1, ’b-’) ax1.set_xlabel(’time (s)’) ax1.set_ylabel(’exp’) ax2 = ax1.twinx() s2 = np.sin(2*np.pi*t) ax2.plot(t, s2, ’r.’) ax2.set_ylabel(’sin’) plt.show() 22.1.13 Generate images without having a window popup The easiest way to do this is use an image backend (see What is a backend?) such as Agg (for PNGs), PDF, SVG or PS. In your ﬁgure generating script, just place call matplotlib.use() directive before importing pylab or pyplot: import matplotlib matplotlib.use(’Agg’) import matplotlib.pyplot as plt plt.plot([1,2,3]) plt.savefig(’myfig’) See Also: Matplotlib in a web application server For information about running matplotlib inside of a web application. 22.1.14 Use show() The user interface backends need to start the GUI mainloop, and this is what show() does. It tells matplotlib to raise all of the ﬁgure windows and start the mainloop. Because the mainloop is blocking, you should only 198 Chapter 22. Howto Matplotlib, Release 0.99.1.1 call this once per script, at the end. If you are using matplotlib to generate images only and do not want a user interface window, you do not need to call show (see Generate images without having a window popup and What is a backend?). Because it is expensive to draw, matplotlib does not want to redrawing the ﬁgure many times in a script such as the following: plot([1,2,3]) xlabel(’time’) ylabel(’volts’) title(’a simple plot’) show() # # # # draw here ? and here ? and here ? and here ? It is possible to force matplotlib to draw after every command, which is what you usually want when working interactively at the python console (see Using matplotlib in a python shell), but in a script you want to defer all drawing until the script has executed. This is especially important for complex ﬁgures that take some time to draw. show() is designed to tell matplotlib that you’re all done issuing commands and you want to draw the ﬁgure now. Note: show() should be called at most once per script and it should be the last line of your script. At that point, the GUI takes control of the interpreter. If you want to force a ﬁgure draw, use draw() instead. Many users are frustrated by show because they want it to be a blocking call that raises the ﬁgure, pauses the script until the ﬁgure is closed, and then allows the script to continue running until the next ﬁgure is created and the next show is made. Something like this: # WARNING : illustrating how NOT to use show for i in range(10): # make figure i show() This is not what show does and unfortunately, because doing blocking calls across user interfaces can be tricky, is currently unsupported, though we have made some progress towards supporting blocking events. 22.2 Contributing: howto 22.2.1 Submit a patch First obtain a copy of matplotlib svn (see Install from svn) and make your changes to the matplotlib source code or documentation and apply a svn diﬀ. If it is feasible, do your diﬀ from the top level directory, the one that contains setup.py. Eg,: > cd /path/to/matplotlib/source > svn diff > mypatch.diff and then post your patch to the matplotlib-devel mailing list. If you do not get a response within 24 hours, post your patch to the sourceforge patch tracker, and follow up on the mailing list with a link to the sourceforge patch submissions. If you still do not hear anything within a week (this shouldn’t happen!), send us a kind and gentle reminder on the mailing list. 22.2. Contributing: howto 199 Matplotlib, Release 0.99.1.1 If you have made lots of local changes and do not want to a diﬀ against the entire tree, but rather against a single directory or ﬁle, that is ﬁne, but we do prefer svn diﬀs against the top level (where setup.py lives) since it is nice to have a consistent way to apply them. If you are posting a patch to ﬁx a code bug, please explain your patch in words – what was broken before and how you ﬁxed it. Also, even if your patch is particularly simple, just a few lines or a single function replacement, we encourage people to submit svn diﬀs against HEAD or the branch they are patching. It just makes life simpler for us, since we (fortunately) get a lot of contributions, and want to receive them in a standard format. If possible, for any non-trivial change, please include a complete, free-standing example that the developers can run unmodiﬁed which shows the undesired behavior pre-patch and the desired behavior post-patch, with a clear verbal description of what to look for. The original developer may have written the function you are working on years ago, and may no longer be with the project, so it is quite possible you are the world expert on the code you are patching and we want to hear as much detail as you can oﬀer. When emailing your patch and examples, feel free to paste any code into the text of the message, indeed we encourage it, but also attach the patches and examples since many email clients screw up the formatting of plain text, and we spend lots of needless time trying to reformat the code to make it usable. You should check out the guide to developing matplotlib to make sure your patch abides by our coding conventions The Matplotlib Developers’ Guide. 22.2.2 Contribute to matplotlib documentation matplotlib is a big library, which is used in many ways, and the documentation we have only scratches the surface of everything it can do. So far, the place most people have learned all these features are through studying the examples (Search examples), which is a recommended and great way to learn, but it would be nice to have more oﬃcial narrative documentation guiding people through all the dark corners. This is where you come in. There is a good chance you know more about matplotlib usage in some areas, the stuﬀ you do every day, than many of the core developers who write most of the documentation. Just pulled your hair out compiling matplotlib for windows? Write a FAQ or a section for the Installing page. Are you a digital signal processing wizard? Write a tutorial on the signal analysis plotting functions like xcorr(), psd() and specgram(). Do you use matplotlib with django or other popular web application servers? Write a FAQ or tutorial and we’ll ﬁnd a place for it in the User’s Guide. Bundle matplotlib in a py2exe app? ... I think you get the idea. matplotlib is documented using the sphinx extensions to restructured text ReST. sphinx is a extensible python framework for documentation projects which generates HTML and PDF, and is pretty easy to write; you can see the source for this document or any page on this site by clicking on Show Source link at the end of the page in the sidebar (or here for this document). The sphinx website is a good resource for learning sphinx, but we have put together a cheat-sheet at Documenting matplotlib which shows you how to get started, and outlines the matplotlib conventions and extensions, eg for including plots directly from external code in your documents. Once your documentation contributions are working (and hopefully tested by actually building the docs) you can submit them as a patch against svn. See Install from svn and Submit a patch. Looking for something to do? Search for TODO. 200 Chapter 22. Howto Matplotlib, Release 0.99.1.1 22.3 Matplotlib in a web application server Many users report initial problems trying to use maptlotlib in web application servers, because by default matplotlib ships conﬁgured to work with a graphical user interface which may require an X11 connection. Since many barebones application servers do not have X11 enabled, you may get errors if you don’t conﬁgure matplotlib for use in these environments. Most importantly, you need to decide what kinds of images you want to generate (PNG, PDF, SVG) and conﬁgure the appropriate default backend. For 99% of users, this will be the Agg backend, which uses the C++ antigrain rendering engine to make nice PNGs. The Agg backend is also conﬁgured to recognize requests to generate other output formats (PDF, PS, EPS, SVG). The easiest way to conﬁgure matplotlib to use Agg is to call: # do this before importing pylab or pyplot import matplotlib matplotlib.use(’Agg’) import matplotlib.pyplot as plt For more on conﬁguring your backend, see What is a backend?. Alternatively, you can avoid pylab/pyplot altogeher, which will give you a little more control, by calling the API directly as shown in agg_oo.py . You can either generate hardcopy on the ﬁlesystem by calling saveﬁg: # do this before importing pylab or pyplot import matplotlib matplotlib.use(’Agg’) import matplotlib.pyplot as plt fig = plt.figure() ax = fig.add_subplot(111) ax.plot([1,2,3]) fig.savefig(’test.png’) or by saving to a ﬁle handle: import sys fig.savefig(sys.stdout) Here is an example using the Python Imaging Library PIL. First the ﬁgure is saved to a StringIO objectm which is then fed to PIL for further processing: import StringIO, Image imgdata = StringIO.StringIO() fig.savefig(imgdata, format=’png’) imgdata.seek(0) # rewind the data im = Image.open(imgdata) 22.3.1 matplotlib with apache TODO; see Contribute to matplotlib documentation. 22.3. Matplotlib in a web application server 201 Matplotlib, Release 0.99.1.1 22.3.2 matplotlib with django TODO; see Contribute to matplotlib documentation. 22.3.3 matplotlib with zope TODO; see Contribute to matplotlib documentation. 22.3.4 Clickable images for HTML Andrew Dalke of Dalke Scientiﬁc has written a nice article on how to make html click maps with matplotlib agg PNGs. We would also like to add this functionality to SVG and add a SWF backend to support these kind of images. If you are interested in contributing to these eﬀorts that would be great. 22.4 Search examples The nearly 300 code Matplotlib Examples included with the matplotlib source distribution are full-text searchable from the Search Page page, but sometimes when you search, you get a lot of results from the The Matplotlib API or other documentation that you may not be interested in if you just want to ﬁnd a complete, free-standing, working piece of example code. To facilitate example searches, we have tagged every code example page with the keyword codex for code example which shouldn’t appear anywhere else on this site except in the FAQ and in every example. So if you want to search for an example that uses an ellipse, Search Page for codex ellipse. 202 Chapter 22. Howto CHAPTER TWENTYTHREE TROUBLESHOOTING Contents • Troubleshooting – Obtaining matplotlib version – matplotlib install location – .matplotlib directory location – Report a problem – Problems with recent svn versions 23.1 Obtaining matplotlib version To ﬁnd out your matplotlib version number, import it and print the __version__ attribute: >>> import matplotlib >>> matplotlib.__version__ ’0.98.0’ 23.2 matplotlib install location You can ﬁnd what directory matplotlib is installed in by importing it and printing the __file__ attribute: >>> import matplotlib >>> matplotlib.__file__ ’/home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/__init__.pyc’ 23.3 .matplotlib directory location Each user has a .matplotlib/ directory which may contain a matplotlibrc ﬁle and various caches to improve matplotlib’s performance. To locate your .matplotlib/ directory, use matplotlib.get_configdir(): 203 Matplotlib, Release 0.99.1.1 >>> import matplotlib as mpl >>> mpl.get_configdir() ’/home/darren/.matplotlib’ On unix like systems, this directory is generally located in your HOME directory. On windows, it is in your documents and settings directory by default: >>> import matplotlib >>> mpl.get_configdir() ’C:\\Documents and Settings\\jdhunter\\.matplotlib’ If you would like to use a diﬀerent conﬁguration directory, you can do so by specifying the location in your MPLCONFIGDIR environment variable – see Setting environment variables in Linux and OS-X. 23.4 Report a problem If you are having a problem with matplotlib, search the mailing lists ﬁrst: there’s a good chance someone else has already run into your problem. If not, please provide the following information in your e-mail to the mailing list: • your operating system; on Linux/UNIX post the output of uname -a • matplotlib version: python -c ‘import matplotlib; print matplotlib.__version__‘ • where you obtained matplotlib (e.g. your Linux distribution’s packages or the matplotlib Sourceforge site, or the enthought python distribution EPD. • any customizations to your matplotlibrc ﬁle (see Customizing matplotlib). • if the problem is reproducible, please try to provide a minimal, standalone Python script that demonstrates the problem. This is the critical step. If you can’t post a piece of code that we can run and reproduce your error, the chances of getting help are signiﬁcantly diminished. Very often, the mere act of trying to minimize your code to the smallest bit that produces the error will help you ﬁnd a bug in your code that is causing the problem. • you can get very helpful debugging output from matlotlib by running your script with a verbose-helpful or --verbose-debug ﬂags and posting the verbose output the lists: > python simple_plot.py --verbose-helpful > output.txt If you compiled matplotlib yourself, please also provide • any changes you have made to setup.py or setupext.py • the output of: 204 Chapter 23. Troubleshooting Matplotlib, Release 0.99.1.1 rm -rf build python setup.py build The beginning of the build output contains lots of details about your platform that are useful for the matplotlib developers to diagnose your problem. • your compiler version – eg, gcc --version Including this information in your ﬁrst e-mail to the mailing list will save a lot of time. You will likely get a faster response writing to the mailing list than ﬁling a bug in the bug tracker. Most developers check the bug tracker only periodically. If your problem has been determined to be a bug and can not be quickly solved, you may be asked to ﬁle a bug in the tracker so the issue doesn’t get lost. 23.5 Problems with recent svn versions First make sure you have a clean build and install (see Cleanly rebuild and reinstall everything), get the latest svn update, install it and run a simple test script in debug mode: rm -rf rm -rf svn up python python build /path/to/site-packages/matplotlib* setup.py install > build.out examples/pylab_examples/simple_plot.py --verbose-debug > run.out and post build.out and run.out to the matplotlib-devel mailing list (please do not post svn problems to the users list). Of course, you will want to clearly describe your problem, what you are expecting and what you are getting, but often a clean build and install will help. See also Report a problem. 23.5. Problems with recent svn versions 205 Matplotlib, Release 0.99.1.1 206 Chapter 23. Troubleshooting Part III The Matplotlib Developers’ Guide 207 CHAPTER TWENTYFOUR CODING GUIDE 24.1 Version control 24.1.1 svn checkouts Checking out everything in the trunk (matplotlib and toolkits): svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk \ matplotlib --username=youruser --password=yourpass Checking out the main source: svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/\ matplotlib mpl --username=youruser --password=yourpass Branch checkouts, eg the release branch: svn co https://matplotlib.svn.sf.net/svnroot/matplotlib/branches/v0_99_maint mpl99 24.1.2 Committing changes When committing changes to matplotlib, there are a few things to bear in mind. • if your changes are non-trivial, please make an entry in the CHANGELOG • if you change the API, please document it in doc/api/api_changes.rst, and consider posting to matplotlib-devel • Are your changes python2.4 compatible? We still support 2.4, so avoid features new to 2.5 • Can you pass examples/tests/backend_driver.py? This is our poor man’s unit test. • Can you add a test to unit/nose_tests.py to test your changes? • If you have altered extension code, do you pass unit/memleak_hawaii.py? 209 Matplotlib, Release 0.99.1.1 • if you have added new ﬁles or directories, or reorganized existing ones, are the new ﬁles included in the match patterns in MANIFEST.in. This ﬁle determines what goes into the source distribution of the mpl build. • Keep the release branch (eg 0.90 and trunk in sync where it makes sense. If there is a bug on both that needs ﬁxing, use svnmerge.py to keep them in sync. See Using svnmerge below. 24.1.3 Using svnmerge svnmerge is useful for making bugﬁxes to a maintenance branch, and then bringing those changes into the trunk. The basic procedure is: • install svnmerge.py in your PATH: > wget http://svn.collab.net/repos/svn/trunk/contrib/client-side/\ svnmerge/svnmerge.py • get a svn checkout of the branch you’ll be making bugﬁxes to and the trunk (see above) • Create and commit the bugﬁx on the branch. • Then make sure you svn upped on the trunk and have no local modiﬁcations, and then from your checkout of the svn trunk do: svnmerge.py merge -S BRANCHNAME Where BRANCHNAME is the name of the branch to merge from, e.g. v0_99_maint. If you wish to merge only speciﬁc revisions (in an unusual situation), do: > svnmerge.py merge -rNNN1-NNN2 where the NNN are the revision numbers. Ranges are also acceptable. The merge may have found some conﬂicts (code that must be manually resolved). Correct those conﬂicts, build matplotlib and test your choices. If you have resolved any conﬂicts, you can let svn clean up the conﬂict ﬁles for you: > svn -R resolved . svnmerge.py automatically creates a ﬁle containing the commit messages, so you are ready to make the commit: > svn commit -F svnmerge-commit-message.txt 210 Chapter 24. Coding guide Matplotlib, Release 0.99.1.1 Setting up svnmerge Note: The following applies only to release managers when there is a new release. Most developers will not have to concern themselves with this. • Creating a new branch from the trunk (if the release version is 0.98.5 at revision 6573): > svn copy \ https:[email protected] \ https://matplotlib.svn.sf.net/svnroot/matplotlib/branches/v0_98_5_maint \ -m "Creating maintenance branch for 0.98.5" • You can add a new branch for the trunk to “track” using “svnmerge.py init”, e.g., from a working copy of the trunk: > svnmerge.py init https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/v0_98_5_maint property ’svnmerge-integrated’ set on ’.’ After doing a “svn commit” on this, this merge tracking is available to everyone, so there’s no need for anyone else to do the “svnmerge init”. • Tracking can later be removed with the “svnmerge.py uninit” command, e.g.: > svnmerge.py -S v0_9_5_maint uninit 24.1.4 Using git Some matplotlib developers are experimenting with using git on top of the subversion repository. Developers are not required to use git, as subversion will remain the canonical central repository for the foreseeable future. Cloning the git mirror There is an experimental matplotlib github mirror of the subversion repository. To make a local clone of it in the directory mpl.git, enter the following commands: # This will create your copy in the mpl.git directory git clone git://github.com/astraw/matplotlib.git mpl.git cd mpl.git git config --add remote.origin.fetch +refs/remotes/*:refs/remotes/* git fetch git svn init --branches=branches --trunk=trunk/matplotlib --tags=tags https://matplotlib.svn.sourceforge # Now just get the latest svn revisions from the SourceForge SVN repository git svn fetch -r 6800:HEAD To install from this cloned repository, use the commands in the svn installation section: 24.1. Version control 211 Matplotlib, Release 0.99.1.1 > cd mpl.git > python setup.py install Using git The following is a suggested workﬂow for git/git-svn. Start with a virgin tree in sync with the svn trunk on the git branch “master”: git checkout master git svn rebase To create a new, local branch called “whizbang-branch”: git checkout -b whizbang-branch Do make commits to the local branch: # hack on a bunch of files git add bunch of files git commit -m "modified a bunch of files" # repeat this as necessary Now, go back to the master branch and append the history of your branch to the master branch, which will end up as the svn trunk: git git git git git checkout master svn rebase # Ensure we rebase whizbang-branch svn dcommit -n # Check svn dcommit # Actually have most recent svn # Append whizbang changes to master branch that this will apply to svn apply to svn Finally, you may want to continue working on your whizbang-branch, so rebase it to the new master: git checkout whizbang-branch git rebase master If you get the dreaded “Unable to determine upstream SVN information from working tree history” error when running “git svn rebase”, try creating a new git branch based on subversion trunk and cherry pick your patches onto that: git checkout -b work remotes/trunk # create a new "work" branch git cherry-pick <commit> # where <commit> will get applied to new branch 212 Chapter 24. Coding guide Matplotlib, Release 0.99.1.1 Working on a maintenance branch from git The matplotlib maintenance branches are also available through git. (Note that the git svn init line in the instructions above was updated to make this possible. If you created your git mirror without a --branches option, you will need to perform all of the steps again in a new directory). You can see which branches are available with: git branch -a To switch your working copy to the 0.98.5 maintenance branch: git checkout v0_98_5_maint Then you probably want to (as above) create a new local branch based on that branch: git checkout -b whizbang-branch When you git svn dcommit from a maintenance branch, it will commit to that branch, not to the trunk. While it should theoretically be possible to perform merges from a git maintenance branch to a git trunk and then commit those changes back to the SVN trunk, I have yet to ﬁnd the magic incantation to make that work. However, svnmerge as described above can be used and in fact works quite well. A note about git write access The matplotlib developers need to ﬁgure out if there should be write access to the git repository. This implies using the personal URL ([email protected]:astraw/matplotlib.git) rather than the public URL (git://github.com/astraw/matplotlib.git) for the repository. However, doing so may make life complicated in the sense that then there are two writeable matplotlib repositories, which must be synced to prevent divergence. This is probably not an insurmountable problem, but it is a problem that the developers should reach a consensus about. Watch this space... 24.2 Style guide 24.2.1 Importing and name spaces For numpy, use: import numpy as np a = np.array([1,2,3]) For masked arrays, use: import numpy.ma as ma For matplotlib main module, use: 24.2. Style guide 213 Matplotlib, Release 0.99.1.1 import matplotlib as mpl mpl.rcParams[’xtick.major.pad’] = 6 For matplotlib modules (or any other modules), use: import matplotlib.cbook as cbook if cbook.iterable(z): pass We prefer this over the equivalent from matplotlib import cbook because the latter is ambiguous as to whether cbook is a module or a function. The former makes it explicit that you are importing a module or package. There are some modules with names that match commonly used local variable names, eg matplotlib.lines or matplotlib.colors. To avoid the clash, use the preﬁx ‘m’ with the import some.thing as mthing syntax, eg: import import import import matplotlib.lines as mlines matplotlib.transforms as transforms matplotlib.transforms as mtransforms matplotlib.transforms as mtrans # OK # OK, if you want to disambiguate # OK, if you want to abbreviate 24.2.2 Naming, spacing, and formatting conventions In general, we want to hew as closely as possible to the standard coding guidelines for python written by Guido in PEP 0008, though we do not do this throughout. • functions and class methods: lower or lower_underscore_separated • attributes and variables: lower or lowerUpper • classes: Upper or MixedCase Prefer the shortest names that are still readable. Conﬁgure your editor to use spaces, not hard tabs. The standard indentation unit is always four spaces; if there is a ﬁle with tabs or a diﬀerent number of spaces it is a bug – please ﬁx it. To detect and ﬁx these and other whitespace errors (see below), use reindent.py as a command-line script. Unless you are sure your editor always does the right thing, please use reindent.py before checking changes into svn. Keep docstrings uniformly indented as in the example below, with nothing to the left of the triple quotes. The matplotlib.cbook.dedent() function is needed to remove excess indentation only if something will be interpolated into the docstring, again as in the example below. Limit line length to 80 characters. If a logical line needs to be longer, use parentheses to break it; do not use an escaped newline. It may be preferable to use a temporary variable to replace a single long line with two shorter and more readable lines. Please do not commit lines with trailing white space, as it causes noise in svn diﬀs. Tell your editor to strip whitespace from line ends when saving a ﬁle. If you are an emacs user, the following in your .emacs will cause emacs to strip trailing white space upon saving for python, C and C++: 214 Chapter 24. Coding guide Matplotlib, Release 0.99.1.1 ; and similarly for c++-mode-hook and c-mode-hook (add-hook ’python-mode-hook (lambda () (add-hook ’write-file-functions ’delete-trailing-whitespace))) for older versions of emacs (emacs<22) you need to do: (add-hook ’python-mode-hook (lambda () (add-hook ’local-write-file-hooks ’delete-trailing-whitespace))) 24.2.3 Keyword argument processing Matplotlib makes extensive use of **kwargs for pass-through customizations from one function to another. A typical example is in matplotlib.pylab.text(). The deﬁnition of the pylab text function is a simple pass-through to matplotlib.axes.Axes.text(): # in pylab.py def text(*args, **kwargs): ret = gca().text(*args, **kwargs) draw_if_interactive() return ret text() in simpliﬁed form looks like this, i.e., it just passes all args and kwargs on to matplotlib.text.Text.__init__(): # in axes.py def text(self, x, y, s, fontdict=None, withdash=False, **kwargs): t = Text(x=x, y=y, text=s, **kwargs) and __init__() (again with liberties for matplotlib.artist.Artist.update() method: illustration) just passes them on to the # in text.py def __init__(self, x=0, y=0, text=’’, **kwargs): Artist.__init__(self) self.update(kwargs) update does the work looking for methods named like set_property if property is a keyword argument. I.e., no one looks at the keywords, they just get passed through the API to the artist constructor which looks for suitably named methods and calls them with the value. As a general rule, the use of **kwargs should be reserved for pass-through keyword arguments, as in the example above. If all the keyword args are to be used in the function, and not passed on, use the key/value keyword args in the function deﬁnition rather than the **kwargs idiom. In some cases, you may want to consume some keys in the local function, and let others pass through. You can pop the ones to be used locally and pass on the rest. For example, in plot(), scalex and scaley are local arguments and the rest are passed on as Line2D() keyword arguments: 24.2. Style guide 215 Matplotlib, Release 0.99.1.1 # in axes.py def plot(self, *args, **kwargs): scalex = kwargs.pop(’scalex’, True) scaley = kwargs.pop(’scaley’, True) if not self._hold: self.cla() lines = for line in self._get_lines(*args, **kwargs): self.add_line(line) lines.append(line) Note: there is a use case when kwargs are meant to be used locally in the function (not passed on), but you still need the **kwargs idiom. That is when you want to use *args to allow variable numbers of nonkeyword args. In this case, python will not allow you to use named keyword args after the *args usage, so you will be forced to use **kwargs. An example is matplotlib.contour.ContourLabeler.clabel(): # in contour.py def clabel(self, *args, **kwargs): fontsize = kwargs.get(’fontsize’, None) inline = kwargs.get(’inline’, 1) self.fmt = kwargs.get(’fmt’, ’%1.3f ’) colors = kwargs.get(’colors’, None) if len(args) == 0: levels = self.levels indices = range(len(self.levels)) elif len(args) == 1: ...etc... 24.3 Documentation and docstrings Matplotlib uses artist introspection of docstrings to support properties. All properties that you want to support through setp and getp should have a set_property and get_property method in the Artist class. Yes, this is not ideal given python properties or enthought traits, but it is a historical legacy for now. The setter methods use the docstring with the ACCEPTS token to indicate the type of argument the method accepts. Eg. in matplotlib.lines.Line2D: # in lines.py def set_linestyle(self, linestyle): """ Set the linestyle of the line ACCEPTS: [ ’-’ | ’--’ | ’-.’ | ’:’ | ’steps’ | ’None’ | ’ ’ | ’’ ] """ Since matplotlib uses a lot of pass-through kwargs, eg. in every function that creates a line (plot(), semilogx(), semilogy(), etc...), it can be diﬃcult for the new user to know which kwargs are supported. Matplotlib uses a docstring interpolation scheme to support documentation of every function that takes a **kwargs. The requirements are: 1. single point of conﬁguration so changes to the properties don’t require multiple docstring edits. 216 Chapter 24. Coding guide Matplotlib, Release 0.99.1.1 2. as automated as possible so that as properties change, the docs are updated automagically. The functions matplotlib.artist.kwdocd and matplotlib.artist.kwdoc() to facilitate this. They combine python string interpolation in the docstring with the matplotlib artist introspection facility that underlies setp and getp. The kwdocd is a single dictionary that maps class name to a docstring of kwargs. Here is an example from matplotlib.lines: # in lines.py artist.kwdocd[’Line2D’] = artist.kwdoc(Line2D) Then in any function accepting Line2D pass-through kwargs, eg. matplotlib.axes.Axes.plot(): # in axes.py def plot(self, *args, **kwargs): """ Some stuff omitted The kwargs are Line2D properties: %(Line2D)s kwargs scalex and scaley, if defined, are passed on to autoscale_view to determine whether the x and y axes are autoscaled; default True. See Axes.autoscale_view for more information """ pass plot.__doc__ = cbook.dedent(plot.__doc__) % artist.kwdocd Note there is a problem for Artist __init__ methods, eg. matplotlib.patches.Patch.__init__(), which supports Patch kwargs, since the artist inspector cannot work until the class is fully deﬁned and we can’t modify the Patch.__init__.__doc__ docstring outside the class deﬁnition. There are some some manual hacks in this case, violating the “single entry point” requirement above – see the artist.kwdocd[’Patch’] setting in matplotlib.patches. 24.4 Developing a new backend If you are working on a custom backend, the backend setting in matplotlibrc (Customizing matplotlib) supports an external backend via the module directive. if my_backend.py is a matplotlib backend in your PYTHONPATH, you can set use it on one of several ways • in matplotlibrc: backend : module://my_backend • with the use directive is your script: import matplotlib matplotlib.use(’module://my_backend’) • from the command shell with the -d ﬂag: 24.4. Developing a new backend 217 Matplotlib, Release 0.99.1.1 > python simple_plot.py -d module://my_backend 24.5 Licenses Matplotlib only uses BSD compatible code. If you bring in code from another project make sure it has a PSF, BSD, MIT or compatible license (see the Open Source Initiative licenses page for details on individual licenses). If it doesn’t, you may consider contacting the author and asking them to relicense it. GPL and LGPL code are not acceptable in the main code base, though we are considering an alternative way of distributing L/GPL code through an separate channel, possibly a toolkit. If you include code, make sure you include a copy of that code’s license in the license directory if the code’s license requires you to distribute the license with it. Non-BSD compatible licenses are acceptable in matplotlib toolkits (eg basemap), but make sure you clearly state the licenses you are using. 24.5.1 Why BSD compatible? The two dominant license variants in the wild are GPL-style and BSD-style. There are countless other licenses that place speciﬁc restrictions on code reuse, but there is an important diﬀerence to be considered in the GPL and BSD variants. The best known and perhaps most widely used license is the GPL, which in addition to granting you full rights to the source code including redistribution, carries with it an extra obligation. If you use GPL code in your own code, or link with it, your product must be released under a GPL compatible license. I.e., you are required to give the source code to other people and give them the right to redistribute it as well. Many of the most famous and widely used open source projects are released under the GPL, including linux, gcc, emacs and sage. The second major class are the BSD-style licenses (which includes MIT and the python PSF license). These basically allow you to do whatever you want with the code: ignore it, include it in your own open source project, include it in your proprietary product, sell it, whatever. python itself is released under a BSD compatible license, in the sense that, quoting from the PSF license page: There is no GPL-like "copyleft" restriction. Distributing binary-only versions of Python, modified or not, is allowed. There is no requirement to release any of your source code. You can also write extension modules for Python and provide them only in binary form. Famous projects released under a BSD-style license in the permissive sense of the last paragraph are the BSD operating system, python and TeX. There are several reasons why early matplotlib developers selected a BSD compatible license. matplotlib is a python extension, and we choose a license that was based on the python license (BSD compatible). Also, we wanted to attract as many users and developers as possible, and many software companies will not use GPL code in software they plan to distribute, even those that are highly committed to open source development, such as enthought, out of legitimate concern that use of the GPL will “infect” their code base by its viral nature. In eﬀect, they want to retain the right to release some proprietary code. Companies and institutions who use matplotlib often make signiﬁcant contributions, because they have the resources to get a job done, even a boring one. Two of the matplotlib backends (FLTK and WX) were contributed by private 218 Chapter 24. Coding guide Matplotlib, Release 0.99.1.1 companies. The ﬁnal reason behind the licensing choice is compatibility with the other python extensions for scientiﬁc computing: ipython, numpy, scipy, the enthought tool suite and python itself are all distributed under BSD compatible licenses. 24.5. Licenses 219 Matplotlib, Release 0.99.1.1 220 Chapter 24. Coding guide CHAPTER TWENTYFIVE DOCUMENTING MATPLOTLIB 25.1 Getting started The documentation for matplotlib is generated from ReStructured Text using the Sphinx documentation generation tool. Sphinx-0.5 or later is required. You might still run into problems, so most developers work from the sphinx source repository (Mercurial based) because it is a rapidly evolving project: hg clone http://bitbucket.org/birkenfeld/sphinx/ cd sphinx python setup.py install The documentation sources are found in the doc/ directory in the trunk. To build the users guide in html format, cd into doc/ and do: python make.py html or: ./make.py html you can also pass a latex ﬂag to make.py to build a pdf, or pass no arguments to build everything. The output produced by Sphinx can be conﬁgured by editing the conf.py ﬁle located in the doc/. 25.2 Organization of matplotlib’s documentation The actual ReStructured Text ﬁles are kept in doc/users, doc/devel, doc/api and doc/faq. The main entry point is doc/index.rst, which pulls in the index.rst ﬁle for the users guide, developers guide, api reference, and faqs. The documentation suite is built as a single document in order to make the most eﬀective use of cross referencing, we want to make navigating the Matplotlib documentation as easy as possible. Additional ﬁles can be added to the various guides by including their base ﬁle name (the .rst extension is not necessary) in the table of contents. It is also possible to include other documents through the use of an include statement, such as: 221 Matplotlib, Release 0.99.1.1 .. include:: ../../TODO 25.3 Formatting The Sphinx website contains plenty of documentation concerning ReST markup and working with Sphinx in general. Here are a few additional things to keep in mind: • Please familiarize yourself with the Sphinx directives for inline markup. Matplotlib’s documentation makes heavy use of cross-referencing and other semantic markup. For example, when referring to external ﬁles, use the :file: directive. • Function arguments and keywords should be referred to using the emphasis role. This will keep matplotlib’s documentation consistant with Python’s documentation: Here is a description of *argument* Please do not use the default role: Please do not describe ‘argument‘ like this. nor the literal role: Please do not describe ‘‘argument‘‘ like this. • Sphinx does not support tables with column- or row-spanning cells for latex output. Such tables can not be used when documenting matplotlib. • Mathematical expressions can be rendered as png images in html, and in the usual way by latex. For example: 2 :math:‘\sin(x_n^2)‘ yields: sin( xn ), and: .. math:: \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}} yields: ￿ ∞ eiφ −∞ 1 + x2 1e x2 + iφ (25.1) • Interactive IPython sessions can be illustrated in the documentation using the following directive: .. sourcecode:: ipython In [69]: lines = plot([1,2,3]) which would yield: 222 Chapter 25. Documenting matplotlib Matplotlib, Release 0.99.1.1 In [69]: lines = plot([1,2,3]) • Footnotes 1 can be added using [#]_, followed later by: .. rubric:: Footnotes .. [#] • Use the note and warning directives, sparingly, to draw attention to important comments: .. note:: Here is a note yields: Note: here is a note also: Warning: here is a warning • Use the deprecated directive when appropriate: .. deprecated:: 0.98 This feature is obsolete, use something else. yields: Deprecated since version 0.98: This feature is obsolete, use something else. • Use the versionadded and versionchanged directives, which have similar syntax to the deprecated role: .. versionadded:: 0.98 The transforms have been completely revamped. New in version 0.98: The transforms have been completely revamped. • Use the seealso directive, for example: .. seealso:: Using ReST :ref:‘emacs-helpers‘: One example A bit about :ref:‘referring-to-mpl-docs‘: One more yields: See Also: 1 For example. 25.3. Formatting 223 Matplotlib, Release 0.99.1.1 Using ResT Emacs helpers: One example A bit about Referring to mpl documents: One more • Please keep the Glossary in mind when writing documentation. You can create a references to a term in the glossary with the :term: role. • The autodoc extension will handle index entries for the API, but additional entries in the index need to be explicitly added. 25.3.1 Docstrings In addition to the aforementioned formatting suggestions: • Please limit the text width of docstrings to 70 characters. • Keyword arguments should be described using a deﬁnition list. Note: matplotlib makes extensive use of keyword arguments as pass-through arguments, there are a many cases where a table is used in place of a deﬁnition list for autogenerated sections of docstrings. 25.4 Figures 25.4.1 Dynamically generated ﬁgures Figures can be automatically generated from scripts and included in the docs. It is not necessary to explicitly save the ﬁgure in the script, this will be done automatically at build time to ensure that the code that is included runs and produces the advertised ﬁgure. Several ﬁgures will be saved with the same basename as the ﬁlename when the documentation is generated (low and high res PNGs, a PDF). Matplotlib includes a Sphinx extension (sphinxext/plot_directive.py) for generating the images from the python script and including either a png copy for html or a pdf for latex: .. plot:: pyplots/pyplot_simple.py :include-source: If the script produces multiple ﬁgures (through multiple calls to pyplot.figure()), each will be given a numbered ﬁle name and included. The path should be relative to the doc directory. Any plots speciﬁc to the documentation should be added to the doc/pyplots directory and committed to SVN. Plots from the examples directory may be referenced through the symlink mpl_examples in the doc directory. eg.: .. plot:: mpl_examples/pylab_examples/simple_plot.py The :scale: directive rescales the image to some percentage of the original size, though we don’t recommend using this in most cases since it is probably better to choose the correct ﬁgure size and dpi in mpl and let it handle the scaling. :include-source: will present the contents of the ﬁle, marked up as source code. 224 Chapter 25. Documenting matplotlib Matplotlib, Release 0.99.1.1 25.4.2 Static ﬁgures Any ﬁgures that rely on optional system conﬁgurations need to be handled a little diﬀerently. These ﬁgures are not to be generated during the documentation build, in order to keep the prerequisites to the documentation eﬀort as low as possible. Please run the doc/pyplots/make.py script when adding such ﬁgures, and commit the script and the images to svn. Please also add a line to the README in doc/pyplots for any additional requirements necessary to generate a new ﬁgure. Once these steps have been taken, these ﬁgures can be included in the usual way: .. plot:: pyplots/tex_unicode_demo.py :include-source: 25.4.3 Examples The source of the ﬁles in the examples directory are automatically included in the HTML docs. An image is generated and included for all examples in the api and pylab_examples directories. To exclude the example from having an image rendered, insert the following special comment anywhere in the script: # -*- noplot -*- 25.5 Referring to mpl documents In the documentation, you may want to include to a document in the matplotlib src, e.g. a license ﬁle or an image ﬁle from mpl-data, refer to it via a relative path from the document where the rst ﬁle resides, eg, in users/navigation_toolbar.rst, we refer to the image icons with: .. image:: ../../lib/matplotlib/mpl-data/images/subplots.png In the users subdirectory, if I want to refer to a ﬁle in the mpl-data directory, I use the symlink directory. For example, from customizing.rst: .. literalinclude:: ../../lib/matplotlib/mpl-data/matplotlibrc On exception to this is when referring to the examples dir. Relative paths are extremely confusing in the sphinx plot extensions, so without getting into the dirty details, it is easier to simply include a symlink to the ﬁles at the top doc level directory. This way, API documents like matplotlib.pyplot.plot() can refer to the examples in a known location. In the top level doc directory we have symlinks pointing to the mpl examples: home:~/mpl/doc> ls -l mpl_* mpl_examples -> ../examples So we can include plots from the examples dir using the symlink: 25.5. Referring to mpl documents 225 Matplotlib, Release 0.99.1.1 .. plot:: mpl_examples/pylab_examples/simple_plot.py We used to use a symlink for mpl-data too, but the distro becomes very large on platforms that do not support links (eg the font ﬁles are duplicated and large) 25.6 Internal section references To maximize internal consistency in section labeling and references, use hypen separated, descriptive labels for section references, eg: .. _howto-webapp: and refer to it using the standard reference syntax: See :ref:‘howto-webapp‘ Keep in mind that we may want to reorganize the contents later, so let’s avoid top level names in references like user or devel or faq unless necesssary, because for example the FAQ “what is a backend?” could later become part of the users guide, so the label: .. _what-is-a-backend is better than: .. _faq-backend In addition, since underscores are widely used by Sphinx itself, let’s prefer hyphens to separate words. 25.7 Section names, etc For everything but top level chapters, please use Upper lower for section titles, eg Possible hangups rather than Possible Hangups 25.8 Inheritance diagrams Class inheritance diagrams can be generated with the inheritance-diagram directive. To use it, you provide the directive with a number of class or module names (separated by whitespace). If a module name is provided, all classes in that module will be used. All of the ancestors of these classes will be included in the inheritance diagram. A single option is available: parts controls how many of parts in the path to the class are shown. For example, if parts == 1, the class matplotlib.patches.Patch is shown as Patch. If parts == 2, it is shown as patches.Patch. If parts == 0, the full path is shown. 226 Chapter 25. Documenting matplotlib Matplotlib, Release 0.99.1.1 Example: .. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text :parts: 2 25.9 Emacs helpers There is an emacs mode rst.el which automates many important ReST tasks like building and updateing table-of-contents, and promoting or demoting section headings. Here is the basic .emacs conﬁguration: (require ’rst) (setq auto-mode-alist (append ’(("\\.txt" . rst-mode) ("\\.rst$" . rst-mode) ("\\.rest$" . rst-mode)) auto-mode-alist)) Some helpful functions: 25.9. Emacs helpers 227 Matplotlib, Release 0.99.1.1 C-c TAB - rst-toc-insert Insert table of contents at point C-c C-u - rst-toc-update Update the table of contents at point C-c C-l rst-shift-region-left Shift region to the left C-c C-r rst-shift-region-right Shift region to the right 228 Chapter 25. Documenting matplotlib CHAPTER TWENTYSIX DOING A MATPLOLIB RELEASE A guide for developers who are doing a matplotlib release • Edit __init__.py and bump the version number When doing a release 26.1 Testing • Make sure examples/tests/backend_driver.py runs without errors and check the output of the PNG, PDF, PS and SVG backends • Run unit/memleak_hawaii3.py and make sure there are no memory leaks • Run unit/nose_tests.py and make sure all the unit tests are passing • try some GUI examples, eg simple_plot.py with GTKAgg, TkAgg, etc... • remove font cache and tex cache from .matplotlib and test with and without cache on some example script 26.2 Branching Once all the tests are passing and you are ready to do a release, you need to create a release branch and conﬁgure svn-merge to use it; Michael Droettboom should probably handle this step, but if he is not available see instructions at Setting up svnmerge. On the bracnh, do any additional testing you want to do, and then build binaries and source distributions for testing as release candidates. 26.3 Packaging • Make sure the MANIFEST.in us up to date and remove MANIFEST so it will be rebuilt by MANIFEST.in • run svn-clean from in the mpl svn directory before building the sdist • unpack the sdist and make sure you can build from that directory 229 Matplotlib, Release 0.99.1.1 • Use setup.cfg to set the default backends. For windows and OSX, the default backend should be TkAgg. You should also turn on or oﬀ any platform speciﬁc build options you need. Importantly, you also need to make sure that you delete the build dir after any changes to ﬁle:setup.cfg before rebuilding since cruft in the build dir can get carried along. • on windows, unix2dos the rc ﬁle • We have a Makeﬁle for the OS X builds in the mpl source dir release/osx, so use this to prepare the OS X releases. • We have a Makeﬁle for the win32 mingw builds in the mpl source dir release/win32 which you can use this to prepare the windows releases, but this is currently broken for python2.6 as described at http://www.nabble.com/binary-installers-for-python2.6–libpngsegfault%2C-MSVCR90.DLL-and-%09mingw-td23971661.html 26.4 Release candidate testing: Post the release candidates to http://matplotlib.sf.net/release-candidates and post a message to matplotlibusers and devel requesting testing. To post to the server, you can do: > scp somefile.tgz jdh2358,[email protected]:/home/groups/m/ma/matplotlib/htdocs/release-candidate replacing ‘jdh2358’ with your sourceforge login. Any changes to ﬁx bugs in the release candidate should be ﬁxed in the release branch and merged into the trunk with svn-merge; see Using svnmerge. When the release candidate is signed oﬀ on, build the ﬁnal sdist, binaries and eggs, and upload them to the sourceforge release area. 26.5 Uploading • Post the win32 and OS-X binaries for testing and make a request on matplotlib-devel for testing. Pester us if we don’t respond • ftp the source and binaries to the anonymous FTP site: mpl> svn-clean mpl> python setup.py sdist mpl> cd dist/ dist> sftp [email protected] Connecting to frs.sourceforge.net... sftp> cd uploads sftp> ls sftp> lls matplotlib-0.98.2.tar.gz sftp> put matplotlib-0.98.2.tar.gz Uploading matplotlib-0.98.2.tar.gz to /incoming/j/jd/jdh2358/uploads/matplotlib-0.98.2.tar.gz 230 Chapter 26. Doing a matplolib release Matplotlib, Release 0.99.1.1 • go https://sourceforge.net/project/admin/editpackages.php?group_id=80706 and do a ﬁle release. Click on the “Admin” tab to log in as an admin, and then the “File Releases” tab. Go to the bottom and click “add release” and enter the package name but not the version number in the “Package Name” box. You will then be prompted for the “New release name” at which point you can add the version number, eg somepackage-0.1 and click “Create this release”. You will then be taken to a fairly self explanatory page where you can enter the Change notes, the release notes, and select which packages from the incoming ftp archive you want to include in this release. For each binary, you will need to select the platform and ﬁle type, and when you are done you click on the “notify users who are monitoring this package link” 26.6 Announcing Announce the release on matplotlib-announce, matplotlib-users and matplotlib-devel. Include a summary of highlights from the CHANGELOG and/or post the whole CHANGELOG since the last release. 26.6. Announcing 231 Matplotlib, Release 0.99.1.1 232 Chapter 26. Doing a matplolib release CHAPTER TWENTYSEVEN WORKING WITH TRANSFORMATIONS 27.1 matplotlib.transforms matplotlib includes a framework for arbitrary geometric transformations that is used determine the ﬁnal position of all elements drawn on the canvas. Transforms are composed into trees of TransformNode objects whose actual value depends on their children. When the contents of children change, their parents are automatically invalidated. The next time an invalidated transform is accessed, it is recomputed to reﬂect those changes. This invalidation/caching approach prevents unnecessary recomputations of transforms, and contributes to better interactive performance. For example, here is a graph of the transform tree used to plot data to the graph: 233 Matplotlib, Release 0.99.1.1 The framework can be used for both aﬃne and non-aﬃne transformations. However, for speed, we want use the backend renderers to perform aﬃne transformations whenever possible. Therefore, it is possible to perform just the aﬃne or non-aﬃne part of a transformation on a set of data. The aﬃne is always assumed to occur after the non-aﬃne. For any transform: full transform == non-affine part + affine part The backends are not expected to handle non-aﬃne transformations themselves. 234 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 class TransformNode() Bases: object TransformNode is the base class for anything that participates in the transform tree and needs to invalidate its parents or be invalidated. This includes classes that are not really transforms, such as bounding boxes, since some transforms depend on bounding boxes to compute their values. Creates a new TransformNode. frozen() Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used. invalidate() Invalidate this TransformNode and all of its ancestors. Should be called any time the transform changes. set_children(*children) Set the children of the transform, to let the invalidation system know which transforms can invalidate this transform. Should be called from the constructor of any transforms that depend on other transforms. class BboxBase() Bases: matplotlib.transforms.TransformNode This is the base class of all bounding boxes, and provides read-only access to its data. A mutable bounding box is provided by the Bbox class. The canonical representation is as two points, with no restrictions on their ordering. Convenience properties are provided to get the left, bottom, right and top edges and width and height, but these are not stored explicity. Creates a new TransformNode. anchored(c, container=None) Return a copy of the Bbox, shifted to position c within a container. c: may be either: •a sequence (cx, cy) where cx and cy range from 0 to 1, where 0 is left or bottom and 1 is right or top •a string: - ‘C’ for centered - ‘S’ for bottom-center - ‘SE’ for bottom-left - ‘E’ for left - etc. Optional argument container is the box within which the Bbox is positioned; it defaults to the initial Bbox. bounds (property) Returns (x0, y0, width, height). contains(x, y) Returns True if (x, y) is a coordinate inside the bounding box or on its edge. containsx(x) Returns True if x is between or equal to x0 and x1. 27.1. matplotlib.transforms 235 Matplotlib, Release 0.99.1.1 containsy(y) Returns True if y is between or equal to y0 and y1. corners() Return an array of points which are the four corners of this rectangle. For example, if this Bbox is deﬁned by the points (a, b) and (c, d), corners() returns (a, b), (a, d), (c, b) and (c, d). count_contains(vertices) Count the number of vertices contained in the Bbox. vertices is a Nx2 Numpy array. count_overlaps(bboxes) Count the number of bounding boxes that overlap this one. bboxes is a sequence of BboxBase objects expanded(sw, sh) Return a new Bbox which is this Bbox expanded around its center by the given factors sw and sh. extents (property) Returns (x0, y0, x1, y1). frozen() TransformNode is the base class for anything that participates in the transform tree and needs to invalidate its parents or be invalidated. This includes classes that are not really transforms, such as bounding boxes, since some transforms depend on bounding boxes to compute their values. fully_contains(x, y) Returns True if (x, y) is a coordinate inside the bounding box, but not on its edge. fully_containsx(x) Returns True if x is between but not equal to x0 and x1. fully_containsy(y) Returns True if y is between but not equal to y0 and y1. fully_overlaps(other) Returns True if this bounding box overlaps with the given bounding box other, but not on its edge alone. height (property) The height of the bounding box. It may be negative if y1 < y0. intervalx (property) intervalx is the pair of x coordinates that deﬁne the bounding box. It is not guaranteed to be sorted from left to right. intervaly (property) intervaly is the pair of y coordinates that deﬁne the bounding box. It is not guaranteed to be sorted from bottom to top. inverse_transformed(transform) Return a new Bbox object, statically transformed by the inverse of the given transform. 236 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 is_unit() Returns True if the Bbox is the unit bounding box from (0, 0) to (1, 1). max (property) max is the top-right corner of the bounding box. min (property) min is the bottom-left corner of the bounding box. overlaps(other) Returns True if this bounding box overlaps with the given bounding box other. p0 (property) p0 is the ﬁrst pair of (x, y) coordinates that deﬁne the bounding box. It is not guaranteed to be the bottom-left corner. For that, use min. p1 (property) p1 is the second pair of (x, y) coordinates that deﬁne the bounding box. It is not guaranteed to be the top-right corner. For that, use max. padded(p) Return a new Bbox that is padded on all four sides by the given value. rotated(radians) Return a new bounding box that bounds a rotated version of this bounding box by the given radians. The new bounding box is still aligned with the axes, of course. shrunk(mx, my) Return a copy of the Bbox, shrunk by the factor mx in the x direction and the factor my in the y direction. The lower left corner of the box remains unchanged. Normally mx and my will be less than 1, but this is not enforced. shrunk_to_aspect(box_aspect, container=None, ﬁg_aspect=1.0) Return a copy of the Bbox, shrunk so that it is as large as it can be while having the desired aspect ratio, box_aspect. If the box coordinates are relative—that is, fractions of a larger box such as a ﬁgure—then the physical aspect ratio of that ﬁgure is speciﬁed with ﬁg_aspect, so that box_aspect can also be given as a ratio of the absolute dimensions, not the relative dimensions. size (property) The width and height of the bounding box. May be negative, in the same way as width and height. splitx(*args) e.g., bbox.splitx(f1, f2, ...) Returns a list of new Bbox objects formed by splitting the original one with vertical lines at fractional positions f1, f2, ... splity(*args) e.g., bbox.splitx(f1, f2, ...) Returns a list of new Bbox objects formed by splitting the original one with horizontal lines at fractional positions f1, f2, ... 27.1. matplotlib.transforms 237 Matplotlib, Release 0.99.1.1 transformed(transform) Return a new Bbox object, statically transformed by the given transform. translated(tx, ty) Return a copy of the Bbox, statically translated by tx and ty. static union(bboxes) Return a Bbox that contains all of the given bboxes. width (property) The width of the bounding box. It may be negative if x1 < x0. x0 (property) x0 is the ﬁrst of the pair of x coordinates that deﬁne the bounding box. x0 is not guaranteed to be less than x1. If you require that, use xmin. x1 (property) x1 is the second of the pair of x coordinates that deﬁne the bounding box. x1 is not guaranteed to be greater than x0. If you require that, use xmax. xmax (property) xmax is the right edge of the bounding box. xmin (property) xmin is the left edge of the bounding box. y0 (property) y0 is the ﬁrst of the pair of y coordinates that deﬁne the bounding box. y0 is not guaranteed to be less than y1. If you require that, use ymin. y1 (property) y1 is the second of the pair of y coordinates that deﬁne the bounding box. y1 is not guaranteed to be greater than y0. If you require that, use ymax. ymax (property) ymax is the top edge of the bounding box. ymin (property) ymin is the bottom edge of the bounding box. class Bbox(points) Bases: matplotlib.transforms.BboxBase A mutable bounding box. points: a 2x2 numpy array of the form [[x0, y0], [x1, y1]] If you need to create a Bbox object from another form of data, consider the static methods unit(), from_bounds() and from_extents(). static from_bounds(x0, y0, width, height) (staticmethod) Create a new Bbox from x0, y0, width and height. width and height may be negative. static from_extents(*args) (staticmethod) Create a new Bbox from left, bottom, right and top. 238 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 The y-axis increases upwards. get_points() Get the points of the bounding box directly as a numpy array of the form: [[x0, y0], [x1, y1]]. ignore(value) Set whether the existing bounds of the box should be ignored by subsequent calls to update_from_data() or update_from_data_xy(). value: •When True, subsequent calls to update_from_data() will ignore the existing bounds of the Bbox. •When False, subsequent calls to update_from_data() will include the existing bounds of the Bbox. set(other) Set this bounding box from the “frozen” bounds of another Bbox. set_points(points) Set the points of the bounding box directly from a numpy array of the form: [[x0, y0], [x1, y1]]. No error checking is performed, as this method is mainly for internal use. static unit() (staticmethod) Create a new unit Bbox from (0, 0) to (1, 1). update_from_data(x, y, ignore=None) Update the bounds of the Bbox based on the passed in data. After updating, the bounds will have positive width and height; x0 and y0 will be the minimal values. x: a numpy array of x-values y: a numpy array of y-values ignore: • when True, ignore the existing bounds of the Bbox. • when False, include the existing bounds of the Bbox. • when None, use the last value passed to ignore(). update_from_data_xy(xy, ignore=None, updatex=True, updatey=True) Update the bounds of the Bbox based on the passed in data. After updating, the bounds will have positive width and height; x0 and y0 will be the minimal values. xy: a numpy array of 2D points ignore: • when True, ignore the existing bounds of the Bbox. • when False, include the existing bounds of the Bbox. • when None, use the last value passed to ignore(). updatex: when True, update the x values updatey: when True, update the y values 27.1. matplotlib.transforms 239 Matplotlib, Release 0.99.1.1 update_from_path(path, ignore=None, updatex=True, updatey=True) Update the bounds of the Bbox based on the passed in data. After updating, the bounds will have positive width and height; x0 and y0 will be the minimal values. path: a Path instance ignore: • when True, ignore the existing bounds of the Bbox. • when False, include the existing bounds of the Bbox. • when None, use the last value passed to ignore(). updatex: when True, update the x values updatey: when True, update the y values class TransformedBbox(bbox, transform) Bases: matplotlib.transforms.BboxBase A Bbox that is automatically transformed by a given transform. When either the child bounding box or transform changes, the bounds of this bbox will update accordingly. bbox: a child Bbox transform: a 2D Transform get_points() Get the points of the bounding box directly as a numpy array of the form: [[x0, y0], [x1, y1]]. class Transform() Bases: matplotlib.transforms.TransformNode The base class of all TransformNode instances that actually perform a transformation. All non-aﬃne transformations should be subclasses of this class. New aﬃne transformations should be subclasses of Affine2D. Subclasses of this class should override the following members (at minimum): •input_dims •output_dims •transform() •is_separable •has_inverse •inverted() (if has_inverse() can return True) If the transform needs to do something non-standard with mathplotlib.path.Path objects, such as adding curves where there were once line segments, it should override: •transform_path() Creates a new TransformNode. get_affine() Get the aﬃne part of this transform. 240 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 inverted() Return the corresponding inverse transformation. The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy. x === self.inverted().transform(self.transform(x)) transform(values) Performs the transformation on the given array of values. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_affine(values) Performs only the aﬃne part of this transformation on the given array of values. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally a no-op. In aﬃne transformations, this is equivalent to transform(values). Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_angles(angles, pts, radians=False, pushoﬀ=1.0000000000000001e-05) Performs transformation on a set of angles anchored at speciﬁc locations. The angles must be a column vector (i.e., numpy array). The pts must be a two-column numpy array of x,y positions (angle transforms currently only work in 2D). This array must have the same number of rows as angles. radians indicates whether or not input angles are given in radians (True) or degrees (False; the default). pushoﬀ is the distance to move away from pts for determining transformed angles (see discussion of method below). The transformed angles are returned in an array with the same size as angles. The generic version of this method uses a very generic algorithm that transforms pts, as well as locations very close to pts, to ﬁnd the angle in the transformed system. transform_non_affine(values) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_path(path) Returns a transformed copy of path. 27.1. matplotlib.transforms 241 Matplotlib, Release 0.99.1.1 path: a Path instance. In some cases, this transform may insert curves into the path that began as line segments. transform_path_affine(path) Returns a copy of path, transformed only by the aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values transform_path_non_affine(path) Returns a copy of path, transformed only by the non-aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values transform_point(point) A convenience function that returns the transformed copy of a single point. The point is given as a sequence of length input_dims. The transformed point is returned as a sequence of length output_dims. class TransformWrapper(child) Bases: matplotlib.transforms.Transform A helper class that holds a single child transform and acts equivalently to it. This is useful if a node of the transform tree must be replaced at run time with a transform of a diﬀerent type. This class allows that replacement to correctly trigger invalidation. Note that TransformWrapper instances must have the same input and output dimensions during their entire lifetime, so the child transform may only be replaced with another child transform of the same dimensions. child: A class:Transform instance. This child may later be replaced with set(). frozen() Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used. set(child) Replace the current child of this transform with another one. The new child must have the same number of input and output dimensions as the current child. class AffineBase() Bases: matplotlib.transforms.Transform The base class of all aﬃne transformations of any number of dimensions. get_affine() Get the aﬃne part of this transform. get_matrix() Get the underlying transformation matrix as a numpy array. 242 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 transform_non_affine(points) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_path_affine(path) Returns a copy of path, transformed only by the aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values transform_path_non_affine(path) Returns a copy of path, transformed only by the non-aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values class Affine2DBase() Bases: matplotlib.transforms.AffineBase The base class of all 2D aﬃne transformations. 2D aﬃne transformations are performed using a 3x3 numpy array: ace bdf 001 This class provides the read-only interface. For a mutable 2D aﬃne transformation, use Affine2D. Subclasses of this class will generally only need to override a constructor and get_matrix() that generates a custom 3x3 matrix. frozen() Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used. inverted() Return the corresponding inverse transformation. The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy. x === self.inverted().transform(self.transform(x)) static matrix_from_values(a, b, c, d, e, f ) (staticmethod) Create a new transformation matrix as a 3x3 numpy array of the form: 27.1. matplotlib.transforms 243 Matplotlib, Release 0.99.1.1 ace bdf 001 to_values() Return the values of the matrix as a sequence (a,b,c,d,e,f) transform(points) Performs only the aﬃne part of this transformation on the given array of values. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally a no-op. In aﬃne transformations, this is equivalent to transform(values). Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_affine(points) Performs only the aﬃne part of this transformation on the given array of values. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally a no-op. In aﬃne transformations, this is equivalent to transform(values). Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_point(point) A convenience function that returns the transformed copy of a single point. The point is given as a sequence of length input_dims. The transformed point is returned as a sequence of length output_dims. class Affine2D(matrix=None) Bases: matplotlib.transforms.Affine2DBase A mutable 2D aﬃne transformation. Initialize an Aﬃne transform from a 3x3 numpy ﬂoat array: ace bdf 001 If matrix is None, initialize with the identity transform. clear() Reset the underlying matrix to the identity transform. static from_values(a, b, c, d, e, f ) (staticmethod) Create a new Aﬃne2D instance from the given values: 244 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 ace bdf 001 get_matrix() Get the underlying transformation matrix as a 3x3 numpy array: ace bdf 001 static identity() (staticmethod) Return a new Affine2D object that is the identity transform. Unless this transform will be mutated later on, consider using the faster IdentityTransform class instead. rotate(theta) Add a rotation (in radians) to this transform in place. Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg(), translate() and scale(). rotate_around(x, y, theta) Add a rotation (in radians) around the point (x, y) in place. Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg(), translate() and scale(). rotate_deg(degrees) Add a rotation (in degrees) to this transform in place. Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg(), translate() and scale(). rotate_deg_around(x, y, degrees) Add a rotation (in degrees) around the point (x, y) in place. Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg(), translate() and scale(). scale(sx, sy=None) Adds a scale in place. If sy is None, the same scale is applied in both the x- and y-directions. Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg(), translate() and scale(). set(other) Set this transformation from the frozen copy of another Affine2DBase object. set_matrix(mtx) Set the underlying transformation matrix from a 3x3 numpy array: 27.1. matplotlib.transforms 245 Matplotlib, Release 0.99.1.1 ace bdf 001 translate(tx, ty) Adds a translation in place. Returns self, so this method can easily be chained with more calls to rotate(), rotate_deg(), translate() and scale(). class IdentityTransform() Bases: matplotlib.transforms.Affine2DBase A special class that does on thing, the identity transform, in a fast way. frozen() Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used. get_affine() Return the corresponding inverse transformation. The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy. x === self.inverted().transform(self.transform(x)) get_matrix() Get the underlying transformation matrix as a numpy array. inverted() Return the corresponding inverse transformation. The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy. x === self.inverted().transform(self.transform(x)) transform(points) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_affine(points) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). 246 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_non_affine(points) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_path(path) Returns a copy of path, transformed only by the non-aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values transform_path_affine(path) Returns a copy of path, transformed only by the non-aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values transform_path_non_affine(path) Returns a copy of path, transformed only by the non-aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values class BlendedGenericTransform(x_transform, y_transform) Bases: matplotlib.transforms.Transform A “blended” transform uses one transform for the x-direction, and another transform for the ydirection. This “generic” version can handle any given child transform in the x- and y-directions. Create a new “blended” transform using x_transform to transform the x-axis and y_transform to transform the y-axis. You will generally not call this constructor directly but use the blended_transform_factory() function instead, which can determine automatically which kind of blended transform to create. frozen() Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used. 27.1. matplotlib.transforms 247 Matplotlib, Release 0.99.1.1 get_affine() Get the aﬃne part of this transform. inverted() Return the corresponding inverse transformation. The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy. x === self.inverted().transform(self.transform(x)) transform(points) Performs the transformation on the given array of values. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_affine(points) Performs only the aﬃne part of this transformation on the given array of values. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally a no-op. In aﬃne transformations, this is equivalent to transform(values). Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_non_affine(points) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). class BlendedAffine2D(x_transform, y_transform) Bases: matplotlib.transforms.Affine2DBase A “blended” transform uses one transform for the x-direction, and another transform for the ydirection. This version is an optimization for the case where both child transforms are of type Affine2DBase. Create a new “blended” transform using x_transform to transform the x-axis and y_transform to transform the y-axis. Both x_transform and y_transform must be 2D aﬃne transforms. You will generally not call this constructor directly but use the blended_transform_factory() function instead, which can determine automatically which kind of blended transform to create. get_matrix() Get the underlying transformation matrix as a numpy array. 248 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 blended_transform_factory(x_transform, y_transform) Create a new “blended” transform using x_transform to transform the x-axis and y_transform to transform the y-axis. A faster version of the blended transform is returned for the case where both child transforms are aﬃne. class CompositeGenericTransform(a, b) Bases: matplotlib.transforms.Transform A composite transform formed by applying transform a then transform b. This “generic” version can handle any two arbitrary transformations. Create a new composite transform that is the result of applying transform a then transform b. You will generally not call this constructor directly but use the composite_transform_factory() function instead, which can automatically choose the best kind of composite transform instance to create. frozen() Returns a frozen copy of this transform node. The frozen copy will not update when its children change. Useful for storing a previously known state of a transform where copy.deepcopy() might normally be used. get_affine() Get the aﬃne part of this transform. inverted() Return the corresponding inverse transformation. The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy. x === self.inverted().transform(self.transform(x)) transform(points) Performs the transformation on the given array of values. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_affine(points) Performs only the aﬃne part of this transformation on the given array of values. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally a no-op. In aﬃne transformations, this is equivalent to transform(values). Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_non_affine(points) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). 27.1. matplotlib.transforms 249 Matplotlib, Release 0.99.1.1 In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_path(path) Returns a transformed copy of path. path: a Path instance. In some cases, this transform may insert curves into the path that began as line segments. transform_path_affine(path) Returns a copy of path, transformed only by the aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values transform_path_non_affine(path) Returns a copy of path, transformed only by the non-aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values class CompositeAffine2D(a, b) Bases: matplotlib.transforms.Affine2DBase A composite transform formed by applying transform a then transform b. This version is an optimization that handles the case where both a and b are 2D aﬃnes. Create a new composite transform that is the result of applying transform a then transform b. Both a and b must be instances of Affine2DBase. You will generally not call this constructor directly but use the composite_transform_factory() function instead, which can automatically choose the best kind of composite transform instance to create. get_matrix() Get the underlying transformation matrix as a numpy array. composite_transform_factory(a, b) Create a new composite transform that is the result of applying transform a then transform b. Shortcut versions of the blended transform are provided for the case where both child transforms are aﬃne, or one or the other is the identity transform. Composite transforms may also be created using the ‘+’ operator, e.g.: c=a+b class BboxTransform(boxin, boxout) Bases: matplotlib.transforms.Affine2DBase 250 Chapter 27. Working with transformations Matplotlib, Release 0.99.1.1 BboxTransform linearly transforms points from one Bbox to another Bbox. Create a new BboxTransform that linearly transforms points from boxin to boxout. get_matrix() Get the underlying transformation matrix as a numpy array. class BboxTransformTo(boxout) Bases: matplotlib.transforms.Affine2DBase BboxTransformTo is a transformation that linearly transforms points from the unit bounding box to a given Bbox. Create a new BboxTransformTo that linearly transforms points from the unit bounding box to boxout. get_matrix() Get the underlying transformation matrix as a numpy array. class BboxTransformFrom(boxin) Bases: matplotlib.transforms.Affine2DBase BboxTransformFrom linearly transforms points from a given Bbox to the unit bounding box. get_matrix() Get the underlying transformation matrix as a numpy array. class ScaledTranslation(xt, yt, scale_trans) Bases: matplotlib.transforms.Affine2DBase A transformation that translates by xt and yt, after xt and yt have been transformad by the given transform scale_trans. get_matrix() Get the underlying transformation matrix as a numpy array. class TransformedPath(path, transform) Bases: matplotlib.transforms.TransformNode A TransformedPath caches a non-aﬃne transformed copy of the Path. This cached copy is automatically updated when the non-aﬃne part of the transform changes. Create a new TransformedPath from the given Path and Transform. get_fully_transformed_path() Return a fully-transformed copy of the child path. get_transformed_path_and_affine() Return a copy of the child path, with the non-aﬃne part of the transform already applied, along with the aﬃne part of the path necessary to complete the transformation. get_transformed_points_and_affine() Return a copy of the child path, with the non-aﬃne part of the transform already applied, along with the aﬃne part of the path necessary to complete the transformation. Unlike get_transformed_path_and_affine(), no interpolation will be performed. 27.1. matplotlib.transforms 251 Matplotlib, Release 0.99.1.1 nonsingular(vmin, vmax, expander=0.001, tiny=1.0000000000000001e-15, increasing=True) Ensure the endpoints of a range are ﬁnite and not too close together. “too close” means the interval is smaller than ‘tiny’ times the maximum absolute value. If they are too close, each will be moved by the ‘expander’. If ‘increasing’ is True and vmin > vmax, they will be swapped, regardless of whether they are too close. If either is inf or -inf or nan, return - expander, expander. 252 Chapter 27. Working with transformations CHAPTER TWENTYEIGHT ADDING NEW SCALES AND PROJECTIONS TO MATPLOTLIB Matplotlib supports the addition of custom procedures that transform the data before it is displayed. There is an important distinction between two kinds of transformations. Separable transformations, working on a single dimension, are called “scales”, and non-separable transformations, that handle data in two or more dimensions at a time, are called “projections”. From the user’s perspective, the scale of a plot can be set with set_xscale() and set_xscale(). Projections can be chosen using the projection keyword argument to the plot() or subplot() functions, e.g.: plot(x, y, projection="custom") This document is intended for developers and advanced users who need to create new scales and projections for matplotlib. The necessary code for scales and projections can be included anywhere: directly within a plot script, in third-party code, or in the matplotlib source tree itself. 28.1 Creating a new scale Adding a new scale consists of deﬁning a subclass of matplotlib.scale.ScaleBase, that includes the following elements: • A transformation from data coordinates into display coordinates. • An inverse of that transformation. This is used, for example, to convert mouse positions from screen space back into data space. • A function to limit the range of the axis to acceptable values (limit_range_for_scale()). A log scale, for instance, would prevent the range from including values less than or equal to zero. • Locators (major and minor) that determine where to place ticks in the plot, and optionally, how to adjust the limits of the plot to some “good” values. Unlike limit_range_for_scale(), which is always enforced, the range setting here is only used when automatically setting the range of the plot. • Formatters (major and minor) that specify how the tick labels should be drawn. 253 Matplotlib, Release 0.99.1.1 Once the class is deﬁned, it must be registered with matplotlib so that the user can select it. A full-ﬂedged and heavily annotated example is in examples/api/custom_scale_example.py. There are also some classes in matplotlib.scale that may be used as starting points. 28.2 Creating a new projection Adding a new projection consists of deﬁning a subclass of matplotlib.axes.Axes, that includes the following elements: • A transformation from data coordinates into display coordinates. • An inverse of that transformation. This is used, for example, to convert mouse positions from screen space back into data space. • Transformations for the gridlines, ticks and ticklabels. Custom projections will often need to place these elements in special locations, and matplotlib has a facility to help with doing so. • Setting up default values (overriding cla()), since the defaults for a rectilinear axes may not be appropriate. • Deﬁning the shape of the axes, for example, an elliptical axes, that will be used to draw the background of the plot and for clipping any data elements. • Deﬁning custom locators and formatters for the projection. For example, in a geographic projection, it may be more convenient to display the grid in degrees, even if the data is in radians. • Set up interactive panning and zooming. This is left as an “advanced” feature left to the reader, but there is an example of this for polar plots in matplotlib.projections.polar. • Any additional methods for additional convenience or features. Once the class is deﬁned, it must be registered with matplotlib so that the user can select it. A full-ﬂedged and heavily annotated example is in examples/api/custom_projection_example.py. The polar plot functionality in matplotlib.projections.polar may also be of interest. 28.3 API documentation 28.3.1 matplotlib.scale class LinearScale(axis, **kwargs) Bases: matplotlib.scale.ScaleBase The default linear scale. get_transform() The transform for linear scaling is just the IdentityTransform. set_default_locators_and_formatters(axis) Set the locators and formatters to reasonable defaults for linear scaling. 254 Chapter 28. Adding new scales and projections to matplotlib Matplotlib, Release 0.99.1.1 class LogScale(axis, **kwargs) Bases: matplotlib.scale.ScaleBase A standard logarithmic scale. Care is taken so non-positive values are not plotted. For computational eﬃciency (to push as much as possible to Numpy C code in the common cases), this scale provides diﬀerent transforms depending on the base of the logarithm: •base 10 (Log10Transform) •base 2 (Log2Transform) •base e (NaturalLogTransform) •arbitrary base (LogTransform) basex/basey: The base of the logarithm nonposx/nonposy: [’mask’ | ‘clip’ ] non-positive values in x or y can be masked as invalid, or clipped to a very small positive number subsx/subsy: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] will place 10 logarithmically spaced minor ticks between each major tick. get_transform() Return a Transform instance appropriate for the given logarithm base. limit_range_for_scale(vmin, vmax, minpos) Limit the domain to positive values. set_default_locators_and_formatters(axis) Set the locators and formatters to specialized versions for log scaling. class ScaleBase() Bases: object The base class for all scales. Scales are separable transformations, working on a single dimension. Any subclasses will want to override: •name •get_transform() And optionally: • set_default_locators_and_formatters() • limit_range_for_scale() get_transform() Return the Transform object associated with this scale. limit_range_for_scale(vmin, vmax, minpos) Returns the range vmin, vmax, possibly limited to the domain supported by this scale. 28.3. API documentation 255 Matplotlib, Release 0.99.1.1 minpos should be the minimum positive value in the data. This is used by log scales to determine a minimum value. set_default_locators_and_formatters(axis) Set the Locator and Formatter objects on the given axis to match this scale. class SymmetricalLogScale(axis, **kwargs) Bases: matplotlib.scale.ScaleBase The symmetrical logarithmic scale is logarithmic in both the positive and negative directions from the origin. Since the values close to zero tend toward inﬁnity, there is a need to have a range around zero that is linear. The parameter linthresh allows the user to specify the size of this range (-linthresh, linthresh). basex/basey: The base of the logarithm linthreshx/linthreshy: The range (-x, x) within which the plot is linear (to avoid having the plot go to inﬁnity around zero). subsx/subsy: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] will place 10 logarithmically spaced minor ticks between each major tick. get_transform() Return a SymmetricalLogTransform instance. set_default_locators_and_formatters(axis) Set the locators and formatters to specialized versions for symmetrical log scaling. get_scale_docs() Helper function for generating docstrings related to scales. register_scale(scale_class) Register a new kind of scale. scale_class must be a subclass of ScaleBase. scale_factory(scale, axis, **kwargs) Return a scale class by name. ACCEPTS: [ linear | log | symlog ] 28.3.2 matplotlib.projections class ProjectionRegistry() Bases: object Manages the set of projections available to the system. get_projection_class(name) Get a projection class from its name. get_projection_names() Get a list of the names of all projections currently registered. 256 Chapter 28. Adding new scales and projections to matplotlib Matplotlib, Release 0.99.1.1 register(*projections) Register a new set of projection(s). get_projection_class(projection=None) Get a projection class from its name. If projection is None, a standard rectilinear projection is returned. get_projection_names() Get a list of acceptable projection names. projection_factory(projection, ﬁgure, rect, **kwargs) Get a new projection instance. projection is a projection name. ﬁgure is a ﬁgure to add the axes to. rect is a Bbox object specifying the location of the axes within the ﬁgure. Any other kwargs are passed along to the speciﬁc projection constructor being used. matplotlib.projections.polar class PolarAxes(*args, **kwargs) Bases: matplotlib.axes.Axes A polar graph projection, where the input dimensions are theta, r. Theta starts pointing east and goes anti-clockwise. class InvertedPolarTransform() Bases: matplotlib.transforms.Transform The inverse of the polar transform, mapping Cartesian coordinate space x and y back to theta and r. Creates a new TransformNode. inverted() Return the corresponding inverse transformation. The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy. x === self.inverted().transform(self.transform(x)) transform(xy) Performs the transformation on the given array of values. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). class PolarAffine(scale_transform, limits) Bases: matplotlib.transforms.Affine2DBase 28.3. API documentation 257 Matplotlib, Release 0.99.1.1 The aﬃne part of the polar projection. Scales the output so that maximum radius rests on the edge of the axes circle. limits is the view limit of the data. The only part of its bounds that is used is ymax (for the radius maximum). The theta range is always ﬁxed to (0, 2π). get_matrix() Get the underlying transformation matrix as a numpy array. class PolarTransform() Bases: matplotlib.transforms.Transform The base polar transform. This handles projection theta and r into Cartesian coordinate space x and y, but does not perform the ultimate aﬃne transformation into the correct position. Creates a new TransformNode. inverted() Return the corresponding inverse transformation. The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy. x === self.inverted().transform(self.transform(x)) transform(tr) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_non_affine(tr) Performs only the non-aﬃne part of the transformation. transform(values) is always equivalent to transform_affine(transform_non_affine(values)). In non-aﬃne transformations, this is generally equivalent to transform(values). In aﬃne transformations, this is always a no-op. Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims). transform_path(path) Returns a copy of path, transformed only by the non-aﬃne part of this transform. path: a Path instance. transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(va transform_path_non_affine(path) Returns a copy of path, transformed only by the non-aﬃne part of this transform. path: a Path instance. 258 Chapter 28. Adding new scales and projections to matplotlib Matplotlib, Release 0.99.1.1 transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(va class RadialLocator(base) Bases: matplotlib.ticker.Locator Used to locate radius ticks. Ensures that all ticks are strictly positive. For all other tasks, it delegates to the base Locator (which may be diﬀerent depending on the scale of the r-axis. class ThetaFormatter() Bases: matplotlib.ticker.Formatter Used to format the theta tick labels. Converts the native unit of radians into degrees and adds a degree symbol (°). can_zoom() Return True if this axes support the zoom box format_coord(theta, r) Return a format string formatting the coordinate using Unicode characters. get_data_ratio() Return the aspect ratio of the data itself. For a polar plot, this should always be 1.0 set_rgrids(radii, labels=None, angle=None, rpad=None, fmt=None, **kwargs) Set the radial locations and labels of the r grids. The labels will appear at radial distances radii at the given angle in degrees. labels, if not None, is a len(radii) list of strings of the labels to use at each radius. If labels is None, the built-in formatter will be used. rpad is a fraction of the max of radii which will pad each of the radial labels in the radial direction. Return value is a list of tuples (line, label), where line is Line2D instances and the label is Text instances. kwargs are optional text properties for the labels: Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name 28.3. API documentation Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] 259 Matplotlib, Release 0.99.1.1 Table 28.1 – continued from figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number ACCEPTS: sequence of ﬂoats set_rscale(value, **kwargs) call signature: set_yscale(value) Set the scaling of the y-axis: ‘linear’ | ‘log’ | ‘symlog’ ACCEPTS: [’linear’ | ‘log’ | ‘symlog’] Diﬀerent kwargs are accepted, depending on the scale: ‘linear’ ‘log’ basex/basey: The base of the logarithm nonposx/nonposy: [’mask’ | ‘clip’ ] non-positive values in x or y can be masked as invalid, or clipped to a very small positive number 260 Chapter 28. Adding new scales and projections to matplotlib Matplotlib, Release 0.99.1.1 subsx/subsy: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] will place 10 logarithmically spaced minor ticks between each major tick. ‘symlog’ basex/basey: The base of the logarithm linthreshx/linthreshy: The range (-x, x) within which the plot is linear (to avoid having the plot go to inﬁnity around zero). subsx/subsy: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] will place 10 logarithmically spaced minor ticks between each major tick. set_rticks(ticks, minor=False) Set the y ticks with list of ticks ACCEPTS: sequence of ﬂoats Keyword arguments: minor: [ False | True ] Sets the minor ticks if True set_thetagrids(angles, labels=None, frac=None, fmt=None, **kwargs) Set the angles at which to place the theta grids (these gridlines are equal along the theta dimension). angles is in degrees. labels, if not None, is a len(angles) list of strings of the labels to use at each angle. If labels is None, the labels will be fmt % angle frac is the fraction of the polar axes radius at which to place the label (1 is the edge). Eg. 1.05 is outside the axes and 0.95 is inside the axes. Return value is a list of tuples (line, label), where line is Line2D instances and the label is Text instances. kwargs are optional text properties for the labels: Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains 28.3. API documentation Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function 261 Matplotlib, Release 0.99.1.1 family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder Table 28.2 – continued from [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number ACCEPTS: sequence of ﬂoats 262 Chapter 28. Adding new scales and projections to matplotlib CHAPTER TWENTYNINE DOCS OUTLINE Proposed chapters for the docs, who has responsibility for them, and who reviews them. The “unit” doesn’t have to be a full chapter (though in some cases it will be), it may be a chapter or a section in a chapter. User’s guide unit plotting 2-D arrays colormapping quiver plots histograms bar / errorbar x-y plots time series plots date plots working with data custom ticking masked data patches legends animation collections text - mathtext text - usetex text - annotations fonts et al pyplot tut conﬁguration win32 install os x install linux install artist api event handling navigation interactive usage widgets ui - gtk Author Eric Eric Eric Manuel ? ? ? ? John John ? Eric ? ? John ? Michael Darren John Michael ? John Darren Charlie ? Charlie ? Darren John John John ? ? ? Status Reviewer has author Perry ? Darren has author ? has author ? no author Erik Tollerud ? no author ? no author Darren no author ? has author ? has author Darren no author ? has author ? no author ? no author ? has author ? no author ? accepted John accepted John submitted ? no author Darren submitted Eric submitted ? no author Darren no author ? has author ? submitted ? submitted ? submitted ? no author ? no author ? no author ? Continued on next page 263 Matplotlib, Release 0.99.1.1 Table 29.1 – continued from previous page ui - wx ? no author ? ui - tk ? no author ? ui - qt Darren has author ? backend - pdf Jouni ? no author ? backend - ps Darren has author ? backend - svg ? no author ? backend - agg ? no author ? backend - cairo ? no author ? Here is the ouline for the dev guide, much less ﬂeshed out Developer’s guide unit the renderer the canvas the artist transforms documenting mpl coding guide and_much_more Author John John John Michael Darren John ? Status has author has author has author submitted submitted complete ? Reviewer Michael ? ? ? John John, Eric, Mike? Eric ? We also have some work to do converting docstrings to ReST for the API Reference. Please be sure to follow the few guidelines described in Formatting. Once it is converted, please include the module in the API documentation and update the status in the table to “converted”. Once docstring conversion is complete and all the modules are available in the docs, we can ﬁgure out how best to organize the API Reference and continue from there. Module backend_agg backend_cairo backend_cocoa backend_emf backend_ﬂtkagg backend_gdk backend_gtk backend_gtkagg backend_gtkcairo backend_mixed backend_pdf backend_ps backend_qt backend_qtagg backend_qt4 backend_qt4agg backend_svg backend_template backend_tkagg backend_wx 264 Author Darren Darren Darren Darren Darren Status needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion needs conversion Continued on next page Chapter 29. Docs outline Matplotlib, Release 0.99.1.1 Table 29.2 – continued from previous page backend_wxagg needs conversion backends/tkagg needs conversion conﬁg/checkdep Darren needs conversion conﬁg/cutils Darren needs conversion conﬁg/mplconﬁg Darren needs conversion conﬁg/mpltraits Darren needs conversion conﬁg/rcparams Darren needs conversion conﬁg/rcsetup Darren needs conversion conﬁg/tconﬁg Darren needs conversion conﬁg/verbose Darren needs conversion projections/__init__ Mike converted projections/geo Mike converted (not included–experimental) projections/polar Mike converted afm converted artist converted axes converted axis converted backend_bases converted cbook converted cm converted collections converted colorbar converted colors converted contour needs conversion dates Darren needs conversion dviread Darren needs conversion ﬁgure Darren needs conversion ﬁnance Darren needs conversion font_manager Mike converted fontconﬁg_pattern Mike converted image needs conversion legend needs conversion lines Mike & ??? converted mathtext Mike converted mlab John/Mike converted mpl N/A patches Mike converted path Mike converted pylab N/A pyplot converted quiver needs conversion rcsetup needs conversion scale Mike converted table needs conversion texmanager Darren needs conversion text Mike converted Continued on next page 265 Matplotlib, Release 0.99.1.1 ticker transforms type1font units widgets Table 29.2 – continued from previous page John converted Mike converted needs conversion needs conversion needs conversion And we might want to do a similar table for the FAQ, but that may also be overkill... If you agree to author a unit, remove the question mark by your name (or add your name if there is no candidate), and change the status to “has author”. Once you have completed draft and checked it in, you can change the status to “submitted” and try to ﬁnd a reviewer if you don’t have one. The reviewer should read your chapter, test it for correctness (eg try your examples) and change the status to “complete” when done. You are free to lift and convert as much material from the web site or the existing latex user’s guide as you see ﬁt. The more the better. The UI chapters should give an example or two of using mpl with your GUI and any relevant info, such as version, installation, conﬁg, etc... The backend chapters should cover backend speciﬁc conﬁguration (eg PS only options), what features are missing, etc... Please feel free to add units, volunteer to review or author a chapter, etc... It is probably easiest to be an editor. Once you have signed up to be an editor, if you have an author pester the author for a submission every so often. If you don’t have an author, ﬁnd one, and then pester them! Your only two responsibilities are getting your author to produce and checking their work, so don’t be shy. You do not need to be an expert in the subject you are editing – you should know something about it and be willing to read, test, give feedback and pester! 29.1 Reviewer notes If you want to make notes for the authorwhen you have reviewed a submission, you can put them here. As the author cleans them up or addresses them, they should be removed. 29.1.1 mathtext user’s guide– reviewed by JDH This looks good (see Writing mathematical expressions) – there are a few minor things to close the book on this chapter: 1. The main thing to wrap this up is getting the mathtext module ported over to rest and included in the API so the links from the user’s guide tutorial work. • There’s nothing in the mathtext module that I really consider a “public” API (i.e. that would be useful to people just doing plots). If mathtext.py were to be documented, I would put it in the developer’s docs. Maybe I should just take the link in the user’s guide out. - MGD 2. This section might also beneﬁt from a little more detail on the customizations that are possible (eg an example ﬂeshing out the rc options a little bit). Admittedly, this is pretty clear from readin ghte rc ﬁle, but it might be helpful to a newbie. 266 Chapter 29. Docs outline Matplotlib, Release 0.99.1.1 • The only rcParam that is currently useful is mathtext.fontset, which is documented here. The others only apply when mathtext.fontset == ‘custom’, which I’d like to declare “unsupported”. It’s really hard to get a good set of math fonts working that way, though it might be useful in a bind when someone has to use a speciﬁc wacky font for mathtext and only needs basics, like sub/superscripts. - MGD 3. There is still a TODO in the ﬁle to include a complete list of symbols • Done. It’s pretty extensive, thanks to STIX... - MGD 29.1. Reviewer notes 267 Matplotlib, Release 0.99.1.1 268 Chapter 29. Docs outline Part IV The Matplotlib API 269 CHAPTER THIRTY API CHANGES This chapter is a log of changes to matplotlib that aﬀect the outward-facing API. If updating matplotlib breaks your scripts, this list may help describe what changes may be necessary in your code. • You can now print several ﬁgures to one pdf ﬁle. See the docstrings of the class matplotlib.backends.backend_pdf.PdfPages for more information. • Removed conﬁgobj and enthought.traits packages, which are only required by the experimental traited conﬁg and are somewhat out of date. If needed, install them independently. 30.1 Changes in 0.99 • pylab no longer provides a load and save function. These are available in matplotlib.mlab, or you can use numpy.loadtxt and numpy.savetxt for text ﬁles, or np.save and np.load for binary numpy arrays. • User-generated colormaps can now be added to the set recognized by matplotlib.cm.get_cmap(). Colormaps can be made the default and applied to the current image using matplotlib.pyplot.set_cmap(). • changed use_mrecords default to False in mlab.csv2rec since this is partially broken • Axes instances no longer have a “frame” attribute. Instead, use the new “spines” attribute. Spines is a dictionary where the keys are the names of the spines (e.g. ‘left’,’right’ and so on) and the values are the artists that draw the spines. For normal (rectilinear) axes, these artists are Line2D instances. For other axes (such as polar axes), these artists may be Patch instances. • Polar plots no longer accept a resolution kwarg. Instead, each Path must specify its own number of interpolation steps. This is unlikely to be a user-visible change – if interpolation of data is required, that should be done before passing it to matplotlib. 30.2 Changes for 0.98.x • psd(), csd(), and cohere() will now automatically wrap negative frequency components to the beginning of the returned arrays. This is much more sensible behavior and makes them consistent with specgram(). The previous behavior was more of an oversight than a design decision. 271 Matplotlib, Release 0.99.1.1 • Added new keyword parameters nonposx, nonposy to matplotlib.axes.Axes methods that set log scale parameters. The default is still to mask out non-positive values, but the kwargs accept ‘clip’, which causes non-positive values to be replaced with a very small positive value. • Added new matplotlib.pyplot.fignum_exists() and matplotlib.pyplot.get_fignums(); they merely expose information that had been hidden in matplotlib._pylab_helpers. • Deprecated numerix package. • Added new matplotlib.image.imsave() and exposed it to the matplotlib.pyplot interface. • Remove support for pyExcelerator in exceltools – use xlwt instead • Changed the defaults of acorr and xcorr to use usevlines=True, maxlags=10 and normed=True since these are the best defaults • Following keyword parameters for matplotlib.label.Label are now deprecated and new set of parameters are introduced. The new parameters are given as a fraction of the font-size. Also, scatteryoﬀsets, fancybox and columnspacing are added as keyword parameters. Deprecated pad labelsep handlelen handlestextsep axespad New borderpad labelspacing handlelength handletextpad borderaxespad • Removed the conﬁgobj and experimental traits rc support • Modiﬁed matplotlib.mlab.psd(), matplotlib.mlab.csd(), matplotlib.mlab.cohere(), and matplotlib.mlab.specgram() to scale one-sided densities by a factor of 2. Also, optionally scale the densities by the sampling frequency, which gives true values of densities that can be integrated by the returned frequency values. This also gives better MatLab compatibility. The corresponding matplotlib.axes.Axes methods and matplotlib.pyplot functions were updated as well. • Font lookup now uses a nearest-neighbor approach rather than an exact match. Some fonts may be diﬀerent in plots, but should be closer to what was requested. • matplotlib.axes.Axes.set_xlim(), matplotlib.axes.Axes.set_ylim() now return a copy of the viewlim array to avoid modify-in-place surprises. • matplotlib.afm.AFM.get_fullname() and matplotlib.afm.AFM.get_familyname() no longer raise an exception if the AFM ﬁle does not specify these optional attributes, but returns a guess based on the required FontName attribute. • Changed precision kwarg in matplotlib.pyplot.spy(); default is 0, and the string value ‘present’ is used for sparse arrays only to show ﬁlled locations. • matplotlib.collections.EllipseCollection added. • Added angles kwarg to matplotlib.pyplot.quiver() for more ﬂexible speciﬁcation of the arrow angles. • Deprecated (raise NotImplementedError) all the mlab2 functions from matplotlib.mlab out of concern that some of them were not clean room implementations. 272 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 • Methods matplotlib.collections.Collection.get_offsets() and matplotlib.collections.Collection.set_offsets() added to Collection base class. • matplotlib.figure.Figure.figurePatch renamed matplotlib.figure.Figure.patch; matplotlib.axes.Axes.axesPatch renamed matplotlib.axes.Axes.patch; matplotlib.axes.Axes.axesFrame renamed matplotlib.axes.Axes.frame. matplotlib.axes.Axes.get_frame(), which returns matplotlib.axes.Axes.patch, is deprecated. • Changes in the matplotlib.contour.ContourLabeler attributes (matplotlib.pyplot.clabel() function) so that they all have a form like .labelAttribute. The three attributes that are most likely to be used by end users, .cl, .cl_xy and .cl_cvalues have been maintained for the moment (in addition to their renamed versions), but they are deprecated and will eventually be removed. • Moved several functions in matplotlib.mlab and matplotlib.cbook into a separate module matplotlib.numerical_methods because they were unrelated to the initial purpose of mlab or cbook and appeared more coherent elsewhere. 30.3 Changes for 0.98.1 • Removed broken matplotlib.axes3d support and replaced it with a non-implemented error pointing to 0.91.x 30.4 Changes for 0.98.0 • matplotlib.image.imread() now no longer always returns RGBA data—if the image is luminance or RGB, it will return a MxN or MxNx3 array if possible. Also uint8 is no longer always forced to ﬂoat. • Rewrote the matplotlib.cm.ScalarMappable callback infrastructure to use matplotlib.cbook.CallbackRegistry rather than custom callback handling. Any users of matplotlib.cm.ScalarMappable.add_observer() of the ScalarMappable should use the matplotlib.cm.ScalarMappable.callbacks CallbackRegistry instead. • New axes function and Axes method provide control over the color cycle: matplotlib.axes.set_default_color_cycle() matplotlib.axes.Axes.set_color_cycle(). plot and • matplotlib now requires Python 2.4, so matplotlib.cbook will no longer provide set, enumerate(), reversed() or izip() compatibility functions. • In Numpy 1.0, bins are speciﬁed by the left edges only. The axes method matplotlib.axes.Axes.hist() now uses future Numpy 1.3 semantics for histograms. Providing binedges, the last value gives the upper-right edge now, which was implicitly set to +inﬁnity in Numpy 1.0. This also means that the last bin doesn’t contain upper outliers any more by default. • New axes method and pyplot function, hexbin(), is an alternative to scatter() for large datasets. It makes something like a pcolor() of a 2-D histogram, but uses hexagonal bins. 30.3. Changes for 0.98.1 273 Matplotlib, Release 0.99.1.1 • New kwarg, symmetric, in matplotlib.ticker.MaxNLocator allows one require an axis to be centered around zero. • Toolkits must now be imported from mpl_toolkits (not matplotlib.toolkits) 30.4.1 Notes about the transforms refactoring A major new feature of the 0.98 series is a more ﬂexible and extensible transformation infrastructure, written in Python/Numpy rather than a custom C extension. The primary goal of this refactoring was to make it easier to extend matplotlib to support new kinds of projections. This is mostly an internal improvement, and the possible user-visible changes it allows are yet to come. See matplotlib.transforms for a description of the design of the new transformation framework. For eﬃciency, many of these functions return views into Numpy arrays. This means that if you hold on to a reference to them, their contents may change. If you want to store a snapshot of their current values, use the Numpy array method copy(). The view intervals are now stored only in one place – in the matplotlib.axes.Axes instance, not in the locator instances as well. This means locators must get their limits from their matplotlib.axis.Axis, which in turn looks up its limits from the Axes. If a locator is used temporarily and not assigned to an Axis or Axes, (e.g. in matplotlib.contour), a dummy axis must be created to store its bounds. Call matplotlib.ticker.Locator.create_dummy_axis() to do so. The functionality of Pbox has been merged with Bbox. Its methods now all return copies rather than modifying in place. The following lists many of the simple changes necessary to update code from the old transformation framework to the new one. In particular, methods that return a copy are named with a verb in the past tense, whereas methods that alter an object in place are named with a verb in the present tense. 274 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 matplotlib.transforms Old method New method Bbox.get_bounds() transforms.Bbox.bounds Bbox.width() transforms.Bbox.width Bbox.height() transforms.Bbox.height Bbox.intervalx().get_bounds() transforms.Bbox.intervalx Bbox.intervalx().set_bounds() [Bbox.intervalx is now a property.] Bbox.intervaly().get_bounds() transforms.Bbox.intervaly Bbox.intervaly().set_bounds() [Bbox.intervaly is now a property.] Bbox.xmin() transforms.Bbox.x0 or transforms.Bbox.xmin 1 Bbox.ymin() transforms.Bbox.y0 or transforms.Bbox.ymin 1 Bbox.xmax() transforms.Bbox.x1 or transforms.Bbox.xmax 1 Bbox.ymax() transforms.Bbox.y1 or transforms.Bbox.ymax 1 Bbox.overlaps(bboxes)Bbox.count_overlaps(bboxes) bbox_all(bboxes) Bbox.union(bboxes) [transforms.Bbox.union() is a staticmethod.] lbwh_to_bbox(l, b, Bbox.from_bounds(x0, y0, w, h) [transforms.Bbox.from_bounds() is a w, h) staticmethod.] inBbox.inverse_transformed(trans) verse_transform_bbox(trans, bbox) Interinterval_contains_open(tuple, v) val.contains_open(v) Interval.contains(v) interval_contains(tuple, v) idenmatplotlib.transforms.IdentityTransform tity_transform() blend_xy_sep_transform(xtrans, blended_transform_factory(xtrans, ytrans) ytrans) scale_transform(xs, Aﬃne2D().scale(xs[, ys]) ys) get_bbox_transform(boxin, BboxTransform(boxin, boxout) or BboxTransformFrom(boxin) or boxout) BboxTransformTo(boxout) TransTransform.transform(points) form.seq_xy_tup(points) TransTransform.inverted().transform(points) form.inverse_xy_tup(points) 1 The Bbox is bound by the points (x0, y0) to (x1, y1) and there is no deﬁned order to these points, that is, x0 is not necessarily the left edge of the box. To get the left edge of the Bbox, use the read-only property xmin. 30.4. Changes for 0.98.0 275 Matplotlib, Release 0.99.1.1 matplotlib.axes Old method New method Axes.get_position() matplotlib.axes.Axes.get_position() 2 Axes.set_position() matplotlib.axes.Axes.set_position() 3 Axes.toggle_log_lineary() matplotlib.axes.Axes.set_yscale() 4 Subplot class removed. The Polar class has moved to matplotlib.projections.polar. matplotlib.artist Old method New method Artist.set_clip_path(path) Artist.set_clip_path(path, transform) 5 matplotlib.collections Old method linestyle New method linestyles 6 matplotlib.colors Old method New method ColorConverColorConvertor.to_rgba_array(c) tor.to_rgba_list(c) [matplotlib.colors.ColorConvertor.to_rgba_array() returns an Nx4 Numpy array of RGBA color quadruples.] matplotlib.contour Old method Contour._segments New method matplotlib.contour.Contour.get_paths‘() [Returns a list of matplotlib.path.Path instances.] 2 matplotlib.axes.Axes.get_position() used to return a list of points, now it returns a matplotlib.transforms.Bbox instance. 3 matplotlib.axes.Axes.set_position() now accepts either four scalars or a matplotlib.transforms.Bbox instance. 4 Since the recfactoring allows for more than two scale types (‘log’ or ‘linear’), it no longer makes sense to have a toggle. Axes.toggle_log_lineary() has been removed. 5 matplotlib.artist.Artist.set_clip_path() now accepts a matplotlib.path.Path instance and a matplotlib.transforms.Transform that will be applied to the path immediately before clipping. 6 Linestyles are now treated like all other collection attributes, i.e. a single value or multiple values may be provided. 276 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 matplotlib.figure Old method Figure.dpi.get() / Figure.dpi.set() New method matplotlib.figure.Figure.dpi (a property) matplotlib.patches Old method New method Patch.get_verts() matplotlib.patches.Patch.get_path() [Returns a matplotlib.path.Path instance] matplotlib.backend_bases Old method New method GraphicsConGraphicsContext.set_clip_rectangle(bbox) text.set_clip_rectangle(tuple) GraphicsConGraphicsContext.get_clip_path() 7 text.get_clip_path() GraphicsConGraphicsContext.set_clip_path() 8 text.set_clip_path() RendererBase New methods: • draw_path(self, gc, path, transform, rgbFace) • draw_markers(self, gc, marker_path, marker_trans, path, trans, rgbFace) • draw_path_collection(self, master_transform, cliprect, clippath, clippath_trans, paths, all_transforms, offsets, offsetTrans, facecolors, edgecolors, linewidths, linestyles, antialiaseds) [optional] Changed methods: • draw_image(self, x, y, im, bbox) is now draw_image(self, x, y, im, bbox, clippath, clippath_trans) Removed methods: • draw_arc • draw_line_collection • draw_line 7 matplotlib.backend_bases.GraphicsContext.get_clip_path() returns a tuple of the form (path, aﬃne_transform), where path is a matplotlib.path.Path instance and aﬃne_transform is a matplotlib.transforms.Affine2D instance. 8 matplotlib.backend_bases.GraphicsContext.set_clip_path() now only accepts a matplotlib.transforms.TransformedPath instance. 30.4. Changes for 0.98.0 277 Matplotlib, Release 0.99.1.1 • draw_lines • draw_point • draw_quad_mesh • draw_poly_collection • draw_polygon • draw_rectangle • draw_regpoly_collection 30.5 Changes for 0.91.2 • For csv2rec(), checkrows=0 is the new default indicating all rows will be checked for type inference • A warning is issued when an image is drawn on log-scaled axes, since it will not log-scale the image data. • Moved rec2gtk() to matplotlib.toolkits.gtktools • Moved rec2excel() to matplotlib.toolkits.exceltools • Removed, dead/experimental matplotlib.__init__ ExampleInfo, Namespace and Importer code from 30.6 Changes for 0.91.1 30.7 Changes for 0.91.0 • Changed cbook.is_file_like() to cbook.is_writable_file_like() and corrected behavior. • Added ax kwarg to pyplot.colorbar() and Figure.colorbar() so that one can specify the axes object from which space for the colorbar is to be taken, if one does not want to make the colorbar axes manually. • Changed cbook.reversed() so it yields a tuple rather than a (index, tuple). This agrees with the python reversed builtin, and cbook only deﬁnes reversed if python doesnt provide the builtin. • Made skiprows=1 the default on csv2rec() • The gd and paint backends have been deleted. • The errorbar method and function now accept additional kwargs so that upper and lower limits can be indicated by capping the bar with a caret instead of a straight line segment. • The matplotlib.dviread ﬁle now has a parser for ﬁles like psfonts.map and pdftex.map, to map TeX font names to external ﬁles. 278 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 • The ﬁle matplotlib.type1font contains a new class for Type 1 fonts. Currently it simply reads pfa and pfb format ﬁles and stores the data in a way that is suitable for embedding in pdf ﬁles. In the future the class might actually parse the font to allow e.g. subsetting. • matplotlib.FT2Font now supports FT_Attach_File(). In practice this can be used to read an afm ﬁle in addition to a pfa/pfb ﬁle, to get metrics and kerning information for a Type 1 font. • The AFM class now supports querying CapHeight and stem widths. The get_name_char method now has an isord kwarg like get_width_char. • Changed pcolor() default to shading=’ﬂat’; but as noted now in the docstring, it is preferable to simply use the edgecolor kwarg. • The mathtext font commands (\cal, \rm, \it, \tt) now behave as TeX does: they are in eﬀect until the next font change command or the end of the grouping. Therefore uses of $\cal{R}$ should be changed to ${\cal R}$. Alternatively, you may use the new LaTeX-style font commands (\mathcal, \mathrm, \mathit, \mathtt) which do aﬀect the following group, eg. $\mathcal{R}$. • Text creation commands have a new default linespacing and a new linespacing kwarg, which is a multiple of the maximum vertical extent of a line of ordinary text. The default is 1.2; linespacing=2 would be like ordinary double spacing, for example. • Changed default kwarg in matplotlib.colors.Normalize.__init__‘() to clip=False; clipping silently defeats the purpose of the special over, under, and bad values in the colormap, thereby leading to unexpected behavior. The new default should reduce such surprises. • Made the emit property of set_xlim() and set_ylim() True by default; removed the Axes custom callback handling into a ‘callbacks’ attribute which is a CallbackRegistry instance. This now supports the ‘xlim_changed’ and ‘ylim_changed’ Axes events. 30.8 Changes for 0.90.1 The file dviread.py has a (very limited and fragile) dvi reader for usetex support. The API might change in the future so don’t depend on it yet. Removed deprecated support for a float value as a gray-scale; now it must be a string, like ’0.5’. Added alpha kwarg to ColorConverter.to_rgba_list. New method set_bounds(vmin, vmax) for formatters, locators sets the viewInterval and dataInterval from floats. Removed deprecated colorbar_classic. Line2D.get_xdata and get_ydata valid_only=False kwarg is replaced by orig=True. When True, it returns the original data, otherwise the processed data (masked, converted) Some modifications to the units interface. 30.8. Changes for 0.90.1 279 Matplotlib, Release 0.99.1.1 units.ConversionInterface.tickers renamed to units.ConversionInterface.axisinfo and it now returns a units.AxisInfo object rather than a tuple. This will make it easier to add axis info functionality (eg I added a default label on this iteration) w/o having to change the tuple length and hence the API of the client code everytime new functionality is added. Also, units.ConversionInterface.convert_to_value is now simply named units.ConversionInterface.convert. Axes.errorbar uses Axes.vlines and Axes.hlines to draw its error limits int he vertical and horizontal direction. As you’ll see in the changes below, these funcs now return a LineCollection rather than a list of lines. The new return signature for errorbar is ylins, caplines, errorcollections where errorcollections is a xerrcollection, yerrcollection Axes.vlines and Axes.hlines now create and returns a LineCollection, not a list of lines. This is much faster. The kwarg signature has changed, so consult the docs MaxNLocator accepts a new Boolean kwarg (’integer’) to force ticks to integer locations. Commands that pass an argument to the Text constructor or to Text.set_text() now accept any object that can be converted with ’%s’. This affects xlabel(), title(), etc. Barh now takes a **kwargs dict instead of most of the old arguments. This helps ensure that bar and barh are kept in sync, but as a side effect you can no longer pass e.g. color as a positional argument. ft2font.get_charmap() now returns a dict that maps character codes to glyph indices (until now it was reversed) Moved data files into lib/matplotlib so that setuptools’ develop mode works. Re-organized the mpl-data layout so that this source structure is maintained in the installation. (I.e. the ’fonts’ and ’images’ sub-directories are maintained in site-packages.). Suggest removing site-packages/matplotlib/mpl-data and ~/.matplotlib/ttffont.cache before installing 30.9 Changes for 0.90.0 All artists now implement a "pick" method which users should not call. Rather, set the "picker" property of any artist you want to pick on (the epsilon distance in points for a hit test) and register with the "pick_event" callback. See examples/pick_event_demo.py for details 280 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 Bar, barh, and hist have "log" binary kwarg: log=True sets the ordinate to a log scale. Boxplot can handle a list of vectors instead of just an array, so vectors can have different lengths. Plot can handle 2-D x and/or y; it plots the columns. Added linewidth kwarg to bar and barh. Made the default Artist._transform None (rather than invoking identity_transform for each artist only to have it overridden later). Use artist.get_transform() rather than artist._transform, even in derived classes, so that the default transform will be created lazily as needed New LogNorm subclass of Normalize added to colors.py. All Normalize subclasses have new inverse() method, and the __call__() method has a new clip kwarg. Changed class names in colors.py to match convention: normalize -> Normalize, no_norm -> NoNorm. Old names are still available for now. Removed obsolete pcolor_classic command and method. Removed lineprops and markerprops from the Annotation code and replaced them with an arrow configurable with kwarg arrowprops. See examples/annotation_demo.py - JDH 30.10 Changes for 0.87.7 Completely reworked the annotations API because I found the old API cumbersome. The new design is much more legible and easy to read. See matplotlib.text.Annotation and examples/annotation_demo.py markeredgecolor and markerfacecolor cannot be configured in matplotlibrc any more. Instead, markers are generally colored automatically based on the color of the line, unless marker colors are explicitely set as kwargs - NN Changed default comment character for load to ’#’ - JDH math_parse_s_ft2font_svg from mathtext.py & mathtext2.py now returns width, height, svg_elements. svg_elements is an instance of Bunch ( cmbook.py) and has the attributes svg_glyphs and svg_lines, which are both lists. Renderer.draw_arc now takes an additional parameter, rotation. 30.10. Changes for 0.87.7 281 Matplotlib, Release 0.99.1.1 It specifies to draw the artist rotated in degrees anticlockwise. It was added for rotated ellipses. Renamed Figure.set_figsize_inches to Figure.set_size_inches to better match the get method, Figure.get_size_inches. Removed the copy_bbox_transform from transforms.py; added shallowcopy methods to all transforms. All transforms already had deepcopy methods. FigureManager.resize(width, height): resize the window specified in pixels 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: 282 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 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. 30.11 Changes for 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. 30.12 Changes for 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 30.11. Changes for 0.86 283 Matplotlib, Release 0.99.1.1 the same place, and can offset the major ticks with the pad. could be made configurable This 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. 30.13 Changes for 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. 284 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 30.14 Changes for 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. 30.15 Changes for 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 30.14. Changes for 0.83 285 Matplotlib, Release 0.99.1.1 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) 30.16 Changes for 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: 286 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 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]. 30.17 Changes for 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 30.18 Changes for 0.73 - Removed deprecated ColormapJet and friends - Removed all error handling from the verbose object - figure num of zero is now allowed 30.19 Changes for 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 30.17. Changes for 0.80 287 Matplotlib, Release 0.99.1.1 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 30.20 Changes for 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 288 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 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) 30.21 Changes for 0.70 MplEvent factored into a base class Event and derived classes MouseEvent and KeyEvent Removed definct set_measurement in wx toolbar 30.22 Changes for 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. 30.23 Changes for 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. 30.24 Changes for 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 30.21. Changes for 0.70 289 Matplotlib, Release 0.99.1.1 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 30.25 Changes for 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) 30.26 Changes for 0.60 ColormapJet and Grayscale are deprecated. For backwards compatibility, they can be obtained either by doing from matplotlib.cm import ColormapJet 290 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 or from matplotlib.matlab import * They are replaced by cm.jet and cm.grey 30.27 Changes for 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. 30.28 Changes for 0.54 30.28.1 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 ﬁnd that some font sizes and line widths appear diﬀerent 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 efﬁciency, pcolor and scatter have been rewritten to use polygon collections, which are a new set of objects from matplotlib.collections designed to enable eﬃcient 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 signiﬁcantly 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: 30.27. Changes for 0.54.3 291 Matplotlib, Release 0.99.1.1 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 diﬀerent elements of a collection to vary on a property, eg to have diﬀerent 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 ﬁx) 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$’) 30.28.2 Object interface - Application programmers Autoscaling The x and y axis instances no longer have autoscale view. axes.autoscale_view These are handled by 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: 292 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 add_axes(rect, axisbg=defaultcolor, frameon=True) add_subplot(num, axisbg=defaultcolor, frameon=True) Artist methods If you deﬁne 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 diﬀerent API than the Bound2D. Eg, if you want to get the width and height of the bbox OLD:: width = ﬁg.bbox.x.interval() height = ﬁg.bbox.y.interval() New:: width = ﬁg.bbox.width() height = ﬁg.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 deﬁne 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 30.28. Changes for 0.54 293 Matplotlib, Release 0.99.1.1 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.Aﬃne. 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 diﬀerent 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 diﬀerent. You will need to see the updated examples/object_picker.py. See unit/transforms_unit.py for many examples using the new transformations. 30.29 Changes for 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 294 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 * 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 30.29. Changes for 0.50 295 Matplotlib, Release 0.99.1.1 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. 30.30 Changes for 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 296 Chapter 30. API Changes Matplotlib, Release 0.99.1.1 30.31 Changes for 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 30.31. Changes for 0.40 297 Matplotlib, Release 0.99.1.1 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. something missing in my backend code. 298 This was Chapter 30. API Changes CHAPTER THIRTYONE MATPLOTLIB CONFIGURATION 31.1 matplotlib This is an object-orient plotting library. A procedural interface is provided by the companion pylab module, which may be imported directly, e.g: from pylab import * or using ipython: ipython -pylab For the most part, direct use of the object-oriented library is encouraged when programming rather than working interactively. The exceptions are the pylab commands figure(), subplot(), show(), and savefig(), which can greatly simplify scripting. Modules include: matplotlib.axes deﬁnes the Axes class. Most pylab commands are wrappers for Axes methods. The axes module is the highest level of OO access to the library. matplotlib.figure deﬁnes the Figure class. matplotlib.artist deﬁnes the Artist base class for all classes that draw things. matplotlib.lines deﬁnes the Line2D class for drawing lines and markers matplotlib.patches deﬁnes classes for drawing polygons matplotlib.text deﬁnes the Text, TextWithDash, and Annotate classes matplotlib.image deﬁnes the AxesImage and FigureImage classes matplotlib.collections classes for eﬃcient drawing of groups of lines or polygons matplotlib.colors classes for interpreting color speciﬁcations and for making colormaps matplotlib.cm colormaps and the ScalarMappable mixin class for providing color mapping functionality to other classes matplotlib.ticker classes for calculating tick mark locations and for formatting tick labels 299 Matplotlib, Release 0.99.1.1 matplotlib.backends a subpackage with modules for various gui libraries and output formats The base matplotlib namespace includes: rcParams a global dictionary of default conﬁguration settings. It is initialized by code which may be overridded by a matplotlibrc ﬁle. rc() a function for setting groups of rcParams values use() a function for setting the matplotlib backend. If used, this function must be called immediately after importing matplotlib for the ﬁrst time. In particular, it must be called before importing pylab (if pylab is imported). matplotlib is written by John D. Hunter (jdh2358 at gmail.com) and a host of others. rc(group, **kwargs) Set the current rc params. Group is the grouping for the rc, eg. for lines.linewidth the group is lines, for axes.facecolor, the group is axes, and so on. Group may also be a list or tuple of group names, eg. (xtick, ytick). kwargs is a dictionary attribute name/value pairs, eg: rc(’lines’, linewidth=2, color=’r’) sets the current rc params and is equivalent to: rcParams[’lines.linewidth’] = 2 rcParams[’lines.color’] = ’r’ The following aliases are available to save typing for interactive users: Alias ‘lw’ ‘ls’ ‘c’ ‘fc’ ‘ec’ ‘mew’ ‘aa’ Property ‘linewidth’ ‘linestyle’ ‘color’ ‘facecolor’ ‘edgecolor’ ‘markeredgewidth’ ‘antialiased’ Thus you could abbreviate the above rc command as: rc(’lines’, lw=2, c=’r’) Note you can use python’s kwargs dictionary facility to store dictionaries of default parameters. Eg, you can customize the font rc as follows: font = {’family’ : ’monospace’, ’weight’ : ’bold’, ’size’ : ’larger’} rc(’font’, **font) 300 # pass in the font dict as kwargs Chapter 31. matplotlib conﬁguration Matplotlib, Release 0.99.1.1 This enables you to easily switch between several conﬁgurations. Use rcdefaults() to restore the default rc params after changes. rcdefaults() Restore the default rc params - the ones that were created at matplotlib load time. use(arg, warn=True) Set the matplotlib backend to one of the known backends. The argument is case-insensitive. For the Cairo backend, the argument can have an extension to indicate the type of output. Example: use(‘cairo.pdf’) will specify a default of pdf output generated by Cairo. Note: this function must be called before importing pylab for the ﬁrst time; or, if you are not using pylab, it must be called before importing matplotlib.backends. If warn is True, a warning is issued if you try and callthis after pylab or pyplot have been loaded. In certain black magic use cases, eg pyplot.switch_backends, we are doing the reloading necessary to make the backend switch work (in some cases, eg pure image backends) so one can set warn=False to supporess the warnings 31.1. matplotlib 301 Matplotlib, Release 0.99.1.1 302 Chapter 31. matplotlib conﬁguration CHAPTER THIRTYTWO MATPLOTLIB AFM 32.1 matplotlib.afm This is a python interface to Adobe Font Metrics Files. Although a number of other python implementations exist (and may be more complete than mine) I decided not to go with them because either they were either 1. copyrighted or used a non-BSD compatible license 2. had too many dependencies and I wanted a free standing lib 3. Did more than I needed and it was easier to write my own than ﬁgure out how to just get what I needed from theirs It is pretty easy to use, and requires only built-in python libs: >>> from afm import AFM >>> fh = file(’ptmr8a.afm’) >>> afm = AFM(fh) >>> afm.string_width_height(’What the heck?’) (6220.0, 683) >>> afm.get_fontname() ’Times-Roman’ >>> afm.get_kern_dist(’A’, ’f’) 0 >>> afm.get_kern_dist(’A’, ’y’) -92.0 >>> afm.get_bbox_char(’!’) [130, -9, 238, 676] >>> afm.get_bbox_font() [-168, -218, 1000, 898] AUTHOR: John D. Hunter <[email protected]> class AFM(fh) Parse the AFM ﬁle in ﬁle object fh get_angle() Return the fontangle as ﬂoat get_bbox_char(c, isord=False) 303 Matplotlib, Release 0.99.1.1 get_capheight() Return the cap height as ﬂoat get_familyname() Return the font family name, eg, ‘Times’ get_fontname() Return the font name, eg, ‘Times-Roman’ get_fullname() Return the font full name, eg, ‘Times-Roman’ get_height_char(c, isord=False) Get the height of character c from the bounding box. This is the ink height (space is 0) get_horizontal_stem_width() Return the standard horizontal stem width as ﬂoat, or None if not speciﬁed in AFM ﬁle. get_kern_dist(c1, c2) Return the kerning pair distance (possibly 0) for chars c1 and c2 get_kern_dist_from_name(name1, name2) Return the kerning pair distance (possibly 0) for chars name1 and name2 get_name_char(c, isord=False) Get the name of the character, ie, ‘;’ is ‘semicolon’ get_str_bbox(s) Return the string bounding box get_str_bbox_and_descent(s) Return the string bounding box get_underline_thickness() Return the underline thickness as ﬂoat get_vertical_stem_width() Return the standard vertical stem width as ﬂoat, or None if not speciﬁed in AFM ﬁle. get_weight() Return the font weight, eg, ‘Bold’ or ‘Roman’ get_width_char(c, isord=False) Get the width of the character from the character metric WX ﬁeld get_width_from_char_name(name) Get the width of the character from a type1 character name get_xheight() Return the xheight as ﬂoat string_width_height(s) Return the string width (including kerning) and string height as a (w, h) tuple. parse_afm(fh) Parse the Adobe Font Metics ﬁle in ﬁle handle fh. Return value is a (dhead, dcmetrics, dkernpairs, dcomposite) tuple where dhead is a _parse_header() dict, dcmetrics is a 304 Chapter 32. matplotlib afm Matplotlib, Release 0.99.1.1 _parse_composites() dict, dkernpairs is a _parse_kern_pairs() dict (possibly {}), and dcomposite is a _parse_composites() dict (possibly {}) 32.1. matplotlib.afm 305 Matplotlib, Release 0.99.1.1 306 Chapter 32. matplotlib afm CHAPTER THIRTYTHREE MATPLOTLIB ARTISTS 33.1 matplotlib.artist class Artist() Bases: object Abstract base class for someone who renders into a FigureCanvas. 307 Matplotlib, Release 0.99.1.1 add_callback(func) Adds a callback function that will be called whenever one of the Artist‘s properties changes. Returns an id that is useful for removing the callback with remove_callback() later. contains(mouseevent) Test whether the artist contains the mouse event. Returns the truth value and a dictionary of artist speciﬁc details of selection, such as which points are contained in the pick radius. See individual artists for details. convert_xunits(x) For artists in an axes, if the xaxis has units support, convert x using xaxis unit type convert_yunits(y) For artists in an axes, if the yaxis has units support, convert y using yaxis unit type draw(renderer, *args, **kwargs) Derived classes drawing method findobj(match=None) pyplot signature: ﬁndobj(o=gcf(), match=None) Recursively ﬁnd all :class:matplotlib.artist.Artist instances contained in self. match can be •None: return all objects contained in artist (including artist) •function with signature boolean = match(artist) used to ﬁlter matches •class instance: eg Line2D. Only return artists of class type 308 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 get_alpha() Return the alpha value used for blending - not supported on all backends get_animated() Return the artist’s animated state get_axes() Return the Axes instance the artist resides in, or None get_children() Return a list of the child Artist‘s this :class:‘Artist contains. get_clip_box() Return artist clipbox get_clip_on() Return whether artist uses clipping get_clip_path() Return artist clip path get_contains() Return the _contains test used by the artist, or None for default. get_figure() Return the Figure instance the artist belongs to. 33.1. matplotlib.artist 309 Matplotlib, Release 0.99.1.1 get_gid() Returns the group id get_label() Get the label used for this artist in the legend. get_picker() Return the picker object used by this artist get_rasterized() get_snap() Returns the snap setting which may be: •True: snap vertices to the nearest pixel center •False: leave vertices as-is •None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center Only supported by the Agg backends. get_transform() Return the Transform instance used by this artist. get_transformed_clip_path_and_affine() Return the clip path with the non-aﬃne part of its transformation applied, and the remaining aﬃne part of its transformation. get_url() Returns the url get_visible() Return the artist’s visiblity get_zorder() Return the Artist‘s zorder. have_units() Return True if units are set on the x or y axes hitlist(event) List the children of the artist which contain the mouse event event. is_figure_set() Returns True if the artist is assigned to a Figure. is_transform_set() Returns True if Artist has a transform explicitly set. pchanged() Fire an event when property changed, calling all of the registered callbacks. pick(mouseevent) call signature: 310 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 pick(mouseevent) each child artist will ﬁre a pick event if mouseevent is over the artist and the artist has picker set pickable() Return True if Artist is pickable. properties() return a dictionary mapping property name -> value for all Artist props remove() Remove the artist from the ﬁgure if possible. The eﬀect will not be visible until the ﬁgure is redrawn, e.g., with matplotlib.axes.Axes.draw_idle(). Call matplotlib.axes.Axes.relim() to update the axes limits if desired. Note: relim() will not see collections even if the collection was added to axes with autolim = True. Note: there is no support for removing the artist’s legend entry. remove_callback(oid) Remove a callback based on its id. See Also: add_callback() For adding callbacks set(**kwargs) A tkstyle set command, pass kwargs to set properties set_alpha(alpha) Set the alpha value used for blending - not supported on all backends. ACCEPTS: ﬂoat (0.0 transparent through 1.0 opaque) set_animated(b) Set the artist’s animation state. ACCEPTS: [True | False] set_axes(axes) Set the Axes instance in which the artist resides, if any. ACCEPTS: an Axes instance set_clip_box(clipbox) Set the artist’s clip Bbox. ACCEPTS: a matplotlib.transforms.Bbox instance set_clip_on(b) Set whether artist uses clipping. ACCEPTS: [True | False] 33.1. matplotlib.artist 311 Matplotlib, Release 0.99.1.1 set_clip_path(path, transform=None) Set the artist’s clip path, which may be: •a Patch (or subclass) instance •a Path instance, in which case an optional Transform instance may be provided, which will be applied to the path before using it for clipping. •None, to remove the clipping path For eﬃciency, if the path happens to be an axis-aligned rectangle, this method will set the clipping box to the corresponding rectangle and set the clipping path to None. ACCEPTS: [ (Path, Transform) | Patch | None ] set_contains(picker) Replace the contains test used by this artist. The new picker should be a callable function which determines whether the artist is hit by the mouse event: hit, props = picker(artist, mouseevent) If the mouse event is over the artist, return hit = True and props is a dictionary of properties you want returned with the contains test. ACCEPTS: a callable function set_figure(ﬁg) Set the Figure instance the artist belongs to. ACCEPTS: a matplotlib.figure.Figure instance set_gid(gid) Sets the (group) id for the artist ACCEPTS: an id string set_label(s) Set the label to s for auto legend. ACCEPTS: any string set_lod(on) Set Level of Detail on or oﬀ. If on, the artists may examine things like the pixel width of the axes and draw a subset of their contents accordingly ACCEPTS: [True | False] set_picker(picker) Set the epsilon for picking used by this artist picker can be one of the following: •None: picking is disabled for this artist (default) •A boolean: if True then picking will be enabled and the artist will ﬁre a pick event if the mouse event is over the artist 312 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 •A ﬂoat: if picker is a number it is interpreted as an epsilon tolerance in points and the artist will ﬁre oﬀ an event if it’s data is within epsilon of the mouse event. For some artists like lines and patch collections, the artist may provide additional data to the pick event that is generated, e.g. the indices of the data within epsilon of the pick event •A function: if picker is callable, it is a user supplied function which determines whether the artist is hit by the mouse event: hit, props = picker(artist, mouseevent) to determine the hit test. if the mouse event is over the artist, return hit=True and props is a dictionary of properties you want added to the PickEvent attributes. ACCEPTS: [None|ﬂoat|boolean|callable] set_rasterized(rasterized) Force rasterized (bitmap) drawing in vector backend output. Defaults to None, which implies the backend’s default behavior ACCEPTS: [True | False | None] set_snap(snap) Sets the snap setting which may be: •True: snap vertices to the nearest pixel center •False: leave vertices as-is •None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center Only supported by the Agg backends. set_transform(t) Set the Transform instance used by this artist. ACCEPTS: Transform instance set_url(url) Sets the url for the artist ACCEPTS: a url string set_visible(b) Set the artist’s visiblity. ACCEPTS: [True | False] set_zorder(level) Set the zorder for the artist. Artists with lower zorder values are drawn ﬁrst. ACCEPTS: any number update(props) Update the properties of this Artist from the dictionary prop. 33.1. matplotlib.artist 313 Matplotlib, Release 0.99.1.1 update_from(other) Copy properties from other to self. class ArtistInspector(o) A helper class to inspect an Artist and return information about it’s settable properties and their current values. Initialize the artist inspector with an Artist or sequence of Artists. If a sequence is used, we assume it is a homogeneous sequence (all Artists are of the same type) and it is your responsibility to make sure this is so. aliased_name(s) return ‘PROPNAME or alias’ if s has an alias, else return PROPNAME. E.g. for the line markerfacecolor property, which has an alias, return ‘markerfacecolor or mfc’ and for the transform property, which does not, return ‘transform’ aliased_name_rest(s, target) return ‘PROPNAME or alias’ if s has an alias, else return PROPNAME formatted for ReST E.g. for the line markerfacecolor property, which has an alias, return ‘markerfacecolor or mfc’ and for the transform property, which does not, return ‘transform’ findobj(match=None) Recursively ﬁnd all matplotlib.artist.Artist instances contained in self. If match is not None, it can be •function with signature boolean = match(artist) •class instance: eg Line2D used to ﬁlter matches. get_aliases() Get a dict mapping fullname -> alias for each alias in the ArtistInspector. Eg., for lines: {’markerfacecolor’: ’mfc’, ’linewidth’ : ’lw’, } get_setters() Get the attribute strings with setters for object. Eg., for a line, return [’markerfacecolor’, ’linewidth’, ....]. get_valid_values(attr) Get the legal arguments for the setter associated with attr. This is done by querying the docstring of the function set_attr for a line that begins with ACCEPTS: Eg., for a line linestyle, return [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘steps’ | ‘None’ ] 314 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 is_alias(o) Return True if method object o is an alias for another function. pprint_getters() Return the getters and actual values as list of strings. pprint_setters(prop=None, leadingspace=2) If prop is None, return a list of strings of all settable properies and their valid values. If prop is not None, it is a valid property name and that property will be returned as a string of property : valid values. pprint_setters_rest(prop=None, leadingspace=2) If prop is None, return a list of strings of all settable properies and their valid values. Format the output for ReST If prop is not None, it is a valid property name and that property will be returned as a string of property : valid values. properties() return a dictionary mapping property name -> value allow_rasterization(draw) Decorator for Artist.draw method. Provides routines that run before and after the draw call. The before and after functions are useful for changing artist-dependant renderer attributes or making other setup function calls, such as starting and ﬂushing a mixed-mode renderer. get(o, property=None) Return the value of handle property. property is an optional string for the property you want to return Example usage: getp(o) # get all the object properties getp(o, ’linestyle’) # get the linestyle property o is a Artist instance, eg Line2D or an instance of a Axes or matplotlib.text.Text. If the property is ‘somename’, this function returns o.get_somename() getp() can be used to query all the gettable properties with getp(o). Many properties have aliases for shorter typing, e.g. ‘lw’ is an alias for ‘linewidth’. In the output, aliases and full property names will be listed as: property or alias = value e.g.: linewidth or lw = 2 getp(o, property=None) Return the value of handle property. property is an optional string for the property you want to return Example usage: 33.1. matplotlib.artist 315 Matplotlib, Release 0.99.1.1 getp(o) # get all the object properties getp(o, ’linestyle’) # get the linestyle property o is a Artist instance, eg Line2D or an instance of a Axes or matplotlib.text.Text. If the property is ‘somename’, this function returns o.get_somename() getp() can be used to query all the gettable properties with getp(o). Many properties have aliases for shorter typing, e.g. ‘lw’ is an alias for ‘linewidth’. In the output, aliases and full property names will be listed as: property or alias = value e.g.: linewidth or lw = 2 kwdoc(a) setp(h, *args, **kwargs) matplotlib supports the use of setp() (“set property”) and getp() to set and get object properties, as well as to do introspection on the object. For example, to set the linestyle of a line to be dashed, you can do: >>> line, = plot([1,2,3]) >>> setp(line, linestyle=’--’) If you want to know the valid types of arguments, you can provide the name of the property you want to set without a value: >>> setp(line, ’linestyle’) linestyle: [ ’-’ | ’--’ | ’-.’ | ’:’ | ’steps’ | ’None’ ] If you want to see all the properties that can be set, and their possible values, you can do: >>> setp(line) ... long output listing omitted setp() operates on a single instance or a list of instances. If you are in query mode introspecting the possible values, only the ﬁrst instance in the sequence is used. When actually setting values, all the instances will be set. E.g., suppose you have a list of two lines, the following will make both lines thicker and red: >>> >>> >>> >>> >>> 316 x = arange(0,1.0,0.01) y1 = sin(2*pi*x) y2 = sin(4*pi*x) lines = plot(x, y1, x, y2) setp(lines, linewidth=2, color=’r’) Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 setp() works with the matlab(TM) style string/value pairs or with python kwargs. For example, the following are equivalent: >>> setp(lines, ’linewidth’, 2, ’color’, r’) # matlab style >>> setp(lines, linewidth=2, color=’r’) # python style 33.2 matplotlib.legend Place a legend on the axes at location loc. Labels are a sequence of strings and loc can be a string or an integer specifying the legend location The location codes are ‘best’ : 0, (only implemented for axis legends) ‘upper right’ : 1, ‘upper left’ : 2, ‘lower left’ : 3, ‘lower right’ : 4, ‘right’ : 5, ‘center left’ : 6, ‘center right’ : 7, ‘lower center’ : 8, ‘upper center’ : 9, ‘center’ : 10, Return value is a sequence of text, line instances that make up the legend class Legend(parent, handles, labels, loc=None, numpoints=None, markerscale=None, scatterpoints=3, scatteryoﬀsets=None, prop=None, pad=None, labelsep=None, handlelen=None, handletextsep=None, axespad=None, borderpad=None, labelspacing=None, handlelength=None, handletextpad=None, borderaxespad=None, columnspacing=None, ncol=1, mode=None, fancybox=None, shadow=None, title=None, bbox_to_anchor=None, bbox_transform=None) Bases: matplotlib.artist.Artist Place a legend on the axes at location loc. Labels are a sequence of strings and loc can be a string or an integer specifying the legend location The location codes are: ’best’ ’upper right’ ’upper left’ ’lower left’ ’lower right’ ’right’ ’center left’ ’center right’ ’lower center’ ’upper center’ ’center’ : : : : : : : : : : : 0, (only implemented for axis legends) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, loc can be a tuple of the noramilzed coordinate values with respect its parent. Return value is a sequence of text, line instances that make up the legend •parent : the artist that contains the legend •handles : a list of artists (lines, patches) to add to the legend 33.2. matplotlib.legend 317 Matplotlib, Release 0.99.1.1 •labels : a list of strings to label the legend Optional keyword arguments: Keyword loc prop markerscale numpoints scatterpoints scatteryoﬀsets fancybox shadow ncol borderpad labelspacing handlelength handletextpad borderaxespad columnspacing title bbox_to_anchor bbox_transform Description a location code the font property the relative size of legend markers vs. original the number of points in the legend for line the number of points in the legend for scatter plot a list of yoﬀsets for scatter symbols in legend if True, draw a frame with a round fancybox. If None, use rc if True, draw a shadow behind legend number of columns the fractional whitespace inside the legend border the vertical space between the legend entries the length of the legend handles the pad between the legend handle and text the pad between the axes and legend border the spacing between columns the legend title the bbox that the legend will be anchored. the transform for the bbox. transAxes if None. The dimensions of pad and spacing are given as a fraction of the _fontsize. Values from rcParams will be used if None. Users can specify any arbitrary location for the legend using the bbox_to_anchor keyword argument. bbox_to_anchor can be an instance of BboxBase(or its derivatives) or a tuple of 2 or 4 ﬂoats. See set_bbox_to_anchor() for more detail. The legend location can be speciﬁed by setting loc with a tuple of 2 ﬂoats, which is interpreted as the lower-left corner of the legend in the normalized axes coordinate. draw(artist, renderer, *kl) Draw everything that belongs to the legend draw_frame(b) b is a boolean. Set draw frame to b get_bbox_to_anchor() return the bbox that the legend will be anchored get_children() return a list of child artists get_frame() return the Rectangle instance used to frame the legend get_lines() return a list of lines.Line2D instances in the legend get_patches() return a list of patch instances in the legend 318 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 get_texts() return a list of text.Text instance in the legend get_title() return Text instance for the legend title get_window_extent() return a extent of the the legend set_bbox_to_anchor(bbox, transform=None) set the bbox that the legend will be anchored. bbox can be a BboxBase instance, a tuple of [left, bottom, width, height] in the given transform (normalized axes coordinate if None), or a tuple of [left, bottom] where the width and height will be assumed to be zero. set_title(title) set the legend title 33.3 matplotlib.lines This module contains all the 2D line class which can draw with a variety of line styles, markers and colors. class Line2D(xdata, ydata, linewidth=None, linestyle=None, color=None, marker=None, markersize=None, markeredgewidth=None, markeredgecolor=None, markerfacecolor=None, ﬁllstyle=’full’, antialiased=None, dash_capstyle=None, solid_capstyle=None, dash_joinstyle=None, solid_joinstyle=None, pickradius=5, drawstyle=None, markevery=None, **kwargs) Bases: matplotlib.artist.Artist A line - the line can have both a solid linestyle connecting all the vertices, and a marker at each vertex. Additionally, the drawing of the solid line is inﬂuenced by the drawstyle, eg one can create “stepped” lines in various styles. Create a Line2D instance with x and y data in sequences xdata, ydata. The kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle 33.3. matplotlib.lines Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] 319 Matplotlib, Release 0.99.1.1 Table 33.1 – continued from previous pa dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number See set_linestyle() for a decription of the line styles, set_marker() for a description of the markers, and set_drawstyle() for a description of the draw styles. contains(mouseevent) Test whether the mouse event occurred on the line. The pick radius determines the precision of the location test (usually within ﬁve points of the value). Use get_pickradius() or set_pickradius() to view or modify it. Returns True if any values are within the radius along with {’ind’: pointlist is the set of points within the radius. pointlist}, where TODO: sort returned indices by distance draw(artist, renderer, *kl) get_aa() alias for get_antialiased get_antialiased() 320 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 get_c() alias for get_color get_color() get_dash_capstyle() Get the cap style for dashed linestyles get_dash_joinstyle() Get the join style for dashed linestyles get_data(orig=True) Return the xdata, ydata. If orig is True, return the original data get_drawstyle() get_fillstyle() return the marker ﬁllstyle get_linestyle() get_linewidth() get_ls() alias for get_linestyle get_lw() alias for get_linewidth get_marker() get_markeredgecolor() get_markeredgewidth() get_markerfacecolor() get_markersize() get_markevery() return the markevery setting get_mec() alias for get_markeredgecolor get_mew() alias for get_markeredgewidth get_mfc() alias for get_markerfacecolor get_ms() alias for get_markersize get_path() Return the Path object associated with this line. 33.3. matplotlib.lines 321 Matplotlib, Release 0.99.1.1 get_pickradius() return the pick radius used for containment tests get_solid_capstyle() Get the cap style for solid linestyles get_solid_joinstyle() Get the join style for solid linestyles get_window_extent(renderer) get_xdata(orig=True) Return the xdata. If orig is True, return the original data, else the processed data. get_xydata() Return the xy data as a Nx2 numpy array. get_ydata(orig=True) Return the ydata. If orig is True, return the original data, else the processed data. is_dashed() return True if line is dashstyle recache() set_aa(val) alias for set_antialiased set_antialiased(b) True if line should be drawin with antialiased rendering ACCEPTS: [True | False] set_axes(ax) Set the Axes instance in which the artist resides, if any. ACCEPTS: an Axes instance set_c(val) alias for set_color set_color(color) Set the color of the line ACCEPTS: any matplotlib color set_dash_capstyle(s) Set the cap style for dashed linestyles ACCEPTS: [’butt’ | ‘round’ | ‘projecting’] set_dash_joinstyle(s) Set the join style for dashed linestyles ACCEPTS: [’miter’ | ‘round’ | ‘bevel’] 322 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 set_dashes(seq) Set the dash sequence, sequence of dashes with on oﬀ ink in points. If seq is empty or if seq = (None, None), the linestyle will be set to solid. ACCEPTS: sequence of on/oﬀ ink in points set_data(*args) Set the x and y data ACCEPTS: 2D array set_drawstyle(drawstyle) Set the drawstyle of the plot ‘default’ connects the points with lines. The steps variants produce step-plots. ‘steps’ is equivalent to ‘steps-pre’ and is maintained for backward-compatibility. ACCEPTS: [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] set_fillstyle(fs) Set the marker ﬁll style; ‘full’ means ﬁll the whole marker. The other options are for half ﬁlled markers ACCEPTS: [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] set_linestyle(linestyle) Set the linestyle of the line (also accepts drawstyles) linestyle ‘-‘ ‘–‘ ‘-.’ ‘:’ ‘None’ ‘‘ ‘’ description solid dashed dash_dot dotted draw nothing draw nothing draw nothing ‘steps’ is equivalent to ‘steps-pre’ and is maintained for backward-compatibility. See Also: set_drawstyle() To set the drawing style (stepping) of the plot. ACCEPTS: [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘steps–‘. set_linewidth(w) Set the line width in points ACCEPTS: ﬂoat value in points set_ls(val) alias for set_linestyle set_lw(val) alias for set_linewidth 33.3. matplotlib.lines 323 Matplotlib, Release 0.99.1.1 set_marker(marker) Set the line marker marker ‘.’ ‘,’ ‘o’ ‘v’ ‘^’ ‘<’ ‘>’ ‘1’ ‘2’ ‘3’ ‘4’ ‘s’ ‘p’ ‘*’ ‘h’ ‘H’ ‘+’ ‘x’ ‘D’ ‘d’ ‘ |’ ‘_’ TICKLEFT TICKRIGHT TICKUP TICKDOWN CARETLEFT CARETRIGHT CARETUP CARETDOWN ‘None’ ‘‘ ‘’ description point pixel circle triangle_down triangle_up triangle_left triangle_right tri_down tri_up tri_left tri_right square pentagon star hexagon1 hexagon2 plus x diamond thin_diamond vline hline tickleft tickright tickup tickdown caretleft caretright caretup caretdown nothing nothing nothing ACCEPTS: [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ ‘<’ | ’>’ | ’D’ | ’H’ | ’^’ | ’_’ | ’d’ ‘h’ | ’o’ | ’p’ | ’s’ | ’v’ | ’x’ | ’|’ TICKUP | TICKDOWN | TICKLEFT | TICKRIGHT ‘None’ | ’ ’ | ’‘ ] set_markeredgecolor(ec) Set the marker edge color ACCEPTS: any matplotlib color 324 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 set_markeredgewidth(ew) Set the marker edge width in points ACCEPTS: ﬂoat value in points set_markerfacecolor(fc) Set the marker face color ACCEPTS: any matplotlib color set_markersize(sz) Set the marker size in points ACCEPTS: ﬂoat set_markevery(every) Set the markevery property to subsample the plot when using markers. Eg if markevery=5, every 5-th marker will be plotted. every can be None Every point will be plotted an integer N Every N-th marker will be plotted starting with marker 0 A length-2 tuple of integers every=(start, N) will start at point start and plot every N-th marker ACCEPTS: None | integer | (startind, stride) set_mec(val) alias for set_markeredgecolor set_mew(val) alias for set_markeredgewidth set_mfc(val) alias for set_markerfacecolor set_ms(val) alias for set_markersize set_picker(p) Sets the event picker details for the line. ACCEPTS: ﬂoat distance in points or callable pick function fn(artist, event) set_pickradius(d) Sets the pick radius used for containment tests ACCEPTS: ﬂoat distance in points set_solid_capstyle(s) Set the cap style for solid linestyles ACCEPTS: [’butt’ | ‘round’ | ‘projecting’] set_solid_joinstyle(s) Set the join style for solid linestyles ACCEPTS: [’miter’ | ‘round’ | ‘bevel’] 33.3. matplotlib.lines 325 Matplotlib, Release 0.99.1.1 set_transform(t) set the Transformation instance used by this artist ACCEPTS: a matplotlib.transforms.Transform instance set_xdata(x) Set the data np.array for x ACCEPTS: 1D array set_ydata(y) Set the data np.array for y ACCEPTS: 1D array update_from(other) copy properties from other to self class VertexSelector(line) Manage the callbacks to maintain a list of selected vertices for matplotlib.lines.Line2D. Derived classes should override process_selected() to do something with the picks. Here is an example which highlights the selected verts with red circles: import numpy as np import matplotlib.pyplot as plt import matplotlib.lines as lines class HighlightSelected(lines.VertexSelector): def __init__(self, line, fmt=’ro’, **kwargs): lines.VertexSelector.__init__(self, line) self.markers, = self.axes.plot(, , fmt, **kwargs) def process_selected(self, ind, xs, ys): self.markers.set_data(xs, ys) self.canvas.draw() fig = plt.figure() ax = fig.add_subplot(111) x, y = np.random.rand(2, 30) line, = ax.plot(x, y, ’bs-’, picker=5) selector = HighlightSelected(line) plt.show() Initialize the class with a matplotlib.lines.Line2D instance. The line should already be added to some matplotlib.axes.Axes instance and should have the picker property set. onpick(event) When the line is picked, update the set of selected indicies. process_selected(ind, xs, ys) Default “do nothing” implementation of the process_selected() method. ind are the indices of the selected vertices. xs and ys are the coordinates of the selected vertices. 326 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 segment_hits(cx, cy, x, y, radius) Determine if any line segments are within radius of a point. Returns the list of line segments that are within that radius. unmasked_index_ranges(mask, compressed=True) 33.4 matplotlib.patches class Arc(xy, width, height, angle=0.0, theta1=0.0, theta2=360.0, **kwargs) Bases: matplotlib.patches.Ellipse An elliptical arc. Because it performs various optimizations, it can not be ﬁlled. The arc must be used in an Axes instance—it can not be added directly to a Figure—because it is optimized to only render the segments that are inside the axes bounding box with high resolution. The following args are supported: xy center of ellipse width length of horizontal axis height length of vertical axis angle rotation in degrees (anti-clockwise) theta1 starting angle of the arc in degrees theta2 ending angle of the arc in degrees If theta1 and theta2 are not provided, the arc will form a complete ellipse. Valid kwargs are: 33.4. matplotlib.patches 327 Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number draw(artist, renderer, *kl) Ellipses are normally drawn using an approximation that uses eight cubic bezier splines. The error of this approximation is 1.89818e-6, according to this unveriﬁed source: Lancaster, Don. Approximating a Circle or an Ellipse Using Four Bezier Cubic Splines. http://www.tinaja.com/glib/ellipse4.pdf There is a use case where very large ellipses must be drawn with very high accuracy, and it is too expensive to render the entire ellipse with enough segments (either splines or line segments). Therefore, in the case where either radius of the ellipse is large enough that the error of the spline approximation will be visible (greater than one pixel oﬀset from the ideal), a diﬀerent technique is used. In that case, only the visible parts of the ellipse are drawn, with each visible arc using a ﬁxed number of spline segments (8). The algorithm proceeds as follows: 1.The points where the ellipse intersects the axes bounding box are located. (This is done be performing an inverse transformation on the axes bbox such that it is relative to the unit circle – this makes the intersection calculation much easier than doing rotated ellipse intersection directly). 328 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 This uses the “line intersecting a circle” algorithm from: Vince, John. Geometry for Computer Graphics: Formulae, Examples & Proofs. London: Springer-Verlag, 2005. 2.The angles of each of the intersection points are calculated. 3.Proceeding counterclockwise starting in the positive x-direction, each of the visible arcsegments between the pairs of vertices are drawn using the bezier arc approximation technique implemented in matplotlib.path.Path.arc(). class Arrow(x, y, dx, dy, width=1.0, **kwargs) Bases: matplotlib.patches.Patch An arrow patch. Draws an arrow, starting at (x, y), direction and length given by (dx, dy) the width of the arrow is scaled by width. Valid kwargs are: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number get_patch_transform() get_path() 33.4. matplotlib.patches 329 Matplotlib, Release 0.99.1.1 class ArrowStyle() Bases: matplotlib.patches._Style ArrowStyle is a container class which deﬁnes several arrowstyle classes, which is used to create an arrow path along a given path. These are mainly used with FancyArrowPatch. A arrowstyle object can be either created as: ArrowStyle.Fancy(head_length=.4, head_width=.4, tail_width=.4) or: ArrowStyle("Fancy", head_length=.4, head_width=.4, tail_width=.4) or: ArrowStyle("Fancy, head_length=.4, head_width=.4, tail_width=.4") The following classes are deﬁned Class Curve CurveB BracketB CurveFilledB CurveA CurveAB CurveFilledA CurveFilledAB Fancy Simple Wedge Name -> -[ -|> <<-> <|<|-|> fancy simple wedge Attrs None head_length=0.4,head_width=0.2 widthB=1.0,lengthB=0.2,angleB=None head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.4,tail_width=0.4 head_length=0.5,head_width=0.5,tail_width=0.2 tail_width=0.3,shrink_factor=0.5 An instance of any arrow style class is an callable object, whose call signature is: __call__(self, path, mutation_size, linewidth, aspect_ratio=1.) and it returns a tuple of a Path instance and a boolean value. path is a Path instance along witch the arrow will be drawn. mutation_size and aspect_ratio has a same meaning as in BoxStyle. linewidth is a line width to be stroked. This is meant to be used to correct the location of the head so that it does not overshoot the destination point, but not all classes support it. 330 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 class BracketB(widthB=1.0, lengthB=0.20000000000000001, angleB=None) Bases: matplotlib.patches._Bracket An arrow with a bracket([) at its end. widthB width of the bracket lengthB length of the bracket angleB angle between the bracket and the line class Curve() Bases: matplotlib.patches._Curve A simple curve without any arrow head. class CurveA(head_length=0.40000000000000002, head_width=0.20000000000000001) Bases: matplotlib.patches._Curve An arrow with a head at its begin point. head_length length of the arrow head head_width width of the arrow head class CurveAB(head_length=0.40000000000000002, head_width=0.20000000000000001) Bases: matplotlib.patches._Curve An arrow with heads both at the begin and the end point. 33.4. matplotlib.patches 331 Matplotlib, Release 0.99.1.1 head_length length of the arrow head head_width width of the arrow head class CurveB(head_length=0.40000000000000002, head_width=0.20000000000000001) Bases: matplotlib.patches._Curve An arrow with a head at its end point. head_length length of the arrow head head_width width of the arrow head class CurveFilledA(head_length=0.40000000000000002, head_width=0.20000000000000001) Bases: matplotlib.patches._Curve An arrow with ﬁlled triangle head at the begin. head_length length of the arrow head head_width width of the arrow head class CurveFilledAB(head_length=0.40000000000000002, head_width=0.20000000000000001) Bases: matplotlib.patches._Curve An arrow with ﬁlled triangle heads both at the begin and the end point. head_length length of the arrow head head_width width of the arrow head class CurveFilledB(head_length=0.40000000000000002, head_width=0.20000000000000001) Bases: matplotlib.patches._Curve An arrow with ﬁlled triangle head at the end. head_length length of the arrow head head_width width of the arrow head class Fancy(head_length=0.40000000000000002, tail_width=0.40000000000000002) Bases: matplotlib.patches._Base head_width=0.40000000000000002, A fancy arrow. Only works with a quadratic bezier curve. head_length length of the arrow head head_with width of the arrow head tail_width width of the arrow tail transmute(path, mutation_size, linewidth) class Simple(head_length=0.5, head_width=0.5, tail_width=0.20000000000000001) Bases: matplotlib.patches._Base A simple arrow. Only works with a quadratic bezier curve. head_length length of the arrow head 332 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 head_with width of the arrow head tail_width width of the arrow tail transmute(path, mutation_size, linewidth) class Wedge(tail_width=0.29999999999999999, shrink_factor=0.5) Bases: matplotlib.patches._Base Wedge(?) shape. Only wokrs with a quadratic bezier curve. The begin point has a width of the tail_width and the end point has a width of 0. At the middle, the width is shrink_factor*tail_width. tail_width width of the tail shrink_factor fraction of the arrow width at the middle point transmute(path, mutation_size, linewidth) class BoxStyle() Bases: matplotlib.patches._Style BoxStyle is a container class which deﬁnes several boxstyle classes, which are used for FancyBoxPatch. A style object can be created as: BoxStyle.Round(pad=0.2) or: BoxStyle("Round", pad=0.2) or: BoxStyle("Round, pad=0.2") Following boxstyle classes are deﬁned. Class LArrow RArrow Round Round4 Roundtooth Sawtooth Square Name larrow rarrow round round4 roundtooth sawtooth square Attrs pad=0.3 pad=0.3 pad=0.3,rounding_size=None pad=0.3,rounding_size=None pad=0.3,tooth_size=None pad=0.3,tooth_size=None pad=0.3 An instance of any boxstyle class is an callable object, whose call signature is: __call__(self, x0, y0, width, height, mutation_size, aspect_ratio=1.) 33.4. matplotlib.patches 333 Matplotlib, Release 0.99.1.1 and returns a Path instance. x0, y0, width and height specify the location and size of the box to be drawn. mutation_scale determines the overall size of the mutation (by which I mean the transformation of the rectangle to the fancy box). mutation_aspect determines the aspect-ratio of the mutation. class LArrow(pad=0.29999999999999999) Bases: matplotlib.patches._Base (left) Arrow Box transmute(x0, y0, width, height, mutation_size) class RArrow(pad=0.29999999999999999) Bases: matplotlib.patches.LArrow (right) Arrow Box transmute(x0, y0, width, height, mutation_size) class Round(pad=0.29999999999999999, rounding_size=None) Bases: matplotlib.patches._Base A box with round corners. pad amount of padding rounding_size rounding radius of corners. pad if None 334 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 transmute(x0, y0, width, height, mutation_size) class Round4(pad=0.29999999999999999, rounding_size=None) Bases: matplotlib.patches._Base Another box with round edges. pad amount of padding rounding_size rounding size of edges. pad if None transmute(x0, y0, width, height, mutation_size) class Roundtooth(pad=0.29999999999999999, tooth_size=None) Bases: matplotlib.patches.Sawtooth A roundtooth(?) box. pad amount of padding tooth_size size of the sawtooth. pad* if None transmute(x0, y0, width, height, mutation_size) class Sawtooth(pad=0.29999999999999999, tooth_size=None) Bases: matplotlib.patches._Base A sawtooth box. pad amount of padding tooth_size size of the sawtooth. pad* if None transmute(x0, y0, width, height, mutation_size) class Square(pad=0.29999999999999999) Bases: matplotlib.patches._Base A simple square box. pad amount of padding transmute(x0, y0, width, height, mutation_size) class Circle(xy, radius=5, **kwargs) Bases: matplotlib.patches.Ellipse A circle patch. Create true circle at center xy = (x, y) with given radius. Unlike CirclePolygon which is a polygonal approximation, this uses Bézier splines and is much closer to a scale-free circle. Valid kwargs are: 33.4. matplotlib.patches 335 Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number get_radius() return the radius of the circle radius return the radius of the circle set_radius(radius) Set the radius of the circle ACCEPTS: ﬂoat class CirclePolygon(xy, radius=5, resolution=20, **kwargs) Bases: matplotlib.patches.RegularPolygon A polygon-approximation of a circle patch. Create a circle at xy = (x, y) with given radius. This circle is approximated by a regular polygon with resolution sides. For a smoother circle drawn with splines, see Circle. Valid kwargs are: 336 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number class ConnectionPatch(xyA, xyB, coordsA, coordsB=None, axesA=None, axesB=None, arrowstyle=’’, arrow_transmuter=None, connectionstyle=’arc3’, connector=None, patchA=None, patchB=None, shrinkA=0.0, shrinkB=0.0, mutation_scale=10.0, mutation_aspect=None, clip_on=False, **kwargs) Bases: matplotlib.patches.FancyArrowPatch A ConnectionPatch class is to make connecting lines between two points (possibly in diﬀerent axes). Connect point xyA in coordsA with point xyB in coordsB Valid keys are 33.4. matplotlib.patches 337 Matplotlib, Release 0.99.1.1 Key arrowstyle connectionstyle relpos patchA patchB shrinkA shrinkB mutation_scale mutation_aspect ? Description the arrow style the connection style default is (0.5, 0.5) default is bounding box of the text default is None default is 2 points default is 2 points default is text size (in points) default is 1. any key for matplotlib.patches.PathPatch coordsA and coordsB are strings that indicate the coordinates of xyA and xyB. Property ‘ﬁgure points’ ‘ﬁgure pixels’ ‘ﬁgure fraction’ ‘axes points’ ‘axes pixels’ ‘axes fraction’ ‘data’ ‘oﬀset points’ ‘polar’ Description points from the lower left corner of the ﬁgure pixels from the lower left corner of the ﬁgure 0,0 is lower left of ﬁgure and 1,1 is upper, right points from lower left corner of axes pixels from lower left corner of axes 0,1 is lower left of axes and 1,1 is upper right use the coordinate system of the object being annotated (default) Specify an oﬀset (in points) from the xy value you can specify theta, r for the annotation, even in cartesian plots. Note that if you are using a polar axes, you do not need to specify polar for the coordinate system since that is the native “data” coordinate system. draw(renderer) Draw. get_annotation_clip() Return annotation_clip attribute. See set_annotation_clip() for the meaning of return values. get_path_in_displaycoord() Return the mutated path of the arrow in the display coord set_annotation_clip(b) set annotation_clip attribute. •True : the annotation will only be drawn when self.xy is inside the axes. •False : the annotation will always be drawn regardless of its position. 338 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 •None : the self.xy will be checked only if xycoords is “data” class ConnectionStyle() Bases: matplotlib.patches._Style ConnectionStyle is a container class which deﬁnes several connectionstyle classes, which is used to create a path between two points. These are mainly used with FancyArrowPatch. A connectionstyle object can be either created as: ConnectionStyle.Arc3(rad=0.2) or: ConnectionStyle("Arc3", rad=0.2) or: ConnectionStyle("Arc3, rad=0.2") The following classes are deﬁned Class Angle Angle3 Arc Arc3 Bar Name angle angle3 arc arc3 bar Attrs angleA=90,angleB=0,rad=0.0 angleA=90,angleB=0 angleA=0,angleB=0,armA=None,armB=None,rad=0.0 rad=0.0 armA=0.0,armB=0.0,fraction=0.3,angle=None An instance of any connection style class is an callable object, whose call signature is: __call__(self, posA, posB, patchA=None, patchB=None, shrinkA=2., shrinkB=2.) and it returns a Path instance. posA and posB are tuples of x,y coordinates of the two points to be connected. patchA (or patchB) is given, the returned path is clipped so that it start (or end) from the boundary of the patch. The path is further shrunk by shrinkA (or shrinkB) which is given in points. class Angle(angleA=90, angleB=0, rad=0.0) Bases: matplotlib.patches._Base Creates a picewise continuous quadratic bezier path between two points. The path has a one passing-through point placed at the intersecting point of two lines which crosses the start (or end) point and has a angle of angleA (or angleB). The connecting edges are rounded with rad. angleA starting angle of the path angleB ending angle of the path rad rounding radius of the edge connect(posA, posB) 33.4. matplotlib.patches 339 Matplotlib, Release 0.99.1.1 class Angle3(angleA=90, angleB=0) Bases: matplotlib.patches._Base Creates a simple quadratic bezier curve between two points. The middle control points is placed at the intersecting point of two lines which crosses the start (or end) point and has a angle of angleA (or angleB). angleA starting angle of the path angleB ending angle of the path connect(posA, posB) class Arc(angleA=0, angleB=0, armA=None, armB=None, rad=0.0) Bases: matplotlib.patches._Base Creates a picewise continuous quadratic bezier path between two points. The path can have two passing-through points, a point placed at the distance of armA and angle of angleA from point A, another point with respect to point B. The edges are rounded with rad. angleA : starting angle of the path angleB : ending angle of the path armA : length of the starting arm armB : length of the ending arm rad : rounding radius of the edges connect(posA, posB) class Arc3(rad=0.0) Bases: matplotlib.patches._Base Creates a simple quadratic bezier curve between two points. The curve is created so that the middle contol points (C1) is located at the same distance from the start (C0) and end points(C2) and the distance of the C1 to the line connecting C0-C2 is rad times the distance of C0-C2. rad curvature of the curve. connect(posA, posB) class Bar(armA=0.0, armB=0.0, fraction=0.29999999999999999, angle=None) Bases: matplotlib.patches._Base A line with angle between A and B with armA and armB. One of the arm is extend so that they are connected in a right angle. The length of armA is determined by (armA + fraction x AB distance). Same for armB. armA : minimum length of armA armB : minimum length of armB fraction : a fraction of the distance between two points that will be added to armA and armB. angle : anlge of the connecting line (if None, parallel to A and B) connect(posA, posB) class Ellipse(xy, width, height, angle=0.0, **kwargs) Bases: matplotlib.patches.Patch 340 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 A scale-free ellipse. xy center of ellipse width length of horizontal axis height length of vertical axis angle rotation in degrees (anti-clockwise) Valid kwargs are: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number contains(ev) get_patch_transform() get_path() Return the vertices of the rectangle class FancyArrow(x, y, dx, dy, width=0.001, length_includes_head=False, head_width=None, head_length=None, shape=’full’, overhang=0, head_starts_at_zero=False, **kwargs) Bases: matplotlib.patches.Polygon Like Arrow, but lets you set head width and head height independently. Constructor arguments 33.4. matplotlib.patches 341 Matplotlib, Release 0.99.1.1 length_includes_head: True if head is counted in calculating the length. shape: [’full’, ‘left’, ‘right’] overhang: distance that the arrow is swept back (0 overhang means triangular shape). head_starts_at_zero: If True, the head starts being drawn at coordinate 0 instead of ending at coordinate 0. Valid kwargs are: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number class FancyArrowPatch(posA=None, posB=None, path=None, arrowstyle=’simple’, arrow_transmuter=None, connectionstyle=’arc3’, connector=None, patchA=None, patchB=None, shrinkA=2.0, shrinkB=2.0, mutation_scale=1.0, mutation_aspect=None, **kwargs) Bases: matplotlib.patches.Patch A fancy arrow patch. It draws an arrow using the :class:ArrowStyle. If posA and posB is given, a path connecting two point are created according to the connectionstyle. The path will be clipped with patchA and patchB and further shirnked by shrinkA and shrinkB. An arrow is drawn along this resulting path using the arrowstyle parameter. If path provided, an arrow is drawn along this path and patchA, patchB, shrinkA, and shrinkB are ignored. 342 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 The connectionstyle describes how posA and posB are connected. It can be an instance of the ConnectionStyle class (matplotlib.patches.ConnectionStlye) or a string of the connectionstyle name, with optional comma-separated attributes. The following connection styles are available. Class Angle Angle3 Arc Arc3 Bar Name angle angle3 arc arc3 bar Attrs angleA=90,angleB=0,rad=0.0 angleA=90,angleB=0 angleA=0,angleB=0,armA=None,armB=None,rad=0.0 rad=0.0 armA=0.0,armB=0.0,fraction=0.3,angle=None The arrowstyle describes how the fancy arrow will be drawn. It can be string of the available arrowstyle names, with optional comma-separated attributes, or one of the ArrowStyle instance. The optional attributes are meant to be scaled with the mutation_scale. The following arrow styles are available. Class Curve CurveB BracketB CurveFilledB CurveA CurveAB CurveFilledA CurveFilledAB Fancy Simple Wedge Name -> -[ -|> <<-> <|<|-|> fancy simple wedge Attrs None head_length=0.4,head_width=0.2 widthB=1.0,lengthB=0.2,angleB=None head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.2 head_length=0.4,head_width=0.4,tail_width=0.4 head_length=0.5,head_width=0.5,tail_width=0.2 tail_width=0.3,shrink_factor=0.5 mutation_scale [a value with which attributes of arrowstyle] (e.g., head_length) will be scaled. default=1. mutation_aspect [The height of the rectangle will be] squeezed by this value before the mutation and the mutated box will be stretched by the inverse of it. default=None. Valid kwargs are: 33.4. matplotlib.patches 343 Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number draw(renderer) get_arrowstyle() Return the arrowstyle object get_connectionstyle() Return the ConnectionStyle instance get_mutation_aspect() Return the aspect ratio of the bbox mutation. get_mutation_scale() Return the mutation scale. get_path() return the path of the arrow in the data coordinate. Use get_path_in_displaycoord() medthod to retrieve the arrow path in the disaply coord. get_path_in_displaycoord() Return the mutated path of the arrow in the display coord set_arrowstyle(arrowstyle=None, **kw) Set the arrow style. 344 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 arrowstyle can be a string with arrowstyle name with optional comma-separated attributes. Alternatively, the attrs can be provided as keywords. set_arrowstyle(“Fancy,head_length=0.2”) set_arrowstyle(“fancy”, head_length=0.2) Old attrs simply are forgotten. Without argument (or with arrowstyle=None), return available box styles as a list of strings. set_connectionstyle(connectionstyle, **kw) Set the connection style. connectionstyle can be a string with connectionstyle name with optional comma-separated attributes. Alternatively, the attrs can be probided as keywords. set_connectionstyle(“arc,angleA=0,armA=30,rad=10”) gleA=0,armA=30,rad=10) set_connectionstyle(“arc”, an- Old attrs simply are forgotten. Without argument (or with connectionstyle=None), return available styles as a list of strings. set_mutation_aspect(aspect) Set the aspect ratio of the bbox mutation. ACCEPTS: ﬂoat set_mutation_scale(scale) Set the mutation scale. ACCEPTS: ﬂoat set_patchA(patchA) set the begin patch. set_patchB(patchB) set the begin patch set_positions(posA, posB) set the begin end end positions of the connecting path. Use current vlaue if None. class FancyBboxPatch(xy, width, height, boxstyle=’round’, bbox_transmuter=None, mutation_scale=1.0, mutation_aspect=None, **kwargs) Bases: matplotlib.patches.Patch Draw a fancy box around a rectangle with lower left at xy*=(*x, y) with speciﬁed width and height. FancyBboxPatch class is similar to Rectangle class, but it draws a fancy box around the rectangle. The transformation of the rectangle box to the fancy box is delegated to the BoxTransmuterBase and its derived classes. xy = lower left corner width, height boxstyle determines what kind of fancy box will be drawn. It can be a string of the style name with a comma separated attribute, or an instance of BoxStyle. Following box styles are available. 33.4. matplotlib.patches 345 Matplotlib, Release 0.99.1.1 Class LArrow RArrow Round Round4 Roundtooth Sawtooth Square Name larrow rarrow round round4 roundtooth sawtooth square Attrs pad=0.3 pad=0.3 pad=0.3,rounding_size=None pad=0.3,rounding_size=None pad=0.3,tooth_size=None pad=0.3,tooth_size=None pad=0.3 mutation_scale : a value with which attributes of boxstyle (e.g., pad) will be scaled. default=1. mutation_aspect : The height of the rectangle will be squeezed by this value before the mutation and the mutated box will be stretched by the inverse of it. default=None. Valid kwargs are: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number get_bbox() get_boxstyle() Return the boxstyle object get_height() Return the height of the rectangle 346 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 get_mutation_aspect() Return the aspect ratio of the bbox mutation. get_mutation_scale() Return the mutation scale. get_path() Return the mutated path of the rectangle get_width() Return the width of the rectangle get_x() Return the left coord of the rectangle get_y() Return the bottom coord of the rectangle set_bounds(*args) Set the bounds of the rectangle: l,b,w,h ACCEPTS: (left, bottom, width, height) set_boxstyle(boxstyle=None, **kw) Set the box style. boxstyle can be a string with boxstyle name with optional comma-separated attributes. Alternatively, the attrs can be provided as keywords: set_boxstyle("round,pad=0.2") set_boxstyle("round", pad=0.2) Old attrs simply are forgotten. Without argument (or with boxstyle = None), it returns available box styles. ACCEPTS: [ Class LArrow RArrow Round Round4 Roundtooth Sawtooth Square Name larrow rarrow round round4 roundtooth sawtooth square Attrs pad=0.3 pad=0.3 pad=0.3,rounding_size=None pad=0.3,rounding_size=None pad=0.3,tooth_size=None pad=0.3,tooth_size=None pad=0.3 set_height(h) Set the width rectangle ACCEPTS: ﬂoat set_mutation_aspect(aspect) Set the aspect ratio of the bbox mutation. ACCEPTS: ﬂoat 33.4. matplotlib.patches 347 Matplotlib, Release 0.99.1.1 set_mutation_scale(scale) Set the mutation scale. ACCEPTS: ﬂoat set_width(w) Set the width rectangle ACCEPTS: ﬂoat set_x(x) Set the left coord of the rectangle ACCEPTS: ﬂoat set_y(y) Set the bottom coord of the rectangle ACCEPTS: ﬂoat class Patch(edgecolor=None, facecolor=None, linewidth=None, linestyle=None, antialiased=None, hatch=None, ﬁll=True, **kwargs) Bases: matplotlib.artist.Artist A patch is a 2D thingy with a face color and an edge color. If any of edgecolor, facecolor, linewidth, or antialiased are None, they default to their rc params setting. The following kwarg properties are supported 348 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number contains(mouseevent) Test whether the mouse event occurred in the patch. Returns T/F, {} contains_point(point) Returns True if the given point is inside the path (transformed with its transform attribute). draw(artist, renderer, *kl) Draw the Patch to the given renderer. get_aa() Returns True if the Patch is to be drawn with antialiasing. get_antialiased() Returns True if the Patch is to be drawn with antialiasing. get_data_transform() get_ec() Return the edge color of the Patch. get_edgecolor() Return the edge color of the Patch. 33.4. matplotlib.patches 349 Matplotlib, Release 0.99.1.1 get_extents() Return a Bbox object deﬁning the axis-aligned extents of the Patch. get_facecolor() Return the face color of the Patch. get_fc() Return the face color of the Patch. get_fill() return whether ﬁll is set get_hatch() Return the current hatching pattern get_linestyle() Return the linestyle. Will be one of [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] get_linewidth() Return the line width in points. get_ls() Return the linestyle. Will be one of [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] get_lw() Return the line width in points. get_patch_transform() get_path() Return the path of this patch get_transform() Return the Transform applied to the Patch. get_verts() Return a copy of the vertices used in this patch If the patch contains Bézier curves, the curves will be interpolated by line segments. To access the curves as curves, use get_path(). get_window_extent(renderer=None) set_aa(aa) alias for set_antialiased set_antialiased(aa) Set whether to use antialiased rendering ACCEPTS: [True | False] or None for default set_color(c) Set both the edgecolor and the facecolor. ACCEPTS: matplotlib color arg or sequence of rgba tuples See Also: 350 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 set_facecolor(), set_edgecolor() For setting the edge or face color individually. set_ec(color) alias for set_edgecolor set_edgecolor(color) Set the patch edge color ACCEPTS: mpl color spec, or None for default, or ‘none’ for no color set_facecolor(color) Set the patch face color ACCEPTS: mpl color spec, or None for default, or ‘none’ for no color set_fc(color) alias for set_facecolor set_fill(b) Set whether to ﬁll the patch ACCEPTS: [True | False] set_hatch(hatch) Set the hatching pattern hatch can be one of: / \ | + x o O . * - diagonal hatching back diagonal vertical horizontal crossed crossed diagonal small circle large circle dots stars Letters can be combined, in which case all the speciﬁed hatchings are done. If same letter repeats, it increases the density of hatching of that pattern. Hatching is supported in the PostScript, PDF, SVG and Agg backends only. ACCEPTS: [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] set_linestyle(ls) Set the patch linestyle ACCEPTS: [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] set_linewidth(w) Set the patch linewidth in points ACCEPTS: ﬂoat or None for default 33.4. matplotlib.patches 351 Matplotlib, Release 0.99.1.1 set_ls(ls) alias for set_linestyle set_lw(lw) alias for set_linewidth update_from(other) Updates this Patch from the properties of other. class PathPatch(path, **kwargs) Bases: matplotlib.patches.Patch A general polycurve path patch. path is a matplotlib.path.Path object. Valid kwargs are: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number See Also: Patch For additional kwargs get_path() 352 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 class Polygon(xy, closed=True, **kwargs) Bases: matplotlib.patches.Patch A general polygon patch. xy is a numpy array with shape Nx2. If closed is True, the polygon will be closed so the starting and ending points are the same. Valid kwargs are: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number See Also: Patch For additional kwargs get_closed() get_path() get_xy() set_closed(closed) set_xy(vertices) 33.4. matplotlib.patches 353 Matplotlib, Release 0.99.1.1 xy Set/get the vertices of the polygon. This property is provided for backward compatibility with matplotlib 0.91.x only. New code should use get_xy() and set_xy() instead. class Rectangle(xy, width, height, **kwargs) Bases: matplotlib.patches.Patch Draw a rectangle with lower left at xy = (x, y) with speciﬁed width and height. ﬁll is a boolean indicating whether to ﬁll the rectangle Valid kwargs are: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number contains(mouseevent) get_bbox() get_height() Return the height of the rectangle get_patch_transform() get_path() Return the vertices of the rectangle 354 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 get_width() Return the width of the rectangle get_x() Return the left coord of the rectangle get_xy() Return the left and bottom coords of the rectangle get_y() Return the bottom coord of the rectangle set_bounds(*args) Set the bounds of the rectangle: l,b,w,h ACCEPTS: (left, bottom, width, height) set_height(h) Set the width rectangle ACCEPTS: ﬂoat set_width(w) Set the width rectangle ACCEPTS: ﬂoat set_x(x) Set the left coord of the rectangle ACCEPTS: ﬂoat set_xy(xy) Set the left and bottom coords of the rectangle ACCEPTS: 2-item sequence set_y(y) Set the bottom coord of the rectangle ACCEPTS: ﬂoat xy Return the left and bottom coords of the rectangle class RegularPolygon(xy, numVertices, radius=5, orientation=0, **kwargs) Bases: matplotlib.patches.Patch A regular polygon patch. Constructor arguments: xy A length 2 tuple (x, y) of the center. numVertices the number of vertices. radius The distance from the center to each of the vertices. orientation rotates the polygon (in radians). 33.4. matplotlib.patches 355 Matplotlib, Release 0.99.1.1 Valid kwargs are: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number get_patch_transform() get_path() numvertices orientation radius xy class Shadow(patch, ox, oy, props=None, **kwargs) Bases: matplotlib.patches.Patch Create a shadow of the given patch oﬀset by ox, oy. props, if not None, is a patch property update dictionary. If None, the shadow will have have the same color as the face, but darkened. kwargs are 356 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number draw(renderer) get_patch_transform() get_path() class Wedge(center, r, theta1, theta2, width=None, **kwargs) Bases: matplotlib.patches.Patch Wedge shaped patch. Draw a wedge centered at x, y center with radius r that sweeps theta1 to theta2 (in degrees). If width is given, then a partial wedge is drawn from inner radius r - width to outer radius r. Valid kwargs are: 33.4. matplotlib.patches 357 Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number get_path() class YAArrow(ﬁgure, xytip, xybase, width=4, frac=0.10000000000000001, headwidth=12, **kwargs) Bases: matplotlib.patches.Patch Yet another arrow class. This is an arrow that is deﬁned in display space and has a tip at x1, y1 and a base at x2, y2. Constructor arguments: xytip (x, y) location of arrow tip xybase (x, y) location the arrow base mid point ﬁgure The Figure instance (ﬁg.dpi) width The width of the arrow in points frac The fraction of the arrow length occupied by the head headwidth The width of the base of the arrow head in points Valid kwargs are: 358 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number get_patch_transform() get_path() getpoints(x1, y1, x2, y2, k) For line segment deﬁned by (x1, y1) and (x2, y2) return the points on the line that is perpendicular to the line and intersects (x2, y2) and the distance from (x2, y2) of the returned points is k. bbox_artist(artist, renderer, props=None, ﬁll=True) This is a debug function to draw a rectangle around the bounding box returned by get_window_extent() of an artist, to test whether the artist is returning the correct bbox. props is a dict of rectangle props with the additional property ‘pad’ that sets the padding around the bbox in points. draw_bbox(bbox, renderer, color=’k’, trans=None) This is a debug function to draw a rectangle around the bounding box returned by get_window_extent() of an artist, to test whether the artist is returning the correct bbox. 33.5 matplotlib.text 33.5. matplotlib.text 359 Matplotlib, Release 0.99.1.1 Classes for including text in a ﬁgure. class Annotation(s, xy, xytext=None, xycoords=’data’, textcoords=None, arrowprops=None, **kwargs) Bases: matplotlib.text.Text A Text class to make annotating things in the ﬁgure, such as Figure, Axes, Rectangle, etc., easier. Annotate the x, y point xy with text s at x, y location xytext. (If xytext = None, defaults to xy, and if textcoords = None, defaults to xycoords). arrowprops, if not None, is a dictionary of line properties (see matplotlib.lines.Line2D) for the arrow that connects annotation to the point. If the dictionary has a key arrowstyle, a FancyArrowPatch instance is created with the given dictionary and is drawn. Otherwise, a YAArow patch instance is created and drawn. Valid keys for YAArow are Key width frac headwidth shrink ? Description the width of the arrow in points the fraction of the arrow length occupied by the head the width of the base of the arrow head in points oftentimes it is convenient to have the arrowtip and base a bit away from the text and point being annotated. If d is the distance between the text and annotated point, shrink will shorten the arrow so the tip and base are shink percent of the distance d away from the endpoints. ie, shrink=0.05 is 5% any key for matplotlib.patches.polygon Valid keys for FancyArrowPatch are Key arrowstyle connectionstyle relpos patchA patchB shrinkA shrinkB mutation_scale mutation_aspect ? Description the arrow style the connection style default is (0.5, 0.5) default is bounding box of the text default is None default is 2 points default is 2 points default is text size (in points) default is 1. any key for matplotlib.patches.PathPatch xycoords and textcoords are strings that indicate the coordinates of xy and xytext. 360 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 Property ‘ﬁgure points’ ‘ﬁgure pixels’ ‘ﬁgure fraction’ ‘axes points’ ‘axes pixels’ ‘axes fraction’ ‘data’ ‘oﬀset points’ ‘polar’ Description points from the lower left corner of the ﬁgure pixels from the lower left corner of the ﬁgure 0,0 is lower left of ﬁgure and 1,1 is upper, right points from lower left corner of axes pixels from lower left corner of axes 0,1 is lower left of axes and 1,1 is upper right use the coordinate system of the object being annotated (default) Specify an oﬀset (in points) from the xy value you can specify theta, r for the annotation, even in cartesian plots. Note that if you are using a polar axes, you do not need to specify polar for the coordinate system since that is the native “data” coordinate system. If a ‘points’ or ‘pixels’ option is speciﬁed, values will be added to the bottom-left and if negative, values will be subtracted from the top-right. Eg: # 10 points to the right of the left border of the axes and # 5 points below the top border xy=(10,-5), xycoords=’axes points’ Additional kwargs are Text properties: Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing 33.5. matplotlib.text Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) 361 Matplotlib, Release 0.99.1.1 Table 33.3 – continued from lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number contains(event) draw(renderer) Draw the Annotation object to the given renderer. get_annotation_clip() Return annotation_clip attribute. See set_annotation_clip() for the meaning of return values. set_annotation_clip(b) set annotation_clip attribute. •True : the annotation will only be drawn when self.xy is inside the axes. •False : the annotation will always be drawn regardless of its position. •None : the self.xy will be checked only if xycoords is “data” set_figure(ﬁg) update_positions(renderer) Update the pixel positions of the annotated point and the text. class Text(x=0, y=0, text=”, color=None, verticalalignment=’bottom’, horizontalalignment=’left’, multialignment=None, fontproperties=None, rotation=None, linespacing=None, rotation_mode=None, **kwargs) Bases: matplotlib.artist.Artist 362 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 Handle storing and drawing of text in window or data coordinates. Create a Text instance at x, y with string text. Valid kwargs are Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number contains(mouseevent) 33.5. matplotlib.text 363 Matplotlib, Release 0.99.1.1 Test whether the mouse event occurred in the patch. In the case of text, a hit is true anywhere in the axis-aligned bounding-box containing the text. Returns True or False. draw(renderer) Draws the Text object to the given renderer. get_bbox_patch() Return the bbox Patch object. Returns None if the the FancyBboxPatch is not made. get_color() Return the color of the text get_family() Return the list of font families used for font lookup get_font_properties() alias for get_fontproperties get_fontfamily() alias for get_family get_fontname() alias for get_name get_fontproperties() Return the FontProperties object get_fontsize() alias for get_size get_fontstretch() alias for get_stretch get_fontstyle() alias for get_style get_fontvariant() alias for get_variant get_fontweight() alias for get_weight get_ha() alias for get_horizontalalignment get_horizontalalignment() Return the horizontal alignment as string. Will be one of ‘left’, ‘center’ or ‘right’. get_name() Return the font name as string get_position() Return the position of the text as a tuple (x, y) 364 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 get_prop_tup() Return a hashable tuple of properties. Not intended to be human readable, but useful for backends who want to cache derived information about text (eg layouts) and need to know if the text has changed. get_rotation() return the text angle as ﬂoat in degrees get_rotation_mode() get text rotation mode get_size() Return the font size as integer get_stretch() Get the font stretch as a string or number get_style() Return the font style as string get_text() Get the text as string get_va() alias for getverticalalignment() get_variant() Return the font variant as a string get_verticalalignment() Return the vertical alignment as string. Will be one of ‘top’, ‘center’, ‘bottom’ or ‘baseline’. get_weight() Get the font weight as string or number get_window_extent(renderer=None, dpi=None) Return a Bbox object bounding the text, in display units. In addition to being used internally, this is useful for specifying clickable regions in a png ﬁle on a web page. renderer defaults to the _renderer attribute of the text object. This is not assigned until the ﬁrst execution of draw(), so you must use this kwarg if you want to call get_window_extent() prior to the ﬁrst draw(). For getting web page regions, it is simpler to call the method after saving the ﬁgure. dpi defaults to self.ﬁgure.dpi; the renderer dpi is irrelevant. For the web application, if ﬁgure.dpi is not the value used when saving the ﬁgure, then the value that was used must be speciﬁed as the dpi argument. is_math_text(s) Returns True if the given string s contains any mathtext. set_backgroundcolor(color) Set the background color of the text by updating the bbox. 33.5. matplotlib.text 365 Matplotlib, Release 0.99.1.1 See Also: set_bbox() To change the position of the bounding box. ACCEPTS: any matplotlib color set_bbox(rectprops) Draw a bounding box around self. rectprops are any settable properties for a rectangle, eg facecolor=’red’, alpha=0.5. t.set_bbox(dict(facecolor=’red’, alpha=0.5)) If rectprops has “boxstyle” key. A FancyBboxPatch is initialized with rectprops and will be drawn. The mutation scale of the FancyBboxPath is set to the fontsize. ACCEPTS: rectangle prop dict set_color(color) Set the foreground color of the text ACCEPTS: any matplotlib color set_family(fontname) Set the font family. May be either a single string, or a list of strings in decreasing priority. Each string may be either a real font name or a generic font class name. If the latter, the speciﬁc font names will be looked up in the matplotlibrc ﬁle. ACCEPTS: [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] set_font_properties(fp) alias for set_fontproperties set_fontname(fontname) alias for set_family set_fontproperties(fp) Set the font properties that control the matplotlib.font_manager.FontProperties object. text. fp must be a ACCEPTS: a matplotlib.font_manager.FontProperties instance set_fontsize(fontsize) alias for set_size set_fontstretch(stretch) alias for set_stretch set_fontstyle(fontstyle) alias for set_style set_fontvariant(variant) alias for set_variant set_fontweight(weight) alias for set_weight 366 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 set_ha(align) alias for set_horizontalalignment set_horizontalalignment(align) Set the horizontal alignment to one of ACCEPTS: [ ‘center’ | ‘right’ | ‘left’ ] set_linespacing(spacing) Set the line spacing as a multiple of the font size. Default is 1.2. ACCEPTS: ﬂoat (multiple of font size) set_ma(align) alias for set_verticalalignment set_multialignment(align) Set the alignment for multiple lines layout. The layout of the bounding box of all the lines is determined bu the horizontalalignment and verticalalignment properties, but the multiline text within that box can be ACCEPTS: [’left’ | ‘right’ | ‘center’ ] set_name(fontname) alias for set_family set_position(xy) Set the (x, y) position of the text ACCEPTS: (x,y) set_rotation(s) Set the rotation of the text ACCEPTS: [ angle in degrees | ‘vertical’ | ‘horizontal’ ] set_rotation_mode(m) set text rotation mode. If “anchor”, the un-rotated text will ﬁrst aligned according to their ha and va, and then will be rotated with the alignement reference point as a origin. If None (default), the text will be rotated ﬁrst then will be aligned. set_size(fontsize) Set the font size. May be either a size string, relative to the default font size, or an absolute font size in points. ACCEPTS: [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ | ‘xx-large’ ] set_stretch(stretch) Set the font stretch (horizontal condensation or expansion). ACCEPTS: [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘condensed’ | ‘semi-condensed’ | ‘normal’ | ‘semi-expanded’ | ‘expanded’ | ‘extra-expanded’ | ‘ultraexpanded’ ] set_style(fontstyle) Set the font style. 33.5. matplotlib.text 367 Matplotlib, Release 0.99.1.1 ACCEPTS: [ ‘normal’ | ‘italic’ | ‘oblique’] set_text(s) Set the text string s It may contain newlines (\n) or math in LaTeX syntax. ACCEPTS: string or anything printable with ‘%s’ conversion. set_va(align) alias for set_verticalalignment set_variant(variant) Set the font variant, either ‘normal’ or ‘small-caps’. ACCEPTS: [ ‘normal’ | ‘small-caps’ ] set_verticalalignment(align) Set the vertical alignment ACCEPTS: [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] set_weight(weight) Set the font weight. ACCEPTS: [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ‘book’ | ‘medium’ | ‘roman’ | ‘semibold’ | ‘demibold’ | ‘demi’ | ‘bold’ | ‘heavy’ | ‘extra bold’ | ‘black’ ] set_x(x) Set the x position of the text ACCEPTS: ﬂoat set_y(y) Set the y position of the text ACCEPTS: ﬂoat update_bbox_position_size(renderer) Update the location and the size of the bbox. This method should be used when the position and size of the bbox needs to be updated before actually drawing the bbox. update_from(other) Copy properties from other to self class TextWithDash(x=0, y=0, text=”, color=None, verticalalignment=’center’, horizontalalignment=’center’, multialignment=None, fontproperties=None, rotation=None, linespacing=None, dashlength=0.0, dashdirection=0, dashrotation=None, dashpad=3, dashpush=0) Bases: matplotlib.text.Text This is basically a Text with a dash (drawn with a Line2D) before/after it. It is intended to be a drop-in replacement for Text, and should behave identically to it when dashlength = 0.0. The dash always comes between the point speciﬁed by set_position() and the text. When a dash exists, the text alignment arguments (horizontalalignment, verticalalignment) are ignored. dashlength is the length of the dash in canvas units. (default = 0.0). 368 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 dashdirection is one of 0 or 1, where 0 draws the dash after the text and 1 before. (default = 0). dashrotation speciﬁes the rotation of the dash, and should generally stay None. In this case get_dashrotation() returns get_rotation(). (I.e., the dash takes its rotation from the text’s rotation). Because the text center is projected onto the dash, major deviations in the rotation cause what may be considered visually unappealing results. (default = None) dashpad is a padding length to add (or subtract) space between the text and the dash, in canvas units. (default = 3) dashpush “pushes” the dash and text away from the point speciﬁed by set_position() by the amount in canvas units. (default = 0) Note: The alignment of the two objects is based on the bounding box of the Text, as obtained by get_window_extent(). This, in turn, appears to depend on the font metrics as given by the rendering backend. Hence the quality of the “centering” of the label text with respect to the dash varies depending on the backend used. Note: I’m not sure that I got the get_window_extent() right, or whether that’s suﬃcient for providing the object bounding box. draw(renderer) Draw the TextWithDash object to the given renderer. get_dashdirection() Get the direction dash. 1 is before the text and 0 is after. get_dashlength() Get the length of the dash. get_dashpad() Get the extra spacing between the dash and the text, in canvas units. get_dashpush() Get the extra spacing between the dash and the speciﬁed text position, in canvas units. get_dashrotation() Get the rotation of the dash in degrees. get_figure() return the ﬁgure instance the artist belongs to get_position() Return the position of the text as a tuple (x, y) get_prop_tup() Return a hashable tuple of properties. Not intended to be human readable, but useful for backends who want to cache derived information about text (eg layouts) and need to know if the text has changed. get_window_extent(renderer=None) Return a Bbox object bounding the text, in display units. In addition to being used internally, this is useful for specifying clickable regions in a png ﬁle on a web page. 33.5. matplotlib.text 369 Matplotlib, Release 0.99.1.1 renderer defaults to the _renderer attribute of the text object. This is not assigned until the ﬁrst execution of draw(), so you must use this kwarg if you want to call get_window_extent() prior to the ﬁrst draw(). For getting web page regions, it is simpler to call the method after saving the ﬁgure. set_dashdirection(dd) Set the direction of the dash following the text. 1 is before the text and 0 is after. The default is 0, which is what you’d want for the typical case of ticks below and on the left of the ﬁgure. ACCEPTS: int (1 is before, 0 is after) set_dashlength(dl) Set the length of the dash. ACCEPTS: ﬂoat (canvas units) set_dashpad(dp) Set the “pad” of the TextWithDash, which is the extra spacing between the dash and the text, in canvas units. ACCEPTS: ﬂoat (canvas units) set_dashpush(dp) Set the “push” of the TextWithDash, which is the extra spacing between the beginning of the dash and the speciﬁed position. ACCEPTS: ﬂoat (canvas units) set_dashrotation(dr) Set the rotation of the dash, in degrees ACCEPTS: ﬂoat (degrees) set_figure(ﬁg) Set the ﬁgure instance the artist belong to. ACCEPTS: a matplotlib.figure.Figure instance set_position(xy) Set the (x, y) position of the TextWithDash. ACCEPTS: (x, y) set_transform(t) Set the matplotlib.transforms.Transform instance used by this artist. ACCEPTS: a matplotlib.transforms.Transform instance set_x(x) Set the x position of the TextWithDash. ACCEPTS: ﬂoat set_y(y) Set the y position of the TextWithDash. ACCEPTS: ﬂoat 370 Chapter 33. matplotlib artists Matplotlib, Release 0.99.1.1 update_coords(renderer) Computes the actual x, y coordinates for text based on the input x, y and the dashlength. Since the rotation is with respect to the actual canvas’s coordinates we need to map back and forth. get_rotation(rotation) Return the text angle as ﬂoat. rotation may be ‘horizontal’, ‘vertical’, or a numeric value in degrees. 33.5. matplotlib.text 371 Matplotlib, Release 0.99.1.1 372 Chapter 33. matplotlib artists CHAPTER THIRTYFOUR MATPLOTLIB AXES 34.1 matplotlib.axes class Axes(ﬁg, rect, axisbg=None, frameon=True, sharex=None, sharey=None, label=”, xscale=None, yscale=None, **kwargs) Bases: matplotlib.artist.Artist The Axes contains most of the ﬁgure elements: Axis, Tick, Line2D, Text, Polygon, etc., and sets the coordinate system. The Axes instance supports callbacks through a callbacks attribute which is a CallbackRegistry instance. The events you can connect to are ‘xlim_changed’ and ‘ylim_changed’ and the callback will be called with func(ax) where ax is the Axes instance. acorr(x, **kwargs) call signature: acorr(x, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags=10, **kwargs) Plot the autocorrelation of x. If normed = True, normalize the data by the autocorrelation at 0-th lag. x is detrended by the detrend callable (default no normalization). Data are plotted as plot(lags, c, **kwargs) Return value is a tuple (lags, c, line) where: •lags are a length 2*maxlags+1 lag vector •c is the 2*maxlags+1 auto correlation vector •line is a Line2D instance returned by plot() The default linestyle is None and the default marker is ’o’, though these can be overridden with keyword args. The cross correlation is performed with numpy.correlate() with mode = 2. If usevlines is True, vlines() rather than plot() is used to draw vertical lines from the origin to the acorr. Otherwise, the plot style is determined by the kwargs, which are Line2D properties. maxlags is a positive integer detailing the number of lags to show. The default value of None will return all 2imeslen( x) − 1 lags. 373 Matplotlib, Release 0.99.1.1 The return value is a tuple (lags, c, linecol, b) where •linecol is the LineCollection •b is the x-axis. See Also: plot() or vlines() For documentation on valid kwargs. Example: xcorr() above, and acorr() below. Example: add_artist(a) Add any Artist to the axes. Returns the artist. add_collection(collection, autolim=True) Add a Collection instance to the axes. Returns the collection. add_line(line) Add a Line2D to the list of plot lines 374 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Returns the line. add_patch(p) Add a Patch p to the list of axes patches; the clipbox will be set to the Axes clipping box. If the transform is not set, it will be set to transData. Returns the patch. add_table(tab) Add a Table instance to the list of axes tables Returns the table. annotate(*args, **kwargs) call signature: annotate(s, xy, xytext=None, xycoords=’data’, textcoords=’data’, arrowprops=None, **kwargs) Keyword arguments: Annotate the x, y point xy with text s at x, y location xytext. (If xytext = None, defaults to xy, and if textcoords = None, defaults to xycoords). arrowprops, if not None, is a dictionary of line properties (see matplotlib.lines.Line2D) for the arrow that connects annotation to the point. If the dictionary has a key arrowstyle, a FancyArrowPatch instance is created with the given dictionary and is drawn. Otherwise, a YAArow patch instance is created and drawn. Valid keys for YAArow are Key width frac headwidth shrink ? Description the width of the arrow in points the fraction of the arrow length occupied by the head the width of the base of the arrow head in points oftentimes it is convenient to have the arrowtip and base a bit away from the text and point being annotated. If d is the distance between the text and annotated point, shrink will shorten the arrow so the tip and base are shink percent of the distance d away from the endpoints. ie, shrink=0.05 is 5% any key for matplotlib.patches.polygon Valid keys for FancyArrowPatch are 34.1. matplotlib.axes 375 Matplotlib, Release 0.99.1.1 Key arrowstyle connectionstyle relpos patchA patchB shrinkA shrinkB mutation_scale mutation_aspect ? Description the arrow style the connection style default is (0.5, 0.5) default is bounding box of the text default is None default is 2 points default is 2 points default is text size (in points) default is 1. any key for matplotlib.patches.PathPatch xycoords and textcoords are strings that indicate the coordinates of xy and xytext. Property ‘ﬁgure points’ ‘ﬁgure pixels’ ‘ﬁgure fraction’ ‘axes points’ ‘axes pixels’ ‘axes fraction’ ‘data’ ‘oﬀset points’ ‘polar’ Description points from the lower left corner of the ﬁgure pixels from the lower left corner of the ﬁgure 0,0 is lower left of ﬁgure and 1,1 is upper, right points from lower left corner of axes pixels from lower left corner of axes 0,1 is lower left of axes and 1,1 is upper right use the coordinate system of the object being annotated (default) Specify an oset (in points) from the xy value you can specify theta, r for the annotation, even in cartesian plots. Note that if you are using a polar axes, you do not need to specify polar for the coordinate system since that is the native “data” coordinate system. If a ‘points’ or ‘pixels’ option is speciﬁed, values will be added to the bottom-left and if negative, values will be subtracted from the top-right. Eg: # 10 points to the right of the left border of the axes and # 5 points below the top border xy=(10,-5), xycoords=’axes points’ Additional kwargs are Text properties: Property alpha animated axes backgroundcolor 376 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.1 – continued from bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder 34.1. matplotlib.axes rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number 377 Matplotlib, Release 0.99.1.1 apply_aspect(position=None) Use _aspect() and _adjustable() to modify the axes box or the view limits. arrow(x, y, dx, dy, **kwargs) 378 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 call signature: arrow(x, y, dx, dy, **kwargs) Draws arrow on speciﬁed axis from (x, y) to (x + dx, y + dy). Optional kwargs control the arrow properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: 34.1. matplotlib.axes 379 Matplotlib, Release 0.99.1.1 autoscale_view(tight=False, scalex=True, scaley=True) autoscale the view limits using the data limits. You can selectively autoscale only a single axis, eg, the xaxis by setting scaley to False. The autoscaling preserves any axis direction reversal that has already been done. axhline(y=0, xmin=0, xmax=1, **kwargs) call signature: axhline(y=0, xmin=0, xmax=1, **kwargs) Axis Horizontal Line Draw a horizontal line at y from xmin to xmax. With the default values of xmin = 0 and xmax = 1, this line will always span the horizontal extent of the axes, regardless of the xlim settings, even if you change them, eg. with the set_xlim() command. That is, the horizontal extent is in axes coords: 0=left, 0.5=middle, 1.0=right but the y location is in data coordinates. Return value is the Line2D instance. kwargs are the same as kwargs to plot, and can be used to control the line properties. Eg., •draw a thick red hline at y = 0 that spans the xrange >>> axhline(linewidth=4, color=’r’) •draw a default hline at y = 1 that spans the xrange >>> axhline(y=1) 380 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 •draw a default hline at y = .5 that spans the the middle half of the xrange >>> axhline(y=.5, xmin=0.25, xmax=0.75) Valid kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder 34.1. matplotlib.axes Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number 381 Matplotlib, Release 0.99.1.1 See Also: axhspan() for example plot and source code axhspan(ymin, ymax, xmin=0, xmax=1, **kwargs) call signature: axhspan(ymin, ymax, xmin=0, xmax=1, **kwargs) Axis Horizontal Span. y coords are in data units and x coords are in axes (relative 0-1) units. Draw a horizontal span (rectangle) from ymin to ymax. With the default values of xmin = 0 and xmax = 1, this always spans the xrange, regardless of the xlim settings, even if you change them, eg. with the set_xlim() command. That is, the horizontal extent is in axes coords: 0=left, 0.5=middle, 1.0=right but the y location is in data coordinates. Return value is a matplotlib.patches.Polygon instance. Examples: •draw a gray rectangle from y = 0.25-0.75 that spans the horizontal extent of the axes >>> axhspan(0.25, 0.75, facecolor=’0.5’, alpha=0.5) Valid kwargs are Polygon properties: 382 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: 34.1. matplotlib.axes 383 Matplotlib, Release 0.99.1.1 axis(*v, **kwargs) Convenience method for manipulating the x and y view limits and the aspect ratio of the plot. kwargs are passed on to set_xlim() and set_ylim() axvline(x=0, ymin=0, ymax=1, **kwargs) call signature: axvline(x=0, ymin=0, ymax=1, **kwargs) Axis Vertical Line Draw a vertical line at x from ymin to ymax. With the default values of ymin = 0 and ymax = 1, this line will always span the vertical extent of the axes, regardless of the ylim settings, even if you change them, eg. with the set_ylim() command. That is, the vertical extent is in axes coords: 0=bottom, 0.5=middle, 1.0=top but the x location is in data coordinates. Return value is the Line2D instance. kwargs are the same as kwargs to plot, and can be used to control the line properties. Eg., •draw a thick red vline at x = 0 that spans the yrange >>> axvline(linewidth=4, color=’r’) •draw a default vline at x = 1 that spans the yrange 384 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 >>> axvline(x=1) •draw a default vline at x = .5 that spans the the middle half of the yrange >>> axvline(x=.5, ymin=0.25, ymax=0.75) Valid kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata 34.1. matplotlib.axes Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 385 Matplotlib, Release 0.99.1.1 Table 34.3 – continued from previous pa 1D array any number ydata zorder See Also: axhspan() for example plot and source code axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs) call signature: axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs) Axis Vertical Span. x coords are in data units and y coords are in axes (relative 0-1) units. Draw a vertical span (rectangle) from xmin to xmax. With the default values of ymin = 0 and ymax = 1, this always spans the yrange, regardless of the ylim settings, even if you change them, eg. with the set_ylim() command. That is, the vertical extent is in axes coords: 0=bottom, 0.5=middle, 1.0=top but the y location is in data coordinates. Return value is the matplotlib.patches.Polygon instance. Examples: •draw a vertical green translucent rectangle from x=1.25 to 1.55 that spans the yrange of the axes >>> axvspan(1.25, 1.55, facecolor=’g’, alpha=0.5) Valid kwargs are Polygon properties: 386 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number See Also: axhspan() for example plot and source code bar(left, height, width=0.80000000000000004, bottom=None, color=None, edgecolor=None, linewidth=None, yerr=None, xerr=None, ecolor=None, capsize=3, align=’edge’, orientation=’vertical’, log=False, **kwargs) call signature: bar(left, height, width=0.8, bottom=0, color=None, edgecolor=None, linewidth=None, yerr=None, xerr=None, ecolor=None, capsize=3, align=’edge’, orientation=’vertical’, log=False) Make a bar plot with rectangles bounded by: left, left + width, bottom, bottom + height (left, right, bottom and top edges) left, height, width, and bottom can be either scalars or sequences Return value is a list of matplotlib.patches.Rectangle instances. Required arguments: 34.1. matplotlib.axes 387 Matplotlib, Release 0.99.1.1 Argument left height Description the x coordinates of the left sides of the bars the heights of the bars Optional keyword arguments: Keyword width bottom color edgecolor linewidth xerr yerr ecolor capsize align orientation log Description the widths of the bars the y coordinates of the bottom edges of the bars the colors of the bars the colors of the bar edges width of bar edges; None means use default linewidth; 0 means don’t draw edges. if not None, will be used to generate errorbars on the bar chart if not None, will be used to generate errorbars on the bar chart speciﬁes the color of any errorbar (default 3) determines the length in points of the error bar caps ‘edge’ (default) | ‘center’ ‘vertical’ | ‘horizontal’ [False|True] False (default) leaves the orientation axis as-is; True sets it to log scale For vertical bars, align = ‘edge’ aligns bars by their left edges in left, while align = ‘center’ interprets these values as the x coordinates of the bar centers. For horizontal bars, align = ‘edge’ aligns bars by their bottom edges in bottom, while align = ‘center’ interprets these values as the y coordinates of the bar centers. The optional arguments color, edgecolor, linewidth, xerr, and yerr can be either scalars or sequences of length equal to the number of bars. This enables you to use bar as the basis for stacked bar charts, or candlestick plots. Other optional kwargs: 388 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: A stacked bar chart. 34.1. matplotlib.axes 389 Matplotlib, Release 0.99.1.1 barbs(*args, **kw) Plot a 2-D ﬁeld of barbs. call signatures: barb(U, barb(U, barb(X, barb(X, V, V, Y, Y, **kw) C, **kw) U, V, **kw) U, V, C, **kw) Arguments: X, Y : The x and y coordinates of the barb locations (default is head of barb; see pivot kwarg) U, V : give the x and y components of the barb shaft C: an optional array used to map colors to the barbs All arguments may be 1-D or 2-D arrays or sequences. If X and Y are absent, they will be generated as a uniform grid. If U and V are 2-D arrays but X and Y are 1-D, and if len(X ) and len(Y ) match the column and row dimensions of U, then X and Y will be expanded with numpy.meshgrid(). U, V, C may be masked arrays, but masked X, Y are not supported at present. Keyword arguments: 390 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 length: Length of the barb in points; the other parts of the barb are scaled against this. Default is 9 pivot: [ ‘tip’ | ‘middle’ ] The part of the arrow that is at the grid point; the arrow rotates about this point, hence the name pivot. Default is ‘tip’ barbcolor: [ color | color sequence ] Speciﬁes the color all parts of the barb except any ﬂags. This parameter is analagous to the edgecolor parameter for polygons, which can be used instead. However this parameter will override facecolor. ﬂagcolor: [ color | color sequence ] Speciﬁes the color of any ﬂags on the barb. This parameter is analagous to the facecolor parameter for polygons, which can be used instead. However this parameter will override facecolor. If this is not set (and C has not either) then ﬂagcolor will be set to match barbcolor so that the barb has a uniform color. If C has been set, ﬂagcolor has no eﬀect. sizes: A dictionary of coeﬃcients specifying the ratio of a given feature to the length of the barb. Only those values one wishes to override need to be included. These features include: • ‘spacing’ - space between features (ﬂags, full/half barbs) • ‘height’ - height (distance from shaft to top) of a ﬂag or full barb • ‘width’ - width of a ﬂag, twice the width of a full barb • ‘emptybarb’ - radius of the circle used for low magnitudes ﬁll_empty: A ﬂag on whether the empty barbs (circles) that are drawn should be ﬁlled with the ﬂag color. If they are not ﬁlled, they will be drawn such that no color is applied to the center. Default is False rounding: A ﬂag to indicate whether the vector magnitude should be rounded when allocating barb components. If True, the magnitude is rounded to the nearest multiple of the half-barb increment. If False, the magnitude is simply truncated to the next lowest multiple. Default is True barb_increments: A dictionary of increments specifying values to associate with different parts of the barb. Only those values one wishes to override need to be included. • ‘half’ - half barbs (Default is 5) • ‘full’ - full barbs (Default is 10) • ‘ﬂag’ - ﬂags (default is 50) ﬂip_barb: Either a single boolean ﬂag or an array of booleans. Single boolean indicates whether the lines and ﬂags should point opposite to normal for all barbs. An array (which should be the same size as the other data arrays) indicates whether to ﬂip for each individual barb. Normal behavior is for the barbs and lines to point right (comes from wind barbs having these features point towards low pressure in the Northern Hemisphere.) Default is False Barbs are traditionally used in meteorology as a way to plot the speed and direction of wind observations, but can technically be used to plot any two dimensional vector quantity. As opposed 34.1. matplotlib.axes 391 Matplotlib, Release 0.99.1.1 to arrows, which give vector magnitude by the length of the arrow, the barbs give more quantitative information about the vector magnitude by putting slanted lines or a triangle for various increments in magnitude, as show schematically below: : /\ \ : /\ \ : / \ \ \ :/ \ \ \ : ------------------------------ The largest increment is given by a triangle (or “ﬂag”). After those come full lines (barbs). The smallest increment is a half line. There is only, of course, ever at most 1 half line. If the magnitude is small and only needs a single half-line and no full lines or triangles, the half-line is oﬀset from the end of the barb so that it can be easily distinguished from barbs with a single full line. The magnitude for the barb shown above would nominally be 65, using the standard increments of 50, 10, and 5. linewidths and edgecolors can be used to customize the barb. Additional PolyCollection keyword arguments: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path cmap color colorbar contains edgecolor or edgecolors facecolor or facecolors figure gid label linestyle or linestyles or dashes linewidth or lw or linewidths lod norm offsets picker pickradius rasterized snap 392 Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a colormap or registered colormap name matplotlib color arg or sequence of rgba tuples unknown a callable function matplotlib color arg or sequence of rgba tuples matplotlib color arg or sequence of rgba tuples a matplotlib.figure.Figure instance an id string any string [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] ﬂoat or sequence of ﬂoats [True | False] unknown ﬂoat or sequence of ﬂoats [None|ﬂoat|boolean|callable] unknown [True | False | None] unknown Continued on next page Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 transform url urls visible zorder Table 34.4 – continued from previous page Transform instance a url string unknown [True | False] any number Example: 34.1. matplotlib.axes 393 Matplotlib, Release 0.99.1.1 barh(bottom, width, height=0.80000000000000004, left=None, **kwargs) call signature: barh(bottom, width, height=0.8, left=0, **kwargs) Make a horizontal bar plot with rectangles bounded by: left, left + width, bottom, bottom + height (left, right, bottom and top edges) bottom, width, height, and left can be either scalars or sequences Return value is a list of matplotlib.patches.Rectangle instances. Required arguments: Argument bottom width Description the vertical positions of the bottom edges of the bars the lengths of the bars Optional keyword arguments: 394 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Keyword height left color edgecolor linewidth xerr yerr ecolor capsize align log Description the heights (thicknesses) of the bars the x coordinates of the left edges of the bars the colors of the bars the colors of the bar edges width of bar edges; None means use default linewidth; 0 means don’t draw edges. if not None, will be used to generate errorbars on the bar chart if not None, will be used to generate errorbars on the bar chart speciﬁes the color of any errorbar (default 3) determines the length in points of the error bar caps ‘edge’ (default) | ‘center’ [False|True] False (default) leaves the horizontal axis as-is; True sets it to log scale Setting align = ‘edge’ aligns bars by their bottom edges in bottom, while align = ‘center’ interprets these values as the y coordinates of the bar centers. The optional arguments color, edgecolor, linewidth, xerr, and yerr can be either scalars or sequences of length equal to the number of bars. This enables you to use barh as the basis for stacked bar charts, or candlestick plots. other optional kwargs: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder 34.1. matplotlib.axes Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number 395 Matplotlib, Release 0.99.1.1 boxplot(x, notch=0, sym=’b+’, vert=1, whis=1.5, positions=None, widths=None) call signature: boxplot(x, notch=0, sym=’+’, vert=1, whis=1.5, positions=None, widths=None) Make a box and whisker plot for each column of x or each vector in sequence x. The box extends from the lower to upper quartile values of the data, with a line at the median. The whiskers extend from the box to show the range of the data. Flier points are those past the end of the whiskers. •notch = 0 (default) produces a rectangular box plot. •notch = 1 will produce a notched box plot sym (default ‘b+’) is the default symbol for ﬂier points. Enter an empty string (‘’) if you don’t want to show ﬂiers. •vert = 1 (default) makes the boxes vertical. •vert = 0 makes horizontal boxes. This seems goofy, but that’s how Matlab did it. whis (default 1.5) deﬁnes the length of the whiskers as a function of the inner quartile range. They extend to the most extreme data point within ( whis*(75%-25%) ) data range. positions (default 1,2,...,n) sets the horizontal positions of the boxes. The ticks and limits are automatically set to match the positions. widths is either a scalar or a vector and sets the width of each box. The default is 0.5, or 0.15*(distance between extreme positions) if that is smaller. x is an array or a sequence of vectors. Returns a dictionary mapping each component of the boxplot to a list of the matplotlib.lines.Line2D instances created. Example: 396 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 397 Matplotlib, Release 0.99.1.1 398 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 399 Matplotlib, Release 0.99.1.1 400 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 401 Matplotlib, Release 0.99.1.1 402 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 broken_barh(xranges, yrange, **kwargs) call signature: broken_barh(self, xranges, yrange, **kwargs) A collection of horizontal bars spanning yrange with a sequence of xranges. Required arguments: Argument xranges yrange Description sequence of (xmin, xwidth) sequence of (ymin, ywidth) kwargs are matplotlib.collections.BrokenBarHCollection properties: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on 34.1. matplotlib.axes Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] Continued on next page 403 Matplotlib, Release 0.99.1.1 Table 34.5 – continued from previous page clip_path [ (Path, Transform) | Patch | None ] cmap a colormap or registered colormap name color matplotlib color arg or sequence of rgba tuples colorbar unknown contains a callable function edgecolor or edgecolors matplotlib color arg or sequence of rgba tuples facecolor or facecolors matplotlib color arg or sequence of rgba tuples figure a matplotlib.figure.Figure instance gid an id string label any string linestyle or linestyles or dashes [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] linewidth or lw or linewidths ﬂoat or sequence of ﬂoats lod [True | False] norm unknown offsets ﬂoat or sequence of ﬂoats picker [None|ﬂoat|boolean|callable] pickradius unknown rasterized [True | False | None] snap unknown transform Transform instance url a url string urls unknown visible [True | False] zorder any number these can either be a single argument, ie: facecolors = ’black’ or a sequence of arguments for the various bars, ie: facecolors = (’black’, ’red’, ’green’) Example: 404 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 can_zoom() Return True if this axes support the zoom box cla() Clear the current axes clabel(CS, *args, **kwargs) call signature: clabel(cs, **kwargs) adds labels to line contours in cs, where cs is a ContourSet object returned by contour. clabel(cs, v, **kwargs) only labels contours listed in v. Optional keyword arguments: fontsize: See http://matplotlib.sf.net/fonts.html colors: • if None, the color of each label matches the color of the corresponding contour • if one string color, e.g. colors = ‘r’ or colors = ‘red’, all labels will be plotted in this color 34.1. matplotlib.axes 405 Matplotlib, Release 0.99.1.1 • if a tuple of matplotlib color args (string, ﬂoat, rgb, etc), diﬀerent labels will be plotted in diﬀerent colors in the order speciﬁed inline: controls whether the underlying contour is removed or not. Default is True. inline_spacing: space in pixels to leave on each side of label when placing inline. Defaults to 5. This spacing will be exact for labels at locations where the contour is straight, less so for labels on curved contours. fmt: a format string for the label. Default is ‘%1.3f’ Alternatively, this can be a dictionary matching contour levels with arbitrary strings to use for each contour level (i.e., fmt[level]=string) manual: if True, contour labels will be placed manually using mouse clicks. Click the ﬁrst button near a contour to add a label, click the second button (or potentially both mouse buttons at once) to ﬁnish adding labels. The third button can be used to remove the last label added, but only if labels are not inline. Alternatively, the keyboard can be used to select label locations (enter to end label placement, delete or backspace act like the third mouse button, and any other key will select a label location). rightside_up: if True (default), label rotations will always be plus or minus 90 degrees from level. 406 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 407 Matplotlib, Release 0.99.1.1 408 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 409 Matplotlib, Release 0.99.1.1 clear() clear the axes cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) call signature: cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend = mlab.detrend_none, window = mlab.window_hanning, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) cohere() the coherence between x and y. Coherence is the normalized cross spectral density: C xy = |P xy |2 P xx Pyy (34.1) Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a 410 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Fc: integer The center frequency of x (defaults to 0), which oﬀsets the x extents of the plot to reﬂect the frequency range used when a signal is acquired and then ﬁltered and downsampled to baseband. The return value is a tuple (Cxy, f ), where f are the frequencies of the coherence vector. kwargs are applied to the lines. References: •Bendat & Piersol – Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986) kwargs control the Line2D properties of the coherence plot: Property alpha animated antialiased or aa axes clip_box 34.1. matplotlib.axes Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance 411 Matplotlib, Release 0.99.1.1 Table 34.6 – continued from previous pa clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Example: 412 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 connect(s, func) Register observers to be notiﬁed when certain events occur. Register with callback functions with the following signatures. The function has the following signature: func(ax) # where ax is the instance making the callback. The following events can be connected to: ‘xlim_changed’,’ylim_changed’ The connection id is is returned - you can use this with disconnect to disconnect from the axes event contains(mouseevent) Test whether the mouse event occured in the axes. Returns T/F, {} contains_point(point) Returns True if the point (tuple of x,y) is inside the axes (the area deﬁned by the its patch). A pixel coordinate is required. contour(*args, **kwargs) contour() and contourf() draw contour lines and ﬁlled contours, respectively. Except as noted, function signatures and return values are the same for both versions. 34.1. matplotlib.axes 413 Matplotlib, Release 0.99.1.1 contourf() diﬀers from the Matlab (TM) version in that it does not draw the polygon edges, because the contouring engine yields simply connected regions with branch cuts. To draw the edges, add line contours with calls to contour(). call signatures: contour(Z) make a contour plot of an array Z. The level values are chosen automatically. contour(X,Y,Z) X, Y specify the (x, y) coordinates of the surface contour(Z,N) contour(X,Y,Z,N) contour N automatically-chosen levels. contour(Z,V) contour(X,Y,Z,V) draw contour lines at the values speciﬁed in sequence V contourf(..., V) ﬁll the (len(V )-1) regions between the values in V contour(Z, **kwargs) Use keyword args to control colors, linewidth, origin, cmap ... see below for more details. X, Y, and Z must be arrays with the same dimensions. Z may be a masked array, but ﬁlled contouring may not handle internal masked regions correctly. C = contour(...) returns a ContourSet object. Optional keyword arguments: colors: [ None | string | (mpl_colors) ] If None, the colormap speciﬁed by cmap will be used. If a string, like ‘r’ or ‘red’, all levels will be plotted in this color. If a tuple of matplotlib color args (string, ﬂoat, rgb, etc), diﬀerent levels will be plotted in diﬀerent colors in the order speciﬁed. alpha: ﬂoat The alpha blending value cmap: [ None | Colormap ] A cm Colormap instance or None. If cmap is None and colors is None, a default Colormap is used. 414 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 norm: [ None | Normalize ] A matplotlib.colors.Normalize instance for scaling data values to colors. If norm is None and colors is None, the default linear scaling is used. origin: [ None | ‘upper’ | ‘lower’ | ‘image’ ] If None, the ﬁrst value of Z will correspond to the lower left corner, location (0,0). If ‘image’, the rc value for image.origin will be used. This keyword is not active if X and Y are speciﬁed in the call to contour. extent: [ None | (x0,x1,y0,y1) ] If origin is not None, then extent is interpreted as in matplotlib.pyplot.imshow(): it gives the outer pixel boundaries. In this case, the position of Z[0,0] is the center of the pixel, not a corner. If origin is None, then (x0, y0) is the position of Z[0,0], and (x1, y1) is the position of Z[-1,-1]. This keyword is not active if X and Y are speciﬁed in the call to contour. locator: [ None | ticker.Locator subclass ] If locator is None, the default MaxNLocator is used. The locator is used to determine the contour levels if they are not given explicitly via the V argument. extend: [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ] Unless this is ‘neither’, contour levels are automatically added to one or both ends of the range so that all data are included. These added ranges are then mapped to the special colormap values which default to the ends of the colormap range, but can be set via matplotlib.cm.Colormap.set_under() and matplotlib.cm.Colormap.set_over() methods. contour-only keyword arguments: linewidths: [ None | number | tuple of numbers ] If linewidths is None, the default width in lines.linewidth in matplotlibrc is used. If a number, all levels will be plotted with this linewidth. If a tuple, diﬀerent levels will be plotted with diﬀerent linewidths in the order speciﬁed linestyles: [None | ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ] If linestyles is None, the ‘solid’ is used. linestyles can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than the number of contour levels it will be repeated as necessary. If contour is using a monochrome colormap and the contour level is less than 0, then the linestyle speciﬁed in contour.negative_linestyle in matplotlibrc will be used. contourf-only keyword arguments: antialiased: [ True | False ] enable antialiasing 34.1. matplotlib.axes 415 Matplotlib, Release 0.99.1.1 nchunk: [ 0 | integer ] If 0, no subdivision of the domain. Specify a positive integer to divide the domain into subdomains of roughly nchunk by nchunk points. This may never actually be advantageous, so this option may be removed. Chunking introduces artifacts at the chunk boundaries unless antialiased is False. Example: 416 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 417 Matplotlib, Release 0.99.1.1 418 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 419 Matplotlib, Release 0.99.1.1 contourf (*args, **kwargs) contour() and contourf() draw contour lines and ﬁlled contours, respectively. Except as noted, function signatures and return values are the same for both versions. contourf() diﬀers from the Matlab (TM) version in that it does not draw the polygon edges, because the contouring engine yields simply connected regions with branch cuts. To draw the edges, add line contours with calls to contour(). call signatures: contour(Z) make a contour plot of an array Z. The level values are chosen automatically. contour(X,Y,Z) X, Y specify the (x, y) coordinates of the surface contour(Z,N) contour(X,Y,Z,N) contour N automatically-chosen levels. 420 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 contour(Z,V) contour(X,Y,Z,V) draw contour lines at the values speciﬁed in sequence V contourf(..., V) ﬁll the (len(V )-1) regions between the values in V contour(Z, **kwargs) Use keyword args to control colors, linewidth, origin, cmap ... see below for more details. X, Y, and Z must be arrays with the same dimensions. Z may be a masked array, but ﬁlled contouring may not handle internal masked regions correctly. C = contour(...) returns a ContourSet object. Optional keyword arguments: colors: [ None | string | (mpl_colors) ] If None, the colormap speciﬁed by cmap will be used. If a string, like ‘r’ or ‘red’, all levels will be plotted in this color. If a tuple of matplotlib color args (string, ﬂoat, rgb, etc), diﬀerent levels will be plotted in diﬀerent colors in the order speciﬁed. alpha: ﬂoat The alpha blending value cmap: [ None | Colormap ] A cm Colormap instance or None. If cmap is None and colors is None, a default Colormap is used. norm: [ None | Normalize ] A matplotlib.colors.Normalize instance for scaling data values to colors. If norm is None and colors is None, the default linear scaling is used. origin: [ None | ‘upper’ | ‘lower’ | ‘image’ ] If None, the ﬁrst value of Z will correspond to the lower left corner, location (0,0). If ‘image’, the rc value for image.origin will be used. This keyword is not active if X and Y are speciﬁed in the call to contour. extent: [ None | (x0,x1,y0,y1) ] If origin is not None, then extent is interpreted as in matplotlib.pyplot.imshow(): it gives the outer pixel boundaries. In this case, the position of Z[0,0] is the center of the pixel, not a corner. If origin is None, then (x0, y0) is the position of Z[0,0], and (x1, y1) is the position of Z[-1,-1]. This keyword is not active if X and Y are speciﬁed in the call to contour. 34.1. matplotlib.axes 421 Matplotlib, Release 0.99.1.1 locator: [ None | ticker.Locator subclass ] If locator is None, the default MaxNLocator is used. The locator is used to determine the contour levels if they are not given explicitly via the V argument. extend: [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ] Unless this is ‘neither’, contour levels are automatically added to one or both ends of the range so that all data are included. These added ranges are then mapped to the special colormap values which default to the ends of the colormap range, but can be set via matplotlib.cm.Colormap.set_under() and matplotlib.cm.Colormap.set_over() methods. contour-only keyword arguments: linewidths: [ None | number | tuple of numbers ] If linewidths is None, the default width in lines.linewidth in matplotlibrc is used. If a number, all levels will be plotted with this linewidth. If a tuple, diﬀerent levels will be plotted with diﬀerent linewidths in the order speciﬁed linestyles: [None | ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ] If linestyles is None, the ‘solid’ is used. linestyles can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than the number of contour levels it will be repeated as necessary. If contour is using a monochrome colormap and the contour level is less than 0, then the linestyle speciﬁed in contour.negative_linestyle in matplotlibrc will be used. contourf-only keyword arguments: antialiased: [ True | False ] enable antialiasing nchunk: [ 0 | integer ] If 0, no subdivision of the domain. Specify a positive integer to divide the domain into subdomains of roughly nchunk by nchunk points. This may never actually be advantageous, so this option may be removed. Chunking introduces artifacts at the chunk boundaries unless antialiased is False. Example: 422 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 423 Matplotlib, Release 0.99.1.1 424 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 425 Matplotlib, Release 0.99.1.1 426 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) call signature: csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) The cross spectral density P xy by Welch’s average periodogram method. The vectors x and y are divided into NFFT length segments. Each segment is detrended by function detrend and windowed by function window. The product of the direct FFTs of x and y are averaged over each segment to compute P xy , with a scaling to correct for power loss due to windowing. Returns the tuple (Pxy, freqs). P is the cross spectrum (complex valued), and 10 log10 |P xy | is plotted. Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. 34.1. matplotlib.axes 427 Matplotlib, Release 0.99.1.1 detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Fc: integer The center frequency of x (defaults to 0), which oﬀsets the x extents of the plot to reﬂect the frequency range used when a signal is acquired and then ﬁltered and downsampled to baseband. References: Bendat & Piersol – Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986) kwargs control the Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path 428 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.7 – continued from previous pa color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Example: 34.1. matplotlib.axes 429 Matplotlib, Release 0.99.1.1 disconnect(cid) disconnect from the Axes event. drag_pan(button, key, x, y) Called when the mouse moves during a pan operation. button is the mouse button number: •1: LEFT •2: MIDDLE •3: RIGHT key is a “shift” key x, y are the mouse coordinates in display coords. Note: Intended to be overridden by new projection types. draw(artist, renderer, *kl) Draw everything (plot lines, axes, labels) draw_artist(a) This method can only be used after an initial draw which caches the renderer. It is used to eﬃciently update Axes data (axis ticks, labels, etc are not updated) 430 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 end_pan() Called when a pan operation completes (when the mouse button is up.) Note: Intended to be overridden by new projection types. errorbar(x, y, yerr=None, xerr=None, fmt=’-’, ecolor=None, elinewidth=None, capsize=3, barsabove=False, lolims=False, uplims=False, xlolims=False, xuplims=False, **kwargs) call signature: errorbar(x, y, yerr=None, xerr=None, fmt=’-’, ecolor=None, elinewidth=None, capsize=3, barsabove=False, lolims=False, uplims=False, xlolims=False, xuplims=False) Plot x versus y with error deltas in yerr and xerr. Vertical errorbars are plotted if yerr is not None. Horizontal errorbars are plotted if xerr is not None. x, y, xerr, and yerr can all be scalars, which plots a single error bar at x, y. Optional keyword arguments: xerr/yerr: [ scalar | N, Nx1, or 2xN array-like ] If a scalar number, len(N) array-like object, or an Nx1 array-like object, errorbars are drawn +/- value. If a rank-1, 2xN numpy array, errorbars are drawn at -row1 and +row2 fmt: ‘-‘ The plot format symbol for y. If fmt is None, just plot the errorbars with no line symbols. This can be useful for creating a bar plot with errorbars. ecolor: [ None | mpl color ] a matplotlib color arg which gives the color the errorbar lines; if None, use the marker color. elinewidth: scalar the linewidth of the errorbar lines. If None, use the linewidth. capsize: scalar the size of the error bar caps in points barsabove: [ True | False ] if True, will plot the errorbars above the plot symbols. Default is below. lolims/uplims/xlolims/xuplims: [ False | True ] These arguments can be used to indicate that a value gives only upper/lower limits. In that case a caret symbol is used to indicate this. lims-arguments may be of the same type as xerr and yerr. All other keyword arguments are passed on to the plot command for the markers, so you can add additional key=value pairs to control the errorbar markers. For example, this code makes big red squares with thick green edges: x,y,yerr = rand(3,10) errorbar(x, y, yerr, marker=’s’, mfc=’red’, mec=’green’, ms=20, mew=4) where mfc, mec, ms and mew are aliases for the longer property names, markerfacecolor, markeredgecolor, markersize and markeredgewith. valid kwargs for the marker properties are 34.1. matplotlib.axes 431 Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Return value is a length 3 tuple. The ﬁrst element is the Line2D instance for the y symbol lines. The second element is a list of error bar cap lines, the third element is a list of LineCollection instances for the horizontal and vertical error ranges. 432 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Example: 34.1. matplotlib.axes 433 Matplotlib, Release 0.99.1.1 434 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 435 Matplotlib, Release 0.99.1.1 436 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 437 Matplotlib, Release 0.99.1.1 438 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 439 Matplotlib, Release 0.99.1.1 440 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 441 Matplotlib, Release 0.99.1.1 fill(*args, **kwargs) call signature: fill(*args, **kwargs) Plot ﬁlled polygons. args is a variable length argument, allowing for multiple x, y pairs with an optional color format string; see plot() for details on the argument parsing. For example, to plot a polygon with vertices at x, y in blue.: ax.fill(x,y, ’b’ ) An arbitrary number of x, y, color groups can be speciﬁed: ax.fill(x1, y1, ’g’, x2, y2, ’r’) Return value is a list of Patch instances that were added. The same color strings that plot() supports are supported by the ﬁll format string. If you would like to ﬁll below a curve, eg. shade a region between 0 and y along x, use fill_between() The closed kwarg will close the polygon when True (default). kwargs control the Polygon properties: 442 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: 34.1. matplotlib.axes 443 Matplotlib, Release 0.99.1.1 fill_between(x, y1, y2=0, where=None, **kwargs) call signature: fill_between(x, y1, y2=0, where=None, **kwargs) Create a PolyCollection ﬁlling the regions between y1 and y2 where where==True x an N length np array of the x data y1 an N length scalar or np array of the y data y2 an N length scalar or np array of the y data where if None, default to ﬁll between everywhere. If not None, it is a a N length numpy boolean array and the ﬁll will only happen over the regions where where==True kwargs keyword args passed on to the PolyCollection kwargs control the Polygon properties: Property alpha animated antialiased or antialiaseds array Description ﬂoat [True | False] Boolean or sequence of booleans unknown Continued on next page 444 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.9 – continued from previous page axes an Axes instance clim a length 2 sequence of ﬂoats clip_box a matplotlib.transforms.Bbox instance clip_on [True | False] clip_path [ (Path, Transform) | Patch | None ] cmap a colormap or registered colormap name color matplotlib color arg or sequence of rgba tuples colorbar unknown contains a callable function edgecolor or edgecolors matplotlib color arg or sequence of rgba tuples facecolor or facecolors matplotlib color arg or sequence of rgba tuples figure a matplotlib.figure.Figure instance gid an id string label any string linestyle or linestyles or dashes [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] linewidth or lw or linewidths ﬂoat or sequence of ﬂoats lod [True | False] norm unknown offsets ﬂoat or sequence of ﬂoats picker [None|ﬂoat|boolean|callable] pickradius unknown rasterized [True | False | None] snap unknown transform Transform instance url a url string urls unknown visible [True | False] zorder any number 34.1. matplotlib.axes 445 Matplotlib, Release 0.99.1.1 446 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 447 Matplotlib, Release 0.99.1.1 See Also: fill_betweenx() for ﬁlling between two sets of x-values fill_betweenx(y, x1, x2=0, where=None, **kwargs) call signature: fill_between(y, x1, x2=0, where=None, **kwargs) Create a PolyCollection ﬁlling the regions between x1 and x2 where where==True y an N length np array of the y data x1 an N length scalar or np array of the x data x2 an N length scalar or np array of the x data where if None, default to ﬁll between everywhere. If not None, it is a a N length numpy boolean array and the ﬁll will only happen over the regions where where==True kwargs keyword args passed on to the PolyCollection kwargs control the Polygon properties: %(PolyCollection)s 448 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 34.1. matplotlib.axes 449 Matplotlib, Release 0.99.1.1 See Also: fill_between() for ﬁlling between two sets of y-values format_coord(x, y) return a format string formatting the x, y coord format_xdata(x) Return x string formatted. This function will use the attribute self.fmt_xdata if it is callable, else will fall back on the xaxis major formatter format_ydata(y) Return y string formatted. This function will use the fmt_ydata attribute if it is callable, else will fall back on the yaxis major formatter frame get_adjustable() get_anchor() get_aspect() get_autoscale_on() Get whether autoscaling is applied for both axes on plot commands 450 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 get_autoscalex_on() Get whether autoscaling for the x-axis is applied on plot commands get_autoscaley_on() Get whether autoscaling for the y-axis is applied on plot commands get_axes_locator() return axes_locator get_axis_bgcolor() Return the axis background color get_axisbelow() Get whether axis below is true or not get_child_artists() Return a list of artists the axes contains. Deprecated since version 0.98. get_children() return a list of child artists get_cursor_props() return the cursor propertiess as a (linewidth, color) tuple, where linewidth is a ﬂoat and color is an RGBA tuple get_data_ratio() Returns the aspect ratio of the raw data. This method is intended to be overridden by new projection types. get_data_ratio_log() Returns the aspect ratio of the raw data in log scale. Will be used when both axis scales are in log. get_frame() Return the axes Rectangle frame get_frame_on() Get whether the axes rectangle patch is drawn get_images() return a list of Axes images contained by the Axes get_legend() Return the legend.Legend instance, or None if no legend is deﬁned get_legend_handles_labels() return handles and labels for legend ax.legend() is equivalent to h, l = ax.get_legend_handles_labels() ax.legend(h, l) get_lines() Return a list of lines contained by the Axes 34.1. matplotlib.axes 451 Matplotlib, Release 0.99.1.1 get_navigate() Get whether the axes responds to navigation commands get_navigate_mode() Get the navigation toolbar button status: ‘PAN’, ‘ZOOM’, or None get_position(original=False) Return the a copy of the axes rectangle as a Bbox get_rasterization_zorder() Get zorder value below which artists will be rasterized get_renderer_cache() get_shared_x_axes() Return a copy of the shared axes Grouper object for x axes get_shared_y_axes() Return a copy of the shared axes Grouper object for y axes get_tightbbox(renderer) return the tight bounding box of the axes. The dimension of the Bbox in canvas coordinate. get_title() Get the title text string. get_window_extent(*args, **kwargs) get the axes bounding box in display space; args and kwargs are empty get_xaxis() Return the XAxis instance get_xaxis_text1_transform(pad_points) Get the transformation used for drawing x-axis labels, which will add the given amount of padding (in points) between the axes and the label. The x-direction is in data coordinates and the y-direction is in axis coordinates. Returns a 3-tuple of the form: (transform, valign, halign) where valign and halign are requested alignments for the text. Note: This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in diﬀerent locations. get_xaxis_text2_transform(pad_points) Get the transformation used for drawing the secondary x-axis labels, which will add the given amount of padding (in points) between the axes and the label. The x-direction is in data coordinates and the y-direction is in axis coordinates. Returns a 3-tuple of the form: (transform, valign, halign) where valign and halign are requested alignments for the text. Note: This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in diﬀerent locations. 452 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 get_xaxis_transform(which=’grid’) Get the transformation used for drawing x-axis labels, ticks and gridlines. The x-direction is in data coordinates and the y-direction is in axis coordinates. Note: This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in diﬀerent locations. get_xbound() Returns the x-axis numerical bounds where: lowerBound < upperBound get_xgridlines() Get the x grid lines as a list of Line2D instances get_xlabel() Get the xlabel text string. get_xlim() Get the x-axis range [xmin, xmax] get_xmajorticklabels() Get the xtick labels as a list of Text instances get_xminorticklabels() Get the xtick labels as a list of Text instances get_xscale() get_xticklabels(minor=False) Get the xtick labels as a list of Text instances get_xticklines() Get the xtick lines as a list of Line2D instances get_xticks(minor=False) Return the x ticks as a list of locations get_yaxis() Return the YAxis instance get_yaxis_text1_transform(pad_points) Get the transformation used for drawing y-axis labels, which will add the given amount of padding (in points) between the axes and the label. The x-direction is in axis coordinates and the y-direction is in data coordinates. Returns a 3-tuple of the form: (transform, valign, halign) where valign and halign are requested alignments for the text. Note: This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in diﬀerent locations. 34.1. matplotlib.axes 453 Matplotlib, Release 0.99.1.1 get_yaxis_text2_transform(pad_points) Get the transformation used for drawing the secondary y-axis labels, which will add the given amount of padding (in points) between the axes and the label. The x-direction is in axis coordinates and the y-direction is in data coordinates. Returns a 3-tuple of the form: (transform, valign, halign) where valign and halign are requested alignments for the text. Note: This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in diﬀerent locations. get_yaxis_transform(which=’grid’) Get the transformation used for drawing y-axis labels, ticks and gridlines. The x-direction is in axis coordinates and the y-direction is in data coordinates. Note: This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in diﬀerent locations. get_ybound() Return y-axis numerical bounds in the form of lowerBound < upperBound get_ygridlines() Get the y grid lines as a list of Line2D instances get_ylabel() Get the ylabel text string. get_ylim() Get the y-axis range [ymin, ymax] get_ymajorticklabels() Get the xtick labels as a list of Text instances get_yminorticklabels() Get the xtick labels as a list of Text instances get_yscale() get_yticklabels(minor=False) Get the xtick labels as a list of Text instances get_yticklines() Get the ytick lines as a list of Line2D instances get_yticks(minor=False) Return the y ticks as a list of locations grid(b=None, **kwargs) call signature: grid(self, b=None, **kwargs) 454 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Set the axes grids on or oﬀ; b is a boolean If b is None and len(kwargs)==0, toggle the grid state. If kwargs are supplied, it is assumed that you want a grid and b is thus set to True kawrgs are used to set the grid line properties, eg: ax.grid(color=’r’, linestyle=’-’, linewidth=2) Valid Line2D kwargs are Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible 34.1. matplotlib.axes Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 455 Matplotlib, Release 0.99.1.1 Table 34.10 – continued from previous pa xdata ydata zorder 1D array 1D array any number has_data() Return True if any artists have been added to axes. This should not be used to determine whether the dataLim need to be updated, and may not actually be useful for anything. hexbin(x, y, C=None, gridsize=100, bins=None, xscale=’linear’, yscale=’linear’, extent=None, cmap=None, norm=None, vmin=None, vmax=None, alpha=1.0, linewidths=None, edgecolors=’none’, reduce_C_function=<function mean at 0x254c488>, mincnt=None, marginals=False, **kwargs) call signature: hexbin(x, y, C = None, gridsize = 100, bins = None, xscale = ’linear’, yscale = ’linear’, cmap=None, norm=None, vmin=None, vmax=None, alpha=1.0, linewidths=None, edgecolors=’none’ reduce_C_function = np.mean, mincnt=None, marginals=True **kwargs) Make a hexagonal binning plot of x versus y, where x, y are 1-D sequences of the same length, N. If C is None (the default), this is a histogram of the number of occurences of the observations at (x[i],y[i]). If C is speciﬁed, it speciﬁes values at the coordinate (x[i],y[i]). These values are accumulated for each hexagonal bin and then reduced according to reduce_C_function, which defaults to numpy’s mean function (np.mean). (If C is speciﬁed, it must also be a 1-D sequence of the same length as x and y.) x, y and/or C may be masked arrays, in which case only unmasked points will be plotted. Optional keyword arguments: gridsize: [ 100 | integer ] The number of hexagons in the x-direction, default is 100. The corresponding number of hexagons in the y-direction is chosen such that the hexagons are approximately regular. Alternatively, gridsize can be a tuple with two elements specifying the number of hexagons in the x-direction and the y-direction. bins: [ None | ‘log’ | integer | sequence ] If None, no binning is applied; the color of each hexagon directly corresponds to its count value. If ‘log’, use a logarithmic scale for the color map. Internally, log10 (i + 1) is used to determine the hexagon color. If an integer, divide the counts in the speciﬁed number of bins, and color the hexagons accordingly. If a sequence of values, the values of the lower bound of the bins to be used. 456 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 xscale: [ ‘linear’ | ‘log’ ] Use a linear or log10 scale on the horizontal axis. scale: [ ‘linear’ | ‘log’ ] Use a linear or log10 scale on the vertical axis. mincnt: None | a positive integer If not None, only display cells with more than mincnt number of points in the cell marginals: True|False if marginals is True, plot the marginal density as colormapped rectagles along the bottom of the x-axis and left of the y-axis extent: [ None | scalars (left, right, bottom, top) ] The limits of the bins. The default assigns the limits based on gridsize, x, y, xscale and yscale. Other keyword arguments controlling color mapping and normalization arguments: cmap: [ None | Colormap ] a matplotlib.cm.Colormap instance. If None, defaults to rc image.cmap. norm: [ None | Normalize ] matplotlib.colors.Normalize instance is used to scale luminance data to 0,1. vmin/vmax: scalar vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array C is used. Note if you pass a norm instance, your settings for vmin and vmax will be ignored. alpha: scalar the alpha value for the patches linewidths: [ None | scalar ] If None, defaults to rc lines.linewidth. Note that this is a tuple, and if you set the linewidths argument you must set it as a sequence of ﬂoats, as required by RegularPolyCollection. Other keyword arguments controlling the Collection properties: edgecolors: [ None | mpl color | color sequence ] If ‘none’, draws the edges in the same color as the ﬁll color. This is the default, as it avoids unsightly unpainted pixels between the hexagons. If None, draws the outlines in the default color. If a matplotlib color arg or sequence of rgba tuples, draws the outlines in the speciﬁed color. Here are the standard descriptions of all the Collection kwargs: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path 34.1. matplotlib.axes Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] Continued on next page 457 Matplotlib, Release 0.99.1.1 Table 34.11 – continued from previous page cmap a colormap or registered colormap name color matplotlib color arg or sequence of rgba tuples colorbar unknown contains a callable function edgecolor or edgecolors matplotlib color arg or sequence of rgba tuples facecolor or facecolors matplotlib color arg or sequence of rgba tuples figure a matplotlib.figure.Figure instance gid an id string label any string linestyle or linestyles or dashes [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] linewidth or lw or linewidths ﬂoat or sequence of ﬂoats lod [True | False] norm unknown offsets ﬂoat or sequence of ﬂoats picker [None|ﬂoat|boolean|callable] pickradius unknown rasterized [True | False | None] snap unknown transform Transform instance url a url string urls unknown visible [True | False] zorder any number The return value is a PolyCollection instance; use get_array() on this PolyCollection to get the counts in each hexagon.. If marginals is True, horizontal bar and vertical bar (both PolyCollections) will be attached to the return collection as attributes hbar and vbar Example: 458 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 hist(x, bins=10, range=None, normed=False, weights=None, cumulative=False, bottom=None, histtype=’bar’, align=’mid’, orientation=’vertical’, rwidth=None, log=False, **kwargs) call signature: hist(x, bins=10, range=None, normed=False, cumulative=False, bottom=None, histtype=’bar’, align=’mid’, orientation=’vertical’, rwidth=None, log=False, **kwargs) Compute and draw the histogram of x. The return value is a tuple (n, bins, patches) or ([n0, n1, ...], bins, [patches0, patches1,...]) if the input contains multiple data. Keyword arguments: bins: Either an integer number of bins or a sequence giving the bins. x are the data to be binned. x can be an array, a 2D array with multiple data in its columns, or a list of arrays with data of diﬀerent length. Note, if bins is an integer input argument=numbins, bins + 1 bin edges will be returned, compatible with the semantics of numpy.histogram() with the new = True argument. Unequally spaced bins are supported if bins is a sequence. range: The lower and upper range of the bins. Lower and upper outliers are ignored. If not provided, range is (x.min(), x.max()). Range has no eﬀect if bins is a sequence. If bins is a sequence or range is speciﬁed, autoscaling is set oﬀ (autoscale_on is set to False) and the xaxis limits are set to encompass the full speciﬁed bin range. 34.1. matplotlib.axes 459 Matplotlib, Release 0.99.1.1 normed: If True, the ﬁrst element of the return tuple will be the counts normalized to form a probability density, i.e., n/(len(x)*dbin). In a probability density, the integral of the histogram should be 1; you can verify that with a trapezoidal integration of the probability density function: pdf, bins, patches = ax.hist(...) print np.sum(pdf * np.diff(bins)) weights An array of weights, of the same shape as x. Each value in x only contributes its associated weight towards the bin count (instead of 1). If normed is True, the weights are normalized, so that the integral of the density over the range remains 1. cumulative: If True, then a histogram is computed where each bin gives the counts in that bin plus all bins for smaller values. The last bin gives the total number of datapoints. If normed is also True then the histogram is normalized such that the last bin equals 1. If cumulative evaluates to less than 0 (e.g. -1), the direction of accumulation is reversed. In this case, if normed is also True, then the histogram is normalized such that the ﬁrst bin equals 1. histtype: [ ‘bar’ | ‘barstacked’ | ‘step’ | ‘stepﬁlled’ ] The type of histogram to draw. • ‘bar’ is a traditional bar-type histogram. If multiple data are given the bars are aranged side by side. • ‘barstacked’ is a bar-type histogram where multiple data are stacked on top of each other. • ‘step’ generates a lineplot that is by default unﬁlled. • ‘stepﬁlled’ generates a lineplot that is by default ﬁlled. align: [’left’ | ‘mid’ | ‘right’ ] Controls how the histogram is plotted. • ‘left’: bars are centered on the left bin edges. • ‘mid’: bars are centered between the bin edges. • ‘right’: bars are centered on the right bin edges. orientation: [ ‘horizontal’ | ‘vertical’ ] If ‘horizontal’, barh() will be used for bartype histograms and the bottom kwarg will be the left edges. rwidth: The relative width of the bars as a fraction of the bin width. If None, automatically compute the width. Ignored if histtype = ‘step’ or ‘stepﬁlled’. log: If True, the histogram axis will be set to a log scale. If log is True and x is a 1D array, empty bins will be ﬁltered out and only the non-empty (n, bins, patches) will be returned. kwargs are used to update the properties of the hist Rectangle instances: 460 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number You can use labels for your histogram, and only the ﬁrst Rectangle gets the label (the others get the magic string ‘_nolegend_’. This will make the histograms work in the intuitive way for bar charts: ax.hist(10+2*np.random.randn(1000), label=’men’) ax.hist(12+3*np.random.randn(1000), label=’women’, alpha=0.5) ax.legend() label can also be a sequence of strings. If multiple data is provided in x, the labels are asigned sequentially to the histograms. Example: 34.1. matplotlib.axes 461 Matplotlib, Release 0.99.1.1 hlines(y, xmin, xmax, colors=’k’, linestyles=’solid’, label=”, **kwargs) call signature: hlines(y, xmin, xmax, colors=’k’, linestyles=’solid’, **kwargs) Plot horizontal lines at each y from xmin to xmax. Returns the LineCollection that was added. Required arguments: y: a 1-D numpy array or iterable. xmin and xmax: can be scalars or len(x) numpy arrays. If they are scalars, then the respective values are constant, else the widths of the lines are determined by xmin and xmax. Optional keyword arguments: colors: a line collections color argument, either a single color or a len(y) list of colors linestyles: [ ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ] Example: 462 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 hold(b=None) call signature: hold(b=None) Set the hold state. If hold is None (default), toggle the hold state. Else set the hold state to boolean value b. Examples: •toggle hold: >>> hold() •turn hold on: >>> hold(True) •turn hold oﬀ >>> hold(False) When hold is True, subsequent plot commands will be added to the current axes. When hold is False, the current axes and ﬁgure will be cleared on the next plot command imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=1.0, vmin=None, vmax=None, origin=None, extent=None, shape=None, ﬁlternorm=1, ﬁlterrad=4.0, imlim=None, resample=None, url=None, **kwargs) call signature: 34.1. matplotlib.axes 463 Matplotlib, Release 0.99.1.1 imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=1.0, vmin=None, vmax=None, origin=None, extent=None, **kwargs) Display the image in X to current axes. X may be a ﬂoat array, a uint8 array or a PIL image. If X is an array, X can have the following shapes: •MxN – luminance (grayscale, ﬂoat array only) •MxNx3 – RGB (ﬂoat or uint8 array) •MxNx4 – RGBA (ﬂoat or uint8 array) The value for each component of MxNx3 and MxNx4 ﬂoat arrays should be in the range 0.0 to 1.0; MxN ﬂoat arrays may be normalised. An matplotlib.image.AxesImage instance is returned. Keyword arguments: cmap: [ None | Colormap ] A matplotlib.cm.Colormap instance, eg. cm.jet. If None, default to rc image.cmap value. cmap is ignored when X has RGB(A) information aspect: [ None | ‘auto’ | ‘equal’ | scalar ] If ‘auto’, changes the image aspect ratio to match that of the axes If ‘equal’, and extent is None, changes the axes aspect ratio to match that of the image. If extent is not None, the axes aspect ratio is changed to match that of the extent. If None, default to rc image.aspect value. interpolation: Acceptable values are None, ‘nearest’, ‘bilinear’, ‘bicubic’, ‘spline16’, ‘spline36’, ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’, ‘quadric’, ‘catrom’, ‘gaussian’, ‘bessel’, ‘mitchell’, ‘sinc’, ‘lanczos’, If interpolation is None, default to rc image.interpolation. See also the ﬁlternorm and ﬁlterrad parameters norm: [ None | Normalize ] An matplotlib.colors.Normalize instance; None, default is normalization(). This scales luminance -> 0-1 if norm is only used for an MxN ﬂoat array. vmin/vmax: [ None | scalar ] Used to scale a luminance image to 0-1. If either is None, the min and max of the luminance values will be used. Note if norm is not None, the settings for vmin and vmax will be ignored. alpha: scalar The alpha blending value, between 0 (transparent) and 1 (opaque) origin: [ None | ‘upper’ | ‘lower’ ] Place the [0,0] index of the array in the upper left or lower left corner of the axes. If None, default to rc image.origin. 464 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 extent: [ None | scalars (left, right, bottom, top) ] Data limits for the axes. The default assigns zero-based row, column indices to the x, y centers of the pixels. shape: [ None | scalars (columns, rows) ] For raw buﬀer images ﬁlternorm: A parameter for the antigrain image resize ﬁlter. From the antigrain documentation, if ﬁlternorm = 1, the ﬁlter normalizes integer values and corrects the rounding errors. It doesn’t do anything with the source ﬂoating point values, it corrects only integers according to the rule of 1.0 which means that any sum of pixel weights must be equal to 1.0. So, the ﬁlter function must produce a graph of the proper shape. ﬁlterrad: The ﬁlter radius for ﬁlters that have a radius parameter, i.e. when interpolation is one of: ‘sinc’, ‘lanczos’ or ‘blackman’ Additional kwargs are Artist properties: Property alpha animated axes clip_box clip_on clip_path contains figure gid label lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a callable function a matplotlib.figure.Figure instance an id string any string [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: 34.1. matplotlib.axes 465 Matplotlib, Release 0.99.1.1 in_axes(mouseevent) return True if the given mouseevent (in display coords) is in the Axes invert_xaxis() Invert the x-axis. invert_yaxis() Invert the y-axis. ishold() return the HOLD status of the axes legend(*args, **kwargs) call signature: legend(*args, **kwargs) Place a legend on the current axes at location loc. Labels are a sequence of strings and loc can be a string or an integer specifying the legend location. To make a legend with existing lines: legend() legend() by itself will try and build a legend using the label property of the lines/patches/collections. You can set the label of a line by doing: 466 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 plot(x, y, label=’my data’) or: line.set_label(’my data’). If label is set to ‘_nolegend_’, the item will not be shown in legend. To automatically generate the legend from labels: legend( (’label1’, ’label2’, ’label3’) ) To make a legend for a list of lines and labels: legend( (line1, line2, line3), (’label1’, ’label2’, ’label3’) ) To make a legend at a given location, using a location argument: legend( (’label1’, ’label2’, ’label3’), loc=’upper left’) or: legend( (line1, line2, line3), (’label1’, ’label2’, ’label3’), loc=2) The location codes are Location String ‘best’ ‘upper right’ ‘upper left’ ‘lower left’ ‘lower right’ ‘right’ ‘center left’ ‘center right’ ‘lower center’ ‘upper center’ ‘center’ Location Code 0 1 2 3 4 5 6 7 8 9 10 Users can specify any arbitrary location for the legend using the bbox_to_anchor keyword argument. bbox_to_anchor can be an instance of BboxBase(or its derivatives) or a tuple of 2 or 4 ﬂoats. For example, loc = ‘upper right’, bbox_to_anchor = (0.5, 0.5) will place the legend so that the upper right corner of the legend at the center of the axes. The legend location can be speciﬁed in other coordinate, by using the bbox_transform keyword. The loc itslef can be a 2-tuple giving x,y of the lower-left corner of the legend in axes coords (bbox_to_anchor is ignored). 34.1. matplotlib.axes 467 Matplotlib, Release 0.99.1.1 Keyword arguments: prop: [ None | FontProperties | dict ] A matplotlib.font_manager.FontProperties instance. If prop is a dictionary, a new instance will be created with prop. If None, use rc settings. numpoints: integer The number of points in the legend for line scatterpoints: integer The number of points in the legend for scatter plot scatteroﬀsets: list of ﬂoats a list of yoﬀsets for scatter symbols in legend markerscale: [ None | scalar ] The relative size of legend markers vs. original. If None, use rc settings. fancybox: [ None | False | True ] if True, draw a frame with a round fancybox. If None, use rc shadow: [ None | False | True ] If True, draw a shadow behind legend. If None, use rc settings. ncol [integer] number of columns. default is 1 mode [[ “expand” | None ]] if mode is “expand”, the legend will be horizontally expanded to ﬁll the axes area (or bbox_to_anchor) bbox_to_anchor [an instance of BboxBase or a tuple of 2 or 4 ﬂoats] the bbox that the legend will be anchored. bbox_transform [[ an instance of Transform | None ]] the transform for the bbox. transAxes if None. title [string] the legend title Padding and spacing between various elements use following keywords parameters. The dimensions of these values are given as a fraction of the fontsize. Values from rcParams will be used if None. Keyword borderpad labelspacing handlelength handletextpad borderaxespad columnspacing Description the fractional whitespace inside the legend border the vertical space between the legend entries the length of the legend handles the pad between the legend handle and text the pad between the axes and legend border the spacing between columns Example: 468 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Also see Legend guide. loglog(*args, **kwargs) call signature: loglog(*args, **kwargs) Make a plot with log scaling on the x and y axis. loglog() supports all the keyword arguments of plot() matplotlib.axes.Axes.set_xscale() / matplotlib.axes.Axes.set_yscale(). and Notable keyword arguments: basex/basey: scalar > 1 base of the x/y logarithm subsx/subsy: [ None | sequence ] the location of the minor x/y ticks; None defaults to autosubs, which depend on the number of decades in the plot; see matplotlib.axes.Axes.set_xscale() / matplotlib.axes.Axes.set_yscale() for details nonposx/nonposy: [’mask’ | ‘clip’ ] non-positive values in x or y can be masked as invalid, or clipped to a very small positive number The remaining valid kwargs are Line2D properties: 34.1. matplotlib.axes 469 Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Example: 470 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 matshow(Z, **kwargs) Plot a matrix or array as an image. The matrix will be shown the way it would be printed, with the ﬁrst row at the top. Row and column numbering is zero-based. Argument: Z anything that can be interpreted as a 2-D array kwargs all are passed to imshow(). matshow() sets defaults for extent, origin, interpolation, and aspect; use care in overriding the extent and origin kwargs, because they interact. (Also, if you want to change them, you probably should be using imshow directly in your own version of matshow.) Returns: an matplotlib.image.AxesImage instance. minorticks_off () Remove minor ticks from the axes. minorticks_on() Add autoscaling minor ticks to the axes. pcolor(*args, **kwargs) call signatures: pcolor(C, **kwargs) pcolor(X, Y, C, **kwargs) 34.1. matplotlib.axes 471 Matplotlib, Release 0.99.1.1 Create a pseudocolor plot of a 2-D array. C is the array of color values. X and Y, if given, specify the (x, y) coordinates of the colored quadrilaterals; the quadrilateral for C[i,j] has corners at: (X[i, (X[i, (X[i+1, (X[i+1, j], j+1], j], j+1], Y[i, Y[i, Y[i+1, Y[i+1, j]), j+1]), j]), j+1]). Ideally the dimensions of X and Y should be one greater than those of C; if the dimensions are the same, then the last row and column of C will be ignored. Note that the the column index corresponds to the x-coordinate, and the row index corresponds to y; for details, see the Grid Orientation section below. If either or both of X and Y are 1-D arrays or column vectors, they will be expanded as needed into the appropriate 2-D arrays, making a rectangular grid. X, Y and C may be masked arrays. If either C[i, j], or one of the vertices surrounding C[i,j] (X or Y at [i, j], [i+1, j], [i, j+1],[i+1, j+1]) is masked, nothing is plotted. Keyword arguments: cmap: [ None | Colormap ] A matplotlib.cm.Colormap instance. If None, use rc settings. norm: [ None | Normalize ] An matplotlib.colors.Normalize instance is used to scale luminance data to 0,1. If None, defaults to normalize(). vmin/vmax: [ None | scalar ] vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array C is used. If you pass a norm instance, vmin and vmax will be ignored. shading: [ ‘ﬂat’ | ‘faceted’ ] If ‘faceted’, a black grid is drawn around each rectangle; if ‘ﬂat’, edges are not drawn. Default is ‘ﬂat’, contrary to Matlab(TM). This kwarg is deprecated; please use ‘edgecolors’ instead: • shading=’ﬂat’ – edgecolors=’None’ • shading=’faceted – edgecolors=’k’ edgecolors: [ None | ‘None’ | color | color sequence] If None, the rc setting is used by default. If ‘None’, edges will not be visible. An mpl color or sequence of colors will set the edge color alpha: 0 <= scalar <= 1 the alpha blending value Return value is a matplotlib.collection.Collection instance. The grid orientation follows the Matlab(TM) convention: an array C with shape (nrows, ncolumns) is plotted with the 472 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 column number as X and the row number as Y, increasing up; hence it is plotted the way the array would be printed, except that the Y axis is reversed. That is, C is taken as C*(*y, x). Similarly for meshgrid(): x = np.arange(5) y = np.arange(3) X, Y = meshgrid(x,y) is equivalent to: X = array([[0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]) Y = array([[0, 0, 0, 0, 0], [1, 1, 1, 1, 1], [2, 2, 2, 2, 2]]) so if you have: C = rand( len(x), len(y)) then you need: pcolor(X, Y, C.T) or: pcolor(C.T) Matlab pcolor() always discards the last row and column of C, but matplotlib displays the last row and column if X and Y are not speciﬁed, or if X and Y have one more row and column than C. kwargs can be used to control the PolyCollection properties: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path cmap color colorbar contains edgecolor or edgecolors facecolor or facecolors figure 34.1. matplotlib.axes Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a colormap or registered colormap name matplotlib color arg or sequence of rgba tuples unknown a callable function matplotlib color arg or sequence of rgba tuples matplotlib color arg or sequence of rgba tuples a matplotlib.figure.Figure instance Continued on next page 473 Matplotlib, Release 0.99.1.1 Table 34.13 – continued from previous page gid an id string label any string linestyle or linestyles or dashes [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] linewidth or lw or linewidths ﬂoat or sequence of ﬂoats lod [True | False] norm unknown offsets ﬂoat or sequence of ﬂoats picker [None|ﬂoat|boolean|callable] pickradius unknown rasterized [True | False | None] snap unknown transform Transform instance url a url string urls unknown visible [True | False] zorder any number pcolorfast(*args, **kwargs) pseudocolor plot of a 2-D array Experimental; this is a version of pcolor that does not draw lines, that provides the fastest possible rendering with the Agg backend, and that can handle any quadrilateral grid. Call signatures: pcolor(C, **kwargs) pcolor(xr, yr, C, **kwargs) pcolor(x, y, C, **kwargs) pcolor(X, Y, C, **kwargs) C is the 2D array of color values corresponding to quadrilateral cells. Let (nr, nc) be its shape. C may be a masked array. pcolor(C, **kwargs) is equivalent to pcolor([0,nc], [0,nr], C, **kwargs) xr, yr specify the ranges of x and y corresponding to the rectangular region bounding C. If: xr = [x0, x1] and: yr = [y0,y1] then x goes from x0 to x1 as the second index of C goes from 0 to nc, etc. (x0, y0) is the outermost corner of cell (0,0), and (x1, y1) is the outermost corner of cell (nr-1, nc-1). All cells are rectangles of the same size. This is the fastest version. 474 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 x, y are 1D arrays of length nc +1 and nr +1, respectively, giving the x and y boundaries of the cells. Hence the cells are rectangular but the grid may be nonuniform. The speed is intermediate. (The grid is checked, and if found to be uniform the fast version is used.) X and Y are 2D arrays with shape (nr +1, nc +1) that specify the (x,y) coordinates of the corners of the colored quadrilaterals; the quadrilateral for C[i,j] has corners at (X[i,j],Y[i,j]), (X[i,j+1],Y[i,j+1]), (X[i+1,j],Y[i+1,j]), (X[i+1,j+1],Y[i+1,j+1]). The cells need not be rectangular. This is the most general, but the slowest to render. It may produce faster and more compact output using ps, pdf, and svg backends, however. Note that the the column index corresponds to the x-coordinate, and the row index corresponds to y; for details, see the “Grid Orientation” section below. Optional keyword arguments: cmap: [ None | Colormap ] A cm Colormap instance from cm. If None, use rc settings. norm: [ None | Normalize ] An mcolors.Normalize instance is used to scale luminance data to 0,1. If None, defaults to normalize() vmin/vmax: [ None | scalar ] vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array C is used. If you pass a norm instance, vmin and vmax will be None. alpha: 0 <= scalar <= 1 the alpha blending value Return value is an image if a regular or rectangular grid is speciﬁed, and a QuadMesh collection in the general quadrilateral case. pcolormesh(*args, **kwargs) call signatures: pcolormesh(C) pcolormesh(X, Y, C) pcolormesh(C, **kwargs) C may be a masked array, but X and Y may not. Masked array support is implemented via cmap and norm; in contrast, pcolor() simply does not draw quadrilaterals with masked colors or vertices. Keyword arguments: cmap: [ None | Colormap ] A matplotlib.cm.Colormap instance. If None, use rc settings. norm: [ None | Normalize ] A matplotlib.colors.Normalize instance is used to scale luminance data to 0,1. If None, defaults to normalize(). vmin/vmax: [ None | scalar ] vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array C is used. If you pass a norm instance, vmin and vmax will be ignored. shading: [ ‘ﬂat’ | ‘faceted’ ] If ‘faceted’, a black grid is drawn around each rectangle; if ‘ﬂat’, edges are not drawn. Default is ‘ﬂat’, contrary to Matlab(TM). 34.1. matplotlib.axes 475 Matplotlib, Release 0.99.1.1 This kwarg is deprecated; please use ‘edgecolors’ instead: • shading=’ﬂat’ – edgecolors=’None’ • shading=’faceted – edgecolors=’k’ edgecolors: [ None | ‘None’ | color | color sequence] If None, the rc setting is used by default. If ‘None’, edges will not be visible. An mpl color or sequence of colors will set the edge color alpha: 0 <= scalar <= 1 the alpha blending value Return value is a matplotlib.collection.QuadMesh object. kwargs can be used to control the matplotlib.collections.QuadMesh properties: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path cmap color colorbar contains edgecolor or edgecolors facecolor or facecolors figure gid label linestyle or linestyles or dashes linewidth or lw or linewidths lod norm offsets picker pickradius rasterized snap transform url urls visible 476 Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a colormap or registered colormap name matplotlib color arg or sequence of rgba tuples unknown a callable function matplotlib color arg or sequence of rgba tuples matplotlib color arg or sequence of rgba tuples a matplotlib.figure.Figure instance an id string any string [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] ﬂoat or sequence of oats [True | False] unknown ﬂoat or sequence of ﬂoats [None|ﬂoat|boolean|callable] unknown [True | False | None] unknown Transform instance a url string unknown [True | False] Continued on next page Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.14 – continued from previous page any number zorder See Also: pcolor() For an explanation of the grid orientation and the expansion of 1-D X and/or Y to 2-D arrays. pick(*args) call signature: pick(mouseevent) each child artist will ﬁre a pick event if mouseevent is over the artist and the artist has picker set pie(x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.59999999999999998, shadow=False, labeldistance=1.1000000000000001) call signature: pie(x, explode=None, labels=None, colors=(’b’, ’g’, ’r’, ’c’, ’m’, ’y’, ’k’, ’w’), autopct=None, pctdistance=0.6, labeldistance=1.1, shadow=False) Make a pie chart of array x. The fractional area of each wedge is given by x/sum(x). If sum(x) <= 1, then the values of x give the fractional area directly and the array will not be normalized. Keyword arguments: explode: [ None | len(x) sequence ] If not None, is a len(x) array which speciﬁes the fraction of the radius with which to oﬀset each wedge. colors: [ None | color sequence ] A sequence of matplotlib color args through which the pie chart will cycle. labels: [ None | len(x) sequence of strings ] A sequence of strings providing the labels for each wedge autopct: [ None | format string | format function ] If not None, is a string or function used to label the wedges with their numeric value. The label will be placed inside the wedge. If it is a format string, the label will be fmt%pct. If it is a function, it will be called. pctdistance: scalar The ratio between the center of each pie slice and the start of the text generated by autopct. Ignored if autopct is None; default is 0.6. labeldistance: scalar The radial distance at which the pie labels are drawn shadow: [ False | True ] Draw a shadow beneath the pie. The pie chart will probably look best if the ﬁgure and axes are square. Eg.: 34.1. matplotlib.axes 477 Matplotlib, Release 0.99.1.1 figure(figsize=(8,8)) ax = axes([0.1, 0.1, 0.8, 0.8]) Return value: If autopct is None, return the tuple (patches, texts): • patches is a sequence of matplotlib.patches.Wedge instances • texts is a list of the label matplotlib.text.Text instances. If autopct is not None, return the tuple (patches, texts, autotexts), where patches and texts are as above, and autotexts is a list of Text instances for the numeric labels. plot(*args, **kwargs) Plot lines and/or markers to the Axes. args is a variable length argument, allowing for multiple x, y pairs with an optional format string. For example, each of the following is legal: plot(x, y) plot(x, y, ’bo’) plot(y) plot(y, ’r+’) # # # # plot x plot x plot y ditto, and y using default line style and color and y using blue circle markers using x as index array 0..N-1 but with red plusses If x and/or y is 2-dimensional, then the corresponding columns will be plotted. An arbitrary number of x, y, fmt groups can be speciﬁed, as in: a.plot(x1, y1, ’g^’, x2, y2, ’g-’) Return value is a list of lines that were added. The following format string characters are accepted to control the line style or marker: 478 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 character ’-’ ’--’ ’-.’ ’:’ ’.’ ’,’ ’o’ ’v’ ’^’ ’<’ ’>’ ’1’ ’2’ ’3’ ’4’ ’s’ ’p’ ’*’ ’h’ ’H’ ’+’ ’x’ ’D’ ’d’ ’|’ ’_’ description solid line style dashed line style dash-dot line style dotted line style point marker pixel marker circle marker triangle_down marker triangle_up marker triangle_left marker triangle_right marker tri_down marker tri_up marker tri_left marker tri_right marker square marker pentagon marker star marker hexagon1 marker hexagon2 marker plus marker x marker diamond marker thin_diamond marker vline marker hline marker The following color abbreviations are supported: character ‘b’ ‘g’ ‘r’ ‘c’ ‘m’ ‘y’ ‘k’ ‘w’ color blue green red cyan magenta yellow black white In addition, you can specify colors in many weird and wonderful ways, including full names (’green’), hex strings (’#008000’), RGB or RGBA tuples ((0,1,0,1)) or grayscale intensities as a string (’0.8’). Of these, the string speciﬁcations can be used in place of a fmt group, but the tuple forms can be used only as kwargs. Line styles and colors are combined in a single format string, as in ’bo’ for blue circles. The kwargs can be used to set line properties (any property that has a set_* method). You can use this to set a line label (for auto legends), linewidth, anitialising, marker face color, etc. Here is an example: 34.1. matplotlib.axes 479 Matplotlib, Release 0.99.1.1 plot([1,2,3], [1,2,3], ’go-’, label=’line 1’, linewidth=2) plot([1,2,3], [1,4,9], ’rs’, label=’line 2’) axis([0, 4, 0, 10]) legend() If you make multiple lines with one plot command, the kwargs apply to all those lines, e.g.: plot(x1, y1, x2, y2, antialised=False) Neither line will be antialiased. You do not need to use format strings, which are just abbreviations. All of the line properties can be controlled by keyword arguments. For example, you can set the color, marker, linestyle, and markercolor with: plot(x, y, color=’green’, linestyle=’dashed’, marker=’o’, markerfacecolor=’blue’, markersize=12). See :class:‘~matplotlib.lines.Line2D‘ for details. The kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc 480 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.15 – continued from previous pa markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number kwargs scalex and scaley, if deﬁned, are passed on to autoscale_view() to determine whether the x and y axes are autoscaled; the default is True. plot_date(x, y, fmt=’bo’, tz=None, xdate=True, ydate=False, **kwargs) call signature: plot_date(x, y, fmt=’bo’, tz=None, xdate=True, ydate=False, **kwargs) Similar to the plot() command, except the x or y (or both) data is considered to be dates, and the axis is labeled accordingly. x and/or y can be a sequence of dates represented as ﬂoat days since 0001-01-01 UTC. Keyword arguments: fmt: string The plot format string. tz: [ None | timezone string ] The time zone to use in labeling dates. If None, defaults to rc value. xdate: [ True | False ] If True, the x-axis will be labeled with dates. ydate: [ False | True ] If True, the y-axis will be labeled with dates. Note if you are using custom date tickers and formatters, it may be necessary to set the formatters/locators after the call to plot_date() since plot_date() will set the default tick locator to matplotlib.dates.AutoDateLocator (if the tick locator is not already set to a matplotlib.dates.DateLocator instance) and the default tick formatter to matplotlib.dates.AutoDateFormatter (if the tick formatter is not already set to a matplotlib.dates.DateFormatter instance). Valid kwargs are Line2D properties: 34.1. matplotlib.axes 481 Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number See Also: dates for helper functions 482 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 date2num(), num2date() and drange() for help on creating the required ﬂoating point dates. psd(x, NFFT=256, Fs=2, Fc=0, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) call signature: psd(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) The power spectral density by Welch’s average periodogram method. The vector x is divided into NFFT length segments. Each segment is detrended by function detrend and windowed by function window. noverlap gives the length of the overlap between segments. The |ﬀt(i)|2 of each segment i are averaged to compute Pxx, with a scaling to correct for power loss due to windowing. Fs is the sampling frequency. Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and 34.1. matplotlib.axes 483 Matplotlib, Release 0.99.1.1 both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Fc: integer The center frequency of x (defaults to 0), which oﬀsets the x extents of the plot to reﬂect the frequency range used when a signal is acquired and then ﬁltered and downsampled to baseband. Returns the tuple (Pxx, freqs). For plotting, the power is plotted as 10 log10 (P xx ) for decibels, though Pxx itself is returned. References: Bendat & Piersol – Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986) kwargs control the Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker 484 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.17 – continued from previous pa pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Example: quiver(*args, **kw) Plot a 2-D ﬁeld of arrows. call signatures: quiver(U, V, **kw) quiver(U, V, C, **kw) 34.1. matplotlib.axes 485 Matplotlib, Release 0.99.1.1 quiver(X, Y, U, V, **kw) quiver(X, Y, U, V, C, **kw) Arguments: X, Y : The x and y coordinates of the arrow locations (default is tail of arrow; see pivot kwarg) U, V : give the x and y components of the arrow vectors C: an optional array used to map colors to the arrows All arguments may be 1-D or 2-D arrays or sequences. If X and Y are absent, they will be generated as a uniform grid. If U and V are 2-D arrays but X and Y are 1-D, and if len(X ) and len(Y ) match the column and row dimensions of U, then X and Y will be expanded with numpy.meshgrid(). U, V, C may be masked arrays, but masked X, Y are not supported at present. Keyword arguments: units: [’width’ | ‘height’ | ‘dots’ | ‘inches’ | ‘x’ | ‘y’ ] arrow units; the arrow dimensions except for length are in multiples of this unit. • ‘width’ or ‘height’: the width or height of the axes • ‘dots’ or ‘inches’: pixels or inches, based on the ﬁgure dpi • ‘x’ or ‘y’: X or Y data units The arrows scale diﬀerently depending on the units. For ‘x’ or ‘y’, the arrows get larger as one zooms in; for other units, the arrow size is independent of the zoom state. For ‘width or ‘height’, the arrow size increases with the width and height of the axes, respectively, when the the window is resized; for ‘dots’ or ‘inches’, resizing does not change the arrows. angles: [’uv’ | ‘xy’ | array] With the default ‘uv’, the arrow aspect ratio is 1, so that if U*==*V the angle of the arrow on the plot is 45 degrees CCW from the x-axis. With ‘xy’, the arrow points from (x,y) to (x+u, y+v). Alternatively, arbitrary angles may be speciﬁed as an array of values in degrees, CCW from the x-axis. scale: [ None | ﬂoat ] data units per arrow unit, e.g. m/s per plot width; a smaller scale parameter makes the arrow longer. If None, a simple autoscaling algorithm is used, based on the average vector length and the number of vectors. width: shaft width in arrow units; default depends on choice of units, above, and number of vectors; a typical starting value is about 0.005 times the width of the plot. headwidth: scalar head width as multiple of shaft width, default is 3 486 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 headlength: scalar head length as multiple of shaft width, default is 5 headaxislength: scalar head length at shaft intersection, default is 4.5 minshaft: scalar length below which arrow scales, in units of head length. Do not set this to less than 1, or small arrows will look terrible! Default is 1 minlength: scalar minimum length as a multiple of shaft width; if an arrow length is less than this, plot a dot (hexagon) of this diameter instead. Default is 1. pivot: [ ‘tail’ | ‘middle’ | ‘tip’ ] The part of the arrow that is at the grid point; the arrow rotates about this point, hence the name pivot. color: [ color | color sequence ] This is a synonym for the PolyCollection facecolor kwarg. If C has been set, color has no eﬀect. The defaults give a slightly swept-back arrow; to make the head a triangle, make headaxislength the same as headlength. To make the arrow more pointed, reduce headwidth or increase headlength and headaxislength. To make the head smaller relative to the shaft, scale down all the head parameters. You will probably do best to leave minshaft alone. linewidths and edgecolors can be used to customize the arrow outlines. PolyCollection keyword arguments: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path cmap color colorbar contains edgecolor or edgecolors facecolor or facecolors figure gid label linestyle or linestyles or dashes linewidth or lw or linewidths lod norm offsets picker pickradius 34.1. matplotlib.axes Additional Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a colormap or registered colormap name matplotlib color arg or sequence of rgba tuples unknown a callable function matplotlib color arg or sequence of rgba tuples matplotlib color arg or sequence of rgba tuples a matplotlib.figure.Figure instance an id string any string [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] ﬂoat or sequence of ﬂoats [True | False] unknown ﬂoat or sequence of ﬂoats [None|ﬂoat|boolean|callable] unknown Continued on next page 487 Matplotlib, Release 0.99.1.1 Table 34.18 – continued from previous page [True | False | None] unknown Transform instance a url string unknown [True | False] any number rasterized snap transform url urls visible zorder quiverkey(*args, **kw) Add a key to a quiver plot. call signature: quiverkey(Q, X, Y, U, label, **kw) Arguments: Q: The Quiver instance returned by a call to quiver. X, Y : The location of the key; additional explanation follows. U: The length of the key label: a string with the length and units of the key Keyword arguments: coordinates = [ ‘axes’ | ‘ﬁgure’ | ‘data’ | ‘inches’ ] Coordinate system and units for X, Y : ‘axes’ and ‘ﬁgure’ are normalized coordinate systems with 0,0 in the lower left and 1,1 in the upper right; ‘data’ are the axes data coordinates (used for the locations of the vectors in the quiver plot itself); ‘inches’ is position in the ﬁgure in inches, with 0,0 at the lower left corner. color: overrides face and edge colors from Q. labelpos = [ ‘N’ | ‘S’ | ‘E’ | ‘W’ ] Position the label above, below, to the right, to the left of the arrow, respectively. labelsep: Distance in inches between the arrow and the label. Default is 0.1 labelcolor: defaults to default Text color. fontproperties: A dictionary with keyword arguments accepted FontProperties initializer: family, style, variant, size, weight by the Any additional keyword arguments are used to override vector properties taken from Q. The positioning of the key depends on X, Y, coordinates, and labelpos. If labelpos is ‘N’ or ‘S’, X, Y give the position of the middle of the key arrow. If labelpos is ‘E’, X, Y positions the head, and if labelpos is ‘W’, X, Y positions the tail; in either of these two cases, X, Y is somewhere in the middle of the arrow+label key object. 488 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 redraw_in_frame() This method can only be used after an initial draw which caches the renderer. It is used to eﬃciently update Axes data (axis ticks, labels, etc are not updated) relim() recompute the data limits based on current artists reset_position() Make the original position the active position scatter(x, y, s=20, c=’b’, marker=’o’, cmap=None, norm=None, vmin=None, vmax=None, alpha=1.0, linewidths=None, faceted=True, verts=None, **kwargs) call signatures: scatter(x, y, s=20, c=’b’, marker=’o’, cmap=None, norm=None, vmin=None, vmax=None, alpha=1.0, linewidths=None, verts=None, **kwargs) Make a scatter plot of x versus y, where x, y are converted to 1-D sequences which must be of the same length, N. Keyword arguments: s: size in points^2. It is a scalar or an array of the same length as x and y. c: a color. c can be a single color format string, or a sequence of color speciﬁcations of length N, or a sequence of N numbers to be mapped to colors using the cmap and norm speciﬁed via kwargs (see below). Note that c should not be a single numeric RGB or RGBA sequence because that is indistinguishable from an array of values to be colormapped. c can be a 2-D array in which the rows are RGB or RGBA, however. marker: can be one of: Value ‘s’ ‘o’ ‘^’ ‘>’ ‘v’ ‘<’ ‘d’ ‘p’ ‘h’ ‘8’ ‘+’ ‘x’ Description square circle triangle up triangle right triangle down triangle left diamond pentagram hexagon octagon plus cross The marker can also be a tuple (numsides, style, angle), which will create a custom, regular symbol. numsides: the number of sides style: the style of the regular symbol: 34.1. matplotlib.axes 489 Matplotlib, Release 0.99.1.1 Value 0 1 2 3 Description a regular polygon a star-like symbol an asterisk a circle (numsides and angle is ignored) angle: the angle of rotation of the symbol Finally, marker can be (verts, 0): verts is a sequence of (x, y) vertices for a custom scatter symbol. Alternatively, use the kwarg combination marker = None, verts = verts. Any or all of x, y, s, and c may be masked arrays, in which case all masks will be combined and only unmasked points will be plotted. Other keyword arguments: the color mapping and normalization arguments will be used only if c is an array of ﬂoats. cmap: [ None | Colormap ] A matplotlib.colors.Colormap instance or registered name. If None, defaults to rc image.cmap. cmap is only used if c is an array of ﬂoats. norm: [ None | Normalize ] A matplotlib.colors.Normalize instance is used to scale luminance data to 0, 1. If None, use the default normalize(). norm is only used if c is an array of ﬂoats. vmin/vmax: vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array C is used. Note if you pass a norm instance, your settings for vmin and vmax will be ignored. alpha: 0 <= scalar <= 1 The alpha value for the patches linewidths: [ None | scalar | sequence ] If None, defaults to (lines.linewidth,). Note that this is a tuple, and if you set the linewidths argument you must set it as a sequence of ﬂoats, as required by RegularPolyCollection. Optional kwargs control the Collection properties; in particular: edgecolors: ‘none’ to plot faces with no outlines facecolors: ‘none’ to plot unﬁlled outlines Here are the standard descriptions of all the Collection kwargs: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on 490 Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] Continued on next page Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.19 – continued from previous page clip_path [ (Path, Transform) | Patch | None ] cmap a colormap or registered colormap name color matplotlib color arg or sequence of rgba tuples colorbar unknown contains a callable function edgecolor or edgecolors matplotlib color arg or sequence of rgba tuples facecolor or facecolors matplotlib color arg or sequence of rgba tuples figure a matplotlib.figure.Figure instance gid an id string label any string linestyle or linestyles or dashes [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] linewidth or lw or linewidths ﬂoat or sequence of ﬂoats lod [True | False] norm unknown offsets ﬂoat or sequence of ﬂoats picker [None|ﬂoat|boolean|callable] pickradius unknown rasterized [True | False | None] snap unknown transform Transform instance url a url string urls unknown visible [True | False] zorder any number A Collection instance is returned. semilogx(*args, **kwargs) call signature: semilogx(*args, **kwargs) Make a plot with log scaling on the x axis. semilogx() supports all the keyword matplotlib.axes.Axes.set_xscale(). arguments of plot() and Notable keyword arguments: basex: scalar > 1 base of the x logarithm subsx: [ None | sequence ] The location of the minor xticks; None defaults to autosubs, which depend on the number of decades in the plot; see set_xscale() for details. nonposx: [’mask’ | ‘clip’ ] non-positive values in x can be masked as invalid, or clipped to a very small positive number 34.1. matplotlib.axes 491 Matplotlib, Release 0.99.1.1 The remaining valid kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number See Also: loglog() For example code and ﬁgure 492 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 semilogy(*args, **kwargs) call signature: semilogy(*args, **kwargs) Make a plot with log scaling on the y axis. semilogy() supports all the keyword matplotlib.axes.Axes.set_yscale(). arguments of plot() and Notable keyword arguments: basey: scalar > 1 Base of the y logarithm subsy: [ None | sequence ] The location of the minor yticks; None defaults to autosubs, which depend on the number of decades in the plot; see set_yscale() for details. nonposy: [’mask’ | ‘clip’ ] non-positive values in y can be masked as invalid, or clipped to a very small positive number The remaining valid kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms 34.1. matplotlib.axes Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat 493 Matplotlib, Release 0.99.1.1 Table 34.21 – continued from previous pa None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder See Also: loglog() For example code and ﬁgure set_adjustable(adjustable) ACCEPTS: [ ‘box’ | ‘datalim’ ] set_anchor(anchor) anchor value ‘C’ ‘SW’ ‘S’ ‘SE’ ‘E’ ‘NE’ ‘N’ ‘NW’ ‘W’ description Center bottom left bottom bottom right right top right top top left left set_aspect(aspect, adjustable=None, anchor=None) aspect value ‘auto’ ‘normal’ ‘equal’ num description automatic; ﬁll position rectangle with data same as ‘auto’; deprecated same scaling from data to plot units for x and y a circle will be stretched such that the height is num times the width. aspect=1 is the same as aspect=’equal’. adjustable 494 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 value ‘box’ ‘datalim’ description change physical size of axes change xlim or ylim anchor value ‘C’ ‘SW’ ‘S’ ‘SE’ etc. description centered lower left corner middle of bottom edge lower right corner set_autoscale_on(b) Set whether autoscaling is applied on plot commands accepts: [ True | False ] set_autoscalex_on(b) Set whether autoscaling for the x-axis is applied on plot commands accepts: [ True | False ] set_autoscaley_on(b) Set whether autoscaling for the y-axis is applied on plot commands accepts: [ True | False ] set_axes_locator(locator) set axes_locator ACCEPT [a callable object which takes an axes instance and renderer and] returns a bbox. set_axis_bgcolor(color) set the axes background color ACCEPTS: any matplotlib color - see colors() set_axis_off () turn oﬀ the axis set_axis_on() turn on the axis set_axisbelow(b) Set whether the axis ticks and gridlines are above or below most artists ACCEPTS: [ True | False ] set_color_cycle(clist) Set the color cycle for any future plot commands on this Axes. clist is a list of mpl color speciﬁers. set_cursor_props(*args) Set the cursor property as: 34.1. matplotlib.axes 495 Matplotlib, Release 0.99.1.1 ax.set_cursor_props(linewidth, color) or: ax.set_cursor_props((linewidth, color)) ACCEPTS: a (ﬂoat, color) tuple set_figure(ﬁg) Set the class:~matplotlib.axes.Axes ﬁgure accepts a class:~matplotlib.ﬁgure.Figure instance set_frame_on(b) Set whether the axes rectangle patch is drawn ACCEPTS: [ True | False ] set_navigate(b) Set whether the axes responds to navigation toolbar commands ACCEPTS: [ True | False ] set_navigate_mode(b) Set the navigation toolbar button status; Warning: this is not a user-API function. set_position(pos, which=’both’) Set the axes position with: pos = [left, bottom, width, height] in relative 0,1 coords, or pos can be a Bbox There are two position variables: one which is ultimately used, but which may be modiﬁed by apply_aspect(), and a second which is the starting point for apply_aspect(). Optional keyword arguments: which value ‘active’ ‘original’ ‘both’ description to change the ﬁrst to change the second to change both set_rasterization_zorder(z) Set zorder value below which artists will be rasterized set_title(label, fontdict=None, **kwargs) call signature: set_title(label, fontdict=None, **kwargs): 496 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Set the title for the axes. kwargs are Text properties: Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number ACCEPTS: str See Also: 34.1. matplotlib.axes 497 Matplotlib, Release 0.99.1.1 text() for information on how override and the optional args work set_xbound(lower=None, upper=None) Set the lower and upper numerical bounds of the x-axis. This method will honor axes inversion regardless of parameter order. set_xlabel(xlabel, fontdict=None, labelpad=None, **kwargs) call signature: set_xlabel(xlabel, fontdict=None, labelpad=None, **kwargs) Set the label for the xaxis. labelpad is the spacing in points between the label and the x-axis Valid kwargs are Text properties: Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform 498 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.23 – continued fro url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number ACCEPTS: str See Also: text() for information on how override and the optional args work set_xlim(xmin=None, xmax=None, emit=True, **kwargs) call signature: set_xlim(self, *args, **kwargs) Set the limits for the xaxis Returns the current xlimits as a length 2 tuple: [xmin, xmax] Examples: set_xlim((valmin, valmax)) set_xlim(valmin, valmax) set_xlim(xmin=1) # xmax unchanged set_xlim(xmax=1) # xmin unchanged Keyword arguments: ymin: scalar the min of the ylim ymax: scalar the max of the ylim emit: [ True | False ] notify observers of lim change ACCEPTS: len(2) sequence of ﬂoats set_xscale(value, **kwargs) call signature: set_xscale(value) Set the scaling of the x-axis: ‘linear’ | ‘log’ | ‘symlog’ ACCEPTS: [’linear’ | ‘log’ | ‘symlog’] 34.1. matplotlib.axes 499 Matplotlib, Release 0.99.1.1 Diﬀerent kwargs are accepted, depending on the scale: ‘linear’ ‘log’ basex/basey: The base of the logarithm nonposx/nonposy: [’mask’ | ‘clip’ ] non-positive values in x or y can be masked as invalid, or clipped to a very small positive number subsx/subsy: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] will place 10 logarithmically spaced minor ticks between each major tick. ‘symlog’ basex/basey: The base of the logarithm linthreshx/linthreshy: The range (-x, x) within which the plot is linear (to avoid having the plot go to inﬁnity around zero). subsx/subsy: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] will place 10 logarithmically spaced minor ticks between each major tick. set_xticklabels(labels, fontdict=None, minor=False, **kwargs) call signature: set_xticklabels(labels, fontdict=None, minor=False, **kwargs) Set the xtick labels with list of strings labels. Return a list of axis text instances. kwargs set the Text properties. Valid properties are Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha 500 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.24 – continued fro label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number ACCEPTS: sequence of strings set_xticks(ticks, minor=False) Set the x ticks with list of ticks ACCEPTS: sequence of ﬂoats set_ybound(lower=None, upper=None) Set the lower and upper numerical bounds of the y-axis. This method will honor axes inversion regardless of parameter order. set_ylabel(ylabel, fontdict=None, labelpad=None, **kwargs) call signature: set_ylabel(ylabel, fontdict=None, labelpad=None, **kwargs) Set the label for the yaxis labelpad is the spacing in points between the label and the y-axis Valid kwargs are Text properties: Property 34.1. matplotlib.axes Description 501 Matplotlib, Release 0.99.1.1 Table 34.25 – continued fro alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number ACCEPTS: str See Also: text() for information on how override and the optional args work 502 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 set_ylim(ymin=None, ymax=None, emit=True, **kwargs) call signature: set_ylim(self, *args, **kwargs): Set the limits for the yaxis; v = [ymin, ymax]: set_ylim((valmin, valmax)) set_ylim(valmin, valmax) set_ylim(ymin=1) # ymax unchanged set_ylim(ymax=1) # ymin unchanged Keyword arguments: ymin: scalar the min of the ylim ymax: scalar the max of the ylim emit: [ True | False ] notify observers of lim change Returns the current ylimits as a length 2 tuple ACCEPTS: len(2) sequence of ﬂoats set_yscale(value, **kwargs) call signature: set_yscale(value) Set the scaling of the y-axis: ‘linear’ | ‘log’ | ‘symlog’ ACCEPTS: [’linear’ | ‘log’ | ‘symlog’] Diﬀerent kwargs are accepted, depending on the scale: ‘linear’ ‘log’ basex/basey: The base of the logarithm nonposx/nonposy: [’mask’ | ‘clip’ ] non-positive values in x or y can be masked as invalid, or clipped to a very small positive number subsx/subsy: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] will place 10 logarithmically spaced minor ticks between each major tick. ‘symlog’ basex/basey: The base of the logarithm linthreshx/linthreshy: The range (-x, x) within which the plot is linear (to avoid having the plot go to inﬁnity around zero). 34.1. matplotlib.axes 503 Matplotlib, Release 0.99.1.1 subsx/subsy: Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] will place 10 logarithmically spaced minor ticks between each major tick. set_yticklabels(labels, fontdict=None, minor=False, **kwargs) call signature: set_yticklabels(labels, fontdict=None, minor=False, **kwargs) Set the ytick labels with list of strings labels. Return a list of Text instances. kwargs set Text properties for the labels. Valid properties are Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant 504 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 Table 34.26 – continued fro verticalalignment or va or ma visible weight or fontweight x y zorder [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number ACCEPTS: sequence of strings set_yticks(ticks, minor=False) Set the y ticks with list of ticks ACCEPTS: sequence of ﬂoats Keyword arguments: minor: [ False | True ] Sets the minor ticks if True specgram(x, NFFT=256, Fs=2, Fc=0, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=128, cmap=None, xextent=None, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) call signature: specgram(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=128, cmap=None, xextent=None, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) Compute a spectrogram of data in x. Data are split into NFFT length segments and the PSD of each section is computed. The windowing function window is applied to each segment, and the amount of overlap of each segment is speciﬁed with noverlap. Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is 34.1. matplotlib.axes 505 Matplotlib, Release 0.99.1.1 window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Fc: integer The center frequency of x (defaults to 0), which oﬀsets the y extents of the plot to reﬂect the frequency range used when a signal is acquired and then ﬁltered and downsampled to baseband. cmap: A matplotlib.cm.Colormap instance; if None use default determined by rc xextent: The image extent along the x-axis. xextent = (xmin,xmax) The default is (0,max(bins)), where bins is the return value from mlab.specgram() kwargs: Additional kwargs are passed on to imshow which makes the specgram image Return value is (Pxx, freqs, bins, im): •bins are the time points the spectrogram is calculated over •freqs is an array of frequencies •Pxx is a len(times) x len(freqs) array of power •im is a matplotlib.image.AxesImage instance Note: If x is real (i.e. non-complex), only the positive spectrum is shown. If x is complex, both positive and negative parts of the spectrum are shown. This can be overridden using the sides keyword argument. Example: 506 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 spy(Z, precision=0, marker=None, markersize=None, aspect=’equal’, **kwargs) call signature: spy(Z, precision=0, marker=None, markersize=None, aspect=’equal’, **kwargs) spy(Z) plots the sparsity pattern of the 2-D array Z. If precision is 0, any non-zero value will be plotted; else, values of |Z | > precision will be plotted. For scipy.sparse.spmatrix instances, there is a special case: if precision is ‘present’, any value present in the array will be plotted, even if it is identically zero. The array will be plotted as it would be printed, with the ﬁrst index (row) increasing down and the second index (column) increasing to the right. By default aspect is ‘equal’, so that each array element occupies a square space; set the aspect kwarg to ‘auto’ to allow the plot to ﬁll the plot box, or to any scalar number to specify the aspect ratio of an array element directly. Two plotting styles are available: image or marker. Both are available for full arrays, but only the marker style works for scipy.sparse.spmatrix instances. If marker and markersize are None, an image will be returned and any remaining kwargs are passed to imshow(); else, a Line2D object will be returned with the value of marker determining 34.1. matplotlib.axes 507 Matplotlib, Release 0.99.1.1 the marker type, and any remaining kwargs passed to the plot() method. If marker and markersize are None, useful kwargs include: •cmap •alpha See Also: imshow() For image options. For controlling colors, e.g. cyan background and red marks, use: cmap = mcolors.ListedColormap([’c’,’r’]) If marker or markersize is not None, useful kwargs include: •marker •markersize •color Useful values for marker include: •‘s’ square (default) •‘o’ circle •‘.’ point •‘,’ pixel See Also: plot() For plotting options start_pan(x, y, button) Called when a pan operation has started. x, y are the mouse coordinates in display coords. button is the mouse button number: •1: LEFT •2: MIDDLE •3: RIGHT Note: Intended to be overridden by new projection types. stem(x, y, linefmt=’b-’, markerfmt=’bo’, basefmt=’r-’) call signature: stem(x, y, linefmt=’b-’, markerfmt=’bo’, basefmt=’r-’) 508 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 A stem plot plots vertical lines (using linefmt) at each x location from the baseline to y, and places a marker there using markerfmt. A horizontal line at 0 is is plotted using basefmt. Return value is a tuple (markerline, stemlines, baseline). See Also: this document for details examples/pylab_examples/stem_plot.py for a demo step(x, y, *args, **kwargs) call signature: step(x, y, *args, **kwargs) Make a step plot. Additional keyword args to step() are the same as those for plot(). x and y must be 1-D sequences, and it is assumed, but not checked, that x is uniformly increasing. Keyword arguments: where: [ ‘pre’ | ‘post’ | ‘mid’ ] If ‘pre’, the interval from x[i] to x[i+1] has level y[i+1] If ‘post’, that interval has level y[i] If ‘mid’, the jumps in y occur half-way between the x-values. table(**kwargs) call signature: table(cellText=None, cellColours=None, cellLoc=’right’, colWidths=None, rowLabels=None, rowColours=None, rowLoc=’left’, colLabels=None, colColours=None, colLoc=’center’, loc=’bottom’, bbox=None): Add a table to the current axes. Returns a matplotlib.table.Table instance. For ﬁner grained control over tables, use the Table class and add it to the axes with add_table(). Thanks to John Gill for providing the class and table. kwargs control the Table properties: 34.1. matplotlib.axes 509 Matplotlib, Release 0.99.1.1 Property alpha animated axes clip_box clip_on clip_path contains figure fontsize gid label lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a callable function a matplotlib.figure.Figure instance a ﬂoat in points an id string any string [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number text(x, y, s, fontdict=None, withdash=False, **kwargs) call signature: text(x, y, s, fontdict=None, **kwargs) Add text in string s to axis at location x, y, data coordinates. Keyword arguments: fontdict: A dictionary to override the default text properties. If fontdict is None, the defaults are determined by your rc parameters. withdash: [ False | True ] Creates a TextWithDash instance instead of a Text instance. Individual keyword arguments can be used to override any given parameter: text(x, y, s, fontsize=12) The default transform speciﬁes that text is in data coords, alternatively, you can specify text in axis coords (0,0 is lower-left and 1,1 is upper-right). The example below places text in the center of the axes: text(0.5, 0.5,’matplotlib’, horizontalalignment=’center’, verticalalignment=’center’, transform = ax.transAxes) 510 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 You can put a rectangular box around the text instance (eg. to set a background color) by using the keyword bbox. bbox is a dictionary of matplotlib.patches.Rectangle properties. For example: text(x, y, s, bbox=dict(facecolor=’red’, alpha=0.5)) Valid kwargs are matplotlib.text.Text properties: Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder 34.1. matplotlib.axes Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number 511 Matplotlib, Release 0.99.1.1 ticklabel_format(**kwargs) Convenience method for manipulating the ScalarFormatter used by default for linear axes. Optional keyword arguments: Keyword style scilimits axis Description [ ‘sci’ (or ‘scientiﬁc’) | ‘plain’ ] plain turns oﬀ scientiﬁc notation (m, n), pair of integers; if style is ‘sci’, scientiﬁc notation will be used for numbers outside the range 10‘-m‘:sup: to 10‘n‘:sup:. Use (0,0) to include all numbers. [ ‘x’ | ‘y’ | ‘both’ ] Only the major ticks are aﬀected. If the method is called when the ScalarFormatter is not the Formatter being used, an AttributeError will be raised. twinx() call signature: ax = twinx() create a twin of Axes for generating a plot with a sharex x-axis but independent y axis. The y-axis of self will have ticks on left and the returned axes will have ticks on the right twiny() call signature: ax = twiny() create a twin of Axes for generating a plot with a shared y-axis but independent x axis. The x-axis of self will have ticks on bottom and the returned axes will have ticks on the top update_datalim(xys, updatex=True, updatey=True) Update the data lim bbox with seq of xy tups or equiv. 2-D array update_datalim_bounds(bounds) Update the datalim to include the given Bbox bounds update_datalim_numerix(x, y) Update the data lim bbox with seq of xy tups vlines(x, ymin, ymax, colors=’k’, linestyles=’solid’, label=”, **kwargs) call signature: vlines(x, ymin, ymax, color=’k’, linestyles=’solid’) Plot vertical lines at each x from ymin to ymax. ymin or ymax can be scalars or len(x) numpy arrays. If they are scalars, then the respective values are constant, else the heights of the lines are determined by ymin and ymax. colors a line collections color args, either a single color or a len(x) list of colors linestyles 512 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 one of [ ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ] Returns the matplotlib.collections.LineCollection that was added. kwargs are LineCollection properties: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path cmap color colorbar contains edgecolor or edgecolors facecolor or facecolors figure gid label linestyle or linestyles or dashes linewidth or lw or linewidths lod norm offsets picker pickradius rasterized segments snap transform url urls verts visible zorder Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a colormap or registered colormap name matplotlib color arg or sequence of rgba tuples unknown a callable function matplotlib color arg or sequence of rgba tuples matplotlib color arg or sequence of rgba tuples a matplotlib.figure.Figure instance an id string any string [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] ﬂoat or sequence of ﬂoats [True | False] unknown ﬂoat or sequence of ﬂoats [None|ﬂoat|boolean|callable] unknown [True | False | None] unknown unknown Transform instance a url string unknown unknown [True | False] any number xaxis_date(tz=None) Sets up x-axis ticks and labels that treat the x data as dates. tz is the time zone to use in labeling dates. Defaults to rc value. xaxis_inverted() 34.1. matplotlib.axes 513 Matplotlib, Release 0.99.1.1 Returns True if the x-axis is inverted. xcorr(x, y, normed=True, detrend=<function detrend_none at 0x30b5d70>, usevlines=True, maxlags=10, **kwargs) call signature: def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags=10, **kwargs): Plot the cross correlation between x and y. If normed = True, normalize the data by the cross correlation at 0-th lag. x and y are detrended by the detrend callable (default no normalization). x and y must be equal length. Data are plotted as plot(lags, c, **kwargs) Return value is a tuple (lags, c, line) where: •lags are a length 2*maxlags+1 lag vector •c is the 2*maxlags+1 auto correlation vector •line is a Line2D instance returned by plot(). The default linestyle is None and the default marker is ‘o’, though these can be overridden with keyword args. The cross correlation is performed with numpy.correlate() with mode = 2. If usevlines is True: vlines() rather than plot() is used to draw vertical lines from the origin to the xcorr. Otherwise the plotstyle is determined by the kwargs, which are Line2D properties. The return value is a tuple (lags, c, linecol, b) where linecol is the matplotlib.collections.LineCollection instance and b is the x-axis. maxlags is a positive integer detailing the number of lags to show. The default value of None will return all (2*len(x)-1) lags. Example: xcorr() above, and acorr() below. Example: 514 Chapter 34. matplotlib axes Matplotlib, Release 0.99.1.1 yaxis_date(tz=None) Sets up y-axis ticks and labels that treat the y data as dates. tz is the time zone to use in labeling dates. Defaults to rc value. yaxis_inverted() Returns True if the y-axis is inverted. Subplot alias of AxesSubplot class SubplotBase(ﬁg, *args, **kwargs) Base class for subplots, which are Axes instances with additional methods to facilitate generating and manipulating a set of Axes within a ﬁgure. ﬁg is a matplotlib.figure.Figure instance. args is the tuple (numRows, numCols, plotNum), where the array of subplots in the ﬁgure has dimensions numRows, numCols, and where plotNum is the number of the subplot being created. plotNum starts at 1 in the upper left corner and increases to the right. If numRows <= numCols <= plotNum < 10, args can be the decimal integer numRows * 100 + numCols * 10 + plotNum. change_geometry(numrows, numcols, num) change subplot geometry, eg. from 1,1,1 to 2,2,3 34.1. matplotlib.axes 515 Matplotlib, Release 0.99.1.1 get_geometry() get the subplot geometry, eg 2,2,3 is_first_col() is_first_row() is_last_col() is_last_row() label_outer() set the visible property on ticklabels so xticklabels are visible only if the subplot is in the last row and yticklabels are visible only if the subplot is in the ﬁrst column update_params() update the subplot position from ﬁg.subplotpars set_default_color_cycle(clist) Change the default cycle of colors that will be used by the plot command. This must be called before creating the Axes to which it will apply; it will apply to all future axes. clist is a sequence of mpl color speciﬁers subplot_class_factory(axes_class=None) 516 Chapter 34. matplotlib axes CHAPTER THIRTYFIVE MATPLOTLIB AXIS 35.1 matplotlib.axis Classes for the ticks and x and y axis class Axis(axes, pickradius=15) Bases: matplotlib.artist.Artist Public attributes •axes.transData - transform data coords to display coords •axes.transAxes - transform axis coords to display coords •labelpad - number of points between the axis and its label Init the axis with the parent Axes instance cla() clear the current axis convert_units(x) draw(artist, renderer, *kl) Draw the axis lines, grid lines, tick lines and labels get_children() get_data_interval() return the Interval instance for this axis data limits get_gridlines() Return the grid lines as a list of Line2D instance get_label() Return the axis label as a Text instance get_label_text() Get the text of the label get_major_formatter() Get the formatter of the major ticker 517 Matplotlib, Release 0.99.1.1 get_major_locator() Get the locator of the major ticker get_major_ticks(numticks=None) get the tick instances; grow as necessary get_majorticklabels() Return a list of Text instances for the major ticklabels get_majorticklines() Return the major tick lines as a list of Line2D instances get_majorticklocs() Get the major tick locations in data coordinates as a numpy array get_minor_formatter() Get the formatter of the minor ticker get_minor_locator() Get the locator of the minor ticker get_minor_ticks(numticks=None) get the minor tick instances; grow as necessary get_minorticklabels() Return a list of Text instances for the minor ticklabels get_minorticklines() Return the minor tick lines as a list of Line2D instances get_minorticklocs() Get the minor tick locations in data coordinates as a numpy array get_offset_text() Return the axis oﬀsetText as a Text instance get_pickradius() Return the depth of the axis used by the picker get_scale() get_ticklabel_extents(renderer) Get the extents of the tick labels on either side of the axes. get_ticklabels(minor=False) Return a list of Text instances for ticklabels get_ticklines(minor=False) Return the tick lines as a list of Line2D instances get_ticklocs(minor=False) Get the tick locations in data coordinates as a numpy array get_transform() get_units() return the units for axis 518 Chapter 35. matplotlib axis Matplotlib, Release 0.99.1.1 get_view_interval() return the Interval instance for this axis view limits grid(b=None, which=’major’, **kwargs) Set the axis grid on or oﬀ; b is a boolean. Use which = ‘major’ | ‘minor’ to set the grid for major or minor ticks. If b is None and len(kwargs)==0, toggle the grid state. If kwargs are supplied, it is assumed you want the grid on and b will be set to True. kwargs are used to set the line properties of the grids, eg, xax.grid(color=’r’, linestyle=’-‘, linewidth=2) have_units() iter_ticks() Iterate through all of the major and minor ticks. limit_range_for_scale(vmin, vmax) pan(numsteps) Pan numsteps (can be positive or negative) set_clip_path(clippath, transform=None) set_data_interval() Set the axis data limits set_label_coords(x, y, transform=None) Set the coordinates of the label. By default, the x coordinate of the y label is determined by the tick label bounding boxes, but this can lead to poor alignment of multiple ylabels if there are multiple axes. Ditto for the y coodinate of the x label. You can also specify the coordinate system of the label with the transform. If None, the default coordinate system will be the axes coordinate system (0,0) is (left,bottom), (0.5, 0.5) is middle, etc set_label_text(label, fontdict=None, **kwargs) Sets the text value of the axis label ACCEPTS: A string value for the label set_major_formatter(formatter) Set the formatter of the major ticker ACCEPTS: A Formatter instance set_major_locator(locator) Set the locator of the major ticker ACCEPTS: a Locator instance set_minor_formatter(formatter) Set the formatter of the minor ticker ACCEPTS: A Formatter instance 35.1. matplotlib.axis 519 Matplotlib, Release 0.99.1.1 set_minor_locator(locator) Set the locator of the minor ticker ACCEPTS: a Locator instance set_pickradius(pickradius) Set the depth of the axis used by the picker ACCEPTS: a distance in points set_scale(value, **kwargs) set_ticklabels(ticklabels, *args, **kwargs) Set the text values of the tick labels. Return a list of Text instances. Use kwarg minor=True to select minor ticks. ACCEPTS: sequence of strings set_ticks(ticks, minor=False) Set the locations of the tick marks from sequence ticks ACCEPTS: sequence of ﬂoats set_units(u) set the units for axis ACCEPTS: a units tag set_view_interval(vmin, vmax, ignore=False) update_units(data) introspect data for units converter and update the axis.converter instance if necessary. Return True is data is registered for unit conversion zoom(direction) Zoom in/out on axis; if direction is >0 zoom in, else zoom out class Tick(axes, loc, label, size=None, gridOn=None, tick1On=True, tick2On=True, label1On=True, label2On=False, major=True) Bases: matplotlib.artist.Artist Abstract base class for the axis ticks, grid lines and labels 1 refers to the bottom of the plot for xticks and the left for yticks 2 refers to the top of the plot for xticks and the right for yticks Publicly accessible attributes: tick1line a Line2D instance tick2line a Line2D instance gridline a Line2D instance label1 a Text instance label2 a Text instance gridOn a boolean which determines whether to draw the tickline 520 Chapter 35. matplotlib axis Matplotlib, Release 0.99.1.1 tick1On a boolean which determines whether to draw the 1st tickline tick2On a boolean which determines whether to draw the 2nd tickline label1On a boolean which determines whether to draw tick label label2On a boolean which determines whether to draw tick label bbox is the Bound2D bounding box in display coords of the Axes loc is the tick location in data coords size is the tick size in relative, axes coords contains(mouseevent) Test whether the mouse event occured in the Tick marks. This function always returns false. It is more useful to test if the axis as a whole contains the mouse rather than the set of tick marks. draw(artist, renderer, *kl) get_children() get_loc() Return the tick location (data coords) as a scalar get_pad() Get the value of the tick label pad in points get_pad_pixels() get_view_interval() return the view Interval instance for the axis this tick is ticking set_clip_path(clippath, transform=None) Set the artist’s clip path, which may be: •a Patch (or subclass) instance •a Path instance, in which case an optional Transform instance may be provided, which will be applied to the path before using it for clipping. •None, to remove the clipping path For eﬃciency, if the path happens to be an axis-aligned rectangle, this method will set the clipping box to the corresponding rectangle and set the clipping path to None. ACCEPTS: [ (Path, Transform) | Patch | None ] set_label(s) Set the text of ticklabel ACCEPTS: str set_label1(s) Set the text of ticklabel ACCEPTS: str set_label2(s) Set the text of ticklabel2 35.1. matplotlib.axis 521 Matplotlib, Release 0.99.1.1 ACCEPTS: str set_pad(val) Set the tick label pad in points ACCEPTS: ﬂoat set_view_interval(vmin, vmax, ignore=False) class Ticker() class XAxis(axes, pickradius=15) Bases: matplotlib.axis.Axis Init the axis with the parent Axes instance contains(mouseevent) Test whether the mouse event occured in the x axis. get_data_interval() return the Interval instance for this axis data limits get_label_position() Return the label position (top or bottom) get_minpos() get_text_heights(renderer) Returns the amount of space one should reserve for text above and below the axes. Returns a tuple (above, below) get_ticks_position() Return the ticks position (top, bottom, default or unknown) get_view_interval() return the Interval instance for this axis view limits set_data_interval(vmin, vmax, ignore=False) return the Interval instance for this axis data limits set_label_position(position) Set the label position (top or bottom) ACCEPTS: [ ‘top’ | ‘bottom’ ] set_ticks_position(position) Set the ticks position (top, bottom, both, default or none) both sets the ticks to appear on both positions, but does not change the tick labels. default resets the tick positions to the default: ticks on both positions, labels at bottom. none can be used if you don’t want any ticks. ACCEPTS: [ ‘top’ | ‘bottom’ | ‘both’ | ‘default’ | ‘none’ ] set_view_interval(vmin, vmax, ignore=False) tick_bottom() use ticks only on bottom 522 Chapter 35. matplotlib axis Matplotlib, Release 0.99.1.1 tick_top() use ticks only on top class XTick(axes, loc, label, size=None, gridOn=None, tick1On=True, tick2On=True, label1On=True, label2On=False, major=True) Bases: matplotlib.axis.Tick Contains all the Artists needed to make an x tick - the tick line, the label text and the grid line bbox is the Bound2D bounding box in display coords of the Axes loc is the tick location in data coords size is the tick size in relative, axes coords get_data_interval() return the Interval instance for this axis data limits get_minpos() get_view_interval() return the Interval instance for this axis view limits set_view_interval(vmin, vmax, ignore=False) update_position(loc) Set the location of tick in data coords with scalar loc class YAxis(axes, pickradius=15) Bases: matplotlib.axis.Axis Init the axis with the parent Axes instance contains(mouseevent) Test whether the mouse event occurred in the y axis. Returns True | False get_data_interval() return the Interval instance for this axis data limits get_label_position() Return the label position (left or right) get_minpos() get_text_widths(renderer) get_ticks_position() Return the ticks position (left, right, both or unknown) get_view_interval() return the Interval instance for this axis view limits set_data_interval(vmin, vmax, ignore=False) return the Interval instance for this axis data limits set_label_position(position) Set the label position (left or right) ACCEPTS: [ ‘left’ | ‘right’ ] 35.1. matplotlib.axis 523 Matplotlib, Release 0.99.1.1 set_offset_position(position) set_ticks_position(position) Set the ticks position (left, right, both or default) both sets the ticks to appear on both positions, but does not change the tick labels. default resets the tick positions to the default: ticks on both positions, labels on the left. ACCEPTS: [ ‘left’ | ‘right’ | ‘both’ | ‘default’ | ‘none’ ] set_view_interval(vmin, vmax, ignore=False) tick_left() use ticks only on left tick_right() use ticks only on right class YTick(axes, loc, label, size=None, gridOn=None, tick1On=True, tick2On=True, label1On=True, label2On=False, major=True) Bases: matplotlib.axis.Tick Contains all the Artists needed to make a Y tick - the tick line, the label text and the grid line bbox is the Bound2D bounding box in display coords of the Axes loc is the tick location in data coords size is the tick size in relative, axes coords get_data_interval() return the Interval instance for this axis data limits get_minpos() get_view_interval() return the Interval instance for this axis view limits set_view_interval(vmin, vmax, ignore=False) update_position(loc) Set the location of tick in data coords with scalar loc 524 Chapter 35. matplotlib axis CHAPTER THIRTYSIX MATPLOTLIB CBOOK 36.1 matplotlib.cbook A collection of utility functions and classes. Many (but not all) from the Python Cookbook – hence the name cbook class Bunch(**kwds) Often we want to just collect a bunch of stuﬀ together, naming each item of the bunch; a dictionary’s OK for that, but a small do- nothing class is even handier, and prettier to use. Whenever you want to group a few variables: >>> point = Bunch(datum=2, squared=4, coord=12) >>> point.datum By: Alex Martelli From: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52308 class CallbackRegistry(signals) Handle registering and disconnecting for a set of signals and callbacks: signals = ’eat’, ’drink’, ’be merry’ def oneat(x): print ’eat’, x def ondrink(x): print ’drink’, x callbacks = CallbackRegistry(signals) ideat = callbacks.connect(’eat’, oneat) iddrink = callbacks.connect(’drink’, ondrink) #tmp = callbacks.connect(’drunk’, ondrink) # this will raise a ValueError callbacks.process(’drink’, 123) # will call oneat callbacks.process(’eat’, 456) # will call ondrink callbacks.process(’be merry’, 456) # nothing will be called 525 Matplotlib, Release 0.99.1.1 callbacks.disconnect(ideat) callbacks.process(’eat’, 456) # disconnect oneat # nothing will be called signals is a sequence of valid signals connect(s, func) register func to be called when a signal s is generated func will be called disconnect(cid) disconnect the callback registered with callback id cid process(s, *args, **kwargs) process signal s. All of the functions registered to receive callbacks on s will be called with *args and **kwargs class GetRealpathAndStat() class Grouper(init=, ) Bases: object This class provides a lightweight way to group arbitrary objects together into disjoint sets when a full-blown graph data structure would be overkill. Objects can be joined using join(), tested for connectedness using joined(), and all disjoint sets can be retreived by using the object as an iterator. The objects being joined must be hashable and weak-referenceable. For example: >>> class Foo: ... def __init__(self, s): ... self.s = s ... def __repr__(self): ... return self.s ... >>> a, b, c, d, e, f = [Foo(x) for x in ’abcdef’] >>> g = Grouper() >>> g.join(a, b) >>> g.join(b, c) >>> g.join(d, e) >>> list(g) [[d, e], [a, b, c]] >>> g.joined(a, b) True >>> g.joined(a, c) True >>> g.joined(a, d) False clean() Clean dead weak references from the dictionary get_siblings(a) Returns all of the items joined with a, including itself. 526 Chapter 36. matplotlib cbook Matplotlib, Release 0.99.1.1 join(a, *args) Join given arguments into the same set. Accepts one or more arguments. joined(a, b) Returns True if a and b are members of the same set. class Idle(func) Bases: matplotlib.cbook.Scheduler Schedule callbacks when scheduler is idle run() class MemoryMonitor(nmax=20000) clear() plot(i0=0, isub=1, ﬁg=None) report(segments=4) xy(i0=0, isub=1) class Null(*args, **kwargs) Null objects always and reliably “do nothing.” class RingBuffer(size_max) class that implements a not-yet-full buﬀer append(x) append an element at the end of the buﬀer get() Return a list of elements from the oldest to the newest. class Scheduler() Bases: threading.Thread Base class for timeout and idle scheduling stop() class Sorter() Sort by attribute or item Example usage: sort = Sorter() list = [(1, 2), (4, 8), (0, 3)] dict = [{’a’: 3, ’b’: 4}, {’a’: 5, ’b’: 2}, {’a’: 0, ’b’: 0}, {’a’: 9, ’b’: 9}] sort(list) # default sort 36.1. matplotlib.cbook 527 Matplotlib, Release 0.99.1.1 sort(list, 1) sort(dict, ’a’) # sort by index 1 # sort a list of dicts by key ’a’ byAttribute(data, attributename, inplace=1) byItem(data, itemindex=None, inplace=1) sort(data, itemindex=None, inplace=1) class Stack(default=None) Implement a stack where elements can be pushed on and you can move back and forth. But no pop. Should mimic home / back / forward in a browser back() move the position back and return the current element bubble(o) raise o to the top of the stack and return o. o must be in the stack clear() empty the stack empty() forward() move the position forward and return the current element home() push the ﬁrst element onto the top of the stack push(o) push object onto stack at current position - all elements occurring later than the current position are discarded remove(o) remove element o from the stack class Timeout(wait, func) Bases: matplotlib.cbook.Scheduler Schedule recurring events with a wait time in seconds run() class Xlator() Bases: dict All-in-one multiple-string-substitution class Example usage: text = "Larry Wall is the creator of Perl" adict = { "Larry Wall" : "Guido van Rossum", "creator" : "Benevolent Dictator for Life", "Perl" : "Python", 528 Chapter 36. matplotlib cbook Matplotlib, Release 0.99.1.1 } print multiple_replace(adict, text) xlat = Xlator(adict) print xlat.xlat(text) xlat(text) Translate text, returns the modiﬁed text. allequal(seq) Return True if all elements of seq compare equal. If seq is 0 or 1 length, return True allpairs(x) return all possible pairs in sequence x Condensed by Alex Martelli from this thread on c.l.python alltrue(seq) Return True if all elements of seq evaluate to True. If seq is empty, return False. class converter(missing=’Null’, missingval=None) Base class for handling string -> python type with support for missing values is_missing(s) dedent(s) Remove excess indentation from docstring s. Discards any leading blank lines, then removes up to n whitespace characters from each line, where n is the number of leading whitespace characters in the ﬁrst line. It diﬀers from textwrap.dedent in its deletion of leading blank lines and its use of the ﬁrst non-blank line to determine the indentation. It is also faster in most cases. delete_masked_points(*args) Find all masked and/or non-ﬁnite points in a set of arguments, and return the arguments with only the unmasked points remaining. Arguments can be in any of 5 categories: 1.1-D masked arrays 2.1-D ndarrays 3.ndarrays with more than one dimension 4.other non-string iterables 5.anything else The ﬁrst argument must be in one of the ﬁrst four categories; any argument with a length diﬀering from that of the ﬁrst argument (and hence anything in category 5) then will be passed through unchanged. Masks are obtained from all arguments of the correct length in categories 1, 2, and 4; a point is bad if masked in a masked array or if it is a nan or inf. No attempt is made to extract a mask from categories 2, 3, and 4 if np.isfinite() does not yield a Boolean array. 36.1. matplotlib.cbook 529 Matplotlib, Release 0.99.1.1 All input arguments that are not passed unchanged are returned as ndarrays after removing the points or rows corresponding to masks in any of the arguments. A vastly simpler version of this function was originally written as a helper for Axes.scatter(). dict_delall(d, keys) delete all of the keys from the dict d distances_along_curve(X ) This function has been moved to matplotlib.mlab – please import it from there exception_to_str(s=None) finddir(o, match, case=False) return all attributes of o which match string in match. if case is True require an exact case match. flatten(seq, scalarp=<function is_scalar_or_string at 0x282acf8>) this generator ﬂattens nested containers such as >>> l=( (’John’, ’Hunter’), (1,23), [[[[42,(5,23)]]]]) so that >>> for i in flatten(l): print i, John Hunter 1 23 42 5 23 By: Composite of Holger Krekel and Luther Blissett From: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/121294 and Recipe 1.12 in cookbook get_recursive_filelist(args) Recurs all the ﬁles and dirs in args ignoring symbolic links and return the ﬁles as a list of strings get_split_ind(seq, N ) seq is a list of words. Return the index into seq such that: len(’ ’.join(seq[:ind])<=N is_closed_polygon(X ) This function has been moved to matplotlib.mlab – please import it from there is_numlike(obj) return true if obj looks like a number is_scalar(obj) return true if obj is not string like and is not iterable is_scalar_or_string(val) is_sequence_of_strings(obj) Returns true if obj is iterable and contains strings is_string_like(obj) Return True if obj looks like a string 530 Chapter 36. matplotlib cbook Matplotlib, Release 0.99.1.1 is_writable_file_like(obj) return true if obj looks like a ﬁle object with a write method issubclass_safe(x, klass) return issubclass(x, klass) and return False on a TypeError isvector(X ) This function has been moved to matplotlib.mlab – please import it from there iterable(obj) return true if obj is iterable less_simple_linear_interpolation(x, y, xi, extrap=False) This function has been moved to matplotlib.mlab – please import it from there listFiles(root, patterns=’*’, recurse=1, return_folders=0) Recursively list ﬁles from Parmar and Martelli in the Python Cookbook class maxdict(maxsize) Bases: dict A dictionary with a maximum size; this doesn’t override all the relevant methods to contrain size, just setitem, so use with caution mkdirs(newdir, mode=511) make directory newdir recursively, and set mode. Equivalent to > mkdir -p NEWDIR > chmod MODE NEWDIR onetrue(seq) Return True if one element of seq is True. It seq is empty, return False. path_length(X ) This function has been moved to matplotlib.mlab – please import it from there pieces(seq, num=2) Break up the seq into num tuples popall(seq) empty a list print_cycles(objects, outstream=<open show_progress=False) ﬁle ’<stdout>’, mode ’w’ at 0x7f8bﬀ702198>, objects A list of objects to ﬁnd cycles in. It is often useful to pass in gc.garbage to ﬁnd the cycles that are preventing some objects from being garbage collected. outstream The stream for output. show_progress If True, print the number of objects reached as they are found. quad2cubic(q0x, q0y, q1x, q1y, q2x, q2y) This function has been moved to matplotlib.mlab – please import it from there 36.1. matplotlib.cbook 531 Matplotlib, Release 0.99.1.1 recursive_remove(path) report_memory(i=0) return the memory consumed by process reverse_dict(d) reverse the dictionary – may lose data if values are not unique! safe_masked_invalid(x) safezip(*args) make sure args are equal len before zipping class silent_list(type, seq=None) Bases: list override repr when returning a list of matplotlib artists to prevent long, meaningless output. This is meant to be used for a homogeneous list of a give type simple_linear_interpolation(a, steps) soundex(name, len=4) soundex module conforming to Odell-Russell algorithm strip_math(s) remove latex formatting from mathtext to_filehandle(fname, ﬂag=’rU’, return_opened=False) fname can be a ﬁlename or a ﬁle handle. Support for gzipped ﬁles is automatic, if the ﬁlename ends in .gz. ﬂag is a read/write ﬂag for file() class todate(fmt=’%Y-%m-%d’, missing=’Null’, missingval=None) Bases: matplotlib.cbook.converter convert to a date or None use a time.strptime() format string for conversion class todatetime(fmt=’%Y-%m-%d’, missing=’Null’, missingval=None) Bases: matplotlib.cbook.converter convert to a datetime or None use a time.strptime() format string for conversion class tofloat(missing=’Null’, missingval=None) Bases: matplotlib.cbook.converter convert to a ﬂoat or None class toint(missing=’Null’, missingval=None) Bases: matplotlib.cbook.converter convert to an int or None class tostr(missing=’Null’, missingval=”) Bases: matplotlib.cbook.converter convert to string or None 532 Chapter 36. matplotlib cbook Matplotlib, Release 0.99.1.1 unicode_safe(s) unique(x) Return a list of unique elements of x unmasked_index_ranges(mask, compressed=True) Find index ranges where mask is False. mask will be ﬂattened if it is not already 1-D. Returns Nx2 numpy.ndarray with each row the start and stop indices for slices of the compressed numpy.ndarray corresponding to each of N uninterrupted runs of unmasked values. If optional argument compressed is False, it returns the start and stop indices into the original numpy.ndarray, not the compressed numpy.ndarray. Returns None if there are no unmasked values. Example: y = ma.array(np.arange(5), mask = [0,0,1,0,0]) ii = unmasked_index_ranges(ma.getmaskarray(y)) # returns array [[0,2,] [2,4,]] y.compressed()[ii[1,0]:ii[1,1]] # returns array [3,4,] ii = unmasked_index_ranges(ma.getmaskarray(y), compressed=False) # returns array [[0, 2], [3, 5]] y.filled()[ii[1,0]:ii[1,1]] # returns array [3,4,] Prior to the transforms refactoring, this was used to support masked arrays in Line2D. vector_lengths(X, P=2.0, axis=None) This function has been moved to matplotlib.mlab – please import it from there wrap(preﬁx, text, cols) wrap text with preﬁx at length cols 36.1. matplotlib.cbook 533 Matplotlib, Release 0.99.1.1 534 Chapter 36. matplotlib cbook CHAPTER THIRTYSEVEN MATPLOTLIB CM 37.1 matplotlib.cm This module provides a large set of colormaps, functions for registering new colormaps and for getting a colormap by name, and a mixin class for adding color mapping functionality. class ScalarMappable(norm=None, cmap=None) This is a mixin class to support scalar -> RGBA mapping. Handles normalization and colormapping norm is an instance of colors.Normalize or one of its subclasses, used to map luminance to 0-1. cmap is a cm colormap instance, for example cm.jet add_checker(checker) Add an entry to a dictionary of boolean ﬂags that are set to True when the mappable is changed. autoscale() Autoscale the scalar limits on the norm instance using the current array autoscale_None() Autoscale the scalar limits on the norm instance using the current array, changing only limits that are None changed() Call this whenever the mappable is changed to notify all the callbackSM listeners to the ‘changed’ signal check_update(checker) If mappable has changed since the last check, return True; else return False get_array() Return the array get_clim() return the min, max of the color limits for image scaling get_cmap() return the colormap set_array(A) Set the image array from numpy array A 535 Matplotlib, Release 0.99.1.1 set_clim(vmin=None, vmax=None) set the norm limits for image scaling; if vmin is a length2 sequence, interpret it as (vmin, vmax) which is used to support setp ACCEPTS: a length 2 sequence of ﬂoats set_cmap(cmap) set the colormap for luminance data ACCEPTS: a colormap or registered colormap name set_colorbar(im, ax) set the colorbar image and axes associated with mappable set_norm(norm) set the normalization instance to_rgba(x, alpha=1.0, bytes=False) Return a normalized rgba array corresponding to x. If x is already an rgb array, insert alpha; if it is already rgba, return it unchanged. If bytes is True, return rgba as 4 uint8s instead of 4 ﬂoats. get_cmap(name=None, lut=None) Get a colormap instance, defaulting to rc values if name is None. Colormaps added with register_cmap() take precedence over builtin colormaps. If name is a colors.Colormap instance, it will be returned. If lut is not None it must be an integer giving the number of entries desired in the lookup table, and name must be a standard mpl colormap name with a corresponding data dictionary in datad. register_cmap(name=None, cmap=None, data=None, lut=None) Add a colormap to the set recognized by get_cmap(). It can be used in two ways: register_cmap(name=’swirly’, cmap=swirly_cmap) register_cmap(name=’choppy’, data=choppydata, lut=128) In the ﬁrst case, cmap must be a colors.Colormap instance. The name is optional; if absent, the name will be the name attribute of the cmap. In the second case, the three arguments are passed to the colors.LinearSegmentedColormap initializer, and the resulting colormap is registered. revcmap(data) 536 Chapter 37. matplotlib cm CHAPTER THIRTYEIGHT MATPLOTLIB COLLECTIONS 38.1 matplotlib.collections Classes for the eﬃcient drawing of large collections of objects that share most properties, e.g. a large number of line segments or polygons. The classes are not meant to be as ﬂexible as their single element counterparts (e.g. you may not be able to select all line styles) but they are meant to be fast for common use cases (e.g. a bunch of solid line segemnts) class AsteriskPolygonCollection(numsides, rotation=0, sizes=(1, ), **kwargs) Bases: matplotlib.collections.RegularPolyCollection Draw a collection of regular asterisks with numsides points. numsides the number of sides of the polygon rotation the rotation of the polygon in radians sizes gives the area of the circle circumscribing the regular polygon in points^2 Valid Collection keyword arguments: 537 Matplotlib, Release 0.99.1.1 • edgecolors: None • facecolors: None • linewidths: None • antialiaseds: None • oﬀsets: None • transOﬀset: transforms.IdentityTransform() • norm: None (optional for matplotlib.cm.ScalarMappable) • cmap: None (optional for matplotlib.cm.ScalarMappable) oﬀsets and transOﬀset are used to translate the patch after rendering (default no oﬀsets) If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. Example: see examples/dynamic_collection.py for complete example: offsets = np.random.rand(20,2) facecolors = [cm.jet(x) for x in np.random.rand(20)] black = (0,0,0,1) collection = RegularPolyCollection( numsides=5, # a pentagon rotation=0, sizes=(50,), facecolors = facecolors, edgecolors = (black,), linewidths = (1,), offsets = offsets, transOffset = ax.transData, ) class BrokenBarHCollection(xranges, yrange, **kwargs) Bases: matplotlib.collections.PolyCollection A collection of horizontal bars spanning yrange with a sequence of xranges. xranges sequence of (xmin, xwidth) yrange ymin, ywidth Valid Collection keyword arguments: • edgecolors: None • facecolors: None • linewidths: None • antialiaseds: None • oﬀsets: None • transOﬀset: transforms.IdentityTransform() 538 Chapter 38. matplotlib collections Matplotlib, Release 0.99.1.1 • norm: None (optional for matplotlib.cm.ScalarMappable) • cmap: None (optional for matplotlib.cm.ScalarMappable) oﬀsets and transOﬀset are used to translate the patch after rendering (default no oﬀsets) If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. static span_where(x, ymin, ymax, where, **kwargs) Create a BrokenBarHCollection to plot horizontal bars from over the regions in x where where is True. The bars range on the y-axis from ymin to ymax A BrokenBarHCollection is returned. kwargs are passed on to the collection. class CircleCollection(sizes, **kwargs) Bases: matplotlib.collections.Collection A collection of circles, drawn using splines. sizes Gives the area of the circle in points^2 Valid Collection keyword arguments: •edgecolors: None •facecolors: None •linewidths: None •antialiaseds: None •oﬀsets: None •transOﬀset: transforms.IdentityTransform() •norm: None (optional for matplotlib.cm.ScalarMappable) •cmap: None (optional for matplotlib.cm.ScalarMappable) oﬀsets and transOﬀset are used to translate the patch after rendering (default no oﬀsets) If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. draw(renderer) get_paths() get_sizes() return sizes of circles class Collection(edgecolors=None, facecolors=None, linewidths=None, linestyles=’solid’, antialiaseds=None, oﬀsets=None, transOﬀset=None, norm=None, cmap=None, pickradius=5.0, urls=None, **kwargs) Bases: matplotlib.artist.Artist, matplotlib.cm.ScalarMappable Base class for Collections. Must be subclassed to be usable. 38.1. matplotlib.collections 539 Matplotlib, Release 0.99.1.1 All properties in a collection must be sequences or scalars; if scalars, they will be converted to sequences. The property of the ith element of the collection is: prop[i % len(props)] Keyword arguments and default values: •edgecolors: None •facecolors: None •linewidths: None •antialiaseds: None •oﬀsets: None •transOﬀset: transforms.IdentityTransform() •norm: None (optional for matplotlib.cm.ScalarMappable) •cmap: None (optional for matplotlib.cm.ScalarMappable) oﬀsets and transOﬀset are used to translate the patch after rendering (default no oﬀsets). If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. The use of ScalarMappable is optional. If the ScalarMappable matrix _A is not None (ie a call to set_array has been made), at draw time a call to scalar mappable will be made to set the face colors. Create a Collection %(Collection)s contains(mouseevent) Test whether the mouse event occurred in the collection. Returns True | False, dict(ind=itemlist), where every item in itemlist contains the event. draw(artist, renderer, *kl) get_dashes() get_datalim(transData) get_edgecolor() get_edgecolors() get_facecolor() get_facecolors() get_linestyle() get_linestyles() get_linewidth() get_linewidths() 540 Chapter 38. matplotlib collections Matplotlib, Release 0.99.1.1 get_offsets() Return the oﬀsets for the collection. get_paths() get_pickradius() get_transforms() get_urls() get_window_extent(renderer) set_alpha(alpha) Set the alpha tranparencies of the collection. alpha must be a ﬂoat. ACCEPTS: ﬂoat set_antialiased(aa) Set the antialiasing state for rendering. ACCEPTS: Boolean or sequence of booleans set_antialiaseds(aa) alias for set_antialiased set_color(c) Set both the edgecolor and the facecolor. ACCEPTS: matplotlib color arg or sequence of rgba tuples See Also: set_facecolor(), set_edgecolor() For setting the edge or face color individually. set_dashes(ls) alias for set_linestyle set_edgecolor(c) Set the edgecolor(s) of the collection. c can be a matplotlib color arg (all patches have same color), or a sequence of rgba tuples; if it is a sequence the patches will cycle through the sequence. If c is ‘face’, the edge color will always be the same as the face color. If it is ‘none’, the patch boundary will not be drawn. ACCEPTS: matplotlib color arg or sequence of rgba tuples set_edgecolors(c) alias for set_edgecolor set_facecolor(c) Set the facecolor(s) of the collection. c can be a matplotlib color arg (all patches have same color), or a sequence of rgba tuples; if it is a sequence the patches will cycle through the sequence. If c is ‘none’, the patch will not be ﬁlled. 38.1. matplotlib.collections 541 Matplotlib, Release 0.99.1.1 ACCEPTS: matplotlib color arg or sequence of rgba tuples set_facecolors(c) alias for set_facecolor set_linestyle(ls) Set the linestyle(s) for the collection. ACCEPTS: [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] set_linestyles(ls) alias for set_linestyle set_linewidth(lw) Set the linewidth(s) for the collection. lw can be a scalar or a sequence; if it is a sequence the patches will cycle through the sequence ACCEPTS: ﬂoat or sequence of ﬂoats set_linewidths(lw) alias for set_linewidth set_lw(lw) alias for set_linewidth set_offsets(oﬀsets) Set the oﬀsets for the collection. oﬀsets can be a scalar or a sequence. ACCEPTS: ﬂoat or sequence of ﬂoats set_pickradius(pickradius) set_urls(urls) update_from(other) copy properties from other to self update_scalarmappable() If the scalar mappable array is not none, update colors from scalar data class EllipseCollection(widths, heights, angles, units=’points’, **kwargs) Bases: matplotlib.collections.Collection A collection of ellipses, drawn using splines. widths: sequence half-lengths of ﬁrst axes (e.g., semi-major axis lengths) heights: sequence half-lengths of second axes angles: sequence angles of ﬁrst axes, degrees CCW from the X-axis units: [’points’ | ‘inches’ | ‘dots’ | ‘width’ | ‘height’ | ‘x’ | ‘y’] units in which majors and minors are given; ‘width’ and ‘height’ refer to the dimensions of the axes, while ‘x’ and ‘y’ refer to the oﬀsets data units. Additional kwargs inherited from the base Collection: Valid Collection keyword arguments: 542 Chapter 38. matplotlib collections Matplotlib, Release 0.99.1.1 •edgecolors: None •facecolors: None •linewidths: None •antialiaseds: None •oﬀsets: None •transOﬀset: transforms.IdentityTransform() •norm: None (optional for matplotlib.cm.ScalarMappable) •cmap: None (optional for matplotlib.cm.ScalarMappable) oﬀsets and transOﬀset are used to translate the patch after rendering (default no oﬀsets) If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. draw(renderer) get_paths() set_transforms() class LineCollection(segments, linewidths=None, colors=None, antialiaseds=None, linestyles=’solid’, oﬀsets=None, transOﬀset=None, norm=None, cmap=None, pickradius=5, **kwargs) Bases: matplotlib.collections.Collection All parameters must be sequences or scalars; if scalars, they will be converted to sequences. The property of the ith line segment is: prop[i % len(props)] i.e., the properties cycle if the len of props is less than the number of segments. segments a sequence of (line0, line1, line2), where: linen = (x0, y0), (x1, y1), ... (xm, ym) or the equivalent numpy array with two columns. Each line can be a diﬀerent length. colors must be a sequence of RGBA tuples (eg arbitrary color strings, etc, not allowed). antialiaseds must be a sequence of ones or zeros linestyles [ ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ] a string or dash tuple. The dash tuple is: (offset, onoffseq), where onoﬀseq is an even length tuple of on and oﬀ ink in points. 38.1. matplotlib.collections 543 Matplotlib, Release 0.99.1.1 If linewidths, colors, or antialiaseds is None, they default to their rcParams setting, in sequence form. If oﬀsets and transOﬀset are not None, then oﬀsets are transformed by transOﬀset and applied after the segments have been transformed to display coordinates. If oﬀsets is not None but transOﬀset is None, then the oﬀsets are added to the segments before any transformation. In this case, a single oﬀset can be speciﬁed as: offsets=(xo,yo) and this value will be added cumulatively to each successive segment, so as to produce a set of successively oﬀset curves. norm None (optional for matplotlib.cm.ScalarMappable) cmap None (optional for matplotlib.cm.ScalarMappable) pickradius is the tolerance for mouse clicks picking a line. The default is 5 pt. The use of ScalarMappable is optional. If the ScalarMappable matrix _A is not None (ie a call to set_array() has been made), at draw time a call to scalar mappable will be made to set the colors. color(c) Set the color(s) of the line collection. c can be a matplotlib color arg (all patches have same color), or a sequence or rgba tuples; if it is a sequence the patches will cycle through the sequence ACCEPTS: matplotlib color arg or sequence of rgba tuples get_color() get_colors() get_paths() set_color(c) Set the color(s) of the line collection. c can be a matplotlib color arg (all patches have same color), or a sequence or rgba tuples; if it is a sequence the patches will cycle through the sequence. ACCEPTS: matplotlib color arg or sequence of rgba tuples set_segments(segments) set_verts(segments) class PatchCollection(patches, match_original=False, **kwargs) Bases: matplotlib.collections.Collection A generic collection of patches. This makes it easier to assign a color map to a heterogeneous collection of patches. This also may improve plotting speed, since PatchCollection will draw faster than a large number of patches. patches a sequence of Patch objects. This list may include a heterogeneous assortment of diﬀerent patch types. 544 Chapter 38. matplotlib collections Matplotlib, Release 0.99.1.1 match_original If True, use the colors and linewidths of the original patches. If False, new colors may be assigned by providing the standard collection arguments, facecolor, edgecolor, linewidths, norm or cmap. If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. The use of ScalarMappable is optional. If the ScalarMappable matrix _A is not None (ie a call to set_array has been made), at draw time a call to scalar mappable will be made to set the face colors. get_paths() class PolyCollection(verts, sizes=None, closed=True, **kwargs) Bases: matplotlib.collections.Collection verts is a sequence of ( verts0, verts1, ...) where verts_i is a sequence of xy tuples of vertices, or an equivalent numpy array of shape (nv, 2). sizes is None (default) or a sequence of ﬂoats that scale the corresponding verts_i. The scaling is applied before the Artist master transform; if the latter is an identity transform, then the overall scaling is such that if verts_i specify a unit square, then sizes_i is the area of that square in points^2. If len(sizes) < nv, the additional values will be taken cyclically from the array. closed, when True, will explicitly close the polygon. Valid Collection keyword arguments: •edgecolors: None •facecolors: None •linewidths: None •antialiaseds: None •oﬀsets: None •transOﬀset: transforms.IdentityTransform() •norm: None (optional for matplotlib.cm.ScalarMappable) •cmap: None (optional for matplotlib.cm.ScalarMappable) oﬀsets and transOﬀset are used to translate the patch after rendering (default no oﬀsets) If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. draw(renderer) get_paths() set_verts(verts, closed=True) This allows one to delay initialization of the vertices. class QuadMesh(meshWidth, meshHeight, coordinates, showedges, antialiased=True) Bases: matplotlib.collections.Collection Class for the eﬃcient drawing of a quadrilateral mesh. 38.1. matplotlib.collections 545 Matplotlib, Release 0.99.1.1 A quadrilateral mesh consists of a grid of vertices. The dimensions of this array are (meshWidth + 1, meshHeight + 1). Each vertex in the mesh has a diﬀerent set of “mesh coordinates” representing its position in the topology of the mesh. For any values (m, n) such that 0 <= m <= meshWidth and 0 <= n <= meshHeight, the vertices at mesh coordinates (m, n), (m, n + 1), (m + 1, n + 1), and (m + 1, n) form one of the quadrilaterals in the mesh. There are thus (meshWidth * meshHeight) quadrilaterals in the mesh. The mesh need not be regular and the polygons need not be convex. A quadrilateral mesh is represented by a (2 x ((meshWidth + 1) * (meshHeight + 1))) numpy array coordinates, where each row is the x and y coordinates of one of the vertices. To deﬁne the function that maps from a data point to its corresponding color, use the set_cmap() method. Each of these arrays is indexed in row-major order by the mesh coordinates of the vertex (or the mesh coordinates of the lower left vertex, in the case of the colors). For example, the ﬁrst entry in coordinates is the coordinates of the vertex at mesh coordinates (0, 0), then the one at (0, 1), then at (0, 2) .. (0, meshWidth), (1, 0), (1, 1), and so on. static convert_mesh_to_paths(meshWidth, meshHeight, coordinates) Converts a given mesh into a sequence of matplotlib.path.Path objects for easier rendering by backends that do not directly support quadmeshes. This function is primarily of use to backend implementers. draw(artist, renderer, *kl) get_datalim(transData) get_paths(dataTrans=None) class RegularPolyCollection(numsides, rotation=0, sizes=(1, ), **kwargs) Bases: matplotlib.collections.Collection Draw a collection of regular polygons with numsides. numsides the number of sides of the polygon rotation the rotation of the polygon in radians sizes gives the area of the circle circumscribing the regular polygon in points^2 Valid Collection keyword arguments: • edgecolors: None • facecolors: None • linewidths: None • antialiaseds: None • oﬀsets: None • transOﬀset: transforms.IdentityTransform() • norm: None (optional for matplotlib.cm.ScalarMappable) • cmap: None (optional for matplotlib.cm.ScalarMappable) oﬀsets and transOﬀset are used to translate the patch after rendering (default no oﬀsets) 546 Chapter 38. matplotlib collections Matplotlib, Release 0.99.1.1 If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. Example: see examples/dynamic_collection.py for complete example: offsets = np.random.rand(20,2) facecolors = [cm.jet(x) for x in np.random.rand(20)] black = (0,0,0,1) collection = RegularPolyCollection( numsides=5, # a pentagon rotation=0, sizes=(50,), facecolors = facecolors, edgecolors = (black,), linewidths = (1,), offsets = offsets, transOffset = ax.transData, ) draw(artist, renderer, *kl) get_numsides() get_paths() get_rotation() get_sizes() class StarPolygonCollection(numsides, rotation=0, sizes=(1, ), **kwargs) Bases: matplotlib.collections.RegularPolyCollection Draw a collection of regular stars with numsides points. numsides the number of sides of the polygon rotation the rotation of the polygon in radians sizes gives the area of the circle circumscribing the regular polygon in points^2 Valid Collection keyword arguments: • edgecolors: None • facecolors: None • linewidths: None • antialiaseds: None • oﬀsets: None • transOﬀset: transforms.IdentityTransform() • norm: None (optional for matplotlib.cm.ScalarMappable) • cmap: None (optional for matplotlib.cm.ScalarMappable) 38.1. matplotlib.collections 547 Matplotlib, Release 0.99.1.1 oﬀsets and transOﬀset are used to translate the patch after rendering (default no oﬀsets) If any of edgecolors, facecolors, linewidths, antialiaseds are None, they default to their matplotlib.rcParams patch setting, in sequence form. Example: see examples/dynamic_collection.py for complete example: offsets = np.random.rand(20,2) facecolors = [cm.jet(x) for x in np.random.rand(20)] black = (0,0,0,1) collection = RegularPolyCollection( numsides=5, # a pentagon rotation=0, sizes=(50,), facecolors = facecolors, edgecolors = (black,), linewidths = (1,), offsets = offsets, transOffset = ax.transData, ) 548 Chapter 38. matplotlib collections CHAPTER THIRTYNINE MATPLOTLIB COLORBAR 39.1 matplotlib.colorbar Colorbar toolkit with two classes and a function: ColorbarBase the base class with full colorbar drawing functionality. It can be used as-is to make a colorbar for a given colormap; a mappable object (e.g., image) is not needed. Colorbar the derived class for use with images or contour plots. make_axes() a function for resizing an axes and adding a second axes suitable for a colorbar The colorbar() method uses make_axes() and Colorbar; the colorbar() function is a thin wrapper over colorbar(). class Colorbar(ax, mappable, **kw) Bases: matplotlib.colorbar.ColorbarBase add_lines(CS) Add the lines from a non-ﬁlled ContourSet to the colorbar. update_bruteforce(mappable) Manually change any contour line colors. This is called when the image or contour plot to which this colorbar belongs is changed. class ColorbarBase(ax, cmap=None, norm=None, alpha=1.0, values=None, boundaries=None, orientation=’vertical’, extend=’neither’, spacing=’uniform’, ticks=None, format=None, drawedges=False, ﬁlled=True) Bases: matplotlib.cm.ScalarMappable Draw a colorbar in an existing axes. This is a base class for the Colorbar class, which is the basis for the colorbar() method and pylab function. It is also useful by itself for showing a colormap. If the cmap kwarg is given but boundaries and values are left as None, then the colormap will be displayed on a 0-1 scale. To show the under- and over-value colors, specify the norm as: colors.Normalize(clip=False) 549 Matplotlib, Release 0.99.1.1 To show the colors versus index instead of on the 0-1 scale, use: norm=colors.NoNorm. Useful attributes: ax the Axes instance in which the colorbar is drawn lines a LineCollection if lines were drawn, otherwise None dividers a LineCollection if drawedges is True, otherwise None Useful public methods are set_label() and add_lines(). add_lines(levels, colors, linewidths) Draw lines on the colorbar. draw_all() Calculate any free parameters based on the current cmap and norm, and do all the drawing. set_alpha(alpha) set_label(label, **kw) Label the long axis of the colorbar make_axes(parent, **kw) Resize and reposition a parent axes, and return a child axes suitable for a colorbar: cax, kw = make_axes(parent, **kw) Keyword arguments may include the following (with defaults): orientation ‘vertical’ or ‘horizontal’ Property orientation fraction pad shrink aspect Description vertical or horizontal 0.15; fraction of original axes to use for colorbar 0.05 if vertical, 0.15 if horizontal; fraction of original axes between colorbar and new image axes 1.0; fraction by which to shrink the colorbar 20; ratio of long to short dimensions All but the ﬁrst of these are stripped from the input kw set. Returns (cax, kw), the child axes and the reduced kw dictionary. 550 Chapter 39. matplotlib colorbar CHAPTER FORTY MATPLOTLIB COLORS 40.1 matplotlib.colors A module for converting numbers or color arguments to RGB or RGBA RGB and RGBA are sequences of, respectively, 3 or 4 ﬂoats in the range 0-1. This module includes functions and classes for color speciﬁcation conversions, and for mapping numbers to colors in a 1-D array of colors called a colormap. Colormapping typically involves two steps: a data array is ﬁrst mapped onto the range 0-1 using an instance of Normalize or of a subclass; then this number in the 0-1 range is mapped to a color using an instance of a subclass of Colormap. Two are provided here: LinearSegmentedColormap, which is used to generate all the built-in colormap instances, but is also useful for making custom colormaps, and ListedColormap, which is used for generating a custom colormap from a list of color speciﬁcations. The module also provides a single instance, colorConverter, of the ColorConverter class providing methods for converting single color speciﬁcations or sequences of them to RGB or RGBA. Commands which take color arguments can use several formats to specify the colors. For the basic builtin colors, you can use a single letter • b : blue • g : green • r : red • c : cyan • m : magenta • y : yellow • k : black • w : white Gray shades can be given as a string encoding a ﬂoat in the 0-1 range, e.g.: color = ’0.75’ 551 Matplotlib, Release 0.99.1.1 For a greater range of colors, you have two options. You can specify the color using an html hex string, as in: color = ’#eeefff’ or you can pass an R , G , B tuple, where each of R , G , B are in the range [0,1]. Finally, legal html names for colors, like ‘red’, ‘burlywood’ and ‘chartreuse’ are supported. class BoundaryNorm(boundaries, ncolors, clip=False) Bases: matplotlib.colors.Normalize Generate a colormap index based on discrete intervals. Unlike Normalize or LogNorm, BoundaryNorm maps values to integers instead of to the interval 0-1. Mapping to the 0-1 interval could have been done via piece-wise linear interpolation, but using integers seems simpler, and reduces the number of conversions back and forth between integer and ﬂoating point. boundaries a monotonically increasing sequence ncolors number of colors in the colormap to be used If: b[i] <= v < b[i+1] then v is mapped to color j; as i varies from 0 to len(boundaries)-2, j goes from 0 to ncolors-1. Out-of-range values are mapped to -1 if low and ncolors if high; these are converted to valid indices by Colormap.__call__() . inverse(value) class ColorConverter() Provides methods for converting color speciﬁcations to RGB or RGBA Caching is used for more eﬃcient conversion upon repeated calls with the same argument. Ordinarily only the single instance instantiated in this module, colorConverter, is needed. to_rgb(arg) Returns an RGB tuple of three ﬂoats from 0-1. arg can be an RGB or RGBA sequence or a string in any of several forms: 1.a letter from the set ‘rgbcmykw’ 2.a hex color string, like ‘#00FFFF’ 3.a standard name, like ‘aqua’ 4.a ﬂoat, like ‘0.4’, indicating gray on a 0-1 scale if arg is RGBA, the A will simply be discarded. 552 Chapter 40. matplotlib colors Matplotlib, Release 0.99.1.1 to_rgba(arg, alpha=None) Returns an RGBA tuple of four ﬂoats from 0-1. For acceptable values of arg, see to_rgb(). In addition, if arg is “none” (case-insensitive), then (0,0,0,0) will be returned. If arg is an RGBA sequence and alpha is not None, alpha will replace the original A. to_rgba_array(c, alpha=None) Returns a numpy array of RGBA tuples. Accepts a single mpl color spec or a sequence of specs. Special case to handle “no color”: if c is “none” (case-insensitive), then an empty array will be returned. Same for an empty list. class Colormap(name, N=256) Base class for all scalar to rgb mappings Important methods: •set_bad() •set_under() •set_over() Public class attributes: N : number of rgb quantization levels name : name of colormap is_gray() set_bad(color=’k’, alpha=1.0) Set color to be used for masked values. set_over(color=’k’, alpha=1.0) Set color to be used for high out-of-range values. Requires norm.clip = False set_under(color=’k’, alpha=1.0) Set color to be used for low out-of-range values. Requires norm.clip = False class LightSource(azdeg=315, altdeg=45, hsv_max_sat=0) Bases: object hsv_min_val=0, hsv_max_val=1, hsv_min_sat=1, Create a light source coming from the speciﬁed azimuth and elevation. Angles are in degrees, with the azimuth measured clockwise from north and elevation up from the zero plane of the surface. The shade() is used to produce rgb values for a shaded relief image given a data array. Specify the azimuth (measured clockwise from south) and altitude (measured up from the plane of the surface) of the light source in degrees. The color of the resulting image will be darkened by moving the (s,v) values (in hsv colorspace) toward (hsv_min_sat, hsv_min_val) in the shaded regions, or lightened by sliding (s,v) toward (hsv_max_sat hsv_max_val) in regions that are illuminated. The default extremes are chose so that completely shaded points are nearly black (s = 1, v = 0) and completely illuminated points are nearly white (s = 0, v = 1). 40.1. matplotlib.colors 553 Matplotlib, Release 0.99.1.1 shade(data, cmap) Take the input data array, convert to HSV values in the given colormap, then adjust those color values to given the impression of a shaded relief map with a speciﬁed light source. RGBA values are returned, which can then be used to plot the shaded image with imshow. class LinearSegmentedColormap(name, segmentdata, N=256) Bases: matplotlib.colors.Colormap Colormap objects based on lookup tables using linear segments. The lookup table is generated using linear interpolation for each primary color, with the 0-1 domain divided into any number of segments. Create color map from linear mapping segments segmentdata argument is a dictionary with a red, green and blue entries. Each entry should be a list of x, y0, y1 tuples, forming rows in a table. Example: suppose you want red to increase from 0 to 1 over the bottom half, green to do the same over the middle half, and blue over the top half. Then you would use: cdict = {’red’: [(0.0, (0.5, (1.0, 0.0, 0.0), 1.0, 1.0), 1.0, 1.0)], ’green’: [(0.0, (0.25, (0.75, (1.0, 0.0, 0.0, 1.0, 1.0, ’blue’: 0.0, 0.0), 0.0, 0.0), 1.0, 1.0)]} [(0.0, (0.5, (1.0, 0.0), 0.0), 1.0), 1.0)], Each row in the table for a given color is a sequence of x, y0, y1 tuples. In each sequence, x must increase monotonically from 0 to 1. For any input value z falling between x[i] and x[i+1], the output value of a given color will be linearly interpolated between y1[i] and y0[i+1]: row i: x row i+1: x y0 y1 / / y0 y1 Hence y0 in the ﬁrst row and y1 in the last row are never used. See Also: LinearSegmentedColormap.from_list() Static method; factory function for generating a smoothly-varying LinearSegmentedColormap. makeMappingArray() For information about making a mapping array. 554 Chapter 40. matplotlib colors Matplotlib, Release 0.99.1.1 static from_list(name, colors, N=256) Make a linear segmented colormap with name from a sequence of colors which evenly transitions from colors[0] at val=0 to colors[-1] at val=1. N is the number of rgb quantization levels. class ListedColormap(colors, name=’from_list’, N=None) Bases: matplotlib.colors.Colormap Colormap object generated from a list of colors. This may be most useful when indexing directly into a colormap, but it can also be used to generate special colormaps for ordinary mapping. Make a colormap from a list of colors. colors a list of matplotlib color speciﬁcations, or an equivalent Nx3 ﬂoating point array (N rgb values) name a string to identify the colormap N the number of entries in the map. The default is None, in which case there is one colormap entry for each element in the list of colors. If: N < len(colors) the list will be truncated at N. If: N > len(colors) the list will be extended by repetition. class LogNorm(vmin=None, vmax=None, clip=False) Bases: matplotlib.colors.Normalize Normalize a given value to the 0-1 range on a log scale If vmin or vmax is not given, they are taken from the input’s minimum and maximum value respectively. If clip is True and the given value falls outside the range, the returned value will be 0 or 1, whichever is closer. Returns 0 if: vmin==vmax Works with scalars or arrays, including masked arrays. If clip is True, masked values are set to 1; otherwise they remain masked. Clipping silently defeats the purpose of setting the over, under, and masked colors in the colormap, so it is likely to lead to surprises; therefore the default is clip = False. inverse(value) class NoNorm(vmin=None, vmax=None, clip=False) Bases: matplotlib.colors.Normalize Dummy replacement for Normalize, for the case where we want to use indices directly in a ScalarMappable . 40.1. matplotlib.colors 555 Matplotlib, Release 0.99.1.1 If vmin or vmax is not given, they are taken from the input’s minimum and maximum value respectively. If clip is True and the given value falls outside the range, the returned value will be 0 or 1, whichever is closer. Returns 0 if: vmin==vmax Works with scalars or arrays, including masked arrays. If clip is True, masked values are set to 1; otherwise they remain masked. Clipping silently defeats the purpose of setting the over, under, and masked colors in the colormap, so it is likely to lead to surprises; therefore the default is clip = False. inverse(value) class Normalize(vmin=None, vmax=None, clip=False) Normalize a given value to the 0-1 range If vmin or vmax is not given, they are taken from the input’s minimum and maximum value respectively. If clip is True and the given value falls outside the range, the returned value will be 0 or 1, whichever is closer. Returns 0 if: vmin==vmax Works with scalars or arrays, including masked arrays. If clip is True, masked values are set to 1; otherwise they remain masked. Clipping silently defeats the purpose of setting the over, under, and masked colors in the colormap, so it is likely to lead to surprises; therefore the default is clip = False. autoscale(A) Set vmin, vmax to min, max of A. autoscale_None(A) autoscale only None-valued vmin or vmax inverse(value) scaled() return true if vmin and vmax set hex2color(s) Take a hex string s and return the corresponding rgb 3-tuple Example: #efefef -> (0.93725, 0.93725, 0.93725) hsv_to_rgb(hsv) convert hsv values in a numpy array to rgb values both input and output arrays have shape (M,N,3) is_color_like(c) Return True if c can be converted to RGB makeMappingArray(N, data) Create an N -element 1-d lookup table data represented by a list of x,y0,y1 mapping correspondences. Each element in this list represents how a value between 0 and 1 (inclusive) represented by x is mapped to a corresponding value between 0 and 1 (inclusive). The two values of y are to allow for discontinuous mapping functions (say as 556 Chapter 40. matplotlib colors Matplotlib, Release 0.99.1.1 might be found in a sawtooth) where y0 represents the value of y for values of x <= to that given, and y1 is the value to be used for x > than that given). The list must start with x=0, end with x=1, and all values of x must be in increasing order. Values between the given mapping points are determined by simple linear interpolation. The function returns an array “result” where result[x*(N-1)] gives the closest value for values of x between 0 and 1. no_norm alias of NoNorm normalize alias of Normalize rgb2hex(rgb) Given a len 3 rgb tuple of 0-1 ﬂoats, return the hex string rgb_to_hsv(arr) convert rgb values in a numpy array to hsv values input and output arrays should have shape (M,N,3) 40.1. matplotlib.colors 557 Matplotlib, Release 0.99.1.1 558 Chapter 40. matplotlib colors CHAPTER FORTYONE MATPLOTLIB DATES 41.1 matplotlib.dates Matplotlib provides sophisticated date plotting capabilities, standing on the shoulders of python datetime, the add-on modules pytz and dateutils. datetime objects are converted to ﬂoating point numbers which represent the number of days since 0001-01-01 UTC. The helper functions date2num(), num2date() and drange() are used to facilitate easy conversion to and from datetime and numeric ranges. A wide range of speciﬁc and general purpose date tick locators and formatters are provided in this module. See matplotlib.ticker for general information on tick locators and formatters. These are described below. All the matplotlib date converters, tickers and formatters are timezone aware, and the default timezone is given by the timezone parameter in your matplotlibrc ﬁle. If you leave out a tz timezone instance, the default from your rc ﬁle will be assumed. If you want to use a custom time zone, pass a pytz.timezone instance with the tz keyword argument to num2date(), plot_date(), and any custom date tickers or locators you create. See pytz for information on pytz and timezone handling. The dateutil module provides additional code to handle date ticking, making it easy to place ticks on any 559 Matplotlib, Release 0.99.1.1 kinds of dates. See examples below. 41.1.1 Date tickers Most of the date tickers can locate single or multiple values. For example: # tick on mondays every week loc = WeekdayLocator(byweekday=MO, tz=tz) # tick on mondays and saturdays loc = WeekdayLocator(byweekday=(MO, SA)) In addition, most of the constructors take an interval argument: # tick on mondays every second week loc = WeekdayLocator(byweekday=MO, interval=2) The rrule locator allows completely general date ticking: # tick every 5th easter rule = rrulewrapper(YEARLY, byeaster=1, interval=5) loc = RRuleLocator(rule) Here are all the date tickers: • MinuteLocator: locate minutes • HourLocator: locate hours • DayLocator: locate specifed days of the month • WeekdayLocator: Locate days of the week, eg MO, TU • MonthLocator: locate months, eg 7 for july • YearLocator: locate years that are multiples of base • RRuleLocator: locate using a matplotlib.dates.rrulewrapper. The rrulewrapper is a simple wrapper around a dateutils.rrule (dateutil) which allow almost arbitrary date tick speciﬁcations. See rrule example. • AutoDateLocator: On autoscale, this class picks the best MultipleDateLocator to set the view limits and the tick locations. 41.1.2 Date formatters Here all all the date formatters: • AutoDateFormatter: attempts to ﬁgure out the best format to use. This is most useful when used with the AutoDateLocator. • DateFormatter: use strftime() format strings 560 Chapter 41. matplotlib dates Matplotlib, Release 0.99.1.1 • IndexDateFormatter: date plots with implicit x indexing. date2num(d) d is either a datetime instance or a sequence of datetimes. Return value is a ﬂoating point number (or sequence of ﬂoats) which gives number of days (fraction part represents hours, minutes, seconds) since 0001-01-01 00:00:00 UTC. num2date(x, tz=None) x is a ﬂoat value which gives number of days (fraction part represents hours, minutes, seconds) since 0001-01-01 00:00:00 UTC. Return value is a datetime instance in timezone tz (default to rcparams TZ value). If x is a sequence, a sequence of datetime objects will be returned. drange(dstart, dend, delta) Return a date range as ﬂoat Gregorian ordinals. dstart and dend are datetime instances. delta is a datetime.timedelta instance. epoch2num(e) Convert an epoch or sequence of epochs to the new date format, that is days since 0001. num2epoch(d) Convert days since 0001 to epoch. d can be a number or sequence. mx2num(mxdates) Convert mx datetime instance (or sequence of mx instances) to the new date format. class DateFormatter(fmt, tz=None) Bases: matplotlib.ticker.Formatter Tick location is seconds since the epoch. Use a strftime() format string. Python only supports datetime strftime() formatting for years greater than 1900. Thanks to Andrew Dalke, Dalke Scientiﬁc Software who contributed the strftime() code below to include dates earlier than this year. fmt is an strftime() format string; tz is the tzinfo instance. set_tzinfo(tz) strftime(dt, fmt) class IndexDateFormatter(t, fmt, tz=None) Bases: matplotlib.ticker.Formatter Use with IndexLocator to cycle format strings by index. t is a sequence of dates (ﬂoating point days). fmt is a strftime() format string. class AutoDateFormatter(locator, tz=None) Bases: matplotlib.ticker.Formatter This class attempts to ﬁgure out the best format to use. This is most useful when used with the AutoDateLocator. 41.1. matplotlib.dates 561 Matplotlib, Release 0.99.1.1 class DateLocator(tz=None) Bases: matplotlib.ticker.Locator tz is a tzinfo instance. datalim_to_dt() nonsingular(vmin, vmax) set_tzinfo(tz) viewlim_to_dt() class RRuleLocator(o, tz=None) Bases: matplotlib.dates.DateLocator autoscale() Set the view limits to include the data range. class AutoDateLocator(tz=None) Bases: matplotlib.dates.DateLocator On autoscale, this class picks the best MultipleDateLocator to set the view limits and the tick locations. autoscale() Try to choose the view limits intelligently. get_locator(dmin, dmax) Pick the best locator based on a distance. refresh() Refresh internal information based on current limits. set_axis(axis) class YearLocator(base=1, month=1, day=1, tz=None) Bases: matplotlib.dates.DateLocator Make ticks on a given day of each year that is a multiple of base. Examples: # Tick every year on Jan 1st locator = YearLocator() # Tick every 5 years on July 4th locator = YearLocator(5, month=7, day=4) Mark years that are multiple of base on a given month and day (default jan 1). autoscale() Set the view limits to include the data range. class MonthLocator(bymonth=None, bymonthday=1, interval=1, tz=None) Bases: matplotlib.dates.RRuleLocator Make ticks on occurances of each month month, eg 1, 3, 12. 562 Chapter 41. matplotlib dates Matplotlib, Release 0.99.1.1 Mark every month in bymonth; bymonth can be an int or sequence. Default is range(1,13), i.e. every month. interval is the interval between each iteration. For example, if interval=2, mark every second occurance. class WeekdayLocator(byweekday=1, interval=1, tz=None) Bases: matplotlib.dates.RRuleLocator Make ticks on occurances of each weekday. Mark every weekday in byweekday; byweekday can be a number or sequence. Elements of byweekday must be one of MO, TU, WE, TH, FR, SA, SU, the constants from dateutils.rrule. interval speciﬁes the number of weeks to skip. For example, interval=2 plots every second week. class DayLocator(bymonthday=None, interval=1, tz=None) Bases: matplotlib.dates.RRuleLocator Make ticks on occurances of each day of the month. For example, 1, 15, 30. Mark every day in bymonthday; bymonthday can be an int or sequence. Default is to tick every day of the month: bymonthday=range(1,32) class HourLocator(byhour=None, interval=1, tz=None) Bases: matplotlib.dates.RRuleLocator Make ticks on occurances of each hour. Mark every hour in byhour; byhour can be an int or sequence. Default is to tick every hour: byhour=range(24) interval is the interval between each iteration. For example, if interval=2, mark every second occurrence. class MinuteLocator(byminute=None, interval=1, tz=None) Bases: matplotlib.dates.RRuleLocator Make ticks on occurances of each minute. Mark every minute in byminute; byminute can be an int or sequence. Default is to tick every minute: byminute=range(60) interval is the interval between each iteration. For example, if interval=2, mark every second occurrence. class SecondLocator(bysecond=None, interval=1, tz=None) Bases: matplotlib.dates.RRuleLocator Make ticks on occurances of each second. Mark every second in bysecond; bysecond can be an int or sequence. Default is to tick every second: bysecond = range(60) interval is the interval between each iteration. For example, if interval=2, mark every second occurrence. 41.1. matplotlib.dates 563 Matplotlib, Release 0.99.1.1 class rrule(freq, dtstart=None, interval=1, wkst=None, count=None, until=None, bysetpos=None, bymonth=None, bymonthday=None, byyearday=None, byeaster=None, byweekno=None, byweekday=None, byhour=None, byminute=None, bysecond=None, cache=False) Bases: dateutil.rrule.rrulebase class relativedelta(dt1=None, dt2=None, years=0, months=0, days=0, leapdays=0, weeks=0, hours=0, minutes=0, seconds=0, microseconds=0, year=None, month=None, day=None, weekday=None, yearday=None, nlyearday=None, hour=None, minute=None, second=None, microsecond=None) The relativedelta type is based on the speciﬁcation of the excelent work done by M.-A. Lemburg in his mx.DateTime extension. However, notice that this type does NOT implement the same algorithm as his work. Do NOT expect it to behave like mx.DateTime’s counterpart. There’s two diﬀerent ways to build a relativedelta instance. The ﬁrst one is passing it two date/datetime classes: relativedelta(datetime1, datetime2) And the other way is to use the following keyword arguments: year, month, day, hour, minute, second, microsecond: Absolute information. years, months, weeks, days, hours, minutes, seconds, microseconds: Relative mation, may be negative. infor- weekday: One of the weekday instances (MO, TU, etc). These instances may receive a parameter N, specifying the Nth weekday, which could be positive or negative (like MO(+1) or MO(-2). Not specifying it is the same as specifying +1. You can also use an integer, where 0=MO. leapdays: Will add given days to the date found, if year is a leap year, and the date found is post 28 of february. yearday, nlyearday: Set the yearday or the non-leap year day (jump leap days). These are converted to day/month/leapdays information. Here is the behavior of operations with relativedelta: 1.Calculate the absolute year, using the ‘year’ argument, or the original datetime year, if the argument is not present. 2.Add the relative ‘years’ argument to the absolute year. 3.Do steps 1 and 2 for month/months. 4.Calculate the absolute day, using the ‘day’ argument, or the original datetime day, if the argument is not present. Then, subtract from the day until it ﬁts in the year and month found after their operations. 5.Add the relative ‘days’ argument to the absolute day. Notice that the ‘weeks’ argument is multiplied by 7 and added to ‘days’. 6.Do steps 1 and 2 for hour/hours, minute/minutes, second/seconds, microsecond/microseconds. 7.If the ‘weekday’ argument is present, calculate the weekday, with the given (wday, nth) tuple. wday is the index of the weekday (0-6, 0=Mon), and nth is the number of weeks to add forward 564 Chapter 41. matplotlib dates Matplotlib, Release 0.99.1.1 or backward, depending on its signal. Notice that if the calculated date is already Monday, for example, using (0, 1) or (0, -1) won’t change the day. seconds(s) Return seconds as days. minutes(m) Return minutes as days. hours(h) Return hours as days. weeks(w) Return weeks as days. 41.1. matplotlib.dates 565 Matplotlib, Release 0.99.1.1 566 Chapter 41. matplotlib dates CHAPTER FORTYTWO MATPLOTLIB FIGURE 42.1 matplotlib.figure The ﬁgure module provides the top-level Artist, the Figure, which contains all the plot elements. The following classes are deﬁned SubplotParams control the default spacing of the subplots Figure top level container for all plot elements class Figure(ﬁgsize=None, dpi=None, facecolor=None, edgecolor=None, linewidth=1.0, frameon=True, subplotpars=None) Bases: matplotlib.artist.Artist The Figure instance supports callbacks through a callbacks attribute which is a matplotlib.cbook.CallbackRegistry instance. The events you can connect to are ‘dpi_changed’, and the callback will be called with func(fig) where ﬁg is the Figure instance. The ﬁgure patch is drawn by a the attribute patch a matplotlib.patches.Rectangle instance suppressComposite for multiple ﬁgure images, the ﬁgure will make composite images depending on the renderer option_image_nocomposite function. If suppressComposite is True|False, this will override the renderer ﬁgsize w,h tuple in inches dpi dots per inch facecolor the ﬁgure patch facecolor; defaults to rc figure.facecolor edgecolor the ﬁgure patch edge color; defaults to rc figure.edgecolor linewidth the ﬁgure patch edge linewidth; the default linewidth of the frame frameon if False, suppress drawing the ﬁgure frame subplotpars a SubplotParams instance, defaults to rc add_axes(*args, **kwargs) Add an a axes with axes rect [left, bottom, width, height] where all quantities are in fractions of ﬁgure width and height. kwargs are legal Axes kwargs plus projection which sets the projection 567 Matplotlib, Release 0.99.1.1 type of the axes. (For backward compatibility, polar=True may also be provided, which is equivalent to projection=’polar’). Valid values for projection are: aitoﬀ, hammer, lambert, mollweide, polar, rectilinear. Some of these projections support additional kwargs, which may be provided to add_axes(): rect = l,b,w,h fig.add_axes(rect) fig.add_axes(rect, fig.add_axes(rect, fig.add_axes(rect, fig.add_axes(ax) frameon=False, axisbg=’g’) polar=True) projection=’polar’) # add an Axes instance If the ﬁgure already has an axes with the same parameters, then it will simply make that axes current and return it. If you do not want this behavior, eg. you want to force the creation of a new axes, you must use a unique set of args and kwargs. The axes label attribute has been exposed for this purpose. Eg., if you want two axes that are otherwise identical to be added to the ﬁgure, make sure you give them unique labels: fig.add_axes(rect, label=’axes1’) fig.add_axes(rect, label=’axes2’) The Axes instance will be returned. The following kwargs are supported: Property adjustable alpha anchor animated aspect autoscale_on autoscalex_on autoscaley_on axes axes_locator axis_bgcolor axis_off axis_on axisbelow clip_box clip_on clip_path color_cycle contains cursor_props figure frame_on 568 Description [ ‘box’ | ‘datalim’ ] ﬂoat (0.0 transparent through 1.0 opaque) unknown [True | False] unknown unknown unknown unknown an Axes instance unknown any matplotlib color - see colors() unknown unknown [ True | False ] a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] unknown a callable function a (ﬂoat, color) tuple unknown [ True | False ] Continued on next page Chapter 42. matplotlib ﬁgure Matplotlib, Release 0.99.1.1 Table 42.1 – continued from previous page gid an id string label any string lod [True | False] navigate [ True | False ] navigate_mode unknown picker [None|ﬂoat|boolean|callable] position unknown rasterization_zorder unknown rasterized [True | False | None] snap unknown title str transform Transform instance url a url string visible [True | False] xbound unknown xlabel str xlim len(2) sequence of ﬂoats xscale [’linear’ | ‘log’ | ‘symlog’] xticklabels sequence of strings xticks sequence of ﬂoats ybound unknown ylabel str ylim len(2) sequence of ﬂoats yscale [’linear’ | ‘log’ | ‘symlog’] yticklabels sequence of strings yticks sequence of ﬂoats zorder any number add_axobserver(func) whenever the axes state change, func(self) will be called add_subplot(*args, **kwargs) Add a subplot. Examples: ﬁg.add_subplot(111) ﬁg.add_subplot(1,1,1) # equivalent but more general ﬁg.add_subplot(212, axisbg=’r’) # add subplot with red background ﬁg.add_subplot(111, polar=True) # add a polar subplot ﬁg.add_subplot(sub) # add Subplot instance sub kwargs are legal matplotlib.axes.Axes kwargs plus projection, which chooses a projection type for the axes. (For backward compatibility, polar=True may also be provided, which is equivalent to projection=’polar’). Valid values for projection are: aitoﬀ, hammer, lambert, mollweide, polar, rectilinear. Some of these projections support additional kwargs, which may be provided to add_axes(). The Axes instance will be returned. 42.1. matplotlib.figure 569 Matplotlib, Release 0.99.1.1 If the ﬁgure already has a subplot with key (args, kwargs) then it will simply make that subplot current and return it. The following kwargs are supported: Property adjustable alpha anchor animated aspect autoscale_on autoscalex_on autoscaley_on axes axes_locator axis_bgcolor axis_off axis_on axisbelow clip_box clip_on clip_path color_cycle contains cursor_props figure frame_on gid label lod navigate navigate_mode picker position rasterization_zorder rasterized snap title transform url visible xbound xlabel xlim xscale xticklabels 570 Description [ ‘box’ | ‘datalim’ ] ﬂoat (0.0 transparent through 1.0 opaque) unknown [True | False] unknown unknown unknown unknown an Axes instance unknown any matplotlib color - see colors() unknown unknown [ True | False ] a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] unknown a callable function a (ﬂoat, color) tuple unknown [ True | False ] an id string any string [True | False] [ True | False ] unknown [None|ﬂoat|boolean|callable] unknown unknown [True | False | None] unknown str Transform instance a url string [True | False] unknown str len(2) sequence of ﬂoats [’linear’ | ‘log’ | ‘symlog’] sequence of strings Continued on next page Chapter 42. matplotlib ﬁgure Matplotlib, Release 0.99.1.1 Table 42.2 – continued from previous page xticks sequence of ﬂoats ybound unknown ylabel str ylim len(2) sequence of ﬂoats yscale [’linear’ | ‘log’ | ‘symlog’] yticklabels sequence of strings yticks sequence of ﬂoats zorder any number autofmt_xdate(bottom=0.20000000000000001, rotation=30, ha=’right’) Date ticklabels often overlap, so it is useful to rotate them and right align them. Also, a common use case is a number of subplots with shared xaxes where the x-axis is date data. The ticklabels are often long, and it helps to rotate them on the bottom subplot and turn them oﬀ on other subplots, as well as turn oﬀ xlabels. bottom the bottom of the subplots for subplots_adjust() rotation the rotation of the xtick labels ha the horizontal alignment of the xticklabels clear() Clear the ﬁgure – synonym for ﬁg.clf clf () Clear the ﬁgure colorbar(mappable, cax=None, ax=None, **kw) Create a colorbar for a ScalarMappable instance. Documentation for the pylab thin wrapper: Add a colorbar to a plot. Function signatures for the pyplot interface; all but the ﬁrst are also method signatures for the colorbar() method: colorbar(**kwargs) colorbar(mappable, **kwargs) colorbar(mappable, cax=cax, **kwargs) colorbar(mappable, ax=ax, **kwargs) arguments: mappable the Image, ContourSet, etc. to which the colorbar applies; this argument is mandatory for the colorbar() method but optional for the colorbar() function, which sets the default to the current image. keyword arguments: 42.1. matplotlib.figure 571 Matplotlib, Release 0.99.1.1 cax None | axes object into which the colorbar will be drawn ax None | parent axes object from which space for a new colorbar axes will be stolen Additional keyword arguments are of two kinds: axes properties: Property orientation fraction pad shrink aspect Description vertical or horizontal 0.15; fraction of original axes to use for colorbar 0.05 if vertical, 0.15 if horizontal; fraction of original axes between colorbar and new image axes 1.0; fraction by which to shrink the colorbar 20; ratio of long to short dimensions colorbar properties: Property extend spacing ticks Description [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ] If not ‘neither’, make pointed end(s) for out-of- range values. These are set for a given colormap using the colormap set_under and set_over method [ ‘uniform’ | ‘proportional’ ] Uniform spacing gives each discrete color the same space; proportional makes the space proportional to the data interval. [ None | list of ticks | Locator object ] If None, ticks are determined automatically from the input. for[ None | format string | Formatter object ] If None, the ScalarFormatter is used. If a forma mat string is given, e.g. ‘%.3f’, that is used. An alternative Formatter object may be given instead. drawedgesFalse | True ] If true, draw lines at color boundaries. [ The following will probably be useful only in the context of indexed colors (that is, when the mappable has norm=NoNorm()), or other unusual circumstances. Prop- Description erty bound- None or a sequence aries values None or a sequence which must be of length 1 less than the sequence of boundaries. For eac region delimited by adjacent entries in boundaries, the color mapped to the corresponding value in values will be used. If mappable is a ContourSet, its extend kwarg is included automatically. Note that the shrink kwarg provides a simple way to keep a vertical colorbar, for example, from being taller than the axes of the mappable to which the colorbar is attached; but it is a manual method requiring some trial and error. If the colorbar is too tall (or a horizontal colorbar is too wide) use a smaller value of shrink. For more precise control, you can manually specify the positions of the axes objects in which the mappable and the colorbar are drawn. In this case, do not use any of the axes properties kwargs. 572 Chapter 42. matplotlib ﬁgure Matplotlib, Release 0.99.1.1 returns: Colorbar instance; see also its base class, ColorbarBase. Call the set_label() method to label the colorbar. contains(mouseevent) Test whether the mouse event occurred on the ﬁgure. Returns True,{} delaxes(a) remove a from the ﬁgure and update the current axes dpi draw(artist, renderer, *kl) Render the ﬁgure using matplotlib.backend_bases.RendererBase instance renderer draw_artist(a) draw matplotlib.artist.Artist instance a only – this is available only after the ﬁgure is drawn figimage(X, xo=0, yo=0, alpha=1.0, norm=None, cmap=None, vmin=None, vmax=None, origin=None) call signatures: figimage(X, **kwargs) adds a non-resampled array X to the ﬁgure. figimage(X, xo, yo) with pixel oﬀsets xo, yo, X must be a ﬂoat array: •If X is MxN, assume luminance (grayscale) •If X is MxNx3, assume RGB •If X is MxNx4, assume RGBA Optional keyword arguments: 42.1. matplotlib.figure 573 Matplotlib, Release 0.99.1.1 Keyword xo or yo cmap Description An integer, the x and y image oﬀset in pixels a matplotlib.cm.ColorMap instance, eg cm.jet. If None, default to the rc image.cmap value norm a matplotlib.colors.Normalize instance. The default is normalization(). This scales luminance -> 0-1 vmin|vmax used to scale a luminance image to 0-1. If either is None, the min and max of the are luminance values will be used. Note if you pass a norm instance, the settings for vmin and vmax will be ignored. alpha the alpha blending value, default is 1.0 origin [ ‘upper’ | ‘lower’ ] Indicates where the [0,0] index of the array is in the upper left or lower left corner of the axes. Defaults to the rc image.origin value ﬁgimage complements the axes image (imshow()) which will be resampled to ﬁt the current axes. If you want a resampled image to ﬁll the entire ﬁgure, you can deﬁne an Axes with size [0,1,0,1]. An matplotlib.image.FigureImage instance is returned. gca(**kwargs) Return the current axes, creating one if necessary The following kwargs are supported 574 Chapter 42. matplotlib ﬁgure Matplotlib, Release 0.99.1.1 Property adjustable alpha anchor animated aspect autoscale_on autoscalex_on autoscaley_on axes axes_locator axis_bgcolor axis_off axis_on axisbelow clip_box clip_on clip_path color_cycle contains cursor_props figure frame_on gid label lod navigate navigate_mode picker position rasterization_zorder rasterized snap title transform url visible xbound xlabel xlim xscale xticklabels xticks ybound ylabel 42.1. matplotlib.figure Description [ ‘box’ | ‘datalim’ ] ﬂoat (0.0 transparent through 1.0 opaque) unknown [True | False] unknown unknown unknown unknown an Axes instance unknown any matplotlib color - see colors() unknown unknown [ True | False ] a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] unknown a callable function a (ﬂoat, color) tuple unknown [ True | False ] an id string any string [True | False] [ True | False ] unknown [None|ﬂoat|boolean|callable] unknown unknown [True | False | None] unknown str Transform instance a url string [True | False] unknown str len(2) sequence of ﬂoats [’linear’ | ‘log’ | ‘symlog’] sequence of strings sequence of ﬂoats unknown str Continued on next page 575 Matplotlib, Release 0.99.1.1 Table 42.3 – continued from previous page ylim len(2) sequence of ﬂoats yscale [’linear’ | ‘log’ | ‘symlog’] yticklabels sequence of strings yticks sequence of ﬂoats zorder any number get_axes() get_children() get a list of artists contained in the ﬁgure get_dpi() Return the dpi as a ﬂoat get_edgecolor() Get the edge color of the Figure rectangle get_facecolor() Get the face color of the Figure rectangle get_figheight() Return the ﬁgheight as a ﬂoat get_figwidth() Return the ﬁgwidth as a ﬂoat get_frameon() get the boolean indicating frameon get_size_inches() get_tightbbox(renderer) Return a (tight) bounding box of the ﬁgure in inches. It only accounts axes title, axis labels, and axis ticklabels. Needs improvement. get_window_extent(*args, **kwargs) get the ﬁgure bounding box in display space; kwargs are void ginput(n=1, timeout=30, show_clicks=True, mouse_add=1, mouse_pop=3, mouse_stop=2) call signature: ginput(self, n=1, timeout=30, show_clicks=True, mouse_add=1, mouse_pop=3, mouse_stop=2) Blocking call to interact with the ﬁgure. This will wait for n clicks from the user and return a list of the coordinates of each click. If timeout is zero or negative, does not timeout. 576 Chapter 42. matplotlib ﬁgure Matplotlib, Release 0.99.1.1 If n is zero or negative, accumulate clicks until a middle click (or potentially both mouse buttons at once) terminates the input. Right clicking cancels last input. The buttons used for the various actions (adding points, removing points, terminating the inputs) can be overriden via the arguments mouse_add, mouse_pop and mouse_stop, that give the associated mouse button: 1 for left, 2 for middle, 3 for right. The keyboard can also be used to select points in case your mouse does not have one or more of the buttons. The delete and backspace keys act like right clicking (i.e., remove last point), the enter key terminates input and any other key (not already used by the window manager) selects a point. hold(b=None) Set the hold state. If hold is None (default), toggle the hold state. Else set the hold state to boolean value b. Eg: hold() # toggle hold hold(True) # hold is on hold(False) # hold is off legend(handles, labels, *args, **kwargs) Place a legend in the ﬁgure. Labels are a sequence of strings, handles is a sequence of Line2D or Patch instances, and loc can be a string or an integer specifying the legend location USAGE: legend( (line1, line2, line3), (’label1’, ’label2’, ’label3’), ’upper right’) The loc location codes are: ’best’ : 0, ’upper right’ ’upper left’ ’lower left’ ’lower right’ ’right’ ’center left’ ’center right’ ’lower center’ ’upper center’ ’center’ (currently not supported for figure legends) : : : : : : : : : : 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, loc can also be an (x,y) tuple in ﬁgure coords, which speciﬁes the lower left of the legend box. ﬁgure coords are (0,0) is the left, bottom of the ﬁgure and 1,1 is the right, top. Keyword arguments: 42.1. matplotlib.figure 577 Matplotlib, Release 0.99.1.1 prop: [ None | FontProperties | dict ] A matplotlib.font_manager.FontProperties instance. If prop is a dictionary, a new instance will be created with prop. If None, use rc settings. numpoints: integer The number of points in the legend line, default is 4 scatterpoints: integer The number of points in the legend line, default is 4 scatteroﬀsets: list of ﬂoats a list of yoﬀsets for scatter symbols in legend markerscale: [ None | scalar ] The relative size of legend markers vs. original. If None, use rc settings. fancybox: [ None | False | True ] if True, draw a frame with a round fancybox. If None, use rc shadow: [ None | False | True ] If True, draw a shadow behind legend. If None, use rc settings. ncol [integer] number of columns. default is 1 mode [[ “expand” | None ]] if mode is “expand”, the legend will be horizontally expanded to ﬁll the axes area (or bbox_to_anchor) title [string] the legend title Padding and spacing between various elements use following keywords parameters. The dimensions of these values are given as a fraction of the fontsize. Values from rcParams will be used if None. Keyword borderpad labelspacing handlelength handletextpad borderaxespad columnspacing Description the fractional whitespace inside the legend border the vertical space between the legend entries the length of the legend handles the pad between the legend handle and text the pad between the axes and legend border the spacing between columns Example: 578 Chapter 42. matplotlib ﬁgure Matplotlib, Release 0.99.1.1 savefig(*args, **kwargs) call signature: savefig(fname, dpi=None, facecolor=’w’, edgecolor=’w’, orientation=’portrait’, papertype=None, format=None, transparent=False): Save the current ﬁgure. The output formats available depend on the backend being used. Arguments: fname: A string containing a path to a ﬁlename, or a Python ﬁle-like object. If format is None and fname is a string, the output format is deduced from the extension of the ﬁlename. Keyword arguments: dpi: [ None | scalar > 0 ] The resolution in dots per inch. If None it will default to the value savefig.dpi in the matplotlibrc ﬁle. facecolor, edgecolor: the colors of the ﬁgure rectangle orientation: [ ‘landscape’ | ‘portrait’ ] not supported on all backends; currently only on postscript output 42.1. matplotlib.figure 579 Matplotlib, Release 0.99.1.1 papertype: One of ‘letter’, ‘legal’, ‘executive’, ‘ledger’, ‘a0’ through ‘a10’, ‘b0’ through ‘b10’. Only supported for postscript output. format: One of the ﬁle extensions supported by the active backend. Most backends support png, pdf, ps, eps and svg. transparent: If True, the ﬁgure patch and axes patches will all be transparent. This is useful, for example, for displaying a plot on top of a colored background on a web page. The transparency of these patches will be restored to their original values upon exit of this function. bbox_inches: Bbox in inches. Only the given portion of the ﬁgure is saved. If ‘tight’, try to ﬁgure out the tight bbox of the ﬁgure. pad_inches: Amount of padding around the ﬁgure when bbox_inches is ‘tight’. sca(a) Set the current axes to be a and return a set_canvas(canvas) Set the canvas the contains the ﬁgure ACCEPTS: a FigureCanvas instance set_dpi(val) Set the dots-per-inch of the ﬁgure ACCEPTS: ﬂoat set_edgecolor(color) Set the edge color of the Figure rectangle ACCEPTS: any matplotlib color - see help(colors) set_facecolor(color) Set the face color of the Figure rectangle ACCEPTS: any matplotlib color - see help(colors) set_figheight(val) Set the height of the ﬁgure in inches ACCEPTS: ﬂoat set_figsize_inches(*args, **kwargs) set_figwidth(val) Set the width of the ﬁgure in inches ACCEPTS: ﬂoat set_frameon(b) Set whether the ﬁgure frame (background) is displayed or invisible ACCEPTS: boolean set_size_inches(*args, **kwargs) set_size_inches(w,h, forward=False) 580 Chapter 42. matplotlib ﬁgure Matplotlib, Release 0.99.1.1 Set the ﬁgure size in inches Usage: fig.set_size_inches(w,h) # OR fig.set_size_inches((w,h) ) optional kwarg forward=True will cause the canvas size to be automatically updated; eg you can resize the ﬁgure window from the shell WARNING: forward=True is broken on all backends except GTK* and WX* ACCEPTS: a w,h tuple with w,h in inches subplots_adjust(*args, **kwargs) ﬁg.subplots_adjust(left=None, bottom=None, right=None, top=None, wspace=None, hspace=None) Update the SubplotParams with kwargs (defaulting to rc where None) and update the subplot locations suptitle(t, **kwargs) Add a centered title to the ﬁgure. kwargs are matplotlib.text.Text properties. Using ﬁgure coordinates, the defaults are: •x = 0.5 the x location of text in ﬁgure coords •y = 0.98 the y location of the text in ﬁgure coords •horizontalalignment = ‘center’ the horizontal alignment of the text •verticalalignment = ‘top’ the vertical alignment of the text A matplotlib.text.Text instance is returned. Example: fig.suptitle(’this is the figure title’, fontsize=12) text(x, y, s, *args, **kwargs) Call signature: figtext(x, y, s, fontdict=None, **kwargs) Add text to ﬁgure at location x, y (relative 0-1 coords). See text() for the meaning of the other arguments. kwargs control the Text properties: Property 42.1. matplotlib.figure Description 581 Matplotlib, Release 0.99.1.1 Table 42.4 – continued from alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number waitforbuttonpress(timeout=-1) call signature: waitforbuttonpress(self, timeout=-1) Blocking call to interact with the ﬁgure. 582 Chapter 42. matplotlib ﬁgure Matplotlib, Release 0.99.1.1 This will return True is a key was pressed, False if a mouse button was pressed and None if timeout was reached without either being pressed. If timeout is negative, does not timeout. class SubplotParams(left=None, bottom=None, right=None, top=None, wspace=None, hspace=None) A class to hold the parameters for a subplot All dimensions are fraction of the ﬁgure width or height. All values default to their rc params The following attributes are available left = 0.125 the left side of the subplots of the ﬁgure right = 0.9 the right side of the subplots of the ﬁgure bottom = 0.1 the bottom of the subplots of the ﬁgure top = 0.9 the top of the subplots of the ﬁgure wspace = 0.2 the amount of width reserved for blank space between subplots hspace = 0.2 the amount of height reserved for white space between subplots validate make sure the params are in a legal state (left*<*right, etc) update(left=None, bottom=None, right=None, top=None, wspace=None, hspace=None) Update the current values. If any kwarg is None, default to the current value, if set, otherwise to rc figaspect(arg) Create a ﬁgure with speciﬁed aspect ratio. If arg is a number, use that aspect ratio. If arg is an array, ﬁgaspect will determine the width and height for a ﬁgure that would ﬁt array preserving aspect ratio. The ﬁgure width, height in inches are returned. Be sure to create an axes with equal with and height, eg Example usage: # make a figure twice as tall as it is wide w, h = figaspect(2.) fig = Figure(figsize=(w,h)) ax = fig.add_axes([0.1, 0.1, 0.8, 0.8]) ax.imshow(A, **kwargs) # make a figure with the proper aspect for an array A = rand(5,3) w, h = figaspect(A) fig = Figure(figsize=(w,h)) ax = fig.add_axes([0.1, 0.1, 0.8, 0.8]) ax.imshow(A, **kwargs) Thanks to Fernando Perez for this function 42.1. matplotlib.figure 583 Matplotlib, Release 0.99.1.1 584 Chapter 42. matplotlib ﬁgure CHAPTER FORTYTHREE MATPLOTLIB FONT_MANAGER 43.1 matplotlib.font_manager A module for ﬁnding, managing, and using fonts across platforms. This module provides a single FontManager instance that can be shared across backends and platforms. The findfont() function returns the best TrueType (TTF) font ﬁle in the local or system font path that matches the speciﬁed FontProperties instance. The FontManager also handles Adobe Font Metrics (AFM) font ﬁles for use by the PostScript backend. The design is based on the W3C Cascading Style Sheet, Level 1 (CSS1) font speciﬁcation. Future versions may implement the Level 2 or 2.1 speciﬁcations. Experimental support is included for using fontconﬁg on Unix variant platforms (Linux, OS X, Solaris). To enable it, set the constant USE_FONTCONFIG in this ﬁle to True. Fontconﬁg has the advantage that it is the standard way to look up fonts on X11 platforms, so if a font is installed, it is much more likely to be found. class FontEntry(fname=”, name=”, style=’normal’, stretch=’normal’, size=’medium’) Bases: object variant=’normal’, weight=’normal’, A class for storing Font properties. It is used when populating the font lookup dictionary. class FontManager(size=None, weight=’normal’) On import, the FontManager singleton instance creates a list of TrueType fonts based on the font properties: name, style, variant, weight, stretch, and size. The findfont() method does a nearest neighbor search to ﬁnd the font that most closely matches the speciﬁcation. If no good enough match is found, a default font is returned. findfont(prop, fontext=’ttf’) Search the font list for the font that most closely matches the FontProperties prop. findfont() performs a nearest neighbor search. Each font is given a similarity score to the target font properties. The ﬁrst font with the highest score is returned. If no matches below a certain threshold are found, the default font (usually Vera Sans) is returned. The result is cached, so subsequent lookups don’t have to perform the O(n) nearest neighbor search. 585 Matplotlib, Release 0.99.1.1 See the W3C Cascading Style Sheet, Level 1 documentation for a description of the font ﬁnding algorithm. get_default_size() Return the default font size. get_default_weight() Return the default font weight. score_family(families, family2) Returns a match score between the list of font families in families and the font family name family2. An exact match anywhere in the list returns 0.0. A match by generic font name will return 0.1. No match will return 1.0. score_size(size1, size2) Returns a match score between size1 and size2. If size2 (the size speciﬁed in the font ﬁle) is ‘scalable’, this function always returns 0.0, since any font size can be generated. Otherwise, the result is the absolute distance between size1 and size2, normalized so that the usual range of font sizes (6pt - 72pt) will lie between 0.0 and 1.0. score_stretch(stretch1, stretch2) Returns a match score between stretch1 and stretch2. The result is the absolute value of the diﬀerence between the CSS numeric values of stretch1 and stretch2, normalized between 0.0 and 1.0. score_style(style1, style2) Returns a match score between style1 and style2. An exact match returns 0.0. A match between ‘italic’ and ‘oblique’ returns 0.1. No match returns 1.0. score_variant(variant1, variant2) Returns a match score between variant1 and variant2. An exact match returns 0.0, otherwise 1.0. score_weight(weight1, weight2) Returns a match score between weight1 and weight2. The result is the absolute value of the diﬀerence between the CSS numeric values of weight1 and weight2, normalized between 0.0 and 1.0. set_default_size(size) Set the default font size in points. The initial value is set by font.size in rc. 586 Chapter 43. matplotlib font_manager Matplotlib, Release 0.99.1.1 set_default_weight(weight) Set the default font weight. The initial value is ‘normal’. update_fonts(ﬁlenames) Update the font dictionary with new font ﬁles. Currently not implemented. class FontProperties(family=None, style=None, variant=None, size=None, fname=None, _init=None) Bases: object weight=None, stretch=None, A class for storing and manipulating font properties. The font properties are those described in the W3C Cascading Style Sheet, Level 1 font speciﬁcation. The six properties are: •family: A list of font names in decreasing order of priority. The items may include a generic font family name, either ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, or ‘monospace’. In that case, the actual font to be used will be looked up from the associated rcParam in matplotlibrc. •style: Either ‘normal’, ‘italic’ or ‘oblique’. •variant: Either ‘normal’ or ‘small-caps’. •stretch: A numeric value in the range 0-1000 or one of ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’ or ‘ultra-expanded’ •weight: A numeric value in the range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’ •size: Either an relative value of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xxlarge’ or an absolute font size, e.g. 12 The default font property for TrueType fonts (as speciﬁed in the default matplotlibrc ﬁle) is: sans-serif, normal, normal, normal, normal, scalable. Alternatively, a font may be speciﬁed using an absolute path to a .ttf ﬁle, by using the fname kwarg. The preferred usage of font sizes is to use the relative values, e.g. ‘large’, instead of absolute font sizes, e.g. 12. This approach allows all text sizes to be made larger or smaller based on the font manager’s default font size, i.e. by using the FontManager.set_default_size() method. This class will also accept a fontconﬁg pattern, if it is the only argument provided. See the documentation on fontconﬁg patterns. This support does not require fontconﬁg to be installed. We are merely borrowing its pattern syntax for use here. Note that matplotlib’s internal font manager and fontconﬁg use a diﬀerent algorithm to lookup fonts, so the results of the same pattern may be diﬀerent in matplotlib than in other applications that use fontconﬁg. copy() Return a deep copy of self 43.1. matplotlib.font_manager 587 Matplotlib, Release 0.99.1.1 get_family() Return a list of font names that comprise the font family. get_file() Return the ﬁlename of the associated font. get_fontconfig_pattern() Get a fontconﬁg pattern suitable for looking up the font as speciﬁed with fontconﬁg’s fc-match utility. See the documentation on fontconﬁg patterns. This support does not require fontconﬁg to be installed or support for it to be enabled. We are merely borrowing its pattern syntax for use here. get_name() Return the name of the font that best matches the font properties. get_size() Return the font size. get_size_in_points() get_slant() Return the font style. Values are: ‘normal’, ‘italic’ or ‘oblique’. get_stretch() Return the font stretch or width. Options are: ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’, ‘ultraexpanded’. get_style() Return the font style. Values are: ‘normal’, ‘italic’ or ‘oblique’. get_variant() Return the font variant. Values are: ‘normal’ or ‘small-caps’. get_weight() Set the font weight. Options are: A numeric value in the range 0-1000 or one of ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’ set_family(family) Change the font family. May be either an alias (generic name is CSS parlance), such as: ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, or ‘monospace’, or a real font name. set_file(ﬁle) Set the ﬁlename of the fontﬁle to use. In this case, all other properties will be ignored. set_fontconfig_pattern(pattern) Set the properties by parsing a fontconﬁg pattern. See the documentation on fontconﬁg patterns. This support does not require fontconﬁg to be installed or support for it to be enabled. We are merely borrowing its pattern syntax for use here. 588 Chapter 43. matplotlib font_manager Matplotlib, Release 0.99.1.1 set_name(family) Change the font family. May be either an alias (generic name is CSS parlance), such as: ‘serif, ‘sans-serif’, ‘cursive’, ‘fantasy’, or ‘monospace’, or a real font name. set_size(size) Set the font size. Either an relative value of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’ or an absolute font size, e.g. 12. set_slant(style) Set the font style. Values are: ‘normal’, ‘italic’ or ‘oblique’. set_stretch(stretch) Set the font stretch or width. Options are: ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’ or ‘ultraexpanded’, or a numeric value in the range 0-1000. set_style(style) Set the font style. Values are: ‘normal’, ‘italic’ or ‘oblique’. set_variant(variant) Set the font variant. Values are: ‘normal’ or ‘small-caps’. set_weight(weight) Set the font weight. May be either a numeric value in the range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’ OSXFontDirectory() Return the system font directories for OS X. This is done by starting at the list of hardcoded paths in OSXFontDirectories and returning all nested directories within them. OSXInstalledFonts(directory=None, fontext=’ttf’) Get list of font ﬁles on OS X - ignores font suﬃx by default. afmFontProperty(fontpath, font) A function for populating a FontKey instance by extracting information from the AFM font ﬁle. font is a class:AFM instance. createFontList(fontﬁles, fontext=’ttf’) A function to create a font lookup list. The default is to create a list of TrueType fonts. An AFM font list can optionally be created. findSystemFonts(fontpaths=None, fontext=’ttf’) Search for fonts in the speciﬁed font paths. If no paths are given, will use a standard set of system paths, as well as the list of fonts tracked by fontconﬁg if fontconﬁg is installed and available. A list of TrueType fonts are returned by default with AFM fonts as an option. findfont(prop, **kw) get_fontconfig_fonts(fontext=’ttf’) Grab a list of all the fonts that are being tracked by fontconﬁg by making a system call to fc-list. This is an easy way to grab all of the fonts the user wants to be made available to applications, without needing knowing where all of them reside. 43.1. matplotlib.font_manager 589 Matplotlib, Release 0.99.1.1 get_fontext_synonyms(fontext) Return a list of ﬁle extensions extensions that are synonyms for the given ﬁle extension ﬁleext. is_opentype_cff_font(ﬁlename) Returns True if the given font is a Postscript Compact Font Format Font embedded in an OpenType wrapper. Used by the PostScript and PDF backends that can not subset these fonts. pickle_dump(data, ﬁlename) Equivalent to pickle.dump(data, open(ﬁlename, ‘w’)) but closes the ﬁle to prevent ﬁlehandle leakage. pickle_load(ﬁlename) Equivalent to pickle.load(open(ﬁlename, ‘r’)) but closes the ﬁle to prevent ﬁlehandle leakage. ttfFontProperty(font) A function for populating the FontKey by extracting information from the TrueType font ﬁle. font is a FT2Font instance. ttfdict_to_fnames(d) ﬂatten a ttfdict to all the ﬁlenames it contains weight_as_number(weight) Return the weight property as a numeric value. String values are converted to their corresponding numeric value. win32FontDirectory() Return the user-speciﬁed font directory for Win32. This is looked up from the registry key: \HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Fonts If the key is not found, $WINDIR/Fonts will be returned. win32InstalledFonts(directory=None, fontext=’ttf’) Search for fonts in the speciﬁed font directory, or use the system directories if none given. A list of TrueType font ﬁlenames are returned by default, or AFM fonts if fontext == ‘afm’. x11FontDirectory() Return the system font directories for X11. This is done by starting at the list of hardcoded paths in X11FontDirectories and returning all nested directories within them. 43.2 matplotlib.fontconfig_pattern A module for parsing and generating fontconﬁg patterns. See the fontconﬁg pattern speciﬁcation for more information. class FontconfigPatternParser() A simple pyparsing-based parser for fontconﬁg-style patterns. See the fontconﬁg pattern speciﬁcation for more information. 590 Chapter 43. matplotlib font_manager Matplotlib, Release 0.99.1.1 parse(pattern) Parse the given fontconﬁg pattern and return a dictionary of key/value pairs useful for initializing a font_manager.FontProperties object. family_escape() sub(repl, string[, count = 0]) –> newstring Return the string obtained by replacing the leftmost nonoverlapping occurrences of pattern in string by the replacement repl. family_unescape() sub(repl, string[, count = 0]) –> newstring Return the string obtained by replacing the leftmost nonoverlapping occurrences of pattern in string by the replacement repl. generate_fontconfig_pattern(d) Given a dictionary of key/value pairs, generates a fontconﬁg pattern string. parse_fontconfig_pattern Parse the given fontconﬁg pattern and return a dictionary of key/value pairs useful for initializing a font_manager.FontProperties object. value_escape() sub(repl, string[, count = 0]) –> newstring Return the string obtained by replacing the leftmost nonoverlapping occurrences of pattern in string by the replacement repl. value_unescape() sub(repl, string[, count = 0]) –> newstring Return the string obtained by replacing the leftmost nonoverlapping occurrences of pattern in string by the replacement repl. 43.2. matplotlib.fontconfig_pattern 591 Matplotlib, Release 0.99.1.1 592 Chapter 43. matplotlib font_manager CHAPTER FORTYFOUR MATPLOTLIB NXUTILS 44.1 matplotlib.nxutils general purpose numerical utilities, eg for computational geometry, that are not available in numpy 593 Matplotlib, Release 0.99.1.1 594 Chapter 44. matplotlib nxutils 595 Matplotlib, Release 0.99.1.1 CHAPTER FORTYFIVE MATPLOTLIB MATHTEXT 596 45.1 matplotlib.mathtext Chapter 45. matplotlib mathtext Matplotlib, Release 0.99.1.1 mathtext is a module for parsing a subset of the TeX math syntax and drawing them to a matplotlib backend. For a tutorial of its usage see Writing mathematical expressions. This document is primarily concerned with implementation details. The module uses pyparsing to parse the TeX expression. The Bakoma distribution of the TeX Computer Modern fonts, and STIX fonts are supported. There is experimental support for using arbitrary fonts, but results may vary without proper tweaking and metrics for those fonts. If you ﬁnd TeX expressions that don’t parse or render properly, please email [email protected], but please check KNOWN ISSUES below ﬁrst. class Accent(c, state) Bases: matplotlib.mathtext.Char The font metrics need to be dealt with diﬀerently for accents, since they are already oﬀset correctly from the baseline in TrueType fonts. grow() render(x, y) Render the character to the canvas. shrink() class AutoHeightChar(c, height, depth, state, always=False) Bases: matplotlib.mathtext.Hlist AutoHeightChar will create a character as close to the given height and depth as possible. When using a font with multiple height versions of some characters (such as the BaKoMa fonts), the correct glyph will be selected, otherwise this will always just return a scaled version of the glyph. class AutoWidthChar(c, width, state, always=False, char_class=<class ’matplotlib.mathtext.Char’>) Bases: matplotlib.mathtext.Hlist AutoWidthChar will create a character as close to the given width as possible. When using a font with multiple width versions of some characters (such as the BaKoMa fonts), the correct glyph will be selected, otherwise this will always just return a scaled version of the glyph. class BakomaFonts(*args, **kwargs) Bases: matplotlib.mathtext.TruetypeFonts Use the Bakoma TrueType fonts for rendering. Symbols are strewn about a number of font ﬁles, each of which has its own proprietary 8-bit encoding. get_sized_alternatives_for_symbol(fontname, sym) class Box(width, height, depth) Bases: matplotlib.mathtext.Node Represents any node with a physical location. grow() 45.1. matplotlib.mathtext 597 Matplotlib, Release 0.99.1.1 render(x1, y1, x2, y2) shrink() class Char(c, state) Bases: matplotlib.mathtext.Node Represents a single character. Unlike TeX, the font information and metrics are stored with each Char to make it easier to lookup the font metrics when needed. Note that TeX boxes have a width, height, and depth, unlike Type1 and Truetype which use a full bounding box and an advance in the x-direction. The metrics must be converted to the TeX way, and the advance (if diﬀerent from width) must be converted into a Kern node when the Char is added to its parent Hlist. get_kerning(next) Return the amount of kerning between this and the given character. Called when characters are strung together into Hlist to create Kern nodes. grow() is_slanted() render(x, y) Render the character to the canvas shrink() Error(msg) Helper class to raise parser errors. FT2Font() FT2Font FT2Image() FT2Image class Fil() Bases: matplotlib.mathtext.Glue class Fill() Bases: matplotlib.mathtext.Glue class Filll() Bases: matplotlib.mathtext.Glue class Fonts(default_font_prop, mathtext_backend) Bases: object An abstract base class for a system of fonts to use for mathtext. The class must be able to take symbol keys and font ﬁle names and return the character metrics. It also delegates to a backend class to do the actual drawing. default_font_prop: A FontProperties object to use for the default non-math font, or the base font for Unicode (generic) font rendering. mathtext_backend: A subclass of MathTextBackend used to delegate the actual rendering. 598 Chapter 45. matplotlib mathtext Matplotlib, Release 0.99.1.1 destroy() Fix any cyclical references before the object is about to be destroyed. get_kern(font1, fontclass1, sym1, fontsize1, font2, fontclass2, sym2, fontsize2, dpi) Get the kerning distance for font between sym1 and sym2. fontX : one of the TeX font names: tt, it, rm, cal, sf, bf or default/regular (non-math) fontclassX : TODO symX : a symbol in raw TeX form. e.g. ‘1’, ‘x’ or ‘sigma’ fontsizeX : the fontsize in points dpi: the current dots-per-inch get_metrics(font, font_class, sym, fontsize, dpi) font: one of the TeX font names: tt, it, rm, cal, sf, bf or default/regular (non-math) font_class: TODO sym: a symbol in raw TeX form. e.g. ‘1’, ‘x’ or ‘sigma’ fontsize: font size in points dpi: current dots-per-inch Returns an object with the following attributes: •advance: The advance distance (in points) of the glyph. •height: The height of the glyph in points. •width: The width of the glyph in points. •xmin, xmax, ymin, ymax - the ink rectangle of the glyph •iceberg - the distance from the baseline to the top of the glyph. This corresponds to TeX’s deﬁnition of “height”. get_results(box) Get the data needed by the backend to render the math expression. The return value is backendspeciﬁc. get_sized_alternatives_for_symbol(fontname, sym) Override if your font provides multiple sizes of the same symbol. Should return a list of symbols matching sym in various sizes. The expression renderer will select the most appropriate size for a given situation from this list. get_underline_thickness(font, fontsize, dpi) Get the line thickness that matches the given font. Used as a base unit for drawing lines such as in a fraction or radical. 45.1. matplotlib.mathtext 599 Matplotlib, Release 0.99.1.1 get_used_characters() Get the set of characters that were used in the math expression. Used by backends that need to subset fonts so they know which glyphs to include. get_xheight(font, fontsize, dpi) Get the xheight for the given font and fontsize. render_glyph(ox, oy, facename, font_class, sym, fontsize, dpi) Draw a glyph at •ox, oy: position •facename: One of the TeX face names •font_class: •sym: TeX symbol name or single character •fontsize: fontsize in points •dpi: The dpi to draw at. render_rect_filled(x1, y1, x2, y2) Draw a ﬁlled rectangle from (x1, y1) to (x2, y2). set_canvas_size(w, h, d) Set the size of the buﬀer used to render the math expression. Only really necessary for the bitmap backends. class Glue(glue_type, copy=False) Bases: matplotlib.mathtext.Node Most of the information in this object is stored in the underlying GlueSpec class, which is shared between multiple glue objects. (This is a memory optimization which probably doesn’t matter anymore, but it’s easier to stick to what TeX does.) grow() shrink() class GlueSpec(width=0.0, stretch=0.0, stretch_order=0, shrink=0.0, shrink_order=0) Bases: object See Glue. copy() class factory(glue_type) class HCentered(elements) Bases: matplotlib.mathtext.Hlist A convenience class to create an Hlist whose contents are centered within its enclosing box. class Hbox(width) Bases: matplotlib.mathtext.Box A box with only width (zero height and depth). 600 Chapter 45. matplotlib mathtext Matplotlib, Release 0.99.1.1 class Hlist(elements, w=0.0, m=’additional’, do_kern=True) Bases: matplotlib.mathtext.List A horizontal list of boxes. hpack(w=0.0, m=’additional’) The main duty of hpack() is to compute the dimensions of the resulting boxes, and to adjust the glue if one of those dimensions is pre-speciﬁed. The computed sizes normally enclose all of the material inside the new box; but some items may stick out if negative glue is used, if the box is overfull, or if a \vbox includes other boxes that have been shifted left. •w: speciﬁes a width •m: is either ‘exactly’ or ‘additional’. Thus, hpack(w, ’exactly’) produces a box whose width is exactly w, while hpack(w, ’additional’) yields a box whose width is the natural width plus w. The default values produce a box with the natural width. kern() Insert Kern nodes between Char nodes to set kerning. The Char nodes themselves determine the amount of kerning they need (in get_kerning()), and this function just creates the linked list in the correct way. class Hrule(state) Bases: matplotlib.mathtext.Rule Convenience class to create a horizontal rule. class Kern(width) Bases: matplotlib.mathtext.Node A Kern node has a width ﬁeld to specify a (normally negative) amount of spacing. This spacing correction appears in horizontal lists between letters like A and V when the font designer said that it looks better to move them closer together or further apart. A kern node can also appear in a vertical list, when its width denotes additional spacing in the vertical direction. grow() shrink() class List(elements) Bases: matplotlib.mathtext.Box A list of nodes (either horizontal or vertical). grow() shrink() class MathTextParser(output) Bases: object Create a MathTextParser for the given backend output. get_depth(texstr, dpi=120, fontsize=14) Returns the oﬀset of the baseline from the bottom of the image in pixels. 45.1. matplotlib.mathtext 601 Matplotlib, Release 0.99.1.1 texstr A valid mathtext string, eg r’IQ:$sigma_i=15$’ dpi The dots-per-inch to render the text fontsize The font size in points parse(s, dpi=72, prop=None) Parse the given math expression s at the given dpi. If prop is provided, it is a FontProperties object specifying the “default” font to use in the math expression, used for all non-math text. The results are cached, so multiple calls to parse() with the same expression should be fast. to_mask(texstr, dpi=120, fontsize=14) texstr A valid mathtext string, eg r’IQ:$sigma_i=15$’ dpi The dots-per-inch to render the text fontsize The font size in points Returns a tuple (array, depth) •array is an NxM uint8 alpha ubyte mask array of rasterized tex. •depth is the oﬀset of the baseline from the bottom of the image in pixels. to_png(ﬁlename, texstr, color=’black’, dpi=120, fontsize=14) Writes a tex expression to a PNG ﬁle. Returns the oﬀset of the baseline from the bottom of the image in pixels. ﬁlename A writable ﬁlename or ﬁleobject texstr A valid mathtext string, eg r’IQ:$sigma_i=15$’ color A valid matplotlib color argument dpi The dots-per-inch to render the text fontsize The font size in points Returns the oﬀset of the baseline from the bottom of the image in pixels. to_rgba(texstr, color=’black’, dpi=120, fontsize=14) texstr A valid mathtext string, eg r’IQ:$sigma_i=15$’ color Any matplotlib color argument dpi The dots-per-inch to render the text fontsize The font size in points Returns a tuple (array, depth) •array is an NxM uint8 alpha ubyte mask array of rasterized tex. •depth is the oﬀset of the baseline from the bottom of the image in pixels. exception MathTextWarning Bases: exceptions.Warning 602 Chapter 45. matplotlib mathtext Matplotlib, Release 0.99.1.1 class MathtextBackend() Bases: object The base class for the mathtext backend-speciﬁc code. The purpose of MathtextBackend subclasses is to interface between mathtext and a speciﬁc matplotlib graphics backend. Subclasses need to override the following: •render_glyph() •render_filled_rect() •get_results() And optionally, if you need to use a Freetype hinting style: •get_hinting_type() get_hinting_type() Get the Freetype hinting type to use with this particular backend. get_results(box) Return a backend-speciﬁc tuple to return to the backend after all processing is done. render_filled_rect(x1, y1, x2, y2) Draw a ﬁlled black rectangle from (x1, y1) to (x2, y2). render_glyph(ox, oy, info) Draw a glyph described by info to the reference point (ox, oy). set_canvas_size(w, h, d) Dimension the drawing canvas MathtextBackendAgg() class MathtextBackendAggRender() Bases: matplotlib.mathtext.MathtextBackend Render glyphs and rectangles to an FTImage buﬀer, which is later transferred to the Agg image by the Agg backend. get_hinting_type() get_results(box) render_glyph(ox, oy, info) render_rect_filled(x1, y1, x2, y2) set_canvas_size(w, h, d) class MathtextBackendBbox(real_backend) Bases: matplotlib.mathtext.MathtextBackend A backend whose only purpose is to get a precise bounding box. Only required for the Agg backend. get_hinting_type() get_results(box) 45.1. matplotlib.mathtext 603 Matplotlib, Release 0.99.1.1 render_glyph(ox, oy, info) render_rect_filled(x1, y1, x2, y2) MathtextBackendBitmap() A backend to generate standalone mathtext images. No additional matplotlib backend is required. class MathtextBackendBitmapRender() Bases: matplotlib.mathtext.MathtextBackendAggRender get_results(box) class MathtextBackendCairo() Bases: matplotlib.mathtext.MathtextBackend Store information to write a mathtext rendering to the Cairo backend. get_results(box) render_glyph(ox, oy, info) render_rect_filled(x1, y1, x2, y2) class MathtextBackendPdf () Bases: matplotlib.mathtext.MathtextBackend Store information to write a mathtext rendering to the PDF backend. get_results(box) render_glyph(ox, oy, info) render_rect_filled(x1, y1, x2, y2) class MathtextBackendPs() Bases: matplotlib.mathtext.MathtextBackend Store information to write a mathtext rendering to the PostScript backend. get_results(box) render_glyph(ox, oy, info) render_rect_filled(x1, y1, x2, y2) class MathtextBackendSvg() Bases: matplotlib.mathtext.MathtextBackend Store information to write a mathtext rendering to the SVG backend. get_results(box) render_glyph(ox, oy, info) render_rect_filled(x1, y1, x2, y2) class NegFil() Bases: matplotlib.mathtext.Glue class NegFill() Bases: matplotlib.mathtext.Glue 604 Chapter 45. matplotlib mathtext Matplotlib, Release 0.99.1.1 class NegFilll() Bases: matplotlib.mathtext.Glue class Node() Bases: object A node in the TeX box model get_kerning(next) grow() Grows one level larger. There is no limit to how big something can get. render(x, y) shrink() Shrinks one level smaller. There are only three levels of sizes, after which things will no longer get smaller. class Parser() Bases: object This is the pyparsing-based parser for math expressions. It actually parses full strings containing math expressions, in that raw text may also appear outside of pairs of$. The grammar is based directly on that in TeX, though it cuts a few corners. class State(font_output, font, font_class, fontsize, dpi) Bases: object Stores the state of the parser. States are pushed and popped from a stack as necessary, and the “current” state is always at the top of the stack. copy() font accent(s, loc, toks) auto_sized_delimiter(s, loc, toks) char_over_chars(s, loc, toks) clear() Clear any state before parsing. customspace(s, loc, toks) end_group(s, loc, toks) finish(s, loc, toks) font(s, loc, toks) frac(s, loc, toks) function(s, loc, toks) 45.1. matplotlib.mathtext 605 Matplotlib, Release 0.99.1.1 get_state() Get the current State of the parser. group(s, loc, toks) is_dropsub(nucleus) is_overunder(nucleus) is_slanted(nucleus) math(s, loc, toks) non_math(s, loc, toks) parse(s, fonts_object, fontsize, dpi) Parse expression s using the given fonts_object for output, at the given fontsize and dpi. Returns the parse tree of Node instances. pop_state() Pop a State oﬀ of the stack. push_state() Push a new State onto the stack which is just a copy of the current state. space(s, loc, toks) sqrt(s, loc, toks) start_group(s, loc, toks) subsuperscript(s, loc, toks) symbol(s, loc, toks) class Rule(width, height, depth, state) Bases: matplotlib.mathtext.Box A Rule node stands for a solid black rectangle; it has width, depth, and height ﬁelds just as in an Hlist. However, if any of these dimensions is inf, the actual value will be determined by running the rule up to the boundary of the innermost enclosing box. This is called a “running dimension.” The width is never running in an Hlist; the height and depth are never running in a Vlist. render(x, y, w, h) class Ship() Bases: object Once the boxes have been set up, this sends them to output. Since boxes can be inside of boxes inside of boxes, the main work of Ship is done by two mutually recursive routines, hlist_out() and vlist_out(), which traverse the Hlist nodes and Vlist nodes inside of horizontal and vertical boxes. The global variables used in TeX to store state as it processes have become member variables here. static clamp(value) hlist_out(box) 606 Chapter 45. matplotlib mathtext Matplotlib, Release 0.99.1.1 vlist_out(box) class SsGlue() Bases: matplotlib.mathtext.Glue class StandardPsFonts(default_font_prop) Bases: matplotlib.mathtext.Fonts Use the standard postscript fonts for rendering to backend_ps Unlike the other font classes, BakomaFont and UnicodeFont, this one requires the Ps backend. get_kern(font1, fontclass1, sym1, fontsize1, font2, fontclass2, sym2, fontsize2, dpi) get_underline_thickness(font, fontsize, dpi) get_xheight(font, fontsize, dpi) class StixFonts(*args, **kwargs) Bases: matplotlib.mathtext.UnicodeFonts A font handling class for the STIX fonts. In addition to what UnicodeFonts provides, this class: •supports “virtual fonts” which are complete alpha numeric character sets with diﬀerent font styles at special Unicode code points, such as “Blackboard”. •handles sized alternative characters for the STIXSizeX fonts. get_sized_alternatives_for_symbol(fontname, sym) class StixSansFonts(*args, **kwargs) Bases: matplotlib.mathtext.StixFonts A font handling class for the STIX fonts (that uses sans-serif characters by default). class SubSuperCluster() Bases: matplotlib.mathtext.Hlist SubSuperCluster is a sort of hack to get around that fact that this code do a two-pass parse like TeX. This lets us store enough information in the hlist itself, namely the nucleus, sub- and super-script, such that if another script follows that needs to be attached, it can be reconﬁgured on the ﬂy. class TruetypeFonts(default_font_prop, mathtext_backend) Bases: matplotlib.mathtext.Fonts A generic base class for all font setups that use Truetype fonts (through FT2Font). class CachedFont(font) destroy() get_kern(font1, fontclass1, sym1, fontsize1, font2, fontclass2, sym2, fontsize2, dpi) get_underline_thickness(font, fontsize, dpi) get_xheight(font, fontsize, dpi) 45.1. matplotlib.mathtext 607 Matplotlib, Release 0.99.1.1 class UnicodeFonts(*args, **kwargs) Bases: matplotlib.mathtext.TruetypeFonts An abstract base class for handling Unicode fonts. While some reasonably complete Unicode fonts (such as DejaVu) may work in some situations, the only Unicode font I’m aware of with a complete set of math symbols is STIX. This class will “fallback” on the Bakoma fonts when a required symbol can not be found in the font. get_sized_alternatives_for_symbol(fontname, sym) class VCentered(elements) Bases: matplotlib.mathtext.Hlist A convenience class to create a Vlist whose contents are centered within its enclosing box. class Vbox(height, depth) Bases: matplotlib.mathtext.Box A box with only height (zero width). class Vlist(elements, h=0.0, m=’additional’) Bases: matplotlib.mathtext.List A vertical list of boxes. vpack(h=0.0, m=’additional’, l=inf ) The main duty of vpack() is to compute the dimensions of the resulting boxes, and to adjust the glue if one of those dimensions is pre-speciﬁed. •h: speciﬁes a height •m: is either ‘exactly’ or ‘additional’. •l: a maximum height Thus, vpack(h, ’exactly’) produces a box whose height is exactly h, while vpack(h, ’additional’) yields a box whose height is the natural height plus h. The default values produce a box with the natural width. class Vrule(state) Bases: matplotlib.mathtext.Rule Convenience class to create a vertical rule. get_unicode_index(symbol) get_unicode_index(symbol) -> integer Return the integer index (from the Unicode table) of symbol. symbol can be a single unicode character, a TeX command (i.e. r’pi’), or a Type1 symbol name (i.e. ‘phi’). 608 Chapter 45. matplotlib mathtext CHAPTER FORTYSIX MATPLOTLIB MLAB 46.1 matplotlib.mlab Numerical python functions written for compatability with matlab(TM) commands with the same names. 46.1.1 Matlab(TM) compatible functions cohere() Coherence (normalized cross spectral density) csd() Cross spectral density uing Welch’s average periodogram detrend() Remove the mean or best ﬁt line from an array find() Return the indices where some condition is true; numpy.nonzero is similar but more general. griddata() interpolate irregularly distributed data to a regular grid. prctile() ﬁnd the percentiles of a sequence prepca() Principal Component Analysis psd() Power spectral density uing Welch’s average periodogram rk4() A 4th order runge kutta integrator for 1D or ND systems specgram() Spectrogram (power spectral density over segments of time) 46.1.2 Miscellaneous functions Functions that don’t exist in matlab(TM), but are useful anyway: cohere_pairs() Coherence over all pairs. This is not a matlab function, but we compute coherence a lot in my lab, and we compute it for a lot of pairs. This function is optimized to do this eﬃciently by caching the direct FFTs. rk4() A 4th order Runge-Kutta ODE integrator in case you ever ﬁnd yourself stranded without scipy (and the far superior scipy.integrate tools) contiguous_regions() return the indices of the regions spanned by some logical mask 609 Matplotlib, Release 0.99.1.1 cross_from_below() return the indices where a 1D array crosses a threshold from below cross_from_above() return the indices where a 1D array crosses a threshold from above 46.1.3 record array helper functions A collection of helper methods for numpyrecord arrays See misc Examples rec2txt() pretty print a record array rec2csv() store record array in CSV ﬁle csv2rec() import record array from CSV ﬁle with type inspection rec_append_fields() adds ﬁeld(s)/array(s) to record array rec_drop_fields() drop ﬁelds from record array rec_join() join two record arrays on sequence of ﬁelds rec_groupby() summarize data by groups (similar to SQL GROUP BY) rec_summarize() helper code to ﬁlter rec array ﬁelds into new ﬁelds For the rec viewer functions(e rec2csv), there are a bunch of Format objects you can pass into the functions that will do things like color negative values red, set percent formatting and scaling, etc. Example usage: r = csv2rec(’somefile.csv’, checkrows=0) formatd = dict( weight = FormatFloat(2), change = FormatPercent(2), cost = FormatThousands(2), ) rec2excel(r, ’test.xls’, formatd=formatd) rec2csv(r, ’test.csv’, formatd=formatd) scroll = rec2gtk(r, formatd=formatd) win = gtk.Window() win.set_size_request(600,800) win.add(scroll) win.show_all() gtk.main() 46.1.4 Deprecated functions The following are deprecated; please import directly from numpy (with care–function signatures may diﬀer): 610 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 load() load ASCII ﬁle - use numpy.loadtxt save() save ASCII ﬁle - use numpy.savetxt class FIFOBuffer(nmax) A FIFO queue to hold incoming x, y data in a rotating buﬀer using numpy arrays under the hood. It is assumed that you will call asarrays much less frequently than you add data to the queue – otherwise another data structure will be faster. This can be used to support plots where data is added from a real time feed and the plot object wants to grab data from the buﬀer and plot it to screen less freqeuently than the incoming. If you set the dataLim attr to BBox (eg matplotlib.Axes.dataLim), the dataLim will be updated as new data come in. TODO: add a grow method that will extend nmax Note: mlab seems like the wrong place for this class. Buﬀer up to nmax points. add(x, y) Add scalar x and y to the queue. asarrays() Return x and y as arrays; their length will be the len of data added or nmax. last() Get the last x, y or None. None if no data set. register(func, N ) Call func every time N events are passed; func signature is func(fifo). update_datalim_to_current() Update the datalim in the current data in the ﬁfo. class FormatBool() Bases: matplotlib.mlab.FormatObj fromstr(s) toval(x) class FormatDate(fmt) Bases: matplotlib.mlab.FormatObj fromstr(x) toval(x) class FormatDatetime(fmt=’%Y-%m-%d %H:%M:%S’) Bases: matplotlib.mlab.FormatDate fromstr(x) class FormatFloat(precision=4, scale=1.0) Bases: matplotlib.mlab.FormatFormatStr fromstr(s) 46.1. matplotlib.mlab 611 Matplotlib, Release 0.99.1.1 toval(x) class FormatFormatStr(fmt) Bases: matplotlib.mlab.FormatObj tostr(x) class FormatInt() Bases: matplotlib.mlab.FormatObj fromstr(s) tostr(x) toval(x) class FormatMillions(precision=4) Bases: matplotlib.mlab.FormatFloat class FormatObj() fromstr(s) tostr(x) toval(x) class FormatPercent(precision=4) Bases: matplotlib.mlab.FormatFloat class FormatString() Bases: matplotlib.mlab.FormatObj tostr(x) class FormatThousands(precision=4) Bases: matplotlib.mlab.FormatFloat amap(fn, *args) amap(function, sequence[, sequence, ...]) -> array. Works like map(), but it returns an array. numpy.array(map(...)). This is just a convenient shorthand for base_repr(number, base=2, padding=0) Return the representation of a number in any given base. binary_repr(number, max_length=1025) Return the binary representation of the input number as a string. This is more eﬃcient than using base_repr() with base 2. Increase the value of max_length for very large numbers. Note that on 32-bit machines, 2**1023 is the largest integer power of 2 which can be converted to a Python ﬂoat. bivariate_normal(X, Y, sigmax=1.0, sigmay=1.0, mux=0.0, muy=0.0, sigmaxy=0.0) Bivariate Gaussian distribution for equal shape X, Y. 612 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 See bivariate normal at mathworld. center_matrix(M, dim=0) Return the matrix M with each row having zero mean and unit std. If dim = 1 operate on columns instead of rows. (dim is opposite to the numpy axis kwarg.) cohere(x, y, NFFT=256, Fs=2, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None) The coherence between x and y. Coherence is the normalized cross spectral density: C xy = |P xy |2 P xx Pyy (46.1) x, y Array or sequence containing the data Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. 46.1. matplotlib.mlab 613 Matplotlib, Release 0.99.1.1 The return value is the tuple (Cxy, f ), where f are the frequencies of the coherence vector. For cohere, scaling the individual densities by the sampling frequency has no eﬀect, since the factors cancel out. See Also: psd() and csd() For information about the methods used to compute P xy , P xx and Pyy . cohere_pairs(X, ij, NFFT=256, Fs=2, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, preferSpeedOverMemory=True, progressCallback=<function donothing_callback at 0x30bca28>, returnPxx=False) Call signature: Cxy, Phase, freqs = cohere_pairs( X, ij, ...) Compute the coherence and phase for all pairs ij, in X. X is a numSamples * numCols array ij is a list of tuples. Each tuple is a pair of indexes into the columns of X for which you want to compute coherence. For example, if X has 64 columns, and you want to compute all nonredundant pairs, deﬁne ij as: ij = for i in range(64): for j in range(i+1,64): ij.append( (i,j) ) preferSpeedOverMemory is an optional bool. Defaults to true. If False, limits the caching by only making one, rather than two, complex cache arrays. This is useful if memory becomes critical. Even when preferSpeedOverMemory is False, cohere_pairs() will still give signiﬁcant performace gains over calling cohere() for each pair, and will use subtantially less memory than if preferSpeedOverMemory is True. In my tests with a 43000,64 array over all nonredundant pairs, preferSpeedOverMemory = True delivered a 33% performance boost on a 1.7GHZ Athlon with 512MB RAM compared with preferSpeedOverMemory = False. But both solutions were more than 10x faster than naively crunching all possible pairs through cohere(). Returns: (Cxy, Phase, freqs) where: •Cxy: dictionary of (i, j) tuples -> coherence vector for that pair. cohere(X[:,i], X[:,j]). Number of dictionary keys is len(ij). I.e., Cxy[(i,j) = •Phase: dictionary of phases of the cross spectral density at each frequency for each pair. Keys are (i, j). •freqs: vector of frequencies, equal in length to either the coherence or phase vectors for any (i, j) key. 614 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 Eg., to make a coherence Bode plot: subplot(211) plot( freqs, Cxy[(12,19)]) subplot(212) plot( freqs, Phase[(12,19)]) For a large number of pairs, cohere_pairs() can be much more eﬃcient than just calling cohere() for each pair, because it caches most of the intensive computations. If N is the number of pairs, this function is O(N ) for most of the heavy lifting, whereas calling cohere for each pair is O(N 2 ). However, because of the caching, it is also more memory intensive, making 2 additional complex arrays with approximately the same number of elements as X. See test/cohere_pairs_test.py in the src tree for an example script that shows that this cohere_pairs() and cohere() give the same results for a given pair. See Also: psd() For information about the methods used to compute P xy , P xx and Pyy . contiguous_regions(mask) return a list of (ind0, ind1) such that mask[ind0:ind1].all() is True and we cover all such regions TODO: this is a pure python implementation which probably has a much faster numpy impl cross_from_above(x, threshold) return the indices into x where x crosses some threshold from below, eg the i’s where: x[i-1]>threshold and x[i]<=threshold See Also: cross_from_below() and contiguous_regions() cross_from_below(x, threshold) return the indices into x where x crosses some threshold from below, eg the i’s where: x[i-1]<threshold and x[i]>=threshold Example code: import matplotlib.pyplot as plt t = np.arange(0.0, 2.0, 0.1) s = np.sin(2*np.pi*t) fig = plt.figure() ax = fig.add_subplot(111) ax.plot(t, s, ’-o’) ax.axhline(0.5) ax.axhline(-0.5) 46.1. matplotlib.mlab 615 Matplotlib, Release 0.99.1.1 ind = cross_from_below(s, 0.5) ax.vlines(t[ind], -1, 1) ind = cross_from_above(s, -0.5) ax.vlines(t[ind], -1, 1) plt.show() See Also: cross_from_above() and contiguous_regions() csd(x, y, NFFT=256, Fs=2, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None) The cross power spectral density by Welch’s average periodogram method. The vectors x and y are divided into NFFT length blocks. Each block is detrended by the function detrend and windowed by the function window. noverlap gives the length of the overlap between blocks. The product of the direct FFTs of x and y are averaged over each segment to compute Pxy, with a scaling to correct for power loss due to windowing. If len(x) < NFFT or len(y) < NFFT, they will be zero padded to NFFT. x, y Array or sequence containing the data Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT 616 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Returns the tuple (Pxy, freqs). Refs: Bendat & Piersol – Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986) csv2rec(fname, comments=’#’, skiprows=0, checkrows=0, delimiter=’, ’, converterd=None, names=None, missing=”, missingd=None, use_mrecords=False) Load data from comma/space/tab delimited ﬁle in fname into a numpy record array and return the record array. If names is None, a header row is required to automatically assign the recarray names. The headers will be lower cased, spaces will be converted to underscores, and illegal attribute name characters removed. If names is not None, it is a sequence of names to use for the column names. In this case, it is assumed there is no header row. •fname: can be a ﬁlename or a ﬁle handle. Support for gzipped ﬁles is automatic, if the ﬁlename ends in ‘.gz’ •comments: the character used to indicate the start of a comment in the ﬁle •skiprows: is the number of rows from the top to skip •checkrows: is the number of rows to check to validate the column data type. When set to zero all rows are validated. •converted: if not None, is a dictionary mapping column number or munged column name to a converter function. •names: if not None, is a list of header names. In this case, no header will be read from the ﬁle •missingd is a dictionary mapping munged column names to ﬁeld values which signify that the ﬁeld does not contain actual data and should be masked, e.g. ‘0000-00-00’ or ‘unused’ •missing: a string whose value signals a missing ﬁeld regardless of the column it appears in •use_mrecords: if True, return an mrecords.fromrecords record array if any of the data are missing If no rows are found, None is returned – see examples/loadrec.py csvformat_factory(format) demean(x, axis=0) Return x minus its mean along the speciﬁed axis detrend(x, key=None) detrend_linear(y) Return y minus best ﬁt line; ‘linear’ detrending 46.1. matplotlib.mlab 617 Matplotlib, Release 0.99.1.1 detrend_mean(x) Return x minus the mean(x) detrend_none(x) Return x: no detrending dist(x, y) Return the distance between two points. dist_point_to_segment(p, s0, s1) Get the distance of a point to a segment. p, s0, s1 are xy sequences This algorithm from http://softsurfer.com/Archive/algorithm_0102/algorithm_0102.htm#Distance%20to%20Ray%20o distances_along_curve(X ) Computes the distance between a set of successive points in N dimensions. Where X is an M x N array or matrix. The distances between successive rows is computed. Distance is the standard Euclidean distance. donothing_callback(*args) entropy(y, bins) Return the entropy of the data in y. ￿ pi log2 ( pi ) (46.2) where pi is the probability of observing y in the ith bin of bins. bins can be a number of bins or a range of bins; see numpy.histogram(). Compare S with analytic calculation for a Gaussian: x = mu + sigma * randn(200000) Sanalytic = 0.5 * ( 1.0 + log(2*pi*sigma**2.0) ) exp_safe(x) Compute exponentials which safely underﬂow to zero. Slow, but convenient to use. Note that numpy provides proper ﬂoating point exception handling with access to the underlying hardware. fftsurr(x, detrend=<function detrend_none at 0x30b5d70>, window=<function window_none at 0x30b5050>) Compute an FFT phase randomized surrogate of x. find(condition) Return the indices where ravel(condition) is true frange(xini, xﬁn=None, delta=None, **kw) frange([start,] stop[, step, keywords]) -> array of ﬂoats Return a numpy ndarray containing a progression of ﬂoats. Similar to numpy.arange(), but defaults to a closed interval. frange(x0, x1) returns [x0, x0+1, x0+2, ..., x1]; start defaults to 0, and the endpoint is included. This behavior is diﬀerent from that of range() and numpy.arange(). This is deliberate, 618 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 since frange() will probably be more useful for generating lists of points for function evaluation, and endpoints are often desired in this use. The usual behavior of range() can be obtained by setting the keyword closed = 0, in this case, frange() basically becomes :func:numpy.arange‘. When step is given, it speciﬁes the increment (or decrement). All arguments can be ﬂoating point numbers. frange(x0,x1,d) returns [x0,x0+d,x0+2d,...,xfin] where xﬁn <= x1. frange() can also be called with the keyword npts. This sets the number of points the list should contain (and overrides the value step might have been given). numpy.arange() doesn’t oﬀer this option. Examples: >>> frange(3) array([ 0., 1., 2., 3.]) >>> frange(3,closed=0) array([ 0., 1., 2.]) >>> frange(1,6,2) array([1, 3, 5]) or 1,3,5,7, depending on floating point vagueries >>> frange(1,6.5,npts=5) array([ 1. , 2.375, 3.75 , 5.125, 6.5 ]) get_formatd(r, formatd=None) build a formatd guaranteed to have a key for every dtype name get_sparse_matrix(M, N, frac=0.10000000000000001) Return a M x N sparse matrix with frac elements randomly ﬁlled. get_xyz_where(Z, Cond) Z and Cond are M x N matrices. Z are data and Cond is a boolean matrix where some condition is satisﬁed. Return value is (x, y, z) where x and y are the indices into Z and z are the values of Z at those indices. x, y, and z are 1D arrays. griddata(x, y, z, xi, yi, interp=’nn’) zi = griddata(x,y,z,xi,yi) ﬁts a surface of the form z = f*(*x, y) to the data in the (usually) nonuniformly spaced vectors (x, y, z). griddata() interpolates this surface at the points speciﬁed by (xi, yi) to produce zi. xi and yi must describe a regular grid, can be either 1D or 2D, but must be monotonically increasing. A masked array is returned if any grid points are outside convex hull deﬁned by input data (no extrapolation is done). If interp keyword is set to ‘nn‘ (default), uses natural neighbor interpolation based on Delaunay triangulation. By default, this algorithm is provided by the matplotlib.delaunay package, written by Robert Kern. The triangulation algorithm in this package is known to fail on some nearly pathological cases. For this reason, a separate toolkit (mpl_tookits.natgrid) has been created that provides a more robust algorithm fof triangulation and interpolation. This toolkit is based on the NCAR natgrid library, which contains code that is not redistributable under a BSD-compatible license. When installed, this function will use the mpl_toolkits.natgrid algorithm, otherwise it will use the built-in matplotlib.delaunay package. 46.1. matplotlib.mlab 619 Matplotlib, Release 0.99.1.1 If the interp keyword is set to ‘linear‘, then linear interpolation is used instead of natural neighbor. In this case, the output grid is assumed to be regular with a constant grid spacing in both the x and y directions. For regular grids with nonconstant grid spacing, you must use natural neighbor interpolation. Linear interpolation is only valid if matplotlib.delaunay package is used mpl_tookits.natgrid only provides natural neighbor interpolation. The natgrid matplotlib toolkit can be downloaded from http://sourceforge.net/project/showﬁles.php?group_id=80706& identity(n, rank=2, dtype=’l’, typecode=None) Returns the identity matrix of shape (n, n, ..., n) (rank r). For ranks higher than 2, this object is simply a multi-index Kronecker delta: / id[i0,i1,...,iR] = -| \ 1 if i0=i1=...=iR, 0 otherwise. Optionally a dtype (or typecode) may be given (it defaults to ‘l’). Since rank defaults to 2, this function behaves in the default case (when only n is given) like numpy.identity(n) – but surprisingly, it is much faster. inside_poly(points, verts) points is a sequence of x, y points. verts is a sequence of x, y vertices of a polygon. Return value is a sequence of indices into points for the points that are inside the polygon. is_closed_polygon(X ) Tests whether ﬁrst and last object in a sequence are the same. These are presumably coordinates on a polygonal curve, in which case this function tests if that curve is closed. ispower2(n) Returns the log base 2 of n if n is a power of 2, zero otherwise. Note the potential ambiguity if n == 1: 2**0 == 1, interpret accordingly. isvector(X ) Like the Matlab (TM) function with the same name, returns True if the supplied numpy array or matrix X looks like a vector, meaning it has a one non-singleton axis (i.e., it can have multiple axes, but all must have length 1, except for one of them). If you just want to see if the array has 1 axis, use X.ndim == 1. l1norm(a) Return the l1 norm of a, ﬂattened out. Implemented as a separate function (not a call to norm() for speed). l2norm(a) Return the l2 norm of a, ﬂattened out. Implemented as a separate function (not a call to norm() for speed). less_simple_linear_interpolation(x, y, xi, extrap=False) This function provides simple (but cbook.simple_linear_interpolation()) 620 somewhat linear less so than interpolation. Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 simple_linear_interpolation() will give a list of point between a start and an end, while this does true linear interpolation at an arbitrary set of points. This is very ineﬃcient linear interpolation meant to be used only for a small number of points in relatively non-intensive use cases. For real linear interpolation, use scipy. levypdf (x, gamma, alpha) Returm the levy pdf evaluated at x for params gamma, alpha liaupunov(x, fprime) x is a very long trajectory from a map, and fprime returns the derivative of x. This function will be removed from matplotlib. Returns : .. math: \lambda = \frac{1}{n}\sum \ln|f^’(x_i)| See Also: Lyapunov Exponent Sec 10.5 Strogatz (1994) “Nonlinear Dynamics and Chaos”. Wikipedia article on Lyapunov Exponent. Note: What the function here calculates may not be what you really want; caveat emptor. It also seems that this function’s name is badly misspelled. load(fname, comments=’#’, delimiter=None, converters=None, skiprows=0, usecols=None, unpack=False, dtype=<type ’numpy.ﬂoat64’>) Load ASCII data from fname into an array and return the array. Deprecated: use numpy.loadtxt. The data must be regular, same number of values in every row fname can be a ﬁlename or a ﬁle handle. Support for gzipped ﬁles is automatic, if the ﬁlename ends in ‘.gz’. matﬁle data is not supported; for that, use scipy.io.mio module. Example usage: X = load(’test.dat’) t = X[:,0] y = X[:,1] # data in two columns Alternatively, you can do the same with “unpack”; see below: X = load(’test.dat’) x = load(’test.dat’) # a matrix of data # a single column of data •comments: the character used to indicate the start of a comment in the ﬁle 46.1. matplotlib.mlab 621 Matplotlib, Release 0.99.1.1 •delimiter is a string-like character used to seperate values in the ﬁle. If delimiter is unspeciﬁed or None, any whitespace string is a separator. •converters, if not None, is a dictionary mapping column number to a function that will convert that column to a ﬂoat (or the optional dtype if speciﬁed). Eg, if column 0 is a date string: converters = {0:datestr2num} •skiprows is the number of rows from the top to skip. •usecols, if not None, is a sequence of integer column indexes to extract where 0 is the ﬁrst column, eg usecols=[1,4,5] to extract just the 2nd, 5th and 6th columns •unpack, if True, will transpose the matrix allowing you to unpack into named arguments on the left hand side: t,y = load(’test.dat’, unpack=True) # for two column data x,y,z = load(’somefile.dat’, usecols=[3,5,7], unpack=True) •dtype: the array will have this dtype. default: numpy.float_ See Also: See examples/pylab_examples/load_converter.py in the source tree Exercises these options. many of log2(x, ln2=0.69314718055994529) Return the log(x) in base 2. This is a _slow_ function but which is guaranteed to return the correct integer value if the input is an integer exact power of 2. logspace(xmin, xmax, N ) longest_contiguous_ones(x) Return the indices of the longest stretch of contiguous ones in x, assuming x is a vector of zeros and ones. If there are two equally long stretches, pick the ﬁrst. longest_ones(x) alias for longest_contiguous_ones movavg(x, n) Compute the len(n) moving average of x. norm_flat(a, p=2) norm(a,p=2) -> l-p norm of a.ﬂat Return the l-p norm of a, considered as a ﬂat array. This is NOT a true matrix norm, since arrays of arbitrary rank are always ﬂattened. p can be a number or the string ‘Inﬁnity’ to get the L-inﬁnity norm. normpdf (x, *args) Return the normal pdf evaluated at x; args provides mu, sigma 622 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 path_length(X ) Computes the distance travelled along a polygonal curve in N dimensions. Where X is an M x N array or matrix. Returns an array of length M consisting of the distance along the curve at each point (i.e., the rows of X ). poly_below(xmin, xs, ys) Given a sequence of xs and ys, return the vertices of a polygon that has a horizontal base at xmin and an upper bound at the ys. xmin is a scalar. Intended for use with matplotlib.axes.Axes.fill(), eg: xv, yv = poly_below(0, x, y) ax.fill(xv, yv) poly_between(x, ylower, yupper) Given a sequence of x, ylower and yupper, return the polygon that ﬁlls the regions between them. ylower or yupper can be scalar or iterable. If they are iterable, they must be equal in length to x. Return value is x, y arrays for use with matplotlib.axes.Axes.fill(). prctile(x, p=(0.0, 25.0, 50.0, 75.0, 100.0)) Return the percentiles of x. p can either be a sequence of percentile values or a scalar. If p is a sequence, the ith element of the return sequence is the p*(i)-th percentile of *x. If p is a scalar, the largest value of x less than or equal to the p percentage point in the sequence is returned. prctile_rank(x, p) Return the rank for each element in x, return the rank 0..len(p). Eg if p = (25, 50, 75), the return value will be a len(x) array with values in [0,1,2,3] where 0 indicates the value is less than the 25th percentile, 1 indicates the value is >= the 25th and < 50th percentile, ... and 3 indicates the value is above the 75th percentile cutoﬀ. p is either an array of percentiles in [0..100] or a scalar which indicates how many quantiles of data you want ranked. prepca(P, frac=0) Compute the principal components of P. P is a (numVars, numObs) array. frac is the minimum fraction of variance that a component must contain to be included. Return value is a tuple of the form (Pcomponents, Trans, fracVar) where: •Pcomponents : a (numVars, numObs) array •Trans [the weights matrix, ie, Pcomponents = Trans *] P •fracVar [the fraction of the variance accounted for by each] component returned A similar function of the same name was in the Matlab (TM) R13 Neural Network Toolbox but is not found in later versions; its successor seems to be called “processpcs”. psd(x, NFFT=256, Fs=2, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None) The power spectral density by Welch’s average periodogram method. The vector x is divided into NFFT length blocks. Each block is detrended by the function detrend and windowed by the function 46.1. matplotlib.mlab 623 Matplotlib, Release 0.99.1.1 window. noverlap gives the length of the overlap between blocks. The absolute(ﬀt(block))**2 of each segment are averaged to compute Pxx, with a scaling to correct for power loss due to windowing. If len(x) < NFFT, it will be zero padded to NFFT. x Array or sequence containing the data Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Returns the tuple (Pxx, freqs). Refs: Bendat & Piersol – Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986) 624 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 quad2cubic(q0x, q0y, q1x, q1y, q2x, q2y) Converts a quadratic Bezier curve to a cubic approximation. The inputs are the x and y coordinates of the three control points of a quadratic curve, and the output is a tuple of x and y coordinates of the four control points of the cubic curve. rec2csv(r, fname, delimiter=’, ’, formatd=None, missing=”, missingd=None, withheader=True) Save the data from numpy recarray r into a comma-/space-/tab-delimited ﬁle. The record array dtype names will be used for column headers. fname: can be a ﬁlename or a ﬁle handle. Support for gzipped ﬁles is automatic, if the ﬁlename ends in ‘.gz’ withheader: if withheader is False, do not write the attribute names in the ﬁrst row See Also: csv2rec() For information about missing and missingd, which can be used to ﬁll in masked values into your CSV ﬁle. rec2txt(r, header=None, padding=3, precision=3, ﬁelds=None) Returns a textual representation of a record array. r: numpy recarray header: list of column headers padding: space between each column precision: number of decimal places to use for ﬂoats. Set to an integer to apply to all ﬂoats. Set to a list of integers to apply precision individually. Precision for non-ﬂoats is simply ignored. ﬁelds : if not None, a list of ﬁeld names to print. ﬁelds can be a list of strings like [’ﬁeld1’, ‘ﬁeld2’] or a single comma separated string like ‘ﬁeld1,ﬁeld2’ Example: precision=[0,2,3] Output: ID ABC XYZ Price 12.54 6.32 Return 0.234 -0.076 rec_append_fields(rec, names, arrs, dtypes=None) Return a new record array with ﬁeld names populated with data from arrays in arrs. If appending a single ﬁeld, then names, arrs and dtypes do not have to be lists. They can just be the values themselves. rec_drop_fields(rec, names) Return a new numpy record array with ﬁelds in names dropped. rec_groupby(r, groupby, stats) r is a numpy record array 46.1. matplotlib.mlab 625 Matplotlib, Release 0.99.1.1 groupby is a sequence of record array attribute names that together form the grouping key. eg (‘date’, ‘productcode’) stats is a sequence of (attr, func, outname) tuples which will call x = func(attr) and assign x to the record array output with attribute outname. For example: stats = ( (’sales’, len, ’numsales’), (’sales’, np.mean, ’avgsale’) ) Return record array has dtype names for each attribute name in the the groupby argument, with the associated group values, and for each outname name in the stats argument, with the associated stat summary output. rec_join(key, r1, r2, jointype=’inner’, defaults=None, r1postﬁx=’1’, r2postﬁx=’2’) Join record arrays r1 and r2 on key; key is a tuple of ﬁeld names – if key is a string it is assumed to be a single attribute name. If r1 and r2 have equal values on all the keys in the key tuple, then their ﬁelds will be merged into a new record array containing the intersection of the ﬁelds of r1 and r2. r1 (also r2) must not have any duplicate keys. The jointype keyword can be ‘inner’, ‘outer’, ‘leftouter’. To do a rightouter join just reverse r1 and r2. The defaults keyword is a dictionary ﬁlled with {column_name:default_value} pairs. The keywords r1postﬁx and r2postﬁx are postﬁxed to column names (other than keys) that are both in r1 and r2. rec_keep_fields(rec, names) Return a new numpy record array with only ﬁelds listed in names rec_summarize(r, summaryfuncs) r is a numpy record array summaryfuncs is a list of (attr, func, outname) tuples which will apply func to the the array r*[attr] and assign the output to a new attribute name *outname. The returned record array is identical to r, with extra arrays for each element in summaryfuncs. rk4(derivs, y0, t) Integrate 1D or ND system of ODEs using 4-th order Runge-Kutta. This is a toy implementation which may be useful if you ﬁnd yourself stranded on a system w/o scipy. Otherwise use scipy.integrate(). y0 initial state vector t sample times derivs returns the derivative of the system and has the signature dy = derivs(yi, ti) Example 1 ## 2D system def derivs6(x,t): d1 = x[0] + 2*x[1] d2 = -3*x[0] + 4*x[1] 626 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 return (d1, d2) dt = 0.0005 t = arange(0.0, 2.0, dt) y0 = (1,2) yout = rk4(derivs6, y0, t) Example 2: ## 1D system alpha = 2 def derivs(x,t): return -alpha*x + exp(-t) y0 = 1 yout = rk4(derivs, y0, t) If you have access to scipy, you should probably be using the scipy.integrate tools rather than this function. rms_flat(a) Return the root mean square of all the elements of a, ﬂattened out. safe_isinf (x) numpy.isinf() for arbitrary types safe_isnan(x) numpy.isnan() for arbitrary types save(fname, X, fmt=’%.18e’, delimiter=’ ’) Save the data in X to ﬁle fname using fmt string to convert the data to strings. Deprecated. Use numpy.savetxt. fname can be a ﬁlename or a ﬁle handle. If the ﬁlename ends in ‘.gz’, the ﬁle is automatically saved in compressed gzip format. The load() function understands gzipped ﬁles transparently. Example usage: save(’test.out’, X) # X is an array save(’test1.out’, (x,y,z)) # x,y,z equal sized 1D arrays save(’test2.out’, x) # x is 1D save(’test3.out’, x, fmt=’%1.4e’) # use exponential notation delimiter is used to separate the ﬁelds, eg. delimiter ‘,’ for comma-separated values. segments_intersect(s1, s2) Return True if s1 and s2 intersect. s1 and s2 are deﬁned as: s1: (x1, y1), (x2, y2) s2: (x3, y3), (x4, y4) slopes(x, y) slopes() calculates the slope y‘(x) 46.1. matplotlib.mlab 627 Matplotlib, Release 0.99.1.1 The slope is estimated using the slope obtained from that of a parabola through any three consecutive points. This method should be superior to that described in the appendix of A CONSISTENTLY WELL BEHAVED METHOD OF INTERPOLATION by Russel W. Stineman (Creative Computing July 1980) in at least one aspect: Circles for interpolation demand a known aspect ratio between x- and y-values. For many functions, however, the abscissa are given in diﬀerent dimensions, so an aspect ratio is completely arbitrary. The parabola method gives very similar results to the circle method for most regular cases but behaves much better in special cases. Norbert Nemec, Institute of Theoretical Physics, University or Regensburg, April 2006 Norbert.Nemec at physik.uni-regensburg.de (inspired by a original implementation by Halldor Bjornsson, Icelandic Meteorological Oﬃce, March 2006 halldor at vedur.is) specgram(x, NFFT=256, Fs=2, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=128, pad_to=None, sides=’default’, scale_by_freq=None) Compute a spectrogram of data in x. Data are split into NFFT length segements and the PSD of each section is computed. The windowing function window is applied to each segment, and the amount of overlap of each segment is speciﬁed with noverlap. If x is real (i.e. non-complex) only the spectrum of the positive frequencie is returned. If x is complex then the complete spectrum is returned. Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). 628 Chapter 46. matplotlib mlab Matplotlib, Release 0.99.1.1 pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Returns a tuple (Pxx, freqs, t): •Pxx: 2-D array, columns are the periodograms of successive segments •freqs: 1-D array of frequencies corresponding to the rows in Pxx •t: 1-D array of times corresponding to midpoints of segments. See Also: psd() psd() diﬀers in the default overlap; in returning the mean of the segment periodograms; and in not returning times. stineman_interp(xi, x, y, yp=None) Given data vectors x and y, the slope vector yp and a new abscissa vector xi, the function stineman_interp() uses Stineman interpolation to calculate a vector yi corresponding to xi. Here’s an example that generates a coarse sine curve, then interpolates over a ﬁner abscissa: x = linspace(0,2*pi,20); y = sin(x); yp = cos(x) xi = linspace(0,2*pi,40); yi = stineman_interp(xi,x,y,yp); plot(x,y,’o’,xi,yi) The interpolation method is described in the article A CONSISTENTLY WELL BEHAVED METHOD OF INTERPOLATION by Russell W. Stineman. The article appeared in the July 1980 issue of Creative Computing with a note from the editor stating that while they were: not an academic journal but once in a while something serious and original comes in adding that this was “apparently a real solution” to a well known problem. For yp = None, the routine automatically determines the slopes using the slopes() routine. x is assumed to be sorted in increasing order. For values xi[j] < x[0] or xi[j] > x[-1], the routine tries an extrapolation. The relevance of the data obtained from this, of course, is questionable... 46.1. matplotlib.mlab 629 Matplotlib, Release 0.99.1.1 Original implementation by Halldor Bjornsson, Icelandic Meteorolocial Oﬃce, March 2006 halldor at vedur.is Completely reworked and optimized for Python by Norbert Nemec, Institute of Theoretical Physics, University or Regensburg, April 2006 Norbert.Nemec at physik.uni-regensburg.de vector_lengths(X, P=2.0, axis=None) Finds the length of a set of vectors in n dimensions. This is like the numpy.norm() function for vectors, but has the ability to work over a particular axis of the supplied array or matrix. Computes (sum((x_i)^P))^(1/P) for each {x_i} being the elements of X along the given axis. If axis is None, compute over all elements of X. window_hanning(x) return x times the hanning window of len(x) window_none(x) No window function; simply return x 630 Chapter 46. matplotlib mlab CHAPTER FORTYSEVEN MATPLOTLIB PATH 47.1 matplotlib.path Contains a class for managing paths (polylines). class Path(vertices, codes=None, _interpolation_steps=1) Bases: object Path represents a series of possibly disconnected, possibly closed, line and curve segments. The underlying storage is made up of two parallel numpy arrays: ray of vertices • vertices: an Nx2 ﬂoat ar- • codes: an N-length uint8 array of vertex types These two arrays always have the same length in the ﬁrst dimension. For example, to represent a cubic curve, you must provide three vertices as well as three codes CURVE3. The code types are: •STOP [1 vertex (ignored)] A marker for the end of the entire path (currently not required and ignored) •MOVETO [1 vertex] Pick up the pen and move to the given vertex. •LINETO [1 vertex] Draw a line from the current position to the given vertex. •CURVE3 [1 control point, 1 endpoint] Draw a quadratic Bezier curve from the current position, with the given control point, to the given end point. •CURVE4 [2 control points, 1 endpoint] Draw a cubic Bezier curve from the current position, with the given control points, to the given end point. •CLOSEPOLY [1 vertex (ignored)] Draw a line segment to the start point of the current polyline. Users of Path objects should not access the vertices and codes arrays directly. Instead, they should use iter_segments() to get the vertex/code pairs. This is important, since many Path objects, as an optimization, do not store a codes at all, but have a default one provided for them by iter_segments(). Note also that the vertices and codes arrays should be treated as immutable – there are a number of optimizations and assumptions made up front in the constructor that will not change when the data changes. 631 Matplotlib, Release 0.99.1.1 Create a new path with the given vertices and codes. vertices is an Nx2 numpy ﬂoat array, masked array or Python sequence. codes is an N-length numpy array or Python sequence of type matplotlib.path.Path.code_type. These two arrays must have the same length in the ﬁrst dimension. If codes is None, vertices will be treated as a series of line segments. If vertices contains masked values, they will be converted to NaNs which are then handled correctly by the Agg PathIterator and other consumers of path data, such as iter_segments(). interpolation_steps is used as a hint to certain projections, such as Polar, that this path should be linearly interpolated immediately before drawing. This attribute is primarily an implementation detail and is not intended for public use. class arc(theta1, theta2, n=None, is_wedge=False) (staticmethod) Returns an arc on the unit circle from angle theta1 to angle theta2 (in degrees). If n is provided, it is the number of spline segments to make. If n is not provided, the number of spline segments is determined based on the delta between theta1 and theta2. Masionobe, L. 2003. Drawing an elliptical arc using polylines, quadratic or cubic Bezier curves. code_type alias of uint8 contains_path(path, transform=None) Returns True if this path completely contains the given path. If transform is not None, the path will be transformed before performing the test. contains_point(point, transform=None) Returns True if the path contains the given point. If transform is not None, the path will be transformed before performing the test. get_extents(transform=None) Returns the extents (xmin, ymin, xmax, ymax) of the path. Unlike computing the extents on the vertices alone, this algorithm will take into account the curves and deal with control points appropriately. class hatch(hatchpattern, density=6) Given a hatch speciﬁer, hatchpattern, generates a Path that can be used in a repeated hatching pattern. density is the number of lines per unit square. interpolated(steps) Returns a new path resampled to length N x steps. Does not currently handle interpolating curves. intersects_bbox(bbox, ﬁlled=True) Returns True if this path intersects a given Bbox. ﬁlled, when True, treats the path as if it was ﬁlled. That is, if one path completely encloses the other, intersects_path() will return True. 632 Chapter 47. matplotlib path Matplotlib, Release 0.99.1.1 intersects_path(other, ﬁlled=True) Returns True if this path intersects another given path. ﬁlled, when True, treats the paths as if they were ﬁlled. That is, if one path completely encloses the other, intersects_path() will return True. iter_segments(transform=None, remove_nans=True, clip=None, quantize=False, simplify=None, curves=True) Iterates over all of the curve segments in the path. Each iteration returns a 2-tuple (vertices, code), where vertices is a sequence of 1 - 3 coordinate pairs, and code is one of the Path codes. Additionally, this method can provide a number of standard cleanups and conversions to the path. transform: if not None, the given aﬃne transformation will be applied to the path. remove_nans: if True, will remove all NaNs from the path and insert MOVETO commands to skip over them. clip: if not None, must be a four-tuple (x1, y1, x2, y2) deﬁning a rectangle in which to clip the path. quantize: if None, auto-quantize. If True, force quantize, and if False, don’t quantize. simplify: if True, perform simpliﬁcation, to remove vertices that do not aﬀect the appearance of the path. If False, perform no simpliﬁcation. If None, use the should_simplify member variable. curves: If True, curve segments will be returned as curve segments. If False, all curves will be converted to line segments. class make_compound_path(*args) (staticmethod) Make a compound path from a list of Path objects. Only polygons (not curves) are supported. class make_compound_path_from_polys(XY ) (static method) Make a compound path object to draw a number of polygons with equal numbers of sides XY is a (numpolys x numsides x 2) numpy array of vertices. Return object is a Path 47.1. matplotlib.path 633 Matplotlib, Release 0.99.1.1 to_polygons(transform=None, width=0, height=0) Convert this path to a list of polygons. Each polygon is an Nx2 array of vertices. In other words, each polygon has no MOVETO instructions or curves. This is useful for displaying in backends that do not support compound paths or Bezier curves, such as GDK. If width and height are both non-zero then the lines will be simpliﬁed so that vertices outside of (0, 0), (width, height) will be clipped. transformed(transform) Return a transformed copy of the path. See Also: matplotlib.transforms.TransformedPath A specialized path class that will cache the transformed result and automatically update when the transform changes. class unit_circle() (staticmethod) Returns a Path of the unit circle. The circle is approximated using cubic Bezier curves. This uses 8 splines around the circle using the approach presented here: Lancaster, Don. Approximating a Circle or an Ellipse Using Four Bezier Cubic Splines. class unit_rectangle() (staticmethod) Returns a Path of the unit rectangle from (0, 0) to (1, 1). 634 Chapter 47. matplotlib path Matplotlib, Release 0.99.1.1 class unit_regular_asterisk(numVertices) (staticmethod) Returns a Path for a unit regular asterisk with the given numVertices and radius of 1.0, centered at (0, 0). class unit_regular_polygon(numVertices) (staticmethod) Returns a Path for a unit regular polygon with the given numVertices and radius of 1.0, centered at (0, 0). class unit_regular_star(numVertices, innerCircle=0.5) (staticmethod) Returns a Path for a unit regular star with the given numVertices and radius of 1.0, centered at (0, 0). class wedge(theta1, theta2, n=None) (staticmethod) Returns a wedge of the unit circle from angle theta1 to angle theta2 (in degrees). If n is provided, it is the number of spline segments to make. If n is not provided, the number of spline segments is determined based on the delta between theta1 and theta2. cleanup_path() cleanup_path(path, trans, remove_nans, clip, quantize, simplify, curves) convert_path_to_polygons() convert_path_to_polygons(path, trans, width, height) get_path_collection_extents(*args) Given a sequence of Path objects, returns the bounding box that encapsulates all of them. get_path_extents() get_path_extents(path, trans) path_in_path() path_in_path(a, atrans, b, btrans) path_intersects_path() path_intersects_path(p1, p2) point_in_path() point_in_path(x, y, path, trans) point_in_path_collection() point_in_path_collection(x, y, r, trans, paths, transforms, oﬀsets, oﬀsetTrans, ﬁlled) 47.1. matplotlib.path 635 Matplotlib, Release 0.99.1.1 636 Chapter 47. matplotlib path CHAPTER FORTYEIGHT MATPLOTLIB PYPLOT 48.1 matplotlib.pyplot acorr(x, hold=None, **kwargs) call signature: acorr(x, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags=10, **kwargs) Plot the autocorrelation of x. If normed = True, normalize the data by the autocorrelation at 0-th lag. x is detrended by the detrend callable (default no normalization). Data are plotted as plot(lags, c, **kwargs) Return value is a tuple (lags, c, line) where: •lags are a length 2*maxlags+1 lag vector •c is the 2*maxlags+1 auto correlation vector •line is a Line2D instance returned by plot() The default linestyle is None and the default marker is ’o’, though these can be overridden with keyword args. The cross correlation is performed with numpy.correlate() with mode = 2. If usevlines is True, vlines() rather than plot() is used to draw vertical lines from the origin to the acorr. Otherwise, the plot style is determined by the kwargs, which are Line2D properties. maxlags is a positive integer detailing the number of lags to show. The default value of None will return all 2imeslen( x) − 1 lags. The return value is a tuple (lags, c, linecol, b) where •linecol is the LineCollection •b is the x-axis. See Also: plot() or vlines() For documentation on valid kwargs. 637 Matplotlib, Release 0.99.1.1 Example: xcorr() above, and acorr() below. Example: Additional kwargs: hold = [True|False] overrides default hold state annotate(*args, **kwargs) call signature: annotate(s, xy, xytext=None, xycoords=’data’, textcoords=’data’, arrowprops=None, **kwargs) Keyword arguments: Annotate the x, y point xy with text s at x, y location xytext. (If xytext = None, defaults to xy, and if textcoords = None, defaults to xycoords). arrowprops, if not None, is a dictionary of line properties (see matplotlib.lines.Line2D) for the arrow that connects annotation to the point. If the dictionary has a key arrowstyle, a FancyArrowPatch instance is created with the given dictionary and is drawn. Otherwise, a YAArow patch instance is created and drawn. Valid keys for YAArow are 638 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Key width frac headwidth shrink ? Description the width of the arrow in points the fraction of the arrow length occupied by the head the width of the base of the arrow head in points oftentimes it is convenient to have the arrowtip and base a bit away from the text and point being annotated. If d is the distance between the text and annotated point, shrink will shorten the arrow so the tip and base are shink percent of the distance d away from the endpoints. ie, shrink=0.05 is 5% any key for matplotlib.patches.polygon Valid keys for FancyArrowPatch are Key arrowstyle connectionstyle relpos patchA patchB shrinkA shrinkB mutation_scale mutation_aspect ? Description the arrow style the connection style default is (0.5, 0.5) default is bounding box of the text default is None default is 2 points default is 2 points default is text size (in points) default is 1. any key for matplotlib.patches.PathPatch xycoords and textcoords are strings that indicate the coordinates of xy and xytext. Property ‘ﬁgure points’ ‘ﬁgure pixels’ ‘ﬁgure fraction’ ‘axes points’ ‘axes pixels’ ‘axes fraction’ ‘data’ ‘oﬀset points’ ‘polar’ Description points from the lower left corner of the ﬁgure pixels from the lower left corner of the ﬁgure 0,0 is lower left of ﬁgure and 1,1 is upper, right points from lower left corner of axes pixels from lower left corner of axes 0,1 is lower left of axes and 1,1 is upper right use the coordinate system of the object being annotated (default) Specify an oﬀset (in points) from the xy value you can specify theta, r for the annotation, even in cartesian plots. Note that if you are using a polar axes, you do not need to specify polar for the coordinate system since that is the native “data” coordinate system. If a ‘points’ or ‘pixels’ option is speciﬁed, values will be added to the bottom-left and if negative, values will be subtracted from the top-right. Eg: 48.1. matplotlib.pyplot 639 Matplotlib, Release 0.99.1.1 # 10 points to the right of the left border of the axes and # 5 points below the top border xy=(10,-5), xycoords=’axes points’ Additional kwargs are Text properties: Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder 640 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 arrow(x, y, dx, dy, hold=None, **kwargs) call signature: 48.1. matplotlib.pyplot 641 Matplotlib, Release 0.99.1.1 arrow(x, y, dx, dy, **kwargs) Draws arrow on speciﬁed axis from (x, y) to (x + dx, y + dy). Optional kwargs control the arrow properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: 642 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state autumn() set the default colormap to autumn and apply to current image if any. See help(colormaps) for more information axes(*args, **kwargs) Add an axes at position rect speciﬁed by: •axes() by itself creates a default full subplot(111) window axis. •axes(rect, axisbg=’w’) where rect = [left, bottom, width, height] in normalized (0, 1) units. axisbg is the background color for the axis, default white. •axes(h) where h is an axes instance makes h the current axis. An Axes instance is returned. kwarg axisbg frameon sharex sharey polar Accepts color [True|False] otherax otherax [True|False] Desctiption the axes background color display the frame? current axes shares xaxis attribute with otherax current axes shares yaxis attribute with otherax use a polar axes? Examples: •examples/pylab_examples/axes_demo.py places custom axes. •examples/pylab_examples/shared_axis_demo.py uses sharex and sharey. axhline(y=0, xmin=0, xmax=1, hold=None, **kwargs) call signature: 48.1. matplotlib.pyplot 643 Matplotlib, Release 0.99.1.1 axhline(y=0, xmin=0, xmax=1, **kwargs) Axis Horizontal Line Draw a horizontal line at y from xmin to xmax. With the default values of xmin = 0 and xmax = 1, this line will always span the horizontal extent of the axes, regardless of the xlim settings, even if you change them, eg. with the set_xlim() command. That is, the horizontal extent is in axes coords: 0=left, 0.5=middle, 1.0=right but the y location is in data coordinates. Return value is the Line2D instance. kwargs are the same as kwargs to plot, and can be used to control the line properties. Eg., •draw a thick red hline at y = 0 that spans the xrange >>> axhline(linewidth=4, color=’r’) •draw a default hline at y = 1 that spans the xrange >>> axhline(y=1) •draw a default hline at y = .5 that spans the the middle half of the xrange >>> axhline(y=.5, xmin=0.25, xmax=0.75) Valid kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod 644 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder Table 48.2 – continued from previous pa [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number See Also: axhspan() for example plot and source code Additional kwargs: hold = [True|False] overrides default hold state axhspan(ymin, ymax, xmin=0, xmax=1, hold=None, **kwargs) call signature: axhspan(ymin, ymax, xmin=0, xmax=1, **kwargs) Axis Horizontal Span. y coords are in data units and x coords are in axes (relative 0-1) units. Draw a horizontal span (rectangle) from ymin to ymax. With the default values of xmin = 0 and xmax = 1, this always spans the xrange, regardless of the xlim settings, even if you change them, eg. with the set_xlim() command. That is, the horizontal extent is in axes coords: 0=left, 0.5=middle, 1.0=right but the y location is in data coordinates. Return value is a matplotlib.patches.Polygon instance. Examples: •draw a gray rectangle from y = 0.25-0.75 that spans the horizontal extent of the axes >>> axhspan(0.25, 0.75, facecolor=’0.5’, alpha=0.5) Valid kwargs are Polygon properties: 48.1. matplotlib.pyplot 645 Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: 646 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state axis(*v, **kwargs) Set/Get the axis properties: >>> axis() returns the current axes limits [xmin, xmax, ymin, ymax]. >>> axis(v) sets the min and max of the x and y axes, with v = [xmin, xmax, ymin, ymax]. >>> axis(’off’) turns oﬀ the axis lines and labels. >>> axis(’equal’) changes limits of x or y axis so that equal increments of x and y have the same length; a circle is circular. >>> axis(’scaled’) 48.1. matplotlib.pyplot 647 Matplotlib, Release 0.99.1.1 achieves the same result by changing the dimensions of the plot box instead of the axis data limits. >>> axis(’tight’) changes x and y axis limits such that all data is shown. If all data is already shown, it will move it to the center of the ﬁgure without modifying (xmax - xmin) or (ymax - ymin). Note this is slightly diﬀerent than in matlab. >>> axis(’image’) is ‘scaled’ with the axis limits equal to the data limits. >>> axis(’auto’) and >>> axis(’normal’) are deprecated. They restore default behavior; axis limits are automatically scaled to make the data ﬁt comfortably within the plot box. if len(*v)==0, you can pass in xmin, xmax, ymin, ymax as kwargs selectively to alter just those limits without changing the others. The xmin, xmax, ymin, ymax tuple is returned See Also: xlim(), ylim() For setting the x- and y-limits individually. axvline(x=0, ymin=0, ymax=1, hold=None, **kwargs) call signature: axvline(x=0, ymin=0, ymax=1, **kwargs) Axis Vertical Line Draw a vertical line at x from ymin to ymax. With the default values of ymin = 0 and ymax = 1, this line will always span the vertical extent of the axes, regardless of the ylim settings, even if you change them, eg. with the set_ylim() command. That is, the vertical extent is in axes coords: 0=bottom, 0.5=middle, 1.0=top but the x location is in data coordinates. Return value is the Line2D instance. kwargs are the same as kwargs to plot, and can be used to control the line properties. Eg., •draw a thick red vline at x = 0 that spans the yrange >>> axvline(linewidth=4, color=’r’) •draw a default vline at x = 1 that spans the yrange 648 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 >>> axvline(x=1) •draw a default vline at x = .5 that spans the the middle half of the yrange >>> axvline(x=.5, ymin=0.25, ymax=0.75) Valid kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata 48.1. matplotlib.pyplot Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 649 Matplotlib, Release 0.99.1.1 Table 48.3 – continued from previous pa 1D array any number ydata zorder See Also: axhspan() for example plot and source code Additional kwargs: hold = [True|False] overrides default hold state axvspan(xmin, xmax, ymin=0, ymax=1, hold=None, **kwargs) call signature: axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs) Axis Vertical Span. x coords are in data units and y coords are in axes (relative 0-1) units. Draw a vertical span (rectangle) from xmin to xmax. With the default values of ymin = 0 and ymax = 1, this always spans the yrange, regardless of the ylim settings, even if you change them, eg. with the set_ylim() command. That is, the vertical extent is in axes coords: 0=bottom, 0.5=middle, 1.0=top but the y location is in data coordinates. Return value is the matplotlib.patches.Polygon instance. Examples: •draw a vertical green translucent rectangle from x=1.25 to 1.55 that spans the yrange of the axes >>> axvspan(1.25, 1.55, facecolor=’g’, alpha=0.5) Valid kwargs are Polygon properties: 650 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number See Also: axhspan() for example plot and source code Additional kwargs: hold = [True|False] overrides default hold state bar(left, height, width=0.80000000000000004, bottom=None, color=None, edgecolor=None, linewidth=None, yerr=None, xerr=None, ecolor=None, capsize=3, align=’edge’, orientation=’vertical’, log=False, hold=None, **kwargs) call signature: bar(left, height, width=0.8, bottom=0, color=None, edgecolor=None, linewidth=None, yerr=None, xerr=None, ecolor=None, capsize=3, align=’edge’, orientation=’vertical’, log=False) Make a bar plot with rectangles bounded by: left, left + width, bottom, bottom + height (left, right, bottom and top edges) left, height, width, and bottom can be either scalars or sequences Return value is a list of matplotlib.patches.Rectangle instances. 48.1. matplotlib.pyplot 651 Matplotlib, Release 0.99.1.1 Required arguments: Argument left height Description the x coordinates of the left sides of the bars the heights of the bars Optional keyword arguments: Keyword width bottom color edgecolor linewidth xerr yerr ecolor capsize align orientation log Description the widths of the bars the y coordinates of the bottom edges of the bars the colors of the bars the colors of the bar edges width of bar edges; None means use default linewidth; 0 means don’t draw edges. if not None, will be used to generate errorbars on the bar chart if not None, will be used to generate errorbars on the bar chart speciﬁes the color of any errorbar (default 3) determines the length in points of the error bar caps ‘edge’ (default) | ‘center’ ‘vertical’ | ‘horizontal’ [False|True] False (default) leaves the orientation axis as-is; True sets it to log scale For vertical bars, align = ‘edge’ aligns bars by their left edges in left, while align = ‘center’ interprets these values as the x coordinates of the bar centers. For horizontal bars, align = ‘edge’ aligns bars by their bottom edges in bottom, while align = ‘center’ interprets these values as the y coordinates of the bar centers. The optional arguments color, edgecolor, linewidth, xerr, and yerr can be either scalars or sequences of length equal to the number of bars. This enables you to use bar as the basis for stacked bar charts, or candlestick plots. Other optional kwargs: 652 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: A stacked bar chart. 48.1. matplotlib.pyplot 653 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state barbs(*args, **kw) Plot a 2-D ﬁeld of barbs. call signatures: barb(U, barb(U, barb(X, barb(X, V, V, Y, Y, **kw) C, **kw) U, V, **kw) U, V, C, **kw) Arguments: X, Y : The x and y coordinates of the barb locations (default is head of barb; see pivot kwarg) U, V : give the x and y components of the barb shaft C: an optional array used to map colors to the barbs All arguments may be 1-D or 2-D arrays or sequences. If X and Y are absent, they will be generated as a uniform grid. If U and V are 2-D arrays but X and Y are 1-D, and if len(X ) and len(Y ) match the column and row dimensions of U, then X and Y will be expanded with numpy.meshgrid(). U, V, C may be masked arrays, but masked X, Y are not supported at present. 654 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Keyword arguments: length: Length of the barb in points; the other parts of the barb are scaled against this. Default is 9 pivot: [ ‘tip’ | ‘middle’ ] The part of the arrow that is at the grid point; the arrow rotates about this point, hence the name pivot. Default is ‘tip’ barbcolor: [ color | color sequence ] Speciﬁes the color all parts of the barb except any ﬂags. This parameter is analagous to the edgecolor parameter for polygons, which can be used instead. However this parameter will override facecolor. ﬂagcolor: [ color | color sequence ] Speciﬁes the color of any ﬂags on the barb. This parameter is analagous to the facecolor parameter for polygons, which can be used instead. However this parameter will override facecolor. If this is not set (and C has not either) then ﬂagcolor will be set to match barbcolor so that the barb has a uniform color. If C has been set, ﬂagcolor has no eﬀect. sizes: A dictionary of coeﬃcients specifying the ratio of a given feature to the length of the barb. Only those values one wishes to override need to be included. These features include: • ‘spacing’ - space between features (ﬂags, full/half barbs) • ‘height’ - height (distance from shaft to top) of a ﬂag or full barb • ‘width’ - width of a ﬂag, twice the width of a full barb • ‘emptybarb’ - radius of the circle used for low magnitudes ﬁll_empty: A ﬂag on whether the empty barbs (circles) that are drawn should be ﬁlled with the ﬂag color. If they are not ﬁlled, they will be drawn such that no color is applied to the center. Default is False rounding: A ﬂag to indicate whether the vector magnitude should be rounded when allocating barb components. If True, the magnitude is rounded to the nearest multiple of the half-barb increment. If False, the magnitude is simply truncated to the next lowest multiple. Default is True barb_increments: A dictionary of increments specifying values to associate with diﬀerent parts of the barb. Only those values one wishes to override need to be included. • ‘half’ - half barbs (Default is 5) • ‘full’ - full barbs (Default is 10) • ‘ﬂag’ - ﬂags (default is 50) ﬂip_barb: Either a single boolean ﬂag or an array of booleans. Single boolean indicates whether the lines and ﬂags should point opposite to normal for all barbs. An array (which should be the same size as the other data arrays) indicates whether to ﬂip for each individual barb. Normal behavior is for the barbs and lines to point right (comes from wind barbs having these features point towards low pressure in the Northern Hemisphere.) Default is False 48.1. matplotlib.pyplot 655 Matplotlib, Release 0.99.1.1 Barbs are traditionally used in meteorology as a way to plot the speed and direction of wind observations, but can technically be used to plot any two dimensional vector quantity. As opposed to arrows, which give vector magnitude by the length of the arrow, the barbs give more quantitative information about the vector magnitude by putting slanted lines or a triangle for various increments in magnitude, as show schematically below: : /\ \ : /\ \ : / \ \ \ :/ \ \ \ : ------------------------------ The largest increment is given by a triangle (or “ﬂag”). After those come full lines (barbs). The smallest increment is a half line. There is only, of course, ever at most 1 half line. If the magnitude is small and only needs a single half-line and no full lines or triangles, the half-line is oﬀset from the end of the barb so that it can be easily distinguished from barbs with a single full line. The magnitude for the barb shown above would nominally be 65, using the standard increments of 50, 10, and 5. linewidths and edgecolors can be used to customize the barb. Additional PolyCollection keyword arguments: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path cmap color colorbar contains edgecolor or edgecolors facecolor or facecolors figure gid label linestyle or linestyles or dashes linewidth or lw or linewidths lod norm offsets picker pickradius rasterized 656 Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a colormap or registered colormap name matplotlib color arg or sequence of rgba tuples unknown a callable function matplotlib color arg or sequence of rgba tuples matplotlib color arg or sequence of rgba tuples a matplotlib.figure.Figure instance an id string any string [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] ﬂoat or sequence of ﬂoats [True | False] unknown ﬂoat or sequence of ﬂoats [None|ﬂoat|boolean|callable] unknown [True | False | None] Continued on next page Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 snap transform url urls visible zorder Table 48.4 – continued from previous page unknown Transform instance a url string unknown [True | False] any number Example: 48.1. matplotlib.pyplot 657 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state barh(bottom, width, height=0.80000000000000004, left=None, hold=None, **kwargs) call signature: barh(bottom, width, height=0.8, left=0, **kwargs) Make a horizontal bar plot with rectangles bounded by: left, left + width, bottom, bottom + height (left, right, bottom and top edges) bottom, width, height, and left can be either scalars or sequences Return value is a list of matplotlib.patches.Rectangle instances. Required arguments: Argument bottom width Description the vertical positions of the bottom edges of the bars the lengths of the bars Optional keyword arguments: 658 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Keyword height left color edgecolor linewidth xerr yerr ecolor capsize align log Description the heights (thicknesses) of the bars the x coordinates of the left edges of the bars the colors of the bars the colors of the bar edges width of bar edges; None means use default linewidth; 0 means don’t draw edges. if not None, will be used to generate errorbars on the bar chart if not None, will be used to generate errorbars on the bar chart speciﬁes the color of any errorbar (default 3) determines the length in points of the error bar caps ‘edge’ (default) | ‘center’ [False|True] False (default) leaves the horizontal axis as-is; True sets it to log scale Setting align = ‘edge’ aligns bars by their bottom edges in bottom, while align = ‘center’ interprets these values as the y coordinates of the bar centers. The optional arguments color, edgecolor, linewidth, xerr, and yerr can be either scalars or sequences of length equal to the number of bars. This enables you to use barh as the basis for stacked bar charts, or candlestick plots. other optional kwargs: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder 48.1. matplotlib.pyplot Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number 659 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state bone() set the default colormap to bone and apply to current image if any. See help(colormaps) for more information box(on=None) Turn the axes box on or oﬀ according to on. If on is None, toggle state. boxplot(x, notch=0, sym=’b+’, vert=1, whis=1.5, positions=None, widths=None, hold=None) call signature: boxplot(x, notch=0, sym=’+’, vert=1, whis=1.5, positions=None, widths=None) Make a box and whisker plot for each column of x or each vector in sequence x. The box extends from the lower to upper quartile values of the data, with a line at the median. The whiskers extend from the box to show the range of the data. Flier points are those past the end of the whiskers. •notch = 0 (default) produces a rectangular box plot. •notch = 1 will produce a notched box plot sym (default ‘b+’) is the default symbol for ﬂier points. Enter an empty string (‘’) if you don’t want to show ﬂiers. •vert = 1 (default) makes the boxes vertical. •vert = 0 makes horizontal boxes. This seems goofy, but that’s how Matlab did it. whis (default 1.5) deﬁnes the length of the whiskers as a function of the inner quartile range. They extend to the most extreme data point within ( whis*(75%-25%) ) data range. positions (default 1,2,...,n) sets the horizontal positions of the boxes. The ticks and limits are automatically set to match the positions. widths is either a scalar or a vector and sets the width of each box. 0.15*(distance between extreme positions) if that is smaller. The default is 0.5, or x is an array or a sequence of vectors. Returns a dictionary mapping each component matplotlib.lines.Line2D instances created. of the boxplot to a list of the Example: 660 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 661 Matplotlib, Release 0.99.1.1 662 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 663 Matplotlib, Release 0.99.1.1 664 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 665 Matplotlib, Release 0.99.1.1 666 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state broken_barh(xranges, yrange, hold=None, **kwargs) call signature: broken_barh(self, xranges, yrange, **kwargs) A collection of horizontal bars spanning yrange with a sequence of xranges. Required arguments: Argument xranges yrange Description sequence of (xmin, xwidth) sequence of (ymin, ywidth) kwargs are matplotlib.collections.BrokenBarHCollection properties: Property alpha animated antialiased or antialiaseds array axes clim Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats Continued on next page 48.1. matplotlib.pyplot 667 Matplotlib, Release 0.99.1.1 Table 48.5 – continued from previous page clip_box a matplotlib.transforms.Bbox instance clip_on [True | False] clip_path [ (Path, Transform) | Patch | None ] cmap a colormap or registered colormap name color matplotlib color arg or sequence of rgba tuples colorbar unknown contains a callable function edgecolor or edgecolors matplotlib color arg or sequence of rgba tuples facecolor or facecolors matplotlib color arg or sequence of rgba tuples figure a matplotlib.figure.Figure instance gid an id string label any string linestyle or linestyles or dashes [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] linewidth or lw or linewidths ﬂoat or sequence of ﬂoats lod [True | False] norm unknown offsets ﬂoat or sequence of ﬂoats picker [None|ﬂoat|boolean|callable] pickradius unknown rasterized [True | False | None] snap unknown transform Transform instance url a url string urls unknown visible [True | False] zorder any number these can either be a single argument, ie: facecolors = ’black’ or a sequence of arguments for the various bars, ie: facecolors = (’black’, ’red’, ’green’) Example: 668 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state cla() Clear the current axes clabel(CS, *args, **kwargs) call signature: clabel(cs, **kwargs) adds labels to line contours in cs, where cs is a ContourSet object returned by contour. clabel(cs, v, **kwargs) only labels contours listed in v. Optional keyword arguments: fontsize: See http://matplotlib.sf.net/fonts.html colors: • if None, the color of each label matches the color of the corresponding contour • if one string color, e.g. colors = ‘r’ or colors = ‘red’, all labels will be plotted in this color • if a tuple of matplotlib color args (string, ﬂoat, rgb, etc), diﬀerent labels will be plotted in diﬀerent colors in the order speciﬁed 48.1. matplotlib.pyplot 669 Matplotlib, Release 0.99.1.1 inline: controls whether the underlying contour is removed or not. Default is True. inline_spacing: space in pixels to leave on each side of label when placing inline. Defaults to 5. This spacing will be exact for labels at locations where the contour is straight, less so for labels on curved contours. fmt: a format string for the label. Default is ‘%1.3f’ Alternatively, this can be a dictionary matching contour levels with arbitrary strings to use for each contour level (i.e., fmt[level]=string) manual: if True, contour labels will be placed manually using mouse clicks. Click the ﬁrst button near a contour to add a label, click the second button (or potentially both mouse buttons at once) to ﬁnish adding labels. The third button can be used to remove the last label added, but only if labels are not inline. Alternatively, the keyboard can be used to select label locations (enter to end label placement, delete or backspace act like the third mouse button, and any other key will select a label location). rightside_up: if True (default), label rotations will always be plus or minus 90 degrees from level. 670 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 671 Matplotlib, Release 0.99.1.1 672 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 673 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state clf () Clear the current ﬁgure clim(vmin=None, vmax=None) Set the color limits of the current image To apply clim to all axes images do: clim(0, 0.5) If either vmin or vmax is None, the image min/max respectively will be used for color scaling. If you want to set the clim of multiple images, use, for example: for im in gca().get_images(): im.set_clim(0, 0.05) close(*args) Close a ﬁgure window close() by itself closes the current ﬁgure close(num) closes ﬁgure number num close(h) where h is a Figure instance, closes that ﬁgure 674 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 close(’all’) closes all the ﬁgure windows cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, hold=None, **kwargs) call signature: cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend = mlab.detrend_none, window = mlab.window_hanning, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) cohere() the coherence between x and y. Coherence is the normalized cross spectral density: C xy = |P xy |2 P xx Pyy (48.1) Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. 48.1. matplotlib.pyplot 675 Matplotlib, Release 0.99.1.1 scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Fc: integer The center frequency of x (defaults to 0), which oﬀsets the x extents of the plot to reﬂect the frequency range used when a signal is acquired and then ﬁltered and downsampled to baseband. The return value is a tuple (Cxy, f ), where f are the frequencies of the coherence vector. kwargs are applied to the lines. References: •Bendat & Piersol – Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986) kwargs control the Line2D properties of the coherence plot: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized 676 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Table 48.6 – continued from previous pa snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Example: Additional kwargs: hold = [True|False] overrides default hold state colorbar(mappable=None, cax=None, ax=None, **kw) Add a colorbar to a plot. Function signatures for the pyplot interface; all but the ﬁrst are also method signatures for the colorbar() method: colorbar(**kwargs) colorbar(mappable, **kwargs) 48.1. matplotlib.pyplot 677 Matplotlib, Release 0.99.1.1 colorbar(mappable, cax=cax, **kwargs) colorbar(mappable, ax=ax, **kwargs) arguments: mappable the Image, ContourSet, etc. to which the colorbar applies; this argument is mandatory for the colorbar() method but optional for the colorbar() function, which sets the default to the current image. keyword arguments: cax None | axes object into which the colorbar will be drawn ax None | parent axes object from which space for a new colorbar axes will be stolen Additional keyword arguments are of two kinds: axes properties: Property orientation fraction pad shrink aspect Description vertical or horizontal 0.15; fraction of original axes to use for colorbar 0.05 if vertical, 0.15 if horizontal; fraction of original axes between colorbar and new image axes 1.0; fraction by which to shrink the colorbar 20; ratio of long to short dimensions colorbar properties: Property extend spacing ticks Description [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ] If not ‘neither’, make pointed end(s) for out-of- range values. These are set for a given colormap using the colormap set_under and set_over methods. [ ‘uniform’ | ‘proportional’ ] Uniform spacing gives each discrete color the same space; proportional makes the space proportional to the data interval. [ None | list of ticks | Locator object ] If None, ticks are determined automatically from the input. for[ None | format string | Formatter object ] If None, the ScalarFormatter is used. If a format mat string is given, e.g. ‘%.3f’, that is used. An alternative Formatter object may be given instead. drawedgesFalse | True ] If true, draw lines at color boundaries. [ The following will probably be useful only in the context of indexed colors (that is, when the mappable has norm=NoNorm()), or other unusual circumstances. Prop- Description erty bound- None or a sequence aries values None or a sequence which must be of length 1 less than the sequence of boundaries. For each region delimited by adjacent entries in boundaries, the color mapped to the corresponding value in values will be used. 678 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 If mappable is a ContourSet, its extend kwarg is included automatically. Note that the shrink kwarg provides a simple way to keep a vertical colorbar, for example, from being taller than the axes of the mappable to which the colorbar is attached; but it is a manual method requiring some trial and error. If the colorbar is too tall (or a horizontal colorbar is too wide) use a smaller value of shrink. For more precise control, you can manually specify the positions of the axes objects in which the mappable and the colorbar are drawn. In this case, do not use any of the axes properties kwargs. returns: Colorbar instance; see also its base class, ColorbarBase. Call the set_label() method to label the colorbar. colormaps() matplotlib provides the following colormaps. •autumn •bone •cool •copper •ﬂag •gray •hot •hsv •jet •pink •prism •spring •summer •winter •spectral You can set the colormap for an image, pcolor, scatter, etc, either as a keyword argument: imshow(X, cmap=cm.hot) or post-hoc using the corresponding pylab interface function: imshow(X) hot() jet() In interactive mode, this will update the colormap allowing you to see which one works best for your data. 48.1. matplotlib.pyplot 679 Matplotlib, Release 0.99.1.1 colors() This is a do-nothing function to provide you with help on how matplotlib handles colors. Commands which take color arguments can use several formats to specify the colors. For the basic builtin colors, you can use a single letter Alias ‘b’ ‘g’ ‘r’ ‘c’ ‘m’ ‘y’ ‘k’ ‘w’ Color blue green red cyan magenta yellow black white For a greater range of colors, you have two options. You can specify the color using an html hex string, as in: color = ’#eeefff’ or you can pass an R,G,B tuple, where each of R,G,B are in the range [0,1]. You can also use any legal html name for a color, for example: color = ’red’, color = ’burlywood’ color = ’chartreuse’ The example below creates a subplot with a dark slate gray background subplot(111, axisbg=(0.1843, 0.3098, 0.3098)) Here is an example that creates a pale turqoise title: title(’Is this the best color?’, color=’#afeeee’) connect(s, func) Connect event with string s to func. The signature of func is: def func(event) where event is a matplotlib.backend_bases.Event. The following events are recognized •‘button_press_event’ •‘button_release_event’ •‘draw_event’ •‘key_press_event’ •‘key_release_event’ 680 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 •‘motion_notify_event’ •‘pick_event’ •‘resize_event’ •‘scroll_event’ •‘ﬁgure_enter_event’, •‘ﬁgure_leave_event’, •‘axes_enter_event’, •‘axes_leave_event’ For the location events (button and key press/release), if the mouse is over the axes, the variable event.inaxes will be set to the Axes the event occurs is over, and additionally, the variables event.xdata and event.ydata will be deﬁned. This is the mouse location in data coords. See KeyEvent and MouseEvent for more info. Return value is a connection id that can be used with mpl_disconnect(). Example usage: def on_press(event): print ’you pressed’, event.button, event.xdata, event.ydata cid = canvas.mpl_connect(’button_press_event’, on_press) contour(*args, **kwargs) contour() and contourf() draw contour lines and ﬁlled contours, respectively. Except as noted, function signatures and return values are the same for both versions. contourf() diﬀers from the Matlab (TM) version in that it does not draw the polygon edges, because the contouring engine yields simply connected regions with branch cuts. To draw the edges, add line contours with calls to contour(). call signatures: contour(Z) make a contour plot of an array Z. The level values are chosen automatically. contour(X,Y,Z) X, Y specify the (x, y) coordinates of the surface contour(Z,N) contour(X,Y,Z,N) contour N automatically-chosen levels. 48.1. matplotlib.pyplot 681 Matplotlib, Release 0.99.1.1 contour(Z,V) contour(X,Y,Z,V) draw contour lines at the values speciﬁed in sequence V contourf(..., V) ﬁll the (len(V )-1) regions between the values in V contour(Z, **kwargs) Use keyword args to control colors, linewidth, origin, cmap ... see below for more details. X, Y, and Z must be arrays with the same dimensions. Z may be a masked array, but ﬁlled contouring may not handle internal masked regions correctly. C = contour(...) returns a ContourSet object. Optional keyword arguments: colors: [ None | string | (mpl_colors) ] If None, the colormap speciﬁed by cmap will be used. If a string, like ‘r’ or ‘red’, all levels will be plotted in this color. If a tuple of matplotlib color args (string, ﬂoat, rgb, etc), diﬀerent levels will be plotted in diﬀerent colors in the order speciﬁed. alpha: ﬂoat The alpha blending value cmap: [ None | Colormap ] A cm Colormap instance or None. If cmap is None and colors is None, a default Colormap is used. norm: [ None | Normalize ] A matplotlib.colors.Normalize instance for scaling data values to colors. If norm is None and colors is None, the default linear scaling is used. origin: [ None | ‘upper’ | ‘lower’ | ‘image’ ] If None, the ﬁrst value of Z will correspond to the lower left corner, location (0,0). If ‘image’, the rc value for image.origin will be used. This keyword is not active if X and Y are speciﬁed in the call to contour. extent: [ None | (x0,x1,y0,y1) ] If origin is not None, then extent is interpreted as in matplotlib.pyplot.imshow(): it gives the outer pixel boundaries. In this case, the position of Z[0,0] is the center of the pixel, not a corner. If origin is None, then (x0, y0) is the position of Z[0,0], and (x1, y1) is the position of Z[-1,-1]. This keyword is not active if X and Y are speciﬁed in the call to contour. 682 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 locator: [ None | ticker.Locator subclass ] If locator is None, the default MaxNLocator is used. The locator is used to determine the contour levels if they are not given explicitly via the V argument. extend: [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ] Unless this is ‘neither’, contour levels are automatically added to one or both ends of the range so that all data are included. These added ranges are then mapped to the special colormap values which default to the ends of the colormap range, but can be set via matplotlib.cm.Colormap.set_under() and matplotlib.cm.Colormap.set_over() methods. contour-only keyword arguments: linewidths: [ None | number | tuple of numbers ] If linewidths is None, the default width in lines.linewidth in matplotlibrc is used. If a number, all levels will be plotted with this linewidth. If a tuple, diﬀerent levels will be plotted with diﬀerent linewidths in the order speciﬁed linestyles: [None | ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ] If linestyles is None, the ‘solid’ is used. linestyles can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than the number of contour levels it will be repeated as necessary. If contour is using a monochrome colormap and the contour level is less than 0, then the linestyle speciﬁed in contour.negative_linestyle in matplotlibrc will be used. contourf-only keyword arguments: antialiased: [ True | False ] enable antialiasing nchunk: [ 0 | integer ] If 0, no subdivision of the domain. Specify a positive integer to divide the domain into subdomains of roughly nchunk by nchunk points. This may never actually be advantageous, so this option may be removed. Chunking introduces artifacts at the chunk boundaries unless antialiased is False. Example: 48.1. matplotlib.pyplot 683 Matplotlib, Release 0.99.1.1 684 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 685 Matplotlib, Release 0.99.1.1 686 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 687 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state contourf (*args, **kwargs) contour() and contourf() draw contour lines and ﬁlled contours, respectively. Except as noted, function signatures and return values are the same for both versions. contourf() diﬀers from the Matlab (TM) version in that it does not draw the polygon edges, because the contouring engine yields simply connected regions with branch cuts. To draw the edges, add line contours with calls to contour(). call signatures: contour(Z) make a contour plot of an array Z. The level values are chosen automatically. contour(X,Y,Z) X, Y specify the (x, y) coordinates of the surface contour(Z,N) contour(X,Y,Z,N) contour N automatically-chosen levels. 688 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 contour(Z,V) contour(X,Y,Z,V) draw contour lines at the values speciﬁed in sequence V contourf(..., V) ﬁll the (len(V )-1) regions between the values in V contour(Z, **kwargs) Use keyword args to control colors, linewidth, origin, cmap ... see below for more details. X, Y, and Z must be arrays with the same dimensions. Z may be a masked array, but ﬁlled contouring may not handle internal masked regions correctly. C = contour(...) returns a ContourSet object. Optional keyword arguments: colors: [ None | string | (mpl_colors) ] If None, the colormap speciﬁed by cmap will be used. If a string, like ‘r’ or ‘red’, all levels will be plotted in this color. If a tuple of matplotlib color args (string, ﬂoat, rgb, etc), diﬀerent levels will be plotted in diﬀerent colors in the order speciﬁed. alpha: ﬂoat The alpha blending value cmap: [ None | Colormap ] A cm Colormap instance or None. If cmap is None and colors is None, a default Colormap is used. norm: [ None | Normalize ] A matplotlib.colors.Normalize instance for scaling data values to colors. If norm is None and colors is None, the default linear scaling is used. origin: [ None | ‘upper’ | ‘lower’ | ‘image’ ] If None, the ﬁrst value of Z will correspond to the lower left corner, location (0,0). If ‘image’, the rc value for image.origin will be used. This keyword is not active if X and Y are speciﬁed in the call to contour. extent: [ None | (x0,x1,y0,y1) ] If origin is not None, then extent is interpreted as in matplotlib.pyplot.imshow(): it gives the outer pixel boundaries. In this case, the position of Z[0,0] is the center of the pixel, not a corner. If origin is None, then (x0, y0) is the position of Z[0,0], and (x1, y1) is the position of Z[-1,-1]. This keyword is not active if X and Y are speciﬁed in the call to contour. 48.1. matplotlib.pyplot 689 Matplotlib, Release 0.99.1.1 locator: [ None | ticker.Locator subclass ] If locator is None, the default MaxNLocator is used. The locator is used to determine the contour levels if they are not given explicitly via the V argument. extend: [ ‘neither’ | ‘both’ | ‘min’ | ‘max’ ] Unless this is ‘neither’, contour levels are automatically added to one or both ends of the range so that all data are included. These added ranges are then mapped to the special colormap values which default to the ends of the colormap range, but can be set via matplotlib.cm.Colormap.set_under() and matplotlib.cm.Colormap.set_over() methods. contour-only keyword arguments: linewidths: [ None | number | tuple of numbers ] If linewidths is None, the default width in lines.linewidth in matplotlibrc is used. If a number, all levels will be plotted with this linewidth. If a tuple, diﬀerent levels will be plotted with diﬀerent linewidths in the order speciﬁed linestyles: [None | ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ] If linestyles is None, the ‘solid’ is used. linestyles can also be an iterable of the above strings specifying a set of linestyles to be used. If this iterable is shorter than the number of contour levels it will be repeated as necessary. If contour is using a monochrome colormap and the contour level is less than 0, then the linestyle speciﬁed in contour.negative_linestyle in matplotlibrc will be used. contourf-only keyword arguments: antialiased: [ True | False ] enable antialiasing nchunk: [ 0 | integer ] If 0, no subdivision of the domain. Specify a positive integer to divide the domain into subdomains of roughly nchunk by nchunk points. This may never actually be advantageous, so this option may be removed. Chunking introduces artifacts at the chunk boundaries unless antialiased is False. Example: 690 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 691 Matplotlib, Release 0.99.1.1 692 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 693 Matplotlib, Release 0.99.1.1 694 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state cool() set the default colormap to cool and apply to current image if any. See help(colormaps) for more information copper() set the default colormap to copper and apply to current image if any. See help(colormaps) for more information csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=<function detrend_none at 0x30b5d70>, window=<function window_hanning at 0x30b5c80>, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, hold=None, **kwargs) call signature: csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides=’default’, scale_by_freq=None, **kwargs) The cross spectral density P xy by Welch’s average periodogram method. The vectors x and y are divided into NFFT length segments. Each segment is detrended by function detrend and windowed by function window. The product of the direct FFTs of x and y are averaged over each segment to compute P xy , with a scaling to correct for power loss due to windowing. Returns the tuple (Pxy, freqs). P is the cross spectrum (complex valued), and 10 log10 |P xy | is plotted. 48.1. matplotlib.pyplot 695 Matplotlib, Release 0.99.1.1 Keyword arguments: NFFT : integer The number of data points used in each block for the FFT. Must be even; a power 2 is most eﬃcient. The default value is 256. Fs: scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time unit. The default value is 2. detrend: callable The function applied to each segment before ﬀt-ing, designed to remove the mean or linear trend. Unlike in matlab, where the detrend parameter is a vector, in matplotlib is it a function. The pylab module deﬁnes detrend_none(), detrend_mean(), and detrend_linear(), but you can use a custom function as well. window: callable or ndarray A function or a vector of length NFFT. To create window vectors see window_hanning(), window_none(), numpy.blackman(), numpy.hamming(), numpy.bartlett(), scipy.signal(), scipy.signal.get_window(), etc. The default is window_hanning(). If a function is passed as the argument, it must take a data segment as an argument and return the windowed version of the segment. noverlap: integer The number of points of overlap between blocks. The default value is 0 (no overlap). pad_to: integer The number of points to which the data segment is padded when performing the FFT. This can be diﬀerent from NFFT, which speciﬁes the number of data points used. While not increasing the actual resolution of the psd (the minimum distance between resolvable peaks), this can give more points in the plot, allowing for more detail. This corresponds to the n parameter in the call to ﬀt(). The default is None, which sets pad_to equal to NFFT sides: [ ‘default’ | ‘onesided’ | ‘twosided’ ] Speciﬁes which sides of the PSD to return. Default gives the default behavior, which returns one-sided for real data and both for complex data. ‘onesided’ forces the return of a one-sided PSD, while ‘twosided’ forces two-sided. scale_by_freq: boolean Speciﬁes whether the resulting density values should be scaled by the scaling frequency, which gives density in units of Hz^-1. This allows for integration over the returned frequency values. The default is True for MatLab compatibility. Fc: integer The center frequency of x (defaults to 0), which oﬀsets the x extents of the plot to reﬂect the frequency range used when a signal is acquired and then ﬁltered and downsampled to baseband. References: Bendat & Piersol – Random Data: Analysis and Measurement Procedures, John Wiley & Sons (1986) kwargs control the Line2D properties: Property 696 Description Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Table 48.7 – continued from previous pa alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Example: 48.1. matplotlib.pyplot 697 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state delaxes(*args) delaxes(ax): remove ax from the current ﬁgure. If ax doesn’t exist, an error will be raised. delaxes(): delete the current axes disconnect(cid) disconnect callback id cid Example usage: cid = canvas.mpl_connect(’button_press_event’, on_press) #...later canvas.mpl_disconnect(cid) draw() redraw the current ﬁgure errorbar(x, y, yerr=None, xerr=None, fmt=’-’, ecolor=None, elinewidth=None, capsize=3, barsabove=False, lolims=False, uplims=False, xlolims=False, xuplims=False, hold=None, **kwargs) call signature: errorbar(x, y, yerr=None, xerr=None, fmt=’-’, ecolor=None, elinewidth=None, capsize=3, 698 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 barsabove=False, lolims=False, uplims=False, xlolims=False, xuplims=False) Plot x versus y with error deltas in yerr and xerr. Vertical errorbars are plotted if yerr is not None. Horizontal errorbars are plotted if xerr is not None. x, y, xerr, and yerr can all be scalars, which plots a single error bar at x, y. Optional keyword arguments: xerr/yerr: [ scalar | N, Nx1, or 2xN array-like ] If a scalar number, len(N) array-like object, or an Nx1 array-like object, errorbars are drawn +/- value. If a rank-1, 2xN numpy array, errorbars are drawn at -row1 and +row2 fmt: ‘-‘ The plot format symbol for y. If fmt is None, just plot the errorbars with no line symbols. This can be useful for creating a bar plot with errorbars. ecolor: [ None | mpl color ] a matplotlib color arg which gives the color the errorbar lines; if None, use the marker color. elinewidth: scalar the linewidth of the errorbar lines. If None, use the linewidth. capsize: scalar the size of the error bar caps in points barsabove: [ True | False ] if True, will plot the errorbars above the plot symbols. Default is below. lolims/uplims/xlolims/xuplims: [ False | True ] These arguments can be used to indicate that a value gives only upper/lower limits. In that case a caret symbol is used to indicate this. lims-arguments may be of the same type as xerr and yerr. All other keyword arguments are passed on to the plot command for the markers, so you can add additional key=value pairs to control the errorbar markers. For example, this code makes big red squares with thick green edges: x,y,yerr = rand(3,10) errorbar(x, y, yerr, marker=’s’, mfc=’red’, mec=’green’, ms=20, mew=4) where mfc, mec, ms and mew are aliases for the longer property names, markerfacecolor, markeredgecolor, markersize and markeredgewith. valid kwargs for the marker properties are Property alpha animated antialiased or aa axes clip_box clip_on clip_path 48.1. matplotlib.pyplot Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] 699 Matplotlib, Release 0.99.1.1 Table 48.8 – continued from previous pa color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Return value is a length 3 tuple. The ﬁrst element is the Line2D instance for the y symbol lines. The second element is a list of error bar cap lines, the third element is a list of LineCollection instances for the horizontal and vertical error ranges. Example: 700 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 701 Matplotlib, Release 0.99.1.1 702 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 703 Matplotlib, Release 0.99.1.1 704 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 705 Matplotlib, Release 0.99.1.1 706 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 707 Matplotlib, Release 0.99.1.1 708 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 709 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state figimage(*args, **kwargs) call signatures: figimage(X, **kwargs) adds a non-resampled array X to the ﬁgure. figimage(X, xo, yo) with pixel oﬀsets xo, yo, X must be a ﬂoat array: •If X is MxN, assume luminance (grayscale) •If X is MxNx3, assume RGB •If X is MxNx4, assume RGBA Optional keyword arguments: 710 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Keyword xo or yo cmap Description An integer, the x and y image oﬀset in pixels a matplotlib.cm.ColorMap instance, eg cm.jet. If None, default to the rc image.cmap value norm a matplotlib.colors.Normalize instance. The default is normalization(). This scales luminance -> 0-1 vmin|vmax used to scale a luminance image to 0-1. If either is None, the min and max of the are luminance values will be used. Note if you pass a norm instance, the settings for vmin and vmax will be ignored. alpha the alpha blending value, default is 1.0 origin [ ‘upper’ | ‘lower’ ] Indicates where the [0,0] index of the array is in the upper left or lower left corner of the axes. Defaults to the rc image.origin value ﬁgimage complements the axes image (imshow()) which will be resampled to ﬁt the current axes. If you want a resampled image to ﬁll the entire ﬁgure, you can deﬁne an Axes with size [0,1,0,1]. An matplotlib.image.FigureImage instance is returned. Addition kwargs: hold = [True|False] overrides default hold state figlegend(handles, labels, loc, **kwargs) Place a legend in the ﬁgure. labels a sequence of strings 48.1. matplotlib.pyplot 711 Matplotlib, Release 0.99.1.1 handles a sequence of Line2D or Patch instances loc can be a string or an integer specifying the legend location A matplotlib.legend.Legend instance is returned. Example: figlegend( (line1, line2, line3), (’label1’, ’label2’, ’label3’), ’upper right’ ) See Also: legend() figtext(*args, **kwargs) Call signature: figtext(x, y, s, fontdict=None, **kwargs) Add text to ﬁgure at location x, y (relative 0-1 coords). See text() for the meaning of the other arguments. kwargs control the Text properties: Property alpha animated axes backgroundcolor bbox clip_box clip_on clip_path color contains family or fontfamily or fontname or name figure fontproperties or font_properties gid horizontalalignment or ha label linespacing lod multialignment picker position rasterized rotation 712 Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance any matplotlib color rectangle prop dict a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [ FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ] a matplotlib.figure.Figure instance a matplotlib.font_manager.FontProperties instance an id string [ ‘center’ | ‘right’ | ‘left’ ] any string ﬂoat (multiple of font size) [True | False] [’left’ | ‘right’ | ‘center’ ] [None|ﬂoat|boolean|callable] (x,y) [True | False | None] [ angle in degrees | ‘vertical’ | ‘horizontal’ ] Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Table 48.9 – continued from rotation_mode size or fontsize snap stretch or fontstretch style or fontstyle text transform url variant or fontvariant verticalalignment or va or ma visible weight or fontweight x y zorder unknown [ size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ unknown [ a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘c [ ‘normal’ | ‘italic’ | ‘oblique’] string or anything printable with ‘%s’ conversion. Transform instance a url string [ ‘normal’ | ‘small-caps’ ] [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ] [True | False] [ a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ﬂoat ﬂoat any number figure(num=None, ﬁgsize=None, dpi=None, facecolor=None, edgecolor=None, frameon=True, FigureClass=<class ’matplotlib.ﬁgure.Figure’>, **kwargs) call signature: figure(num=None, figsize=(8, 6), dpi=80, facecolor=’w’, edgecolor=’k’) Create a new ﬁgure and return a matplotlib.figure.Figure instance. If num = None, the ﬁgure number will be incremented and a new ﬁgure will be created. The returned ﬁgure objects have a number attribute holding this number. If num is an integer, and figure(num) already exists, make it active and return a reference to it. If figure(num) does not exist it will be created. Numbering starts at 1, matlab style: figure(1) If you are creating many ﬁgures, make sure you explicitly call “close” on the ﬁgures you are not using, because this will enable pylab to properly clean up the memory. Optional keyword arguments: Keyword ﬁgsize dpi facecolor edgecolor Description width x height in inches; defaults to rc ﬁgure.ﬁgsize resolution; defaults to rc ﬁgure.dpi the background color; defaults to rc ﬁgure.facecolor the border color; defaults to rc ﬁgure.edgecolor rcParams deﬁnes the default values, which can be modiﬁed in the matplotlibrc ﬁle FigureClass is a Figure or derived class that will be passed on to new_figure_manager() in the backends which allows you to hook custom Figure classes into the pylab interface. Additional kwargs will be passed on to your ﬁgure init function. 48.1. matplotlib.pyplot 713 Matplotlib, Release 0.99.1.1 fill(*args, **kwargs) call signature: fill(*args, **kwargs) Plot ﬁlled polygons. args is a variable length argument, allowing for multiple x, y pairs with an optional color format string; see plot() for details on the argument parsing. For example, to plot a polygon with vertices at x, y in blue.: ax.fill(x,y, ’b’ ) An arbitrary number of x, y, color groups can be speciﬁed: ax.fill(x1, y1, ’g’, x2, y2, ’r’) Return value is a list of Patch instances that were added. The same color strings that plot() supports are supported by the ﬁll format string. If you would like to ﬁll below a curve, eg. fill_between() shade a region between 0 and y along x, use The closed kwarg will close the polygon when True (default). kwargs control the Polygon properties: 714 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: 48.1. matplotlib.pyplot 715 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state fill_between(x, y1, y2=0, where=None, hold=None, **kwargs) call signature: fill_between(x, y1, y2=0, where=None, **kwargs) Create a PolyCollection ﬁlling the regions between y1 and y2 where where==True x an N length np array of the x data y1 an N length scalar or np array of the y data y2 an N length scalar or np array of the y data where if None, default to ll between everywhere. If not None, it is a a N length numpy boolean array and the ﬁll will only happen over the regions where where==True kwargs keyword args passed on to the PolyCollection kwargs control the Polygon properties: Property alpha animated antialiased or antialiaseds Description ﬂoat [True | False] Boolean or sequence of booleans Continued on next page 716 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Table 48.10 – continued from previous page array unknown axes an Axes instance clim a length 2 sequence of ﬂoats clip_box a matplotlib.transforms.Bbox instance clip_on [True | False] clip_path [ (Path, Transform) | Patch | None ] cmap a colormap or registered colormap name color matplotlib color arg or sequence of rgba tuples colorbar unknown contains a callable function edgecolor or edgecolors matplotlib color arg or sequence of rgba tuples facecolor or facecolors matplotlib color arg or sequence of rgba tuples figure a matplotlib.figure.Figure instance gid an id string label any string linestyle or linestyles or dashes [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] linewidth or lw or linewidths ﬂoat or sequence of ﬂoats lod [True | False] norm unknown offsets ﬂoat or sequence of ﬂoats picker [None|ﬂoat|boolean|callable] pickradius unknown rasterized [True | False | None] snap unknown transform Transform instance url a url string urls unknown visible [True | False] zorder any number 48.1. matplotlib.pyplot 717 Matplotlib, Release 0.99.1.1 718 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 719 Matplotlib, Release 0.99.1.1 See Also: fill_betweenx() for ﬁlling between two sets of x-values Additional kwargs: hold = [True|False] overrides default hold state fill_betweenx(y, x1, x2=0, where=None, hold=None, **kwargs) call signature: fill_between(y, x1, x2=0, where=None, **kwargs) Create a PolyCollection ﬁlling the regions between x1 and x2 where where==True y an N length np array of the y data x1 an N length scalar or np array of the x data x2 an N length scalar or np array of the x data where if None, default to ﬁll between everywhere. If not None, it is a a N length numpy boolean array and the ﬁll will only happen over the regions where where==True kwargs keyword args passed on to the PolyCollection kwargs control the Polygon properties: %(PolyCollection)s 720 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 48.1. matplotlib.pyplot 721 Matplotlib, Release 0.99.1.1 See Also: fill_between() for ﬁlling between two sets of y-values Additional kwargs: hold = [True|False] overrides default hold state findobj(o=None, match=None) pyplot signature: ﬁndobj(o=gcf(), match=None) Recursively ﬁnd all :class:matplotlib.artist.Artist instances contained in self. match can be •None: return all objects contained in artist (including artist) •function with signature boolean = match(artist) used to ﬁlter matches •class instance: eg Line2D. Only return artists of class type 722 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 flag() set the default colormap to ﬂag and apply to current image if any. See help(colormaps) for more information gca(**kwargs) Return the current axis instance. This can be used to control axis properties either using set or the Axes methods, for example, setting the xaxis range: plot(t,s) set(gca(), ’xlim’, [0,10]) or: plot(t,s) a = gca() a.set_xlim([0,10]) gcf () Return a reference to the current ﬁgure. gci() Get the current ScalarMappable instance (image or patch collection), or None if no images or patch collections have been deﬁned. The commands imshow() and figimage() create Image instances, and the commands pcolor() and scatter() create Collection instances. 48.1. matplotlib.pyplot 723 Matplotlib, Release 0.99.1.1 get_current_fig_manager() get_fignums() Return a list of existing ﬁgure numbers. get_plot_commands() ginput(*args, **kwargs) call signature: ginput(self, n=1, timeout=30, show_clicks=True, mouse_add=1, mouse_pop=3, mouse_stop=2) Blocking call to interact with the ﬁgure. This will wait for n clicks from the user and return a list of the coordinates of each click. If timeout is zero or negative, does not timeout. If n is zero or negative, accumulate clicks until a middle click (or potentially both mouse buttons at once) terminates the input. Right clicking cancels last input. The buttons used for the various actions (adding points, removing points, terminating the inputs) can be overriden via the arguments mouse_add, mouse_pop and mouse_stop, that give the associated mouse button: 1 for left, 2 for middle, 3 for right. The keyboard can also be used to select points in case your mouse does not have one or more of the buttons. The delete and backspace keys act like right clicking (i.e., remove last point), the enter key terminates input and any other key (not already used by the window manager) selects a point. gray() set the default colormap to gray and apply to current image if any. See help(colormaps) for more information grid(b=None, **kwargs) call signature: grid(self, b=None, **kwargs) Set the axes grids on or oﬀ; b is a boolean If b is None and len(kwargs)==0, toggle the grid state. If kwargs are supplied, it is assumed that you want a grid and b is thus set to True kawrgs are used to set the grid line properties, eg: ax.grid(color=’r’, linestyle=’-’, linewidth=2) Valid Line2D kwargs are Property 724 Description Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Table 48.11 – continued from previous pa alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number hexbin(x, y, C=None, gridsize=100, bins=None, xscale=’linear’, yscale=’linear’, extent=None, cmap=None, norm=None, vmin=None, vmax=None, alpha=1.0, linewidths=None, edgecolors=’none’, reduce_C_function=<function mean at 0x254c488>, mincnt=None, marginals=False, hold=None, **kwargs) call signature: 48.1. matplotlib.pyplot 725 Matplotlib, Release 0.99.1.1 hexbin(x, y, C = None, gridsize = 100, bins = None, xscale = ’linear’, yscale = ’linear’, cmap=None, norm=None, vmin=None, vmax=None, alpha=1.0, linewidths=None, edgecolors=’none’ reduce_C_function = np.mean, mincnt=None, marginals=True **kwargs) Make a hexagonal binning plot of x versus y, where x, y are 1-D sequences of the same length, N. If C is None (the default), this is a histogram of the number of occurences of the observations at (x[i],y[i]). If C is speciﬁed, it speciﬁes values at the coordinate (x[i],y[i]). These values are accumulated for each hexagonal bin and then reduced according to reduce_C_function, which defaults to numpy’s mean function (np.mean). (If C is speciﬁed, it must also be a 1-D sequence of the same length as x and y.) x, y and/or C may be masked arrays, in which case only unmasked points will be plotted. Optional keyword arguments: gridsize: [ 100 | integer ] The number of hexagons in the x-direction, default is 100. The corresponding number of hexagons in the y-direction is chosen such that the hexagons are approximately regular. Alternatively, gridsize can be a tuple with two elements specifying the number of hexagons in the x-direction and the y-direction. bins: [ None | ‘log’ | integer | sequence ] If None, no binning is applied; the color of each hexagon directly corresponds to its count value. If ‘log’, use a logarithmic scale for the color map. Internally, log10 (i + 1) is used to determine the hexagon color. If an integer, divide the counts in the speciﬁed number of bins, and color the hexagons accordingly. If a sequence of values, the values of the lower bound of the bins to be used. xscale: [ ‘linear’ | ‘log’ ] Use a linear or log10 scale on the horizontal axis. scale: [ ‘linear’ | ‘log’ ] Use a linear or log10 scale on the vertical axis. mincnt: None | a positive integer If not None, only display cells with more than mincnt number of points in the cell marginals: True|False if marginals is True, plot the marginal density as colormapped rectagles along the bottom of the x-axis and left of the y-axis extent: [ None | scalars (left, right, bottom, top) ] The limits of the bins. The default assigns the limits based on gridsize, x, y, xscale and yscale. Other keyword arguments controlling color mapping and normalization arguments: cmap: [ None | Colormap ] a matplotlib.cm.Colormap instance. If None, defaults to rc image.cmap. norm: [ None | Normalize ] matplotlib.colors.Normalize instance is used to scale luminance data to 0,1. 726 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 vmin/vmax: scalar vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array C is used. Note if you pass a norm instance, your settings for vmin and vmax will be ignored. alpha: scalar the alpha value for the patches linewidths: [ None | scalar ] If None, defaults to rc lines.linewidth. Note that this is a tuple, and if you set the linewidths argument you must set it as a sequence of ﬂoats, as required by RegularPolyCollection. Other keyword arguments controlling the Collection properties: edgecolors: [ None | mpl color | color sequence ] If ‘none’, draws the edges in the same color as the ﬁll color. This is the default, as it avoids unsightly unpainted pixels between the hexagons. If None, draws the outlines in the default color. If a matplotlib color arg or sequence of rgba tuples, draws the outlines in the speciﬁed color. Here are the standard descriptions of all the Collection kwargs: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path cmap color colorbar contains edgecolor or edgecolors facecolor or facecolors figure gid label linestyle or linestyles or dashes linewidth or lw or linewidths lod norm offsets picker pickradius rasterized 48.1. matplotlib.pyplot Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a colormap or registered colormap name matplotlib color arg or sequence of rgba tuples unknown a callable function matplotlib color arg or sequence of rgba tuples matplotlib color arg or sequence of rgba tuples a matplotlib.figure.Figure instance an id string any string [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] ﬂoat or sequence of ﬂoats [True | False] unknown ﬂoat or sequence of ﬂoats [None|ﬂoat|boolean|callable] unknown [True | False | None] Continued on next page 727 Matplotlib, Release 0.99.1.1 snap transform url urls visible zorder Table 48.12 – continued from previous page unknown Transform instance a url string unknown [True | False] any number The return value is a PolyCollection instance; use get_array() on this PolyCollection to get the counts in each hexagon.. If marginals is True, horizontal bar and vertical bar (both PolyCollections) will be attached to the return collection as attributes hbar and vbar Example: Additional kwargs: hold = [True|False] overrides default hold state hist(x, bins=10, range=None, normed=False, weights=None, cumulative=False, bottom=None, histtype=’bar’, align=’mid’, orientation=’vertical’, rwidth=None, log=False, hold=None, **kwargs) call signature: hist(x, bins=10, range=None, normed=False, cumulative=False, bottom=None, histtype=’bar’, align=’mid’, orientation=’vertical’, rwidth=None, log=False, **kwargs) 728 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Compute and draw the histogram of x. The return value is a tuple (n, bins, patches) or ([n0, n1, ...], bins, [patches0, patches1,...]) if the input contains multiple data. Keyword arguments: bins: Either an integer number of bins or a sequence giving the bins. x are the data to be binned. x can be an array, a 2D array with multiple data in its columns, or a list of arrays with data of diﬀerent length. Note, if bins is an integer input argument=numbins, bins + 1 bin edges will be returned, compatible with the semantics of numpy.histogram() with the new = True argument. Unequally spaced bins are supported if bins is a sequence. range: The lower and upper range of the bins. Lower and upper outliers are ignored. If not provided, range is (x.min(), x.max()). Range has no eﬀect if bins is a sequence. If bins is a sequence or range is speciﬁed, autoscaling is set oﬀ (autoscale_on is set to False) and the xaxis limits are set to encompass the full speciﬁed bin range. normed: If True, the ﬁrst element of the return tuple will be the counts normalized to form a probability density, i.e., n/(len(x)*dbin). In a probability density, the integral of the histogram should be 1; you can verify that with a trapezoidal integration of the probability density function: pdf, bins, patches = ax.hist(...) print np.sum(pdf * np.diff(bins)) weights An array of weights, of the same shape as x. Each value in x only contributes its associated weight towards the bin count (instead of 1). If normed is True, the weights are normalized, so that the integral of the density over the range remains 1. cumulative: If True, then a histogram is computed where each bin gives the counts in that bin plus all bins for smaller values. The last bin gives the total number of datapoints. If normed is also True then the histogram is normalized such that the last bin equals 1. If cumulative evaluates to less than 0 (e.g. -1), the direction of accumulation is reversed. In this case, if normed is also True, then the histogram is normalized such that the ﬁrst bin equals 1. histtype: [ ‘bar’ | ‘barstacked’ | ‘step’ | ‘stepﬁlled’ ] The type of histogram to draw. • ‘bar’ is a traditional bar-type histogram. If multiple data are given the bars are aranged side by side. • ‘barstacked’ is a bar-type histogram where multiple data are stacked on top of each other. • ‘step’ generates a lineplot that is by default unﬁlled. • ‘stepﬁlled’ generates a lineplot that is by default ﬁlled. align: [’left’ | ‘mid’ | ‘right’ ] Controls how the histogram is plotted. • ‘left’: bars are centered on the left bin edges. • ‘mid’: bars are centered between the bin edges. 48.1. matplotlib.pyplot 729 Matplotlib, Release 0.99.1.1 • ‘right’: bars are centered on the right bin edges. orientation: [ ‘horizontal’ | ‘vertical’ ] If ‘horizontal’, barh() will be used for bar-type histograms and the bottom kwarg will be the left edges. rwidth: The relative width of the bars as a fraction of the bin width. If None, automatically compute the width. Ignored if histtype = ‘step’ or ‘stepﬁlled’. log: If True, the histogram axis will be set to a log scale. If log is True and x is a 1D array, empty bins will be ﬁltered out and only the non-empty (n, bins, patches) will be returned. kwargs are used to update the properties of the hist Rectangle instances: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color contains edgecolor or ec facecolor or fc figure fill gid hatch label linestyle or ls linewidth or lw lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] or None for default an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] matplotlib color arg or sequence of rgba tuples a callable function mpl color spec, or None for default, or ‘none’ for no color mpl color spec, or None for default, or ‘none’ for no color a matplotlib.figure.Figure instance [True | False] an id string [ ‘/’ | ‘\’ | ‘|’ | ‘-‘ | ‘+’ | ‘x’ | ‘o’ | ‘O’ | ‘.’ | ‘*’ ] any string [’solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’] ﬂoat or None for default [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number You can use labels for your histogram, and only the ﬁrst Rectangle gets the label (the others get the magic string ‘_nolegend_’. This will make the histograms work in the intuitive way for bar charts: ax.hist(10+2*np.random.randn(1000), label=’men’) ax.hist(12+3*np.random.randn(1000), label=’women’, alpha=0.5) ax.legend() label can also be a sequence of strings. If multiple data is provided in x, the labels are asigned sequentially to the histograms. 730 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Example: Additional kwargs: hold = [True|False] overrides default hold state hlines(y, xmin, xmax, colors=’k’, linestyles=’solid’, label=”, hold=None, **kwargs) call signature: hlines(y, xmin, xmax, colors=’k’, linestyles=’solid’, **kwargs) Plot horizontal lines at each y from xmin to xmax. Returns the LineCollection that was added. Required arguments: y: a 1-D numpy array or iterable. xmin and xmax: can be scalars or len(x) numpy arrays. If they are scalars, then the respective values are constant, else the widths of the lines are determined by xmin and xmax. Optional keyword arguments: colors: a line collections color argument, either a single color or a len(y) list of colors linestyles: [ ‘solid’ | ‘dashed’ | ‘dashdot’ | ‘dotted’ ] Example: 48.1. matplotlib.pyplot 731 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state hold(b=None) Set the hold state. If b is None (default), toggle the hold state, else set the hold state to boolean value b: hold() # toggle hold hold(True) # hold is on hold(False) # hold is off When hold is True, subsequent plot commands will be added to the current axes. When hold is False, the current axes and ﬁgure will be cleared on the next plot command. hot() set the default colormap to hot and apply to current image if any. See help(colormaps) for more information hsv() set the default colormap to hsv and apply to current image if any. See help(colormaps) for more information imread(*args, **kwargs) Return image ﬁle in fname as numpy.array. Return value is a numpy.array. For grayscale images, the return array is MxN. For RGB images, the return value is MxNx3. For RGBA images the return value is MxNx4. 732 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 matplotlib can only read PNGs natively, but if PIL is installed, it will use it to load the image and return an array (if possible) which can be used with imshow(). imsave(*args, **kwargs) Saves a 2D numpy.array as an image with one pixel per element. The output formats available depend on the backend being used. Arguments: fname: A string containing a path to a ﬁlename, or a Python ﬁle-like object. If format is None and fname is a string, the output format is deduced from the extension of the ﬁlename. arr: A 2D array. Keyword arguments: vmin/vmax: [ None | scalar ] vmin and vmax set the color scaling for the image by ﬁxing the values that map to the colormap color limits. If either vmin or vmax is None, that limit is determined from the arr min/max value. cmap: cmap is a colors.Colormap instance, eg cm.jet. If None, default to the rc image.cmap value. format: One of the ﬁle extensions supported by the active backend. Most backends support png, pdf, ps, eps and svg. origin [ ‘upper’ | ‘lower’ ] Indicates where the [0,0] index of the array is in the upper left or lower left corner of the axes. Defaults to the rc image.origin value. imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=1.0, vmin=None, vmax=None, origin=None, extent=None, shape=None, ﬁlternorm=1, ﬁlterrad=4.0, imlim=None, resample=None, url=None, hold=None, **kwargs) call signature: imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=1.0, vmin=None, vmax=None, origin=None, extent=None, **kwargs) Display the image in X to current axes. X may be a ﬂoat array, a uint8 array or a PIL image. If X is an array, X can have the following shapes: •MxN – luminance (grayscale, ﬂoat array only) •MxNx3 – RGB (ﬂoat or uint8 array) •MxNx4 – RGBA (ﬂoat or uint8 array) The value for each component of MxNx3 and MxNx4 ﬂoat arrays should be in the range 0.0 to 1.0; MxN ﬂoat arrays may be normalised. An matplotlib.image.AxesImage instance is returned. Keyword arguments: cmap: [ None | Colormap ] A matplotlib.cm.Colormap instance, eg. cm.jet. If None, default to rc image.cmap value. cmap is ignored when X has RGB(A) information aspect: [ None | ‘auto’ | ‘equal’ | scalar ] If ‘auto’, changes the image aspect ratio to match that of the axes 48.1. matplotlib.pyplot 733 Matplotlib, Release 0.99.1.1 If ‘equal’, and extent is None, changes the axes aspect ratio to match that of the image. If extent is not None, the axes aspect ratio is changed to match that of the extent. If None, default to rc image.aspect value. interpolation: Acceptable values are None, ‘nearest’, ‘bilinear’, ‘bicubic’, ‘spline16’, ‘spline36’, ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’, ‘quadric’, ‘catrom’, ‘gaussian’, ‘bessel’, ‘mitchell’, ‘sinc’, ‘lanczos’, If interpolation is None, default to rc image.interpolation. See also the ﬁlternorm and ﬁlterrad parameters norm: [ None | Normalize ] An matplotlib.colors.Normalize instance; if None, default is normalization(). This scales luminance -> 0-1 norm is only used for an MxN ﬂoat array. vmin/vmax: [ None | scalar ] Used to scale a luminance image to 0-1. If either is None, the min and max of the luminance values will be used. Note if norm is not None, the settings for vmin and vmax will be ignored. alpha: scalar The alpha blending value, between 0 (transparent) and 1 (opaque) origin: [ None | ‘upper’ | ‘lower’ ] Place the [0,0] index of the array in the upper left or lower left corner of the axes. If None, default to rc image.origin. extent: [ None | scalars (left, right, bottom, top) ] Data limits for the axes. The default assigns zero-based row, column indices to the x, y centers of the pixels. shape: [ None | scalars (columns, rows) ] For raw buﬀer images ﬁlternorm: A parameter for the antigrain image resize ﬁlter. From the antigrain documentation, if ﬁlternorm = 1, the ﬁlter normalizes integer values and corrects the rounding errors. It doesn’t do anything with the source ﬂoating point values, it corrects only integers according to the rule of 1.0 which means that any sum of pixel weights must be equal to 1.0. So, the ﬁlter function must produce a graph of the proper shape. ﬁlterrad: The ﬁlter radius for ﬁlters that have a radius parameter, i.e. when interpolation is one of: ‘sinc’, ‘lanczos’ or ‘blackman’ Additional kwargs are Artist properties: 734 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Property alpha animated axes clip_box clip_on clip_path contains figure gid label lod picker rasterized snap transform url visible zorder Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a callable function a matplotlib.figure.Figure instance an id string any string [True | False] [None|ﬂoat|boolean|callable] [True | False | None] unknown Transform instance a url string [True | False] any number Example: Additional kwargs: hold = [True|False] overrides default hold state ioff () 48.1. matplotlib.pyplot 735 Matplotlib, Release 0.99.1.1 Turn interactive mode oﬀ. ion() Turn interactive mode on. ishold() Return the hold status of the current axes isinteractive() Return the interactive status jet() set the default colormap to jet and apply to current image if any. See help(colormaps) for more information legend(*args, **kwargs) call signature: legend(*args, **kwargs) Place a legend on the current axes at location loc. Labels are a sequence of strings and loc can be a string or an integer specifying the legend location. To make a legend with existing lines: legend() legend() by itself will try and build a legend using the label property of the lines/patches/collections. You can set the label of a line by doing: plot(x, y, label=’my data’) or: line.set_label(’my data’). If label is set to ‘_nolegend_’, the item will not be shown in legend. To automatically generate the legend from labels: legend( (’label1’, ’label2’, ’label3’) ) To make a legend for a list of lines and labels: legend( (line1, line2, line3), (’label1’, ’label2’, ’label3’) ) To make a legend at a given location, using a location argument: legend( (’label1’, ’label2’, ’label3’), loc=’upper left’) or: 736 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 legend( (line1, line2, line3), (’label1’, ’label2’, ’label3’), loc=2) The location codes are Location String ‘best’ ‘upper right’ ‘upper left’ ‘lower left’ ‘lower right’ ‘right’ ‘center left’ ‘center right’ ‘lower center’ ‘upper center’ ‘center’ Location Code 0 1 2 3 4 5 6 7 8 9 10 Users can specify any arbitrary location for the legend using the bbox_to_anchor keyword argument. bbox_to_anchor can be an instance of BboxBase(or its derivatives) or a tuple of 2 or 4 ﬂoats. For example, loc = ‘upper right’, bbox_to_anchor = (0.5, 0.5) will place the legend so that the upper right corner of the legend at the center of the axes. The legend location can be speciﬁed in other coordinate, by using the bbox_transform keyword. The loc itslef can be a 2-tuple giving x,y of the lower-left corner of the legend in axes coords (bbox_to_anchor is ignored). Keyword arguments: prop: [ None | FontProperties | dict ] A matplotlib.font_manager.FontProperties instance. If prop is a dictionary, a new instance will be created with prop. If None, use rc settings. numpoints: integer The number of points in the legend for line scatterpoints: integer The number of points in the legend for scatter plot scatteroﬀsets: list of ﬂoats a list of yoﬀsets for scatter symbols in legend markerscale: [ None | scalar ] The relative size of legend markers vs. original. If None, use rc settings. fancybox: [ None | False | True ] if True, draw a frame with a round fancybox. If None, use rc shadow: [ None | False | True ] If True, draw a shadow behind legend. If None, use rc settings. ncol [integer] number of columns. default is 1 mode [[ “expand” | None ]] if mode is “expand”, the legend will be horizontally expanded to ﬁll the axes area (or bbox_to_anchor) 48.1. matplotlib.pyplot 737 Matplotlib, Release 0.99.1.1 bbox_to_anchor [an instance of BboxBase or a tuple of 2 or 4 ﬂoats] the bbox that the legend will be anchored. bbox_transform [[ an instance of Transform | None ]] the transform for the bbox. transAxes if None. title [string] the legend title Padding and spacing between various elements use following keywords parameters. The dimensions of these values are given as a fraction of the fontsize. Values from rcParams will be used if None. Keyword borderpad labelspacing handlelength handletextpad borderaxespad columnspacing Description the fractional whitespace inside the legend border the vertical space between the legend entries the length of the legend handles the pad between the legend handle and text the pad between the axes and legend border the spacing between columns Example: Also see Legend guide. loglog(*args, **kwargs) call signature: 738 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 loglog(*args, **kwargs) Make a plot with log scaling on the x and y axis. loglog() supports all the keyword arguments of plot() matplotlib.axes.Axes.set_xscale() / matplotlib.axes.Axes.set_yscale(). and Notable keyword arguments: basex/basey: scalar > 1 base of the x/y logarithm subsx/subsy: [ None | sequence ] the location of the minor x /y ticks; None defaults to autosubs, which depend on the number of decades in the plot; see matplotlib.axes.Axes.set_xscale() / matplotlib.axes.Axes.set_yscale() for details nonposx/nonposy: [’mask’ | ‘clip’ ] non-positive values in x or y can be masked as invalid, or clipped to a very small positive number The remaining valid kwargs are Line2D properties: Property alpha animated antialiased or aa axes clip_box clip_on clip_path color or c contains dash_capstyle dash_joinstyle dashes data drawstyle figure fillstyle gid label linestyle or ls linewidth or lw lod marker markeredgecolor or mec markeredgewidth or mew markerfacecolor or mfc markersize or ms markevery 48.1. matplotlib.pyplot Description ﬂoat (0.0 transparent through 1.0 opaque) [True | False] [True | False] an Axes instance a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] any matplotlib color a callable function [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] sequence of on/oﬀ ink in points 2D array [ ‘default’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ ] a matplotlib.figure.Figure instance [’full’ | ‘left’ | ‘right’ | ‘bottom’ | ‘top’] an id string any string [ ‘-‘ | ‘–‘ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’ ] and any drawstyle in combination with a linestyle, e.g. ‘ ﬂoat value in points [True | False] [ ‘+’ | ‘*’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘<’ | ‘>’ | ‘D’ | ‘H’ | ‘^’ | ‘_’ | ‘d’ | ‘h’ | ‘o’ | ‘p’ | ‘s’ | ‘v any matplotlib color ﬂoat value in points any matplotlib color ﬂoat None | integer | (startind, stride) 739 Matplotlib, Release 0.99.1.1 picker pickradius rasterized snap solid_capstyle solid_joinstyle transform url visible xdata ydata zorder Table 48.13 – continued from previous pa ﬂoat distance in points or callable pick function fn(artist, event) ﬂoat distance in points [True | False | None] unknown [’butt’ | ‘round’ | ‘projecting’] [’miter’ | ‘round’ | ‘bevel’] a matplotlib.transforms.Transform instance a url string [True | False] 1D array 1D array any number Example: Additional kwargs: hold = [True|False] overrides default hold state matshow(A, ﬁgnum=None, **kw) Display an array as a matrix in a new ﬁgure window. The origin is set at the upper left hand corner and rows (ﬁrst dimension of the array) are displayed horizontally. The aspect ratio of the ﬁgure window is that of the array, unless this would make an 740 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 excessively short or narrow ﬁgure. Tick labels for the xaxis are placed on top. With the exception of ﬁgnum, keyword arguments are passed to imshow(). ﬁgnum: [ None | integer | False ] By default, matshow() creates a new ﬁgure window with automatic numbering. If ﬁgnum is given as an integer, the created ﬁgure will use this ﬁgure number. Because of how matshow() tries to set the ﬁgure aspect ratio to be the one of the array, if you provide the number of an already existing ﬁgure, strange things may happen. If ﬁgnum is False or 0, a new ﬁgure window will NOT be created. minorticks_off () Remove minor ticks from the current plot. minorticks_on() Display minor ticks on the current plot. Displaying minor ticks reduces performance; turn them oﬀ using minorticks_oﬀ() if drawing speed is a problem. over(func, *args, **kwargs) over calls: func(*args, **kwargs) with hold(True) and then restores the hold state. pcolor(*args, **kwargs) call signatures: pcolor(C, **kwargs) pcolor(X, Y, C, **kwargs) Create a pseudocolor plot of a 2-D array. C is the array of color values. X and Y, if given, specify the (x, y) coordinates of the colored quadrilaterals; the quadrilateral for C[i,j] has corners at: (X[i, (X[i, (X[i+1, (X[i+1, j], j+1], j], j+1], Y[i, Y[i, Y[i+1, Y[i+1, j]), j+1]), j]), j+1]). Ideally the dimensions of X and Y should be one greater than those of C; if the dimensions are the same, then the last row and column of C will be ignored. Note that the the column index corresponds to the x-coordinate, and the row index corresponds to y; for details, see the Grid Orientation section below. If either or both of X and Y are 1-D arrays or column vectors, they will be expanded as needed into the appropriate 2-D arrays, making a rectangular grid. 48.1. matplotlib.pyplot 741 Matplotlib, Release 0.99.1.1 X, Y and C may be masked arrays. If either C[i, j], or one of the vertices surrounding C[i,j] (X or Y at [i, j], [i+1, j], [i, j+1],[i+1, j+1]) is masked, nothing is plotted. Keyword arguments: cmap: [ None | Colormap ] A matplotlib.cm.Colormap instance. If None, use rc settings. norm: [ None | Normalize ] An matplotlib.colors.Normalize instance is used to scale luminance data to 0,1. If None, defaults to normalize(). vmin/vmax: [ None | scalar ] vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array C is used. If you pass a norm instance, vmin and vmax will be ignored. shading: [ ‘ﬂat’ | ‘faceted’ ] If ‘faceted’, a black grid is drawn around each rectangle; if ‘ﬂat’, edges are not drawn. Default is ‘ﬂat’, contrary to Matlab(TM). This kwarg is deprecated; please use ‘edgecolors’ instead: • shading=’ﬂat’ edgecolors=’None’ – • shading=’faceted – edgecolors=’k’ edgecolors: [ None | ‘None’ | color | color sequence] If None, the rc setting is used by default. If ‘None’, edges will not be visible. An mpl color or sequence of colors will set the edge color alpha: 0 <= scalar <= 1 the alpha blending value Return value is a matplotlib.collection.Collection instance. The grid orientation follows the Matlab(TM) convention: an array C with shape (nrows, ncolumns) is plotted with the column number as X and the row number as Y, increasing up; hence it is plotted the way the array would be printed, except that the Y axis is reversed. That is, C is taken as C*(*y, x). Similarly for meshgrid(): x = np.arange(5) y = np.arange(3) X, Y = meshgrid(x,y) is equivalent to: X = array([[0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]) Y = array([[0, 0, 0, 0, 0], [1, 1, 1, 1, 1], [2, 2, 2, 2, 2]]) so if you have: C = rand( len(x), len(y)) then you need: 742 Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 pcolor(X, Y, C.T) or: pcolor(C.T) Matlab pcolor() always discards the last row and column of C, but matplotlib displays the last row and column if X and Y are not speciﬁed, or if X and Y have one more row and column than C. kwargs can be used to control the PolyCollection properties: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on clip_path cmap color colorbar contains edgecolor or edgecolors facecolor or facecolors figure gid label linestyle or linestyles or dashes linewidth or lw or linewidths lod norm offsets picker pickradius rasterized snap transform url urls visible zorder 48.1. matplotlib.pyplot Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] [ (Path, Transform) | Patch | None ] a colormap or registered colormap name matplotlib color arg or sequence of rgba tuples unknown a callable function matplotlib color arg or sequence of rgba tuples matplotlib color arg or sequence of rgba tuples a matplotlib.figure.Figure instance an id string any string [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-oﬀ-dash-seq) ] ﬂoat or sequence of ﬂoats [True | False] unknown ﬂoat or sequence of ﬂoats [None|ﬂoat|boolean|callable] unknown [True | False | None] unknown Transform instance a url string unknown [True | False] any number 743 Matplotlib, Release 0.99.1.1 Additional kwargs: hold = [True|False] overrides default hold state pcolormesh(*args, **kwargs) call signatures: pcolormesh(C) pcolormesh(X, Y, C) pcolormesh(C, **kwargs) C may be a masked array, but X and Y may not. Masked array support is implemented via cmap and norm; in contrast, pcolor() simply does not draw quadrilaterals with masked colors or vertices. Keyword arguments: cmap: [ None | Colormap ] A matplotlib.cm.Colormap instance. If None, use rc settings. norm: [ None | Normalize ] A matplotlib.colors.Normalize instance is used to scale luminance data to 0,1. If None, defaults to normalize(). vmin/vmax: [ None | scalar ] vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array C is used. If you pass a norm instance, vmin and vmax will be ignored. shading: [ ‘ﬂat’ | ‘faceted’ ] If ‘faceted’, a black grid is drawn around each rectangle; if ‘ﬂat’, edges are not drawn. Default is ‘ﬂat’, contrary to Matlab(TM). This kwarg is deprecated; please use ‘edgecolors’ instead: • shading=’ﬂat’ edgecolors=’None’ – • shading=’faceted – edgecolors=’k’ edgecolors: [ None | ‘None’ | color | color sequence] If None, the rc setting is used by default. If ‘None’, edges will not be visible. An mpl color or sequence of colors will set the edge color alpha: 0 <= scalar <= 1 the alpha blending value Return value is a matplotlib.collection.QuadMesh object. kwargs can be used to control the matplotlib.collections.QuadMesh properties: Property alpha animated antialiased or antialiaseds array axes clim clip_box clip_on 744 Description ﬂoat [True | False] Boolean or sequence of booleans unknown an Axes instance a length 2 sequence of ﬂoats a matplotlib.transforms.Bbox instance [True | False] Continued on next page Chapter 48. matplotlib pyplot Matplotlib, Release 0.99.1.1 Table 48.15 – continued from previous page clip_path [ (Path, Transform) | Patch | None ] cmap a colormap or registered colormap name color matplotlib color arg or sequence of rgba tuples colorbar unknown contains a callable function edgecolor or edgecolors matplotlib color arg or sequence of rgba tuples facecolor or facecolors matplotlib color arg or sequence of rgba tuples figure a matplotlib.figure.Figure instance gid an id string label any string linestyle or linestyles or dashes [’solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | (oﬀset, on-o