API reference

autogpy.AutogpyFigure

alias of autogpy.autognuplot.AutoGnuplotFigure

class autogpy.AutoGnuplotFigure(folder_name, file_identifier='fig', verbose=False, autoescape=True, latex_enabled=True, tikz_enabled=False, allow_strings=False, hostname=None, jpg_convert_density=100, jpg_convert_quality=100, anonymous=False)

Creates an AutoGnuplotFigure object which wraps one gnuplot figure.

Parameters

• folder_name (str) – target location for the figure scripts and data

• file_identifier (str) – common identifier present in the file names of this figure object

• verbose (bool, optional) – (False) Verbose operating mode.

• autoescape (bool, optional) – (True) Autoescapes latex strings. It enables to use latex directly in raw strings without further escaping.

• latex_enabled (bool, optional) – (True) The Makefile of the generated figure will build a latex figure by default (in the first make statement)

• tikz_enabled (bool, optional) – (False) The Makefile of the generated figure will build a latex/tikz figure by default (in the first make statement). Disabled as the default tikz configuration has some issue. See method: display_fixes.

• hostname (str, optional) – (None) Allows to set an hostname different for the system one. This hostname is used for scp calls, so it should be changed to a reacheable hostname, if needed.

• jpg_convert_density (int, optional) –

  100. dpi of the jpg image showed in a jupyter notebook. It is used for the conversion of the pdf image produced by gnuplot.

• jpg_convert_quality (int, optional) –

  100. conversion quality of the jpg image showed in a jupyter notebook. It is used for the conversion of the pdf image produced by gnuplot.

• anonymous (bool, optional) – (False) Specifies if a figure is generated in an anonymous folder. (Options as ssh sync and latex inclusion are turned off).

Returns

fig

Return type

AutoGnuplotFigure

Examples

>>> # Usage case: no context manager, gnuplot syntax.
>>> fig = AutoGnuplotFigure('folder','id')
>>> # for some existing arrays x,y
>>> fig.plot('u 1 : 2 t "my title" ', x ,y)
>>> fig.generate_gnuplot_file()
>>> # only jupyter
>>> fig.jupyter_show_pdflatex(show_stdout=False)

Notes

Setting latex terminal sizes. Change parameters in the member dictionary pdflatex_terminal_parameters

>>> fig.pdflatex_terminal_parameters =
>>> {
>>>     "x_size" : "9.9cm"
>>>     , "y_size" : "8.cm"
>>>     , "font" : "phv,12 "
>>>     , "linewidth" : "2"
>>>     , "other" : "" # use e.g. for header package import
>>> }

add_variable_declaration(name, value, is_string=False)

Add functions and variables declaration in the script preamble.

Parameters

• name (string) – Variable or function name. In case of a function needs to read like “f(x)”

• value (value or string) –

• is_string (bool, optional) – (False) If True wraps value in double-quote signs.

add_xy_dataset(x, y, gnuplot_opt='', fname_specs='')

Deprecated: Makes a x-y plot. Use plot instead.

alter_current_multiplot_parameters(*args, **kw)

Allows to change state variables of current subplot.

Works similarly to extend_global_plotting_parameters, but allows selective changes between one subplot and the next

Parameters

• *args (strings) – Set the global gnuplot state for properties such as axis style, legend position and so on. Use gnuplot syntax. Raw strings are advised.

• autoescape (bool, optional) – Avoids escaping latex strings. Latex source can be written as is.

Returns

fig

Return type

AutoGnuplotFigure

See also

extend_global_plotting_parameters(), set_multiplot(), next_multiplot_group()

Examples

>>> # establishes multiplot mode with 2 rows and one column
>>> fig.set_multiplot("layout 2,1")
>>> #sets logscale in y, globally
>>> fig.extend_global_plotting_parameters(r"set logscale y")
>>> #sets xrange, globally
>>> fig.extend_global_plotting_parameters(r"set xrange [1e-5:1.05e-3]")
>>> #plot in position 1,1
>>> fig.p_generic('u 1 : 2 t "my title" ', x ,y)
>>> #next item in multiplot
>>> fig.next_multiplot_group()
>>> ### to change xrange from second subplot onwards
>>> fig.alter_current_multiplot_parameters(r"set xrange [1e-7:1.05e-2]")
>>> #plot in position 2,1
>>> fig.p_generic('u 1 : 2 t "my title" ', x ,z)

For inset plots

>>> fig.set_multiplot()
>>> #sets logscale in y, globally
>>> fig.extend_global_plotting_parameters(r"set logscale y")
>>> #sets xrange, globally
>>> fig.extend_global_plotting_parameters(r"set xrange [1e-5:1.05e-3]")
>>> #plot in position 1,1
>>> fig.p_generic('u 1 : 2 t "my title" ', x ,y)
>>> #next item in multiplot
>>> fig.next_multiplot_group()
>>> fig.alter_current_multiplot_parameters(
>>> r"""set size 0.6, 0.5
>>> # set size of inset
>>> set origin 0.4, 0.5
>>> # move bottom left corner of inset
>>> """)
>>> #inset plot
>>> fig.p_generic('u 1 : 2 t "my title" ', x ,z)

display_fixes()

displays relevant fixes in case the convert call does not work or to solve a known gnuplot/luatex bug.

extend_global_plotting_parameters(*args, **kw)

Extends the preamble of the gnuplot script to modify the plotting settings.

Expects one or more strings with gnuplot syntax.

Parameters

• *args (strings) – Set the global gnuplot state for properties such as axis style, legend position and so on. Use gnuplot syntax. Raw strings are advised.

• autoescape (bool, optional) – Avoids escaping latex strings. Latex source can be written as is.

Returns

fig

Return type

AutoGnuplotFigure

Examples

>>> figure.extend_global_plotting_parameters(
>>> r'''
>>> set mxtics 2
>>> set mytics 1
>>> #
>>> # color definitions
>>> set border linewidth 1.5
>>> set style line 1 lc rgb '#ff0000'  lt 1 lw 2
>>> set style line 2 lc rgb '#0000ff' lt 3 lw 4
>>> #
>>> # Axes
>>> set style line 11  lc rgb '#100100100' lt 1
>>> set border 3 back ls 11
>>> set tics nomirror out scale 0.75
>>> #
>>> # Grid
>>> set style line 12 lc rgb'#808080' lt 0 lw 1
>>> set grid back ls 12
>>> #
>>> set format y '$%.4f$'
>>> set format x '$%.4f$'
>>> #
>>> set key top left
>>> #
>>> set key samplen 2 inside spacing 1 width 0.3 height 1.5  at graph 0.99, 1.05
>>> #
>>> unset grid
>>> #set logscale y
>>> set xlabel "$\nu$"
>>> set xrange [1e-5:1.05e-3]
>>> set yrange [1e-5:1e-3]
>>> set xtics 0,2e-4,1.01e-3
>>> #set ytics 2e-4,2e-4,1.01e-3
>>> ''')

fit(foo, *args, **kw)

Fitting method from gnuplot.

Parameters

• foo (str) – name of the function to fit (must be defined in set parameters) if foo contains an = (as e.g. in foo = “f(x)=a*x+b”), the function definition is automatically included in the preamble. Note everthing after `= is ported. so far parses only scalar functions, like “f(yy)=tt*yy”

• modfiers (str) – (‘auto_via’) modifiers to the call, suited to include, e.g. the via specifier. if ‘auto_via’ the via parameter is inferred. [experimental]

• *args (list or np.array) – data to fit

• do_not_fit (str or list(str)) – when inferring which parameters to fit, those in do_not_fit are excluded

• unicize_parameter_names (bool) – (False) if True, the inferred parameter names are renamed to be unique. Experimental and buggy!

Examples

>>> figure.fit("g(x)=ax+b",xx,yy)

fplot(foo, xsampling=None, xsampling_N=100, **kw)

Mimicks matlab fplot function.

Matlab ref: https://www.mathworks.com/help/matlab/ref/fplot.html

Parameters

• foo (scalar function) – foo(n) must be evaluable.

• xsampling (iterable, optional) – (np.linspace(-5,5)) contains the x samples on which foo is evaluated.

• **kw (same as in plot) –

generate_gnuplot_file()

Generates the final gnuplot scripts without creating any figure. Includes: Makefile, .gitignore and synchronization scripts.

get_gnuplot_file_content()

returns the gnuplot core file content as a string

get_txt_dataset(ds_path)

loads a txt dataset (proxies np.loadtxt)

hist_generic(x, gnuplot_command_no_u, hist_kw={}, gnuplot_command_using='u 1:2', normalization=None, kde=False, kde_kw={}, reweight=<function AutoGnuplotFigure.<lambda>>, dump_data=False, compress_dumped_data=True, **kw)

Proxy function to generate histograms

Parameters

• x (list, np.array, or other format compatible with np.histogram) – 1D dataset to histogram

• gnuplot_command_no_u (str) – gnuplot plot call arguments, skipping the filename and the usigng part. Should be used for title, plotstyle, etc.

• hist_kw (dict, optional) – ({}) arguments to pass to the inner np.histogram call

• gnuplot_command_using (str, optional) – (“u 1:2”) overrides the default using part. (default: “using 1:2”)

• normalization (float, str, optional) – (None) allows to provide a further normalization coefficient (pass float) or to normalize such that the max is one (pass ‘max’)

• kde (bool, optional) – (False) a gaussian kernel will be used to histogram the data, edges used are from the np.histogram call. Note the number of bins is specified in the hist_kw dict.

• kde_kw (dict, optional) – ({}) parameters to pass to the scipy.stats.gaussian_kde call

• reweight (function, optional) – (lambda: edges_mid : 1) function to reweight the histogram or kde values. Receives the bin center as parameter.

• dump_data (bool, optional) – (False) dumps the input data as csv

• compress_dumped_data (bool, optional) – (True) the data dumped (by dump_data = True) are gz-compressed.

• **kw (optional) – passes through to the inner p_generic call.

Returns

Return type

p_generic output

See also

hist_plthist()

hist_plthist(x, normalization=None, gnuplot_command_no_u_no_title='', title='', suppress_plt_figure=True, **kw)

Histogram function. Proxies the interface of plt.hist for a rapid call swap.

Parameters

• x (list, array) – 1D array to histogram

• normalization (float, str, optional) – (None) renormalizes the data after the historgram (see hist_generic)

• gnuplot_command_no_u_no_title (str, optional) – (‘’) additional gnuplot commands, excluding title

• title (str, optional) – (‘’) gnuplot title

• suppress_plt_figure (bool, optional) – (True) prevents the inner plt.hist call to spawn an histogram figure

• **kw – plt.hist parameters

See also

hist_generic()

jupyter_show(show_stdout=False)

Generates a figure via the jpg terminal and opens it in jupyter. The more advanced jupyter_show_pdflatex and jupyter_show_tikz are advised. This call is left for debug.

Parameters

show_stdout (bool, optional) – (False) outputs stdout and stderr to screen.

jupyter_show_pdflatex(show_stdout=False, show_stderr=False, width=None, height=None)

Shows a pdflatex rendering within the current jupyter notebook.

To work it requires ImageMagick and authorization to render pdf to jpg. Should it fail: https://stackoverflow.com/a/52661288

jupyter_show_tikz(show_stderr=False, show_stdout=False, height=None, width=None)

Shows a pdflatex rendering within the current jupyter notebook.

To work it requires ImageMagick and authorization to render pdf to jpg. Should it fail: https://stackoverflow.com/a/52661288

LUA compilation issue: https://tex.stackexchange.com/a/368194 solution: in /usr/share/gnuplot5/gnuplot/5.0/lua/gnuplot-tikz.lua, replace:

pgf.set_dashtype = function(dashtype) gp.write(“\gpsetdashtype{“..dashtype..”}n”) end

with

pgf.set_dashtype = function(dashtype) gp.write(“%\gpsetdashtype{“..dashtype..”}n”) end

load_gnuplotting_palette(palette_name)

Downloads a color palette https://github.com/Gnuplotting/gnuplot-palettes and return the loading string to be added in the preamble of the plot (see example).

Parameters

palette_name (string) – name of the palette, e.g. ‘moreland’

Returns

Return type

string

Example

>>> # Loads moreland palette in the current figure
>>> fig.extend_global_plotting_parameters ( fig.load_gnuplotting_palette('moreland') )
>>> # colors need to be selected manually

next_multiplot_group()

Shifts the state to the next plot in the multiplot sequence.

Returns

fig

Return type

AutoGnuplotFigure

See also

set_multiplot(), alter_current_multiplot_parameters()

p_generic(command_line, *args, **kw)

Proxies plot for backwards compatibility.

plot(command_line_or_data, *args, **kw)

Central plotting primitive.

Parameters

• command_line_or_data (string, list, np.array or pd.Series) – gnuplot command, without the explicit call to plot and the filename of the content. Alternatively, can be a list or np.array containing data (see *args)

• *args (lists or np.array, optional) – columns with the data, one or more columns can contain strings (e.g. for labels). In this case ‘allow_strings’ must be True.

• fname_specs (string, optional) – (“”) allows to specify a filename for the data different for the default one.

• autoescape (bool, optional) – (as set in by the constructor) allows to selectively modify the class setting for autoescaping.

• allow_strings (bool, optional) – (False) set to True to allows columns with strings. This requires pandas. Might become True by default in the future.

• column_names (list of strings, optional) – (None) set the names of the columns. Considered only if allow_strings=True.

• for_ (string, optional) – (None) allows to use the for gnuplot keyword.

• label (string, optional) – (None) proxies the gnuplot title keyword.

• **generic_gnuplot_command (kw and value, optional) – ({}) allows to pass any gnuplot argument ex ls, linewidth, etc.

print_folder_info()

Proxy for get_folder_info

print_gnuplot_file_content(highlight=True, linenos='inline')

Displays the content of the gnuplot file generated. Intended for debug.

Parameters

• highlight (bool, optional) – (True) Uses pygments to color the gnuplot script.

• linenos (string, optional) – (“inline”) Parameter linenos forwarded to the pygments HtmlFormatter object.

print_latex_snippet()

Propts latex code that can be used to include the figure.

For the moment requires a call to self.generate_gnuplot_file()

set(*args, **kw)

expands to preamble param in each subplot, prepends the set command.

Appending a kw name with __s or __e yields, respectively, string (“… “) or an equation (“$…$ “) value.

Parameters

• *args (castable to str) – each args element is placed in a different line and prepended with set

• **kw (castable to str) – each kw is placed in a different line, its argument follows if the k ends with __s or __e the argument is treated as string or equation.

Examples

>>> figure.set('autoscale',xrange="[0:10]",xlabel__s='t',ylabel__e='f(t)')

yields a gnuplot preamble

>>> set autoscale
>>> set xrange [0:10]
>>> set xlabel 't'
>>> set ylabel '$f(t)$'

See also

unset(), set_multiplot(), set_parameter()

set_figure_linewidth(lw)

Sets the global linewidth parameter for latex/tikz figures.

set_figure_size(x_size=None, y_size=None, **kw)

Sets the terminal figure size and possibly more terminal parameters (string expected).

set_multiplot(specifiers='')

Enables multiplot mode (use in combination with next_multiplot_group).

Parameters

specifiers (str) – multiplot parameters. E.g. argument “layout 2,2” yields a 2x2 matrix

Returns

fig

Return type

AutoGnuplotFigure

See also

next_multiplot_group(), alter_current_multiplot_parameters()

Example

>>> # establishes multiplot mode with 2 rows and one column
>>> fig.set_multiplot("layout 2,1")
>>> #plot in position 1,1
>>> fig.p_generic('u 1 : 2 t "my title" ', x ,y)
>>> #next item in multiplot
>>> fig.next_multiplot_group()
>>> #plot in position 2,1
>>> fig.p_generic('u 1 : 2 t "my title" ', x ,z)

set_multiplot_parameters(*args, **kw)

Proxies alter_current_multiplot_parameters

set_parameters(*args, **kw)

Proxies extend_global_plotting_parameters

unset(*args, **kw)

expands to preamble param in each subplot, prepends the unset command. For the kws the argument is ignored.