"""

L{Plotter} uses a class-wide instance of me to hold weak

references to its instances.

@see: L{Plotter.showAll}, which uses my weak references to show

the Matplotlib figures for all instances of L{Plotter} and

then remove them.

"""

def __init__(self):

"""C{PlotterHolder()}"""

self.pDict = weakref.WeakValueDictionary()

def add(self, obj):

"""

Adds the L{Plotter} instance (or anything, really, but plotters

are what I was intended for) to my weak-reference registry.

Returns an integer ID that you can use with a call to

L{remove} and thus avoid having to keep a reference to the

object yourself.

"""

ID = id(obj)

self.pDict[ID] = obj

return ID

def remove(self, ID):

"""

Removes the L{Plotter} instance identified by the supplied I{ID}

from my weak-reference registry.

"""

if ID in self.pDict:

del self.pDict[ID]

def removeAll(self):

"""

Removes all L{Plotter} instances from my weak-reference registry.

"""

self.pDict.clear()

def doForAll(self, methodName, *args, **kw):

"""

Does the method named I{methodName}, with any args and kw, for

each L{Plotter} instance I'm keeping track of.

Returns C{True} if there was at least one object that successfully

performed I{methodName}.

"""

OK = False

for ID in list(self.pDict.keys()):

if ID in self.pDict:

OK = True

try:

getattr(self.pDict[ID], methodName)(*args, **kw)

except: OK = False

"""

I store dimensions of things for each subplot. If my I{debug}

class attribute is set C{True}, I print info about what's being

set and get for debugging purposes.

"""

debug = False

def __init__(self):

self.sp_dicts = {}

def clear(self):

"""

Clears out all my info.

"""

if self.debug:

print("DIMS cleared")

self.sp_dicts.clear()

def setDims(self, k, name, dims):

"""

For subplot I{k} (index starts at zero), sets the X and Y

dimensions of an object with the specified I{name} to the

supplied sequence I{dims}.

"""

dims = tuple(dims)

if self.debug:

print(sub("DIMS {:d}: {} <-- {}", k, name, dims))

self.sp_dicts.setdefault(k, {})[name] = dims

def getDims(self, k, name):

"""

For subplot I{k}, returns the dimension of the object with the

specified I{name} or C{None} if no such dimension has been

set.

"""

if k not in self.sp_dicts: return

value = self.sp_dicts[k].get(name, None)

if self.debug:

print(sub("DIMS {:d}: {} -> {}", k, name, value))

"""

I provide a Matplotlib C{Figure} with one or more time-vector and

XY subplots of Numpy vectors.

Construct an instance of me with the total number of subplots (to

be intelligently apportioned into one or more rows and columns)

or, with two constructor arguments, the number of columns followed

by the number of rows.

With the I{filePath} keyword, you can specify the file path of a

PNG file for me to create or overwrite with each call to L{show}.

You can set the I{width} and I{height} of the Figure with

constructor keywords, and (read-only) access them via my

properties of the same names. Or set my I{figSize} attribute (in a

subclass or with that constructor keyword) to a 2-sequence with

figure width and height. The default width and height is just shy

of the entire monitor size.

The dimensions are in inches, converted to pixels at 100 DPI,

unless they are both integers and either of them exceeds 75 (which

would equate to a huge 7,500 pixels). In that case, they are

considered to specify the pixel dimensions directly.

Use the "Agg" backend by supplying the constructor keyword

I{useAgg}. This works better for plotting to an image file, and is

selected automatically if you supply a I{filePath} to the

constructor. Be aware that, once selected, that backend will be

used for all instances of me. If you're using the "Agg" backend,

you should specify it the first time an instance is constructed.

Setting the I{verbose} keyword C{True} puts out a bit of info

about annotator positioning. Not for regular use.

Any other keywords you supply to the constructor are supplied to

the underlying Matplotlib plotting call for all

subplots.

Keep the API for L{OptsBase} handy, and maybe a copy of the

U{source<http://edsuom.com/yampex/yampex.plot.py>}, to see all the

plotting options you can set.

@ivar dims: A dict (actually, a subclass of L{Dims}) of sub-dicts

of the dimensions of various text objects, keyed first by

subplot index then the object name.

@ivar Nsp: The number of subplots defined thus far defined with

calls to my instance.

"""

