CurveExpert Professional 2.6.5 documentation

Appendix E: Plugin API

Basic API

api.MainWin()

Returns a handle to the main window. Can be useful if using graphical widgets from the plugin.

Return type:wx.Window
api.calculate_function(abspath, relpath, data=None, add_to_ui=True)

Compute a function from the model given by the abspath/relpath pair, and with the given data. If data is not given, the data currently in the CurveExpert Pro spreadsheet will be used.

Parameters:
  • abspath (string) – can be the strings “$BUILTIN$”, “$USERDIR$”, or a fully qualified path the location of the function library.
  • relpath (string) – “libf/2D/Bessel/Bessel_j0.py”, for example, which is the rest of the path to the actual file that implements the function.
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • add_to_ui (boolean) – whether or not to add the result to the CurveExpert Pro result list.
Return type:

result object

api.calculate_linear_regression(degree, data=None, add_to_ui=True, weighting=0)

Compute a linear regression of the given degree, and with the given data. If data is not given, the data currently in the CurveExpert Pro spreadsheet will be used.

Parameters:
  • degree (integer) – Degree of the polynomial to compute a linear regression for.
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • add_to_ui (boolean) – whether or not to add the result to the CurveExpert Pro result list.
  • weighting (integer) – weighting parameter
Return type:

result object

The return value is a result object, which contains all of the relevant information about that result.

api.calculate_lowess_smoothing(data=None, add_to_ui=True)

Compute a Lowess smoothing with the given data. If data is not given, the data currently in the CurveExpert Pro spreadsheet will be used.

Parameters:
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • add_to_ui (boolean) – whether or not to add the result to the CurveExpert Pro result list.
Return type:

result object

The return value is a result object, which contains all of the relevant information about that result.

api.calculate_movingaverage(windowsize, windowtype='rect', windowpos='centered', windowqual=0, data=None, add_to_ui=True)

Compute a moving average with the given parameters and with the given data. If data is not given, the data currently in the CurveExpert Pro spreadsheet will be used.

Parameters:
  • windowsize (integer) – The total extent of the window, from left to right. The extent can be given as a number of points or a distance along the x axis. See windowqual below.
  • windowqual (integer) – If the windowsize is specified as a distance along the x axis, windowqual should be set to 0. If the windowsize is given as a number of points, windowqual should be set to 1.
  • windowtype (integer) – The function that is used as the weighting function. Should be one of the following: “rect”, “bartlett”, “blackman”, “hamming”, or “hanning”.
  • windowpos (integer) – The position of the window in relation to zero (the centerpoint of the averaging). Should be one of “centered”, “leading”, or “lagging”.
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • add_to_ui (boolean) – whether or not to add the result to the CurveExpert Pro result list.
Return type:

result object

The return value is a result object, which contains all of the relevant information about that result; returns None on error.

api.calculate_nonlinear_regression(abspath, relpath, data=None, add_to_ui=True, weighting=0)

Compute a nonlinear regression from the model given by the abspath/relpath pair, and with the given data. If data is not given, the data currently in the CurveExpert Pro spreadsheet will be used.

Parameters:
  • abspath (string) – can be the strings “$BUILTIN$”, “$USERDIR$”, or a fully qualified path the location of the model library.
  • relpath (string) – “lib/2D/Sigmoidal Models/Weibull.py”, for example, which is the rest of the path to the actual file that implements the model.
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • add_to_ui (boolean) – whether or not to add the result to the CurveExpert Pro result list.
  • weighting (integer) – weighting parameter
Return type:

result object

api.calculate_polynomial_spline(degree, data=None, add_to_ui=True)

Compute a polynomial spline of the given degree, and with the given data. If data is not given, the data currently in the CurveExpert Pro spreadsheet will be used.

Parameters:
  • degree (integer) – Degree of the polynomials used for the splining.
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • add_to_ui (boolean) – whether or not to add the result to the CurveExpert Pro result list.
Return type:

