| 1 | ======================= |
|---|
| 2 | The ``plotting`` module |
|---|
| 3 | ======================= |
|---|
| 4 | |
|---|
| 5 | This module contains a collection of tools for plotting and image processing that shall |
|---|
| 6 | facilitate the generation and handling of your data visualizations. |
|---|
| 7 | It utilizes the Matplotlib and the Python Imaging Library (PIL) packages. |
|---|
| 8 | |
|---|
| 9 | |
|---|
| 10 | --------------------------------------------------------- |
|---|
| 11 | Universal Functions and Classes for Normal Matplotlib Use |
|---|
| 12 | --------------------------------------------------------- |
|---|
| 13 | |
|---|
| 14 | The following functions might be useful for every user of the Matplotlib package. |
|---|
| 15 | |
|---|
| 16 | |
|---|
| 17 | The function ``get_display(display)`` |
|---|
| 18 | ------------------------------------- |
|---|
| 19 | |
|---|
| 20 | Arguments: |
|---|
| 21 | ~~~~~~~~~~ |
|---|
| 22 | * display - if True, a new figure is created. Otherwise, if display is a subplot object, this object is returned. |
|---|
| 23 | |
|---|
| 24 | Returns: |
|---|
| 25 | ~~~~~~~~ |
|---|
| 26 | A pylab object with a plot() function to draw the plots. |
|---|
| 27 | |
|---|
| 28 | |
|---|
| 29 | |
|---|
| 30 | The function ``progress_bar(progress)`` |
|---|
| 31 | --------------------------------------- |
|---|
| 32 | |
|---|
| 33 | Arguments: |
|---|
| 34 | ~~~~~~~~~~ |
|---|
| 35 | * progress - a float between 0. and 1. |
|---|
| 36 | |
|---|
| 37 | Returns: |
|---|
| 38 | ~~~~~~~~ |
|---|
| 39 | Prints a progress bar to stdout, filled to the given ratio. |
|---|
| 40 | |
|---|
| 41 | Example of usage:: |
|---|
| 42 | |
|---|
| 43 | >>> progress_bar(0.7) |
|---|
| 44 | |=================================== | |
|---|
| 45 | |
|---|
| 46 | |
|---|
| 47 | |
|---|
| 48 | The function ``pylab_params(fig_width_pt, ratio, text_fontsize, tick_labelsize, useTex)`` |
|---|
| 49 | ----------------------------------------------------------------------------------------- |
|---|
| 50 | |
|---|
| 51 | Arguments: |
|---|
| 52 | ~~~~~~~~~~ |
|---|
| 53 | * fig_width_pt - figure width in points. If you want to use your figure inside LaTeX, get this value from LaTeX using '\\showthe\\columnwidth'. |
|---|
| 54 | * ratio - ratio between the height and the width of the figure |
|---|
| 55 | * text_fontsize - size of axes and in-pic text fonts |
|---|
| 56 | * tick_labelsize - size of tick label font |
|---|
| 57 | * useTex - enables or disables the use of LaTeX for all labels and texts (for details on how to do that, see http://www.scipy.org/Cookbook/Matplotlib/UsingTex) |
|---|
| 58 | |
|---|
| 59 | Returns: |
|---|
| 60 | ~~~~~~~~ |
|---|
| 61 | A dictionary with a set of parameters that help to nicely format figures. |
|---|
| 62 | The return object can be used to update the pylab run command parameters dictionary 'pylab.rcParams'. |
|---|
| 63 | |
|---|
| 64 | |
|---|
| 65 | |
|---|
| 66 | The function ``set_axis_limits(subplot, xmin, xmax, ymin, ymax)`` |
|---|
| 67 | ----------------------------------------------------------------- |
|---|
| 68 | |
|---|
| 69 | Arguments: |
|---|
| 70 | ~~~~~~~~~~ |
|---|
| 71 | * subplot - the targeted plot |
|---|
| 72 | * xmin, xmax - the limits of the x axis |
|---|
| 73 | * ymin, ymax - the limits of the y axis |
|---|
| 74 | |
|---|
| 75 | Does: |
|---|
| 76 | ~~~~~ |
|---|
| 77 | Defines the axis limits in a plot. |
|---|
| 78 | |
|---|
| 79 | Example of usage:: |
|---|
| 80 | |
|---|
| 81 | >>> x = range(10) |
|---|
| 82 | >>> y = [] |
|---|
| 83 | >>> for i in x: y.append(i*i) |
|---|
| 84 | >>> pylab.plot(x,y) |
|---|
| 85 | >>> plotting.set_axis_limits(pylab, 0., 10., 0., 100.) |
|---|
| 86 | |
|---|
| 87 | |
|---|
| 88 | |
|---|
| 89 | |
|---|
| 90 | The function ``set_labels(subplot, xlabel, ylabel)`` |
|---|
| 91 | ---------------------------------------------------- |
|---|
| 92 | |
|---|
| 93 | Arguments: |
|---|
| 94 | ~~~~~~~~~~ |
|---|
| 95 | * subplot - the targeted plot |
|---|
| 96 | * xlabel - a string for the x label |
|---|
| 97 | * ylabel - a string for the y label |
|---|
| 98 | |
|---|
| 99 | Does: |
|---|
| 100 | ~~~~~ |
|---|
| 101 | Defines the axis labels of a plot. |
|---|
| 102 | |
|---|
| 103 | Example of usage:: |
|---|
| 104 | |
|---|
| 105 | >>> x = range(10) |
|---|
| 106 | >>> y = [] |
|---|
| 107 | >>> for i in x: y.append(i*i) |
|---|
| 108 | >>> pylab.plot(x,y) |
|---|
| 109 | >>> plotting.set_labels(pylab, 'x', 'y=x^2') |
|---|
| 110 | |
|---|
| 111 | |
|---|
| 112 | |
|---|
| 113 | The function ``set_pylab_params(fig_width_pt, ratio, text_fontsize, tick_labelsize, useTex)`` |
|---|
| 114 | --------------------------------------------------------------------------------------------- |
|---|
| 115 | |
|---|
| 116 | Arguments: |
|---|
| 117 | ~~~~~~~~~~ |
|---|
| 118 | * fig_width_pt - figure width in points. If you want to use your figure inside LaTeX, get this value from LaTeX using '\\showthe\\columnwidth'. |
|---|
| 119 | * ratio - ratio between the height and the width of the figure |
|---|
| 120 | * text_fontsize - size of axes and in-pic text fonts |
|---|
| 121 | * tick_labelsize - size of tick label font |
|---|
| 122 | * useTex - enables or disables the use of LaTeX for all labels and texts (for details on how to do that, see http://www.scipy.org/Cookbook/Matplotlib/UsingTex) |
|---|
| 123 | |
|---|
| 124 | Does: |
|---|
| 125 | ~~~~~ |
|---|
| 126 | Updates a set of parameters within the the pylab run command parameters dictionary 'pylab.rcParams' in order to achieve nicely formatted figures. |
|---|
| 127 | |
|---|
| 128 | |
|---|
| 129 | |
|---|
| 130 | ---------------------------------------------------------------- |
|---|
| 131 | Special Plotting Functions and Classes for Specific Requirements |
|---|
| 132 | ---------------------------------------------------------------- |
|---|
| 133 | |
|---|
| 134 | |
|---|
| 135 | |
|---|
| 136 | The function ``save_2D_image(mat, filename)`` |
|---|
| 137 | --------------------------------------------- |
|---|
| 138 | |
|---|
| 139 | Arguments: |
|---|
| 140 | ~~~~~~~~~~ |
|---|
| 141 | * mat - a 2D numpy array of floats between 0 and 1 |
|---|
| 142 | * filename - string specifying the filename where to save the data, has to end on '.png' |
|---|
| 143 | |
|---|
| 144 | Does: |
|---|
| 145 | ~~~~~ |
|---|
| 146 | Saves a 2D numpy array of gray shades between 0 and 1 to a PNG file. |
|---|
| 147 | |
|---|
| 148 | Example of usage:: |
|---|
| 149 | |
|---|
| 150 | >>> import numpy |
|---|
| 151 | >>> a = numpy.random.random([100,100]) # creates a 2D numpy array with random values between 0. and 1. |
|---|
| 152 | >>> save_2D_image(a,'randomarray100x100.png') |
|---|
| 153 | |
|---|
| 154 | |
|---|
| 155 | |
|---|
| 156 | The function ``save_2D_movie(frame_list, filename, frame_duration)`` |
|---|
| 157 | -------------------------------------------------------------------- |
|---|
| 158 | |
|---|
| 159 | Arguments: |
|---|
| 160 | ~~~~~~~~~~ |
|---|
| 161 | * frame_list - a list of 2D numpy arrays of floats between 0 and 1 |
|---|
| 162 | * filename - string specifying the filename where to save the data, has to end on '.zip' |
|---|
| 163 | * frame_duration - specifier for the duration per frame, will be stored as additional meta-data for later playing |
|---|
| 164 | |
|---|
| 165 | Does: |
|---|
| 166 | ~~~~~ |
|---|
| 167 | Saves a list of 2D numpy arrays of gray shades between 0 and 1 to a zipped tree of PNG files. |
|---|
| 168 | |
|---|
| 169 | Example of usage:: |
|---|
| 170 | |
|---|
| 171 | >>> import numpy |
|---|
| 172 | >>> framelist = [] |
|---|
| 173 | >>> for i in range(100): framelist.append(numpy.random.random([100,100])) # creates a list of 2D numpy arrays with random values between 0. and 1. |
|---|
| 174 | >>> save_2D_movie(framelist, 'randommovie100x100x100.zip', 0.1) |
|---|
| 175 | |
|---|
| 176 | |
|---|
| 177 | |
|---|
| 178 | The ``SimpleMultiplot`` class |
|---|
| 179 | ----------------------------- |
|---|
| 180 | This class creates a figure consisting of multiple panels, all with the same datatype and the same x-range. |
|---|
| 181 | |
|---|
| 182 | |
|---|
| 183 | Creation / Constructor Arguments: |
|---|
| 184 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|---|
| 185 | * nrows - number of rows |
|---|
| 186 | * ncolumns - number of columns |
|---|
| 187 | * title - the title of the multi-plot |
|---|
| 188 | * xlabel - label for all x-axes |
|---|
| 189 | * ylabel - label for all y-axes |
|---|
| 190 | * scaling - a tuple consisting of two string out of {"liner","log"}, determining the scaling of the x-axis and y-axis |
|---|
| 191 | |
|---|
| 192 | Here is an example of creating a ``SimpleMultiplot`` object:: |
|---|
| 193 | |
|---|
| 194 | >>> nrows = 4 |
|---|
| 195 | >>> ncolumns = 5 |
|---|
| 196 | >>> title = 'a SimpleMultiplot' |
|---|
| 197 | >>> xlabel = 'the x axis' |
|---|
| 198 | >>> ylabel = 'the y axis' |
|---|
| 199 | >>> scaling = ('linear','log') |
|---|
| 200 | >>> smp = SimpleMultiplot(nrows=self.nrows, ncolumns=self.ncolumns, title=title, xlabel=xlabel, ylabel=ylabel, scaling=scaling) |
|---|
| 201 | |
|---|
| 202 | Selecting Panels: |
|---|
| 203 | ~~~~~~~~~~~~~~~~~ |
|---|
| 204 | Handles to panels can be directly accessed by their indices via the function call ``panel(i)`` or by stepping iteratively through them with function |
|---|
| 205 | ``next_panel()``. |
|---|
| 206 | |
|---|
| 207 | Defining Frames: |
|---|
| 208 | ~~~~~~~~~~~~~~~~ |
|---|
| 209 | The frames surrounding a panel can be defined with the function ``set_frame(ax, boollist, linewidth)``, where ax is the handle to the panel of choice, |
|---|
| 210 | boollist is a list of four booleans defining if [bottom, left, top, right] of the panel shall have a frame line with width linewidth. |
|---|
| 211 | |
|---|
| 212 | Finalising and Saving: |
|---|
| 213 | ~~~~~~~~~~~~~~~~~~~~~~ |
|---|
| 214 | Once a SimpleMultiplot is ready to be saved, calling ``finalise()`` will turn off tick labels for all x-axes except the bottom one. |
|---|
| 215 | The whole plot is saved to a filename and type of choice with the call ``save(filename)``. |
|---|