ph = PlotterHolder()

fc = None

DPI = 100 # Don't change this, for reference only

_settings = {'title', 'xlabel', 'ylabel'}

figSize = None

# Flag to indicate if using Agg rendererer (for generating PNG files)

usingAgg = False

# Show warnings? (Not for regular use.)

verbose = False

@classmethod

def setupClass(cls, useAgg=False):

"""

Called by each instance of me during instantiation. Sets a

class-wide Matplotlib pyplot import the first time it's

called.

If any instance of me is using the Agg renderer, all instances

will.

"""

mpl = importlib.import_module("matplotlib")

if useAgg and not cls.usingAgg:

mpl.use('Agg')

cls.usingAgg = True

else:

try:

raise Exception(

"Neither GTK3Agg nor PyQt5Agg actually work consistently")

mpl.use('GTK3Agg')

except:

try:

mpl.use('tkagg')

except:

if verbose:

print("WARNING: Neither GTK3Agg nor tkagg available!")

if not getattr(cls, 'plt', None):

cls.plt = importlib.import_module("matplotlib.pyplot")

@classmethod

def showAll(cls):

"""

Calls L{show} for the figures generated by all instances of me.

"""

OK = cls.ph.doForAll('show', noShow=True)

if OK: cls.plt.show()

cls.ph.doForAll('clear')

# They should all have removed themselves now, but what the

# heck, clear it anyways

cls.ph.removeAll()

def __init__(self, *args, **kw):

"""

Constructor possibilities (not including keywords, except I{Nc}):

C{Plotter(Nc, Nr)}: Specify I{Nc} columns and I{Nr} rows.

C{Plotter(N)}: Specify up to I{N} subplots in optimal

arrangement of columns and rows.

C{Plotter(N, Nc=x)}: Specify up to I{N} columns subplots with

I{x} columns.

C{Plotter(Nc, Nr, V)}: Specify I{Nc} columns and I{Nr} rows,

with container object I{V}.

C{Plotter(Nc, Nr, V)}: Specify up to I{N} subplots in optimal

arrangement of columns and rows, with container object I{V}.

C{Plotter(N, V, Nc=x)}: Specify up to I{N} columns subplots

with I{x} columns, with container object I{V}.

@keyword filePath: Specify the path of a PNG file to be

created instead of a plot window being opened. (Implies

I{useAgg}.)

@keyword useAgg: Set C{True} to use the "Agg" backend, which

works better for creating image files. If you're going to

specify it for multiple plot images, do so the first time

an instance of me is constructed.

@keyword figSize: Set to a 2-sequence with figure width and

height if not using the default, which is just shy of your

entire monitor size. Dimensions are in inches, converted

to pixels at 100 DPI, unless both are integers and either

exceeds 75. Then they are considered to specify the pixel

dimensions directly.

@keyword width: Specify the figure width part of I{figSize}.

@keyword height: Specify the figure height part of I{figSize}.

@keyword h2: A single index, or a sequence or set containing

one or more indices, of any rows (starting with 0 for the

top row) that have twice the normal height. If an invalid

index is included, an exception will be raised.

@keyword w2: A single index, or a sequence or set containing

one or more indices, of any columns (starting with 0 for

the left column) that have twice the normal width. If an

invalid index is included, an exception will be raised.

"""

args, kw, N, self.Nc, self.Nr = self.parseArgs(*args, **kw)

self.V = args[0] if args else None

self.opts = Opts()

self.filePath = kw.pop('filePath', None)

if 'verbose' in kw: self.verbose = kw.pop('verbose')

useAgg = bool(self.filePath) or kw.pop('useAgg', False)

self.setupClass(useAgg=useAgg)

figSize = kw.pop('figSize', self.figSize)

if figSize is None:

if useAgg or screeninfo is None:

figSize = [10.0, 7.0]

else:

si = screeninfo.screeninfo.get_monitors()[0]

figSize = [

float(x)/self.DPI for x in (si.width-80, si.height-80)]

width = kw.pop('width', None)

if width: figSize[0] = width

height = kw.pop('height', None)

if height: figSize[1] = height

figSize = self._maybePixels(figSize)

self.fig = self.plt.figure(figsize=figSize)

self.figSize = figSize

self.sp = Subplotter(

self, N, self.Nc, self.Nr, kw.pop('h2', []), kw.pop('w2', []))

# The ID is an integer, not a reference to anything

self.ID = self.ph.add(self)

self.kw = kw

self.dims = Dims()

self.xlabels = {}

self.annotators = {}

self.adj = Adjuster(self)

self.reset()

@staticmethod

def parseArgs(*args, **kw):

"""

Parse the supplied I{args} and I{kw} for a constructor call.

Returns a 5-tuple with a revised args list and kw dict, the

number of subplots, the number of columns, and the number of

rows.

"""

N = args[0]

args = list(args[1:])

Nc = kw.pop('Nc', None)

if args and isinstance(args[0], int):

# Nc, Nr specified

if Nc:

raise ValueError(

"You can't specify Nc as both a second arg and keyword")

Nc = N

Nr = args.pop(0)

N = Nc*Nr

else:

# N specified

Nc = Nc if Nc else 3 if N > 6 else 2 if N > 3 else 1

Nr = int(np.ceil(float(N)/Nc))

return args, kw, N, Nc, Nr

def reset(self):

"""

Clears everything out to start fresh.

"""

self.dims.clear()

self.xlabels.clear()

self.annotators.clear()

self._figTitle = None

self.tbmTitle = None

self._isSubplot = False

self._universal_xlabel = False

self._plotter = None

self.Nsp = 0

def __del__(self):

"""

Safely ensures that I am removed from the class-wide I{ph}

instance of L{PlotterHolder}.

"""

# Only an integer is passed to the call

self.ph.remove(self.ID)

# No new references were created, nothing retained

def _maybePixels(self, figSize):

"""

Considers the supplied I{figSize} to be in pixels if both its

elements are integers and at least one of them exceeds 75. In

that case, scales it down by DPI.

Returns the figSize in inches.

"""

bigDim = False

newFigSize = []

for dim in figSize:

if not isinstance(dim, int):

# Not both integers, use original

return figSize

if dim > 75: bigDim = True

# Convert from (presumed) pixels to Matplotlib's stupid inches

newFigSize.append(float(dim)/self.DPI)

# Use the converted dims unless neither was > 75

return newFigSize if bigDim else figSize

@property

def width(self):

"""

Figure width (inches).

"""

return self.fig.get_figwidth()

@property

def height(self):

"""

Figure height (inches).

"""

return self.fig.get_figheight()

def __getattr__(self, name):

"""

You can access plotting methods and a given subplot's plotting

options as attributes.

If you request a plotting method, you'll get an instance of me

with my I{_plotter} method set to I{name} first.

"""

if name in PLOTTER_NAMES:

self._plotter = name

return self

if name in self.opts:

return self.opts[name]

raise AttributeError(sub(

"No plotting option or attribute '{}'", name))

def __enter__(self):

"""

Upon an outer context entry, sets up the first subplot with

cleared axes, preserves a copy of my global options, and

returns a reference to myself as a subplotting tool.

"""

# TODO: Allow my instance to be context-called again

#self.reset()

self.sp.setup()

self._isSubplot = True

self.opts.newLocal()

return self

def __exit__(self, *args):

"""

Upon completion of context, turns minor ticks and grid on if

enabled for this subplot's axis, restores global (all

subplots) options.

If the Agg rendererer is not being used (for generating PNG

files), also sets a hook to adjust the subplot spacings and

annotation positions upon window resizing.

The args are just placeholders for the three args that

C{contextmanager} supplies at the end of context: I{exc_type},

I{exc_val}, I{exc_tb}. (None are useful here.)

@see: L{_doPlots}.

"""

# Do the last (and perhaps only) call's plotting

self._doPlots()

self._isSubplot = False

self.opts.goGlobal()

if not self.usingAgg:

self.fig.canvas.mpl_connect('resize_event', self.subplots_adjust)

def start(self):

"""

An alternative to the context-manager way of using me. Just call

this method and a reference to myself as a subplotting tool

will be returned.

Call L{done} when finished, which is the same thing as exiting

my subplotting context.

"""