result object

The return value is a result object, which contains all of the relevant information about that result.

api.calculate_savitzky_golay_smoothing(data=None, window_size=15, degree=4, add_to_ui=True)

Compute a Savitzky-Golay smoothing with the given data. If data is not given, the data currently in the CurveExpert Pro spreadsheet will be used.

Parameters:
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • window_size (integer) – the number of points in the averaging window, in number of points; must be odd.
  • degree (integer) – the degree of the polynomial that will be used to fit the data within the window. Must be less than the number of points in the window.
  • add_to_ui (boolean) – whether or not to add the result to the CurveExpert Pro result list.
Return type:

result object

The return value is a result object, which contains all of the relevant information about that result.

api.calculate_tensionspline(tension, data=None, add_to_ui=True)

Compute a Tension smoothing with the given tension parameter and the given data. If data is not given, the data currently in the CurveExpert Pro spreadsheet will be used.

Parameters:
  • tension (float) – tension parameter for the spline.
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • add_to_ui (boolean) – whether or not to add the result to the CurveExpert Pro result list.
Return type:

result object

The return value is a result object, which contains all of the relevant information about that result.

api.clear()

Clears all results and the spreadsheet. Functionally the same as the user selecting File->New.

Return type:None
api.clear_message_window()

Clears all text from the message window

api.create_fontproperties(font='Arial', size=12, weight='normal', style='normal')

This API creates a FontProperties object for some particular use (for example, a font for the text in the graph’s add_annotation API).

To create a FontProperties object, simply do, for example:

fp = api.create_fontproperties(font=’TheFontName’,weight=’normal’,style=’normal’,size=12)

Parameters:
  • font (string) – The font given can be any font on your system that you desire to use. The default is “Arial”.
  • size (integer) – The size of the font, in points. The default is 12.
  • weight (string) – The weight of the font; can be one of “ultralight”, “light”, “normal”, “regular, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, or “black”. The default is “normal”.
  • style (string) – The style ofthe font; can be one of “normal”, “italic”, or “oblique”. The default is “normal”.
api.curvefinder(data=None, nonlinreg_builtin=True, nonlinreg_custom=True, linear=True, poly=(4, 8), lowess=False, savgol=False, parent_window=None, progress_caption='', silent=False, do_multicore=True, weighting=0)

Run a batch of regressions against a particular dataset.

Parameters:
  • data (2D numpy array) – numpy array, or None to use the data currently in the spreadsheet.
  • nonlinreg_builtin (boolean) – Search through all built-in nonlinear regressions.
  • nonlinreg_custom (boolean) – Search through all custom (user defined) nonlinear regressions.
  • linear (boolean) – Include a linear regression in the search (straight line, y=ax+b)
  • poly (boolean or 2-tuple, as appropriate) – Search a range of polynomial regressions. If polynomials are desired, this parameter should be set to a tuple indicating the min and max degree of the polynomials to calculate. Otherwise False.
  • lowess (boolean) – Include a Lowess smoothing in the search
  • savgol (boolean) – Include a Savitzky-Golay smoothing in the search; uses 5% of the available points as the averaging window, and a quartic polynomial for fitting within the windows.
  • parent_window (wxWindow object) – If a progress dialog is desired, the parent_window for the progress dialog is given here.
  • progress_caption (string) – Title of the progress dialog that is shown.
  • silent (boolean) – If set to True, will not print any intermediate information to the CurveExpert Pro messages window.
  • do_multicore (boolean) – If set to True, multicore capability will be used if available.
  • weighting (integer) – Choice of default weighting (api.WEIGHTING.DEFAULT), no weighting (api.WEIGHTING.NONE), by y (api.WEIGHTING.Y) by y^2 (api.WEIGHTING.Y2), by x (api.WEIGHTING.X), or by x^2 (api.WEIGHTING.X2). Default weighting means to use no weighting unless there is a standard deviation column, in which case the weighting is the square of the standard deviation.
Return type:

list of result objects, sorted in order of their score.

The return value is a list of result objects, which contains all of the relevant information about that result.

api.extract_from_excel(file_name, sheet_name, range_spec, stdcol=False)

Reads a data from an Excel file (xls or xlsx).

Parameters:
  • file_name (string) – file to read
  • sheet_name (string) – the name of the sheet where the data resides.
  • range_spec (string) – the range of cells in Excel where the data is located. For example, “A1:B10”, or “A1:B10,D1:D10”.
  • stdcol (boolean) – True if the last column of the data in the spreadsheet represents the standard deviation column.
Return type:

numpy array

On error, this routine will return None.

api.get_all_graphs()

Returns a list of all graphs available (a list of Graph objects).

api.get_all_results()

Returns a list of all of the currently computed results; these are the same results as shown in the Results Pane.

Return type:list of result objects
api.get_current_graph()

Returns a Graph object for the currently displayed graph. If there is no graph currently showing (e.g. the spreadsheet page or notes page is active), this call will return None.

api.get_data()

Returns a reference to the dataset shown in the spreadsheet. One can both read and write to this dataset, but its size should not be changed. If the dataset is changed (written to), the API refresh_spreadsheet() must be called once all desired data has been modified.

Return type:numpy array
api.get_main_window()

Returns a handle to the main window. Can be useful if using graphical widgets from the plugin.

Return type:wx.Window
api.get_spreadsheet_selection()

Gets the currently selected rectangle in the spreadsheet. If there is no selection, all four members of the tuple will be -1. Note that the numbers are all zero based, so a top left of 0,0 means row 1, column 1.

Return type:tuple (top,left,bottom,right)
api.import_from_clipboard()

Reads data from the clipboard, importing it with default settings.

Return type:None.
api.import_from_file(fname)

Identical to read_file().

api.message(msg, importance=0)

Print a message to the CurveExpert Pro message pane.

Parameters:
  • msg (string) – string that contains the text to send to the message pane
  • importance (integer) – the importance level of the string. Can be set to 0, 1, or 2. Currently, an importance of 0 prints in black, 1 in red, and 2 in blue.
Return type:

None

api.messages(msgs, importance=0)

Print a batch of messages to the CurveExpert Pro message pane.

Parameters:
  • msg (list of strings) – list of strings that contains the text to send to the message pane
  • importance (integer) – the importance level of the string. Can be set to 0, 1, or 2. Currently, an importance of 0 prints in black, 1 in red, and 2 in blue.
Return type:

None

api.new_graph(name=None, style=None)

Creates a new graph and makes it current. Returns a Graph object.

Parameters:
  • name (string) – name of the plot; used for the notebook tab that the graph appears in.
  • style (integer) – The style of the plot. XY, 3D, or polar. If not given, an XY plot is created.
api.quit()

Shut down CurveExpert Pro.

Return type:None
api.read_file(fname)

Reads a file from disk. The file can be either a cxp file or a text/data file. If a text/data file, it will be imported with default settings. The data read is placed in the CurveExpert Pro spreadsheet; if the data is needed for manipulation in the plugin, see get_data().

Parameters:fname (string) – file to read
Return type:None
api.refresh_spreadsheet()

If the data is changed (via calling get_data() and modifying the data), the plugin should call refresh_spreadsheet() in order to notify CurveExpert Pro about the change.

Return type:None
api.remove_graph(graph)

Removes a graph from the stack of graphs.

Parameters:graph – a Graph object that is the one to remove.
api.reset_with_data(data, stddev=False)

Reinitializes the CurveExpert application with a new dataset. Functionally the same as reading a data file, except that the dataset can be generated inside of a plugin by the user. As such, all current results will be lost.

Parameters:
  • data (numpy array) – array of data, which must have at least two columns.
  • stddev (bool) – flag to state whether or not the last columns is standard deviation data (False by default)
api.result_picker()

Shows a dialog box from which a result can be selected.

Return type:list of selected result objects.
api.set_current_graph(graph)

Causes a graph be made current; i.e.; made visible in the notebook.

Parameters:graph – a Graph object that is the one to make current (bring to the front).
api.set_data(data)

Sets a new dataset into the CurveExpert application with a new dataset. The new dataset must have the same number of columns as the current dataset for this call to succeed.

Returns zero on success, nonzero on error.

Parameters:data (numpy array) – array of data, which must have the same number of columns as the current dataset
Return type:integer
api.text_to_clipboard(txt)

Copy any text string that you have to the clipboard.

Parameters:txt (string) – string that contains the text to copy to the clipboard
Return type:None
api.update_ui()

Allows the user interface to update itself. Useful for flushing text out to the messages window after calls to api.message.

Return type:None

Result Object

class Result.Result(name='Unnamed', kind='Regression', family='NoFamily', id=0)

The Result object holds all information concerning any result calculated in CurveExpert/GraphExpert Professional. As such, there are some fields that are not applicable for all results. As a user of the API, you will not be creating result objects directly, but you will receive them as a return value of the result calculation API’s, such as calculate_nonlinear_regression.

name

The name of the result

kind

The kind of the result. Currently, can be Regression, Interpolation, or Smoothing

family

The family of the result. For example, “Sigmoidal Models”.

spec

The specification of the result, which is a dotted string used to uniquely identify the result. For example, regression.nonlinear.Exponential Models.Reciprocal Logarithm

nindvar

The number of independent variables that the result is applicable for.

nparam

The number of parameters. For example, for a regression model a*x^2 + b*x + c, nparam is 3.

param

The optimized values of the parameters.

param_names

A list of the parameter names, in the same order as the value listed in the param attribute.

valid

Flag to denote whether or not the result is clean; meaning that the data has not change since the result has been computed.

score

The score compute for this result, usually shown in the “Score” column in the Results pane.

corr_coeff

The coefficient of determination, if applicable.

real_corr_coeff

The correlation coefficient, if applicable.

covariance_matrix

The covariance matrix of the result as a 2D array, if applicable.

log

A list of informational strings generated during the calculation of the result that can be useful in some circumstances.

errlog

A list of strings generated during the calculation of the result that, if present, indicate that something has gone awry with the result’s calculation.

covariance_matrix

The covariance matrix of the result as a 2D array, if applicable.

status

Flag to denote the status of the result, as far as its success or failure during computation.

status = -1: uninitialized

status = 0: computed and valid

status = 1: unable to compute (i.e. not enough data points for the model)

status = 2: unable to get an initial guess

status = 3: diverged

status = 4: did not converge; use results with caution.

eval_function(x, *params)

evaluates the result using the independent variable(s) and the set of parameters given in the argument list. Note that functions have no parameters. x can be either a single floating point number, or a numpy array. It must have the appropriate number of columns that matches the number of independent variables appropriate for the result.

Parameters:
  • x (float or array) – independent variable with which to evaluate the result
  • params (float) – argument list for parameters
Return type:

the result evaluation. The type and dimension matches the type passed for x.

For example, to evaluate a model that has three parameters,

r.eval_function(x,a,b,c)

where a, b, and c are the values of the three parameters. To evaluate a result with its current set of parameters,

r.eval_function(x,*r.param)

arclength(a, b)

Find the arclength of a result from limits a to b. Supports only functions with one independent variable. If b < a, returns the negative of the arclength.

Parameters:
  • a (float) – starting point for the arclength calculation
  • b (float) – ending point for the arclength calculation
Return type:

the arclength from a to b (float)

differentiate(x)

Differentiate a result at x. Supports only functions with one independent variable.

Parameters:x (float or numpy array) – location at which to differentiate
Return type:the result of the differentiation, as the same type as x.
integrate(a, b)

Integrate a result from limits a to b. Supports only functions with one independent variable.

Parameters:
  • a (float) – lower limit of the integration
  • b (float) – upper limit of the integration
Return type:

the result of the integration (float)

inverse_eval(y, x0)

Find x at which a result is equal to y. Supports only functions with one independent variable.

Parameters:
  • y (float) – location at which to find the corresponding x.
  • x0 (float) – initial guess for the corresponding x.
Return type:

the result of the inverse evaluation (float)

Note that this function can raise a RuntimeError exception error if the algorithm does not converge.

parameters_to_csv(delimiter=', ')

Generates a CSV representation of the result’s parameters.

Parameters:delimiter (string) – Delimiter to place between parameter name and value.
Return type:string

Example usage (if r is a result object, with a space delimiter):

txt = r.parameters_to_csv(delimiter=’ ‘)

report(confidence=95, delimiter=' ')

Generates a text report for the result, returning that text report as a single string.

Parameters:confidence (integer) – In cases where the confidence level is required (for example, computing the uncertainty in a parameter of a nonlinear regression)
Return type:string

Example usage (if r is a result object):

txt = r.report()

Graph Object

class UGraph.Graph(g)

The Graph object holds information about a graph and has methods that can be used to manipulate that graph.

name

The name of the graph

style

The style of the graph

style = 1: XY plot

style = 3: 3D plot

style = 4: polar plot

add_annotation(s, pos=None, **kwargs)

Adds an annotation to the plot.

Parameters:
  • s (string) – the text for the annotation
  • pos (tuple of two floats) – the position of the annotation (a tuple). If not given, the annotation is positioned at graph coordinate location 0.5,0.5 (the center of the graph).

The add_annotation function can take keyword arguments to modify the properties of the annotation as follows. Any unknown keyword arguments are ignored.

Parameters:
  • coord_system (integer) – 0 = figure coordinates, 1 = data coordinates. Default is figure coordinates.
  • font (FontProperties object) – A font properties object. Default is Arial, normal weight, normal style, and 12 point.
  • font_color (string) – The color of the annotation text, which is a string in the following format: “#FFAABB”. The default color is black “#000000”.
  • multi_alignment – A string describing the horizontal alignment (justification) of the text within the box. Can be “center”, “left”, or “right”. Default is “center”.
  • rotation (integer) – An integer giving the amount of text rotation, in degrees. Can range from -360 to +360.
  • linespacing (float) – A floating point number describing the amount of space to take per line; must be greater then 0.0. Default is 1.2, which very closely resembles single-spaced lines.
  • alpha (float) – alpha transparency of the annotation text. This is a floating point number ranging from 0.0 (fully transparent) to 1.0 (full opaque). Default is 1.0.
  • box_show (bool) – whether or not to show the box around the text.
  • box_style (string) – the style of the box. Can be “square”, “real_square”, “ellipse”, “circle”, “diamond”, “round”, “round4”, “sawtooth”, “roundtooth”, “rarrow”, “larrow”, “triangle”, “parallelogram-right”, “parallelogram-left”, “trapezoid”, or “itrapezoid”. The default is “square”.
  • box_fit_to_text (bool) – whether or not to fit the box to the size of the text. If False, the parameter box_size is used as the size of the box.
  • box_size (tuple of two floats) – the size of the box, given in the same coordinate system as the annotation’s coord_system. Ignored if box_fit_to_text is True.
  • box_fillcolor (string) – the color of the fill inside the box, which is a string in the following format: “#FFAABB”. The default color is black “#000000”.
  • box_edgecolor (string) – the color of the edge of the box, which is a string in the following format: “#FFAABB”. The default color is black “#000000”.
  • box_alpha (float) – the transparency setting of the box (which includes its edge). This is a floating point number ranging from 0.0 (fully transparent) to 1.0 (full opaque). Default is 1.0.
  • boxframe_width (integer) – an integer describing the width of the box edge. The default is 1.
  • box_shadow (bool) – whether or not to draw a shadow behind the box.
  • arrow_show (bool) – whether or not to show an arrow in conjunction with the annotation. The arrow always points from the center of the annotation to the point given by (arrow_x, arrow_y). Default: False
  • arrow_coord_system – 0 = figure coordinates, 1 = data coordinates. Default is data coordinates.
  • arrow_x (float) – The x location of where the arrow should point to, in the coordinate system given by arrow_coord_system.
  • arrow_y (float) – The y location of where the arrow should point to, in the coordinate system given by arrow_coord_system.
  • arrow_alpha (float) – the transparency setting of the arrow . This is a floating point number ranging from 0.0 (fully transparent) to 1.0 (full opaque). Default is 1.0.
  • arrow_color (string) – the color of the arrow, which is a string in the following format: “#FFAABB”. The default color is black “#000000”.
  • arrow_width – an integer describing the width of the arrow edge. The default is 1.
  • arrow_style (string) – a string indicating the style of the arrow. Can be “line”, “thick”, “wedge”, or “fancy”. The default is “line”.
  • arrow_head (string) – a string indicating the style of the arrow’s head. Can be -”, “->”, “<-”, “<->”, “-|>”, “<|-”, “<|-|>”, “-[”, “]-”, “]-[”, or “|-|”. Note that not every arrow head style is compatible with the arrow style. See the CurveExpert Pro GUI for valid combinations. The default is “-|>”.
  • arrow_connection_style (string) – a string indicating the style of the connection line between the annotation and the pointed-to-point. Can be one of “straight”, “xy”, or “arc”. The default is “straight”. Note that not every arrow connection style is compatible with the arrow style. See the CurveExpert Pro GUI for valid combinations.
add_arrow(startpos, endpos, **kwargs)

Adds an arrow to the plot.

Parameters:
  • startpos (tuple of two floats) – start position of the arrow, in graph coordinates.
  • endpos (tuple of two floats) – end position of the arrow, in graph coordinates Should be a tuple.
  • coord_system (integer) – 0 = figure coordinates, 1 = data coordinates. Default is figure coordinates.
  • alpha (float) – alpha transparency of the arrow. This is a floating point number ranging from 0.0 (fully transparent) to 1.0 (full opaque). Default is 1.0.
  • color (string) – The color of the arrow’s edge, which is a string in the following format: “#FFAABB”. The default color is black “#000000”.
  • fillcolor (string) – The color of the arrow’s fill, which is a string in the following format: “#FFAABB”. The default color is black “#000000”.
  • width (integer) – an integer describing the width of the arrow’s line. The default is 1.
  • style (string) – a string indicating the style of the arrow. Can be “line”, “thick”, “wedge”, or “fancy”. The default is “line”.
  • head (string) – a string indicating the style of the arrow’s head. Can be -”, “->”, “<-”, “<->”, “-|>”, “<|-”, “<|-|>”, “-[”, “]-”, “]-[”, or “|-|”. Note that not every arrow head style is compatible with the arrow style. See the CurveExpert Pro GUI for valid combinations. The default is “-|>”.
  • connection_style (string) – a string indicating the style of the connection line between start and end point of the arrow. Can be one of “straight”, “xy”, or “arc”. The default is “straight”. Note that not every arrow connection style is compatible with the arrow style. See the CurveExpert Pro GUI for valid combinations.
  • shape_scaling (float) – A floating point number that determines the “fatness” of the arrow shape. Lower scalings lead to thinner arrow bodies (in cases where the arrow body is a shape, and not just a line), and smaller arrow heads. Higher scalings conversely lead to thicker arrow bodies and correspondingly larger arrow heads.
add_result(r)

Adds a computed result to the graph.

Parameters:r – the result object to add.

Note that adding a result to a graph means that the result must be managed by the application. If it is not, it automatically becomes managed.

apply_theme(theme_name)

applies a particular theme to the graph. The theme must be present on the system.

Parameters:theme_name (string) – A string that gives the name of the theme to apply. Example: “Blackness”
autoscale()

autoscales the graph

clear()

clears all series off of the graph and resets the scaling to its default state.

Return type:True if successful, False if not.
draw_circle(xy, radius, coord_system=0, redraw=True, **kwargs)

Draws a circle on the plot, with center xy and the given radius.

At this time, the circle is not persistent, which means that it is not saved along with the graph to file. If a document is read from disk, the circle will not be present; the plugin must be rerun in order to redraw the circle.

Parameters:
  • xy (a tuple containing two floats) – location of the centerpoint.
  • radius (float) – the radius of the circle

The draw_circle function can take keyword arguments to modify the properties of the circle as follows. Any unknown keyword arguments are ignored.

Parameters:
  • coord_system (integer) – 0 = figure coordinates, 1 = data coordinates. Default is figure coordinates.
  • redraw (boolean) – whether or not to redraw the figure after adding the artist to it. Useful when adding many artists at a time, to reduce screen flicker.
  • edgecolor – color of the edge, given as a hex code, as in “#00FF00”. Common color names may also be given; for example, “red”.
  • fillcolor (string) – color of the fill inside the circle, given as a hex code, as in “#00FF00”. Common color names may also be given; for example, “red”. Can be ‘None’ for no fill.
  • linewidth (integer) – width of the line in points (1/72 of an inch)
  • linestyle (string) – style of the line. Can be one of ‘solid’,’dashed’,’dash_dot’,’dotted’, or ‘None’, which means not to draw the line.
  • alpha (float) – transparency of the circle. Can be 0.0 to 1.0, with zero being transparent, and 1 being opaque.
Return type:

an artist that represents the circle.

An artist can always be removed from the graph by calling its remove() method.

draw_line(xarray, yarray, redraw=True, coord_system=0, **kwargs)

Draws a (potentially) multisegmented line on the plot.

At this time, the line is not persistent, which means that it is not saved along with the graph to file. If a document is read from disk, the line will not be present; the plugin must be rerun in order to redraw the line.

Parameters:
  • xarray (any iterable object returning floats) – sequence of points for the x coordinates
  • yarray (any iterable object returning floats) – sequence of points for the y coordinates

The draw_line function can take keyword arguments to modify the properties of the line as follows. Any unknown keyword arguments are ignored.

Parameters:
  • coord_system (integer) – 0 = figure coordinates, 1 = data coordinates. Default is figure coordinates.
  • redraw (boolean) – whether or not to redraw the figure after adding the artist to it. Useful when adding many artists at a time, to reduce screen flicker.
  • color (string) – color of the line, given as a hex code, as in “#00FF00”. Common color names may also be given; for example, “red”.
  • linewidth (integer) – width of the line in points (1/72 of an inch)
  • linestyle (string) – style of the line. Can be one of ‘solid’,’dashed’,’dash_dot’,’dotted’, or ‘None’, which means not to draw the line.
  • alpha (float) – transparency of the line. Can be 0.0 to 1.0, with zero being transparent, and 1 being opaque.
  • marker (string) – marker for each node of the line. Can be any one of [‘o’ | ‘D’ | ‘h’ | ‘H’ | ‘_’ | ‘’ | ‘None’ | ‘ ‘ | None | ‘8’ | ‘p’ | ‘,’ | ‘+’ | ‘.’ | ‘s’ | ‘*’ | ‘d’ | ‘1’ | ‘3’ | ‘4’ | ‘2’ | ‘v’ | ‘<’ | ‘>’ | ‘^’ | ‘|’ | ‘x’ |
  • markeredgecolor (string) – color of the marker edge, given as a hex code, as in “#00FF00”. Common color names may also be given; for example, “red”. Can be ‘None’ for no marker edge.
  • markerfillcolor (string) – color of the marker fill, given as a hex code, as in “#00FF00”. Common color names may also be given; for example, “red”. Can be ‘None’ for no fill.
  • markeredgewidth (integer) – width of the marker edge, given in points.
Return type:

an artist that represents the line.

An artist can always be removed from the graph by calling its remove() method.

draw_polygon(xarray, yarray, closed=True, coord_system=0, redraw=True, **kwargs)

Draws a polygon on the plot, with the points xy

At this time, the polygon is not persistent, which means that it is not saved along with the graph to file. If a document is read from disk, the polygon will not be present; the plugin must be rerun in order to redraw the polygon.

Parameters:
  • xarray (any iterable object returning floats) – sequence of points for the x coordinates
  • yarray (any iterable object returning floats) – sequence of points for the y coordinates
  • closed (boolean) – if True, the polygon will be closed so that the starting and ending points are the same.

The draw_polygon function can take keyword arguments to modify the properties of the polygon as follows. Any unknown keyword arguments are ignored.

Parameters:
  • coord_system (integer) – 0 = figure coordinates, 1 = data coordinates. Default is figure coordinates.
  • redraw (boolean) – whether or not to redraw the figure after adding the artist to it. Useful when adding many artists at a time, to reduce screen flicker.
  • edgecolor (string) – color of the edge, given as a hex code, as in “#00FF00”. Common color names may also be given; for example, “red”.
  • fillcolor (string) – color of the fill inside the polygon, given as a hex code, as in “#00FF00”. Common color names may also be given; for example, “red”. Can be ‘None’ for no fill.
  • linewidth (integer) – width of the line in points (1/72 of an inch)
  • linestyle (string) – style of the line. Can be one of ‘solid’,’dashed’,’dash_dot’,’dotted’, or ‘None’, which means not to draw the line.
  • alpha (float) – transparency of the polygon. Can be 0.0 to 1.0, with zero being transparent, and 1 being opaque.
Return type:

an artist that represents the polygon.

An artist can always be removed from the graph by calling its remove() method.

get_all_results()

Gets a list of all results plotted on a graph.

Return type:a list of Result objects.
get_properties()

gets the full property object for the graph. All properties are here, but are not documented, unfortunately. If there is some property of the graph that you would like to change that is not accessible through the regular API’s, contact the author. Alternatively, use Python’s introspection capability to look into the properties object.

get_title()

gets the title of the graph

Return type:the title of the graph (string)
hardcopy(interactive=False)

prints the graph to the printer.

Parameters:interactive (bool) – If set to True, the user will be presented with a dialog to select the printer. Otherwise, the printout goes directly to the default printer.
redraw()

Redraws the graph.

remove_result(r)

Removes a computed result from a graph.

Parameters:r – the result object to remove.
save_as(filename)

saves the graph as an external image or vector format file (PNG, JPG, TIFF, BMP, SVG, etc.). The format is deduced from the name of the file.

Parameters:filename (string) – The name of the file to save.
set_axis_extents(axis, extents)

sets the extent of a particular axis.

Parameters:
  • axis (string) – which axis to set. Can be ‘x1’, ‘x2’, or ‘y’. For convenience, ‘x’ can be used in place of ‘x1’, and ‘z’ may be used in the place of ‘y’.
  • extents (tuple of two floats) – the min and max of the axis extent. Should be a tuple of two floating point numbers.
Return type:

True if successful, False if not.

set_axis_label(axis, label)

sets the axis label

Parameters:
  • axis (string) – which axis to label. Can be ‘x1’, ‘x2’, or ‘y’. For convenience, ‘x’ can be used in place of ‘x1’, and ‘z’ may be used in the place of ‘y’.
  • label (string) – a text string to change the label to; mathtext in the string is also valid.
Return type:

True if successful, False if not.

set_properties(p)

sets the full property object for the graph. This sets all properties.

Parameters:p – a full graph property object
set_title(title)

changes the title of the graph

Parameters:title (string) – text string to change the title to; mathtext in the string is also valid.
Return type:True if successful, False if not.
title

gets the title of the graph

Return type:the title of the graph (string)