autoarray.plot.Output#

Bases: object

Sets how the figure or subplot is output, either by displaying it on the screen or writing it to hard-disk.

This object wraps the following Matplotlib methods:

plt.show: https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.show.html
plt.savefig: https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html

The default behaviour is the display the figure on the computer screen, as opposed to outputting to hard-disk as a file.

Parameters:

path (Optional[str]) – If the figure is output to hard-disk the path of the folder it is saved to.
filename (Optional[str]) – If the figure is output to hard-disk the filename used to save it.
prefix (Optional[str]) – A prefix appended before the file name, e.g. (“prefix_filename”).
prefix – A prefix appended after the file name, e.g. (“filenam_suffix”).
format (Union[str, List[str]]) – The format of the output, ‘show’ displays on the computer screen, ‘png’ outputs to .png, ‘fits’ outputs to .fits format.
format_folder (bool) – If True, all images are output in a folder giving the format name, for example path/to/output/png/filename.png. This can make managing large image catalogues easier.
bypass (bool) – Whether to bypass the plt.show or plt.savefig methods, used when plotting a subplot.

__init__(path=None, filename=None, prefix=None, suffix=None, format=None, format_folder=False, bypass=False, bbox_inches='tight', **kwargs)[source]#

Sets how the figure or subplot is output, either by displaying it on the screen or writing it to hard-disk.

This object wraps the following Matplotlib methods:

plt.show: https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.show.html
plt.savefig: https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html

The default behaviour is the display the figure on the computer screen, as opposed to outputting to hard-disk as a file.

Parameters:

path (Optional[str]) – If the figure is output to hard-disk the path of the folder it is saved to.
filename (Optional[str]) – If the figure is output to hard-disk the filename used to save it.
prefix (Optional[str]) – A prefix appended before the file name, e.g. (“prefix_filename”).
prefix – A prefix appended after the file name, e.g. (“filenam_suffix”).
format (Union[str, List[str]]) – The format of the output, ‘show’ displays on the computer screen, ‘png’ outputs to .png, ‘fits’ outputs to .fits format.
format_folder (bool) – If True, all images are output in a folder giving the format name, for example path/to/output/png/filename.png. This can make managing large image catalogues easier.
bypass (bool) – Whether to bypass the plt.show or plt.savefig methods, used when plotting a subplot.

Methods

`__init__`([path, filename, prefix, suffix, ...])	Sets how the figure or subplot is output, either by displaying it on the screen or writing it to hard-disk.
`filename_from`(auto_filename)	Build the final filename string by applying prefix / suffix.
`output_path_from`(format)	Return the directory path for format, creating it if necessary.
`savefig`(filename, output_path, format)	Call `plt.savefig` with the configured `bbox_inches` setting.
`subplot_to_figure`([auto_filename, also_show])	Output a subplot figure, either as an image on the screen or to the hard-disk as a png or fits file.
`to_figure`(structure[, auto_filename])	Output the figure, by either displaying it on the user's screen or to the hard-disk as a .png or .fits file.
`to_figure_output_mode`(filename)	Save the current figure as a numbered PNG snapshot in output mode.

Attributes

`format`	The output format string; defaults to `"show"` when none was given.
`format_list`	The output format(s) as a list, so iteration always works.

__init__(path=None, filename=None, prefix=None, suffix=None, format=None, format_folder=False, bypass=False, bbox_inches='tight', **kwargs)[source]#

Sets how the figure or subplot is output, either by displaying it on the screen or writing it to hard-disk.

This object wraps the following Matplotlib methods:

plt.show: https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.show.html
plt.savefig: https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html

The default behaviour is the display the figure on the computer screen, as opposed to outputting to hard-disk as a file.

Parameters:

path (Optional[str]) – If the figure is output to hard-disk the path of the folder it is saved to.
filename (Optional[str]) – If the figure is output to hard-disk the filename used to save it.
prefix (Optional[str]) – A prefix appended before the file name, e.g. (“prefix_filename”).
prefix – A prefix appended after the file name, e.g. (“filenam_suffix”).
format (Union[str, List[str]]) – The format of the output, ‘show’ displays on the computer screen, ‘png’ outputs to .png, ‘fits’ outputs to .fits format.
format_folder (bool) – If True, all images are output in a folder giving the format name, for example path/to/output/png/filename.png. This can make managing large image catalogues easier.
bypass (bool) – Whether to bypass the plt.show or plt.savefig methods, used when plotting a subplot.

property format: str#: The output format string; defaults to "show" when none was given.

property format_list#: The output format(s) as a list, so iteration always works.

output_path_from(format)[source]#

Return the directory path for format, creating it if necessary.

When format is "show" returns None (no file is written). When format_folder is True the format name is appended as a sub-directory so that png and pdf outputs are kept separate.

Parameters:: format – File format string, e.g. "png", "pdf", or "show".
Returns:: Absolute path to the output directory, or None for format == "show".
Return type:: str or None

filename_from(auto_filename)[source]#

Build the final filename string by applying prefix / suffix.

When no explicit filename was passed to __init__ the auto_filename supplied by the calling plotter is used as the base.

Parameters:: auto_filename – Fallback filename (without extension) when self.filename is None.
Returns:: The resolved filename with any configured prefix and suffix applied.
Return type:: str

savefig(filename, output_path, format)[source]#

Call plt.savefig with the configured bbox_inches setting.

Catches ValueError exceptions (e.g. unsupported format) and logs them without raising, so a single bad output format does not abort the whole script.

Parameters:

filename (str) – Base file name without extension.
output_path (str) – Directory to write the file (must already exist).
format (str) – File format extension string, e.g. "png".

to_figure(structure, auto_filename=None)[source]#

Output the figure, by either displaying it on the user’s screen or to the hard-disk as a .png or .fits file.

Parameters:

structure (Optional[Structure]) – The 2D array of image to be output, required for outputting the image as a fits file.
auto_filename (Optional[str]) – If the filename is not manually specified this name is used instead, which is defined in the parent plotter.

subplot_to_figure(auto_filename=None, also_show=False)[source]#

Output a subplot figure, either as an image on the screen or to the hard-disk as a png or fits file.

Parameters:: auto_filename (Optional[str]) – If the filename is not manually specified this name is used instead, which is defined in the parent plotter.

to_figure_output_mode(filename)[source]#

Save the current figure as a numbered PNG snapshot in output mode.

Output mode is activated by setting the environment variable PYAUTO_OUTPUT_MODE=1. Each call increments a global counter so that figures are saved as 0_filename.png, 1_filename.png, etc. in a sub-directory named after the running script. This is useful for collecting a sequence of figures during automated testing or demonstration scripts.

Parameters:: filename (str) – Base file name (without extension) for this figure.