if self._isSubplot:

raise Exception("You are already in a subplotting context!")

return self.__enter__()

def done(self):

"""

Call this after a call to L{start} when done plotting. This is the

alternative to the context-manager way of using me.

B{Note}: If you don't call this to close out a plotting

session with the alternative method, the last subplot will not

get drawn!

@see: L{start}, which gets called to start the

alternative-method plotting session.

"""

if not self._isSubplot:

raise Exception("You are not in a subplotting context!")

self.__exit__()

def subplots_adjust(self, *args):

"""

Adjusts spacings.

"""

dimThing = args[0] if args else self.fig.get_window_extent()

fWidth, fHeight = [getattr(dimThing, x) for x in ('width', 'height')]

self.adj.updateFigSize(fWidth, fHeight)

if self._figTitle:

kw = {

'm': 10,

'fontsize': self.fontsize('title', 14),

'alpha': 1.0,

'fDims': (fWidth, fHeight),

}

ax = self.fig.get_axes()[0]

if self.tbmTitle: self.tbmTitle.remove()

self.tbmTitle = TextBoxMaker(self.fig, **kw)("N", self._figTitle)

titleObj = self.tbmTitle.tList[0]

else: self.tbmTitle = titleObj = None

kw = self.adj(self._universal_xlabel, titleObj)

try:

self.fig.subplots_adjust(**kw)

except ValueError as e:

if self.verbose:

print((sub(

"WARNING: ValueError '{}' doing subplots_adjust({})",

e.message, ", ".join(

[sub("{}={}", x, kw[x]) for x in kw]))))

self.updateAnnotations()

def updateAnnotations(self, annotator=None):

"""

Updates the positions of all annotations in an already-drawn plot.

When L{PlotHelper} calls this, it will supply the annotator

for its subplot.

"""

plt = self.plt

updated = False

if annotator is None:

for annotator in self.annotators.values():

if annotator.update():

updated = True

elif annotator.update(): updated = True

if updated:

# This raises a warning with newer matplotlib

#plt.pause(0.0001)

plt.draw()

def _doPlots(self):

"""

This gets called by L{__call__} at the beginning of each call to

my subplot-context instance, and by L{__exit__} when subplot

context ends, to do all the plotting for the previous subplot.

Adds minor ticks and a grid, depending on the subplot-specific

options. Then calls L{Opts.newLocal} on my I{opts} to create a

new set of local options.

"""

ax = self.sp.ax

if ax: ax.helper.doPlots()

# Setting calls now use new local options

self.opts.newLocal()

def show(self, windowTitle=None, fh=None, filePath=None, noShow=False):

"""

Call this to show the figure with suplots after the last call to

my instance.

If I have a non-C{None} I{fc} attribute (which must reference

an instance of Qt's C{FigureCanvas}, then the FigureCanvas is

drawn instead of PyPlot doing a window show.

You can supply an open file-like object for PNG data to be

written to (instead of a Matplotlib Figure being displayed)

with the I{fh} keyword. (It's up to you to close the file

object.)

Or, with the I{filePath} keyword, you can specify the file

path of a PNG file for me to create or overwrite. (That

overrides any I{filePath} you set in the constructor.)

"""

try:

self.fig.tight_layout()

except ValueError as e:

if self.verbose:

proto = "WARNING: ValueError '{}' doing tight_layout "+\

"on {:.5g} x {:.5g} figure"

print((sub(proto, e.message, self.width, self.height)))

self.subplots_adjust()

# Calling plt.draw massively slows things down when generating

# plot images on Rpi. And without it, the (un-annotated) plot

# still updates!

if False and self.annotators:

# This is not actually run, see above comment

self.plt.draw()

for annotator in list(self.annotators.values()):

if self.verbose: annotator.setVerbose()

annotator.update()

if fh is None:

if not filePath:

filePath = self.filePath

if filePath:

fh = open(filePath, 'wb+')

if fh is None:

self.plt.draw()

if windowTitle: self.fig.canvas.set_window_title(windowTitle)

if self.fc is not None: self.fc.draw()

elif not noShow: self.plt.show()

else:

self.fig.savefig(fh, format='png')

self.plt.close()

if filePath is not None:

# Only close a file handle I opened myself

fh.close()

if not noShow: self.clear()

def clear(self):

"""

Clears my figure with all annotators and artist

dimensions. Removes my ID from the class-wide

L{PlotterHolder}.

"""

try:

# This causes stupid errors with tkagg, so just wrap it in

# try-except for now

self.fig.clear()

except: pass

self.annotators.clear()

self.dims.clear()

self.ph.remove(self.ID)

def xBounds(self, *args, **kw):

"""

See L{Subplotter.xBounds}.

"""

self.sp.xBounds(*args, **kw)

def yBounds(self, *args, **kw):

"""

See L{Subplotter.yBounds}.

"""

self.sp.yBounds(*args, **kw)

def fontsize(self, name, default=None):

return self.opts['fontsizes'].get(name, default)

def doKeywords(self, kVector, kw):

"""

Applies line style/marker/color settings as keywords for this

vector, except for options already set with keywords.

Then applies plot keywords set via the set_plotKeyword call

and then, with higher priority, those set via the constructor,

if they don't conflict with explicitly set keywords to this

call which takes highest priority.

Returns the new kw dict.

"""

kw = self.opts.kwModified(kVector, kw)

for thisDict in (self.kw, self.plotKeywords):

for name in thisDict:

if name not in kw:

kw[name] = thisDict[name]

return kw

def doSettings(self, k):

"""

Does C{set_XXX} calls on the C{Axes} object for the subplot at

index I{k}.

"""

def bbAdd(textObj):

dims = self.adj.tsc.dims(textObj)

self.dims.setDims(k, name, dims)

for name in self._settings:

value = self.opts[name]

if not value: continue

fontsize = self.fontsize(name, None)

kw = {'size':fontsize} if fontsize else {}

bbAdd(self.sp.set_(name, value, **kw))

if name == 'xlabel':

self.xlabels[k] = value

continue

settings = self.opts['settings']

for name in settings:

bbAdd(self.sp.set_(name, settings[name]))

def __call__(self, *args, **kw):

"""

In the next (perhaps first) subplot, or one whose index is

specified with keyword I{k}, plots the second supplied vector

(and any further ones) versus the first.

If you supply a container object that houses vectors and

provides access to them as items as the first argument, you

can supply vector names instead of the vectors themselves. The

container object must evaluate C{b in a} as C{True} if it

contains a vector with I{b}, and must return the vector with

C{a[b]}.

Many options can be set via the methods in L{OptsBase},

including a title, a list of plot markers and linestyles, and

a list of legend entries for the plots with those keywords.

Set I{useLabels} to C{True} to have annotation labels pointing

to each plot line instead of a legend, with text taken from

the legend list.

You can override my default plotter by specifying the name of

another one with the I{plotter} keyword, e.g.,

C{plotter="step"}. But the usual way to do that is to call the

corresponding method of my instance, e.g., C{sp.step(X, Y)}.

Any other keywords you supply to this call are supplied to the

underlying Matplotlib plotting call. (B{NOTE:} This is a

change from previous versions of Yampex where keywords to this

method were used to C{set_X} the axes, e.g., C{ylabel="foo"}

results in a C{set_ylabel("foo")} command to the C{axes}

object, for this subplot only. Use the new L{OptsBase.set}

command instead.)

Returns a L{SpecialAx} wrapper object for the C{Axes} object

created for the plot.

If you want to do everything with the next subplot on your

own, bit by bit, and only want a reference to its C{Axes}

object (still with special treatment via L{SpecialAx}) just

call this with no args.

For low-level Matplotlib operations, you can access the

underlying C{Axes} object via the returned L{SpecialAx}

object's I{ax} attribute. But none of its special features

will apply to what you do that way.

@keyword k: Set this to the integer index of the subplot you

want the supplied vectors plotted in if not in sequence.

@see: L{_doPlots}.

"""

# Do plotting for the previous call (if any)

self._doPlots()

if 'plotter' not in kw:

plotter = self._plotter

self._plotter = None

if plotter: kw.setdefault('plotter', plotter)

k = kw.pop('k', None)

ax = self.sp[k]

ax.helper.addCall(args, kw)

self.Nsp += 1