ccu.fancyplots.gui package¶

A subpackage for the FancyPlots GUI.

The FancyPlots GUI can be launched programatically a via the following idiom:

import tkinter as tk
from ccu.fancyplots.gui.root import FancyPlotsGUI

root = tk.Tk()
app = FancyPlotsGUI(master=root)
app.master.mainloop()

Alternatively, the GUI can be launched from the command line, via the ccu-fancyplots subcommand:

ccu fed

In both cases, one has the option to load data from a previous FancyPlots session by specifying a cache file via the cache_file parameter of the ccu.fancyplots.gui.root.FancyPlotsGUI constructor or the ccu-fancyplots --cache CLI option of ccu fed.

Submodules¶

ccu.fancyplots.gui.annotation module¶

GUI elements for defining free energy diagram annotations.

This module defines the AnnotationSection class.

class ccu.fancyplots.gui.annotation.AnnotationSection(parent: FancyPlotsGUI, *args, **kwargs)[source]¶

Bases: Labelframe, UpdatableFrame

GUI component for adding annotations to the free energy diagram.

Variables:: annotations – A list of data.Annotations

Create section for adding annotations to the free energy diagram.

create_save_button() → Button[source]¶: Create a save button.

save_annotation() → None[source]¶: Save the created annotation data.

update_annotation() → None[source]¶: Update the displayed annotation data.

update_frames() → None[source]¶: Update the values in the subframes with the annotation.

ccu.fancyplots.gui.energy module¶

GUI elements for defining free energies in a mechanism.

This module defines the EnergyWindow class.

class ccu.fancyplots.gui.energy.EnergyWindow(parent: MechanismSection, *args, **kwargs)[source]¶

Bases: Toplevel

Define free energies for mechanism paths.

Variables:

dropdown – A tk.OptionMenu for selecting the pathway to configure.
energy_definition_frame – A ttk.Frame containing ttk.Entry and ttk.Label instances for defining free energies.
free_energy_entries – A dictionary mapping mechanism step names to the ttk.Entry widget.
free_energy_labels – A dictionary mapping mechanism step names to the labeling widget.
free_energy_vars – A dictionary mapping mechanism step names to the tkinter.StringVar instances in control of the ttk.Entry widgets which record the free energies of the mechanism step.
legend_entry – The ttk.Entry for defining the legend text for the current pathway.
legend_label – The ttk.Label for defining the legend text for the current pathway.
parent – A MechanismSection.
path_var – A tk.StringVar recording the name of the pathway for which energies are being defined.

Create and launch a window for specifying free energies.

Parameters:

parent – The parent mechanism.MechanismSection.
*args – Positional arguments for tkinter.Toplevel.
**kwargs – Keyword arguments fo tkinter.Toplevel.

property options: list[str]¶: The options (pathways) for the option menu.

property pathway¶: The pathway indicated by the dropdown selection.

property pathway_index¶: The index of pathway indicated by the dropdown.

quit_window() → None[source]¶: Gracefully quit the window and save data.

save_energy_data(index: int | None = None) → None[source]¶

Update FED data with the values from EnergyWindow.entries.

Parameters:: index – The index of the pathway to update with the current widget values. Defaults to None, in which case, EnergyWindow.pathway_index is used.

save_legend_data(index: int | None = None) → None[source]¶

Save the legend label for the present pathway and return True.

Parameters:: index – The index of the pathway to update with the current widget values. Defaults to None, in which case, EnergyWindow.pathway_index is used.

update_widgets(_) → None[source]¶: Update the energy and legend Entry widgets.

Developer’s Note

This should be the only place that EnergyWindow._previous_pathway is edited. Unlike other Tkinter widgets whose callbacks allow for the specification of state-dependent variables (e.g., the name of the triggering widget, the value before the action, etc.), the OptionMenu callback is always called without arguments. This makes it difficult to update the parameters before changing the values because the value in the option menu is already changed when the callback is called. A workaround is to duplicate the state of the shown option in the EnergyWindow._previous_pathway attribute and manually manage it here.

ccu.fancyplots.gui.fed module¶

GUI widgets for displaying free energy diagrams.

Specifically, this module provides the FreeEnergyDiagram and TightFreeEnergyDiagram classes.

class ccu.fancyplots.gui.fed.FreeEnergyDiagram(parent: FancyPlotsGUI, *args, **kwargs)[source]¶

Bases: Toplevel

View the free energy diagram.

Variables:

canvas – The FigureCanvasTkAgg in which the free energy diagram in plotted.
coordinate_label – The ttk.Label used to display the mouse coordinates.
cleanup_button – The ttk.Button used to preview the diagram with a tight layout.
introduction – The ttk.Label used to display the cursor coordinate hint.
parent – The root.FancyPlotsGUI.
tooltip – The Tooltip used to display the tight layout hint.

Create a window for displaying a free energy diagram.

Parameters:

parent – The running root.FancyPlotsGUI instance.
*args – Positional arguments for tkinter.Toplevel.
**kwargs – Keyword arguments fo tkinter.Toplevel.

generate_figure() → tuple[Axes | None, Axes | None, Figure | None][source]¶

Generate the free energy diagram.

Returns:: The output of plotting.generate_figure() if a mechanism is defined. Otherwise, (None, None, None).

mouse_coordinates(event: Event) → None[source]¶

Update the mouse coordinates label.

Parameters:: event – A “<Control-Motion>” tk.Event.

resize() → None[source]¶: Resize the window using the formatting parameter.

tight_layout_on_press(_: Event) → None[source]¶: Generate a free energy diagram with a tight layout.

tight_layout_on_release(_: Event) → None[source]¶: Destroy the tight layout free energy diagram.

update_graph() → bool[source]¶

Update the free energy diagram.

Returns:: True if the graph was successfully updated. False, otherwise.

class ccu.fancyplots.gui.fed.TightFreeEnergyDiagram(parent: FancyPlotsGUI, *args, **kwargs)[source]¶

Bases: Toplevel

View the free energy diagram with a tight layout.

Create a window for displaying a tight layout free energy diagram.

Parameters:

parent – The running root.FancyPlotsGUI instance.
*args – Positional arguments for tkinter.Toplevel.
**kwargs – Keyword arguments fo tkinter.Toplevel.

ccu.fancyplots.gui.footer module¶

Miscellaneous GUI elements for FancyPlots.

This module defines the FooterSection class which contains various ttk.Button instances for saving and displaying the graph, resetting parameters, and showing documentation.

class ccu.fancyplots.gui.footer.FooterSection(parent: FancyPlotsGUI, *args, **kwargs)[source]¶

Bases: Frame, UpdatableFrame

A collection of utility buttons for settings, instructions, and graphs.

Variables:

parent – A FancyPlotsGUI.
reset_button – A ttk.Button for resetting formatting parameters.
show_button – A ttk.Button for showing the free energy diagram.
save_button – A ttk.Button for saveing the free energy diagram.
palette_button – A ttk.Button for showing the matplotlib palette.
instructions_button – A ttk.Button for showing the instructions of how to use FancyPlots.

Create a section with miscellaneous GUI elements.

Parameters:

parent – The running root.FancyPlotsGUI instance.
*args – Positional arguments for tkinter.Toplevel.
**kwargs – Keyword arguments fo tkinter.Toplevel.

reset_defaults() → None[source]¶: Reset the formatting parameters to their default values.

save_figure() → None[source]¶: Save the free energy diagram.

show_graph() → None[source]¶: Show the free energy diagram.

show_instructions() → None[source]¶: Show the FancyPlots walkthrough.

show_palette() → None[source]¶: Show the matplotlib colour palette.

update_frames() → None[source]¶: Empty function.

ccu.fancyplots.gui.formatting module¶

GUI elements for defining plot formatting parameters.

This module defines the FormattingSection class.

class ccu.fancyplots.gui.formatting.FormattingSection(parent: FancyPlotsGUI, *args, parameters: FormattingParameters | None = None, **kwargs)[source]¶

Bases: Labelframe, UpdatableFrame

A ttk.LabelFrame containing all formatting parameters.

Note that instances of this class are listeners for the custom <Validate> event emitted by frames.FancyFormatFrame instances.

Variables:

parent – The root.FancyPlotsGUI.
formatting_parameters – A data.FormattingParameters instance mapping the names of formatting parameters to their values. Defaults to a copy of data.DEFAULT_PARAMETERS.
frames – A list of FancyFormatFrame instances in which the formatting parameters are set.

Create a section for specifying plot formatting parameters.

Parameters:

parent – The running root.FancyPlotsGUI instance.
*args – Positional arguments for tkinter.Toplevel.
parameters – A formatting.FormattingParameters dictionary mapping parameter names to their values. Defauls to DEFAULT_PARAMETERS.
**kwargs – Keyword arguments fo tkinter.Toplevel.

initialize_frames() → list[FancyFormatFrame][source]¶

Create ttk.LabelFrame widgets for setting formatting parameters.

Returns:

A list of FancyFormatFrame widgets used to set formatting parameters.

Raises:

NotImplementedError – Unsupported annotation type for formatting
parameter. Only annotated type hints are supported. –

reset_defaults() → None[source]¶: Reset the parameter values to their defaults.

update_frames() → None[source]¶: Update the values in the frame with the formatting parameters.

update_parameters(_: Event) → None[source]¶: Update FormattingSection.formatting_parameters.

ccu.fancyplots.gui.frames module¶

Validation-enabled GUI elements.

This module defines the FancyFormatFrame class.

class ccu.fancyplots.gui.frames.FancyFormatFrame(parent: ~tkinter.ttk.Labelframe, *args, label: str = '', value: ~typing.Any = None, tooltip: str = '', validator: ~ccu.fancyplots.validation.Validator[~ccu.fancyplots.gui.frames._T] = <function no_validation_validator>, serializer: ~ccu.fancyplots.validation.Serializer[~ccu.fancyplots.gui.frames._T] = <function default_serializer>, pad: tuple[float, float, float, float] = (5, 3, 5, 3), **kwargs)[source]¶

Bases: Labelframe

A ttk.LabelFrame for setting formatting parameters.

Note that FancyFormatFrame instances emit the <<Validate>> event. To listen for this event, handlers should be bound to the event using Misc.bind and Misc.event_add.

Variables:

entry – A ttk.Entry in which a user specifies a formatting parameter.
tooltip – A :class`.tooltip.Tooltip` displaying help text.
validator – A validation.Validator used to validate and convert the text in entry.
serializer – A validation.Serializer used to convert the Python value to a string.

A ttk.LabelFrame for setting formatting parameters.

Parameters:

parent – The containing ttk.LabelFrame.
*args – Positional parameters for ttk.LabelFrame.
label – The name of the formatting parameter. Defaults to “”.
value – The initial value of the formatting parameter. Defaults to None.
tooltip – The tooltip message. Defaults to “”.
validator – A Validator for validating and converting user input. Defaults to validation.no_validation_validator().
serializer – A validation.Serializer instance for
converting the Python version of the value to a string.
pad – Specify the padding (left, top, bottom, right) to use for the tooltip. Defaults to (5, 3, 5, 3).
**kwargs – Keyword arguments for ttk.LabelFrame.

alerting_validator(value: str) → bool[source]¶

Validate a value and generate a <<Validate>> event.

Parameters:: value – The value to validate.
Returns:: True if the value if valid. False, otherwise.

Note

Listeners should be bound to the <<Validate>> event in order to respond to this behaviour.

property label_text: str¶: The text used for the FancyFormatFrame label.

property python_value: _T¶

The Python value of the text in FancyFormatFrame.entry.

Raises:

ValidationError – The current value in
FancyFormatFrame.entry –

property value¶: The text in FancyFormatFrame.entry.

class ccu.fancyplots.gui.frames.UpdatableFrame(*args, **kwargs)[source]¶

Bases: Protocol

A GUI element whose children’s state depend on their data.

update_frames() → None[source]¶: This function should update all children of the frame.

ccu.fancyplots.gui.instructions module¶

GUI elements for viewing the FancyPlots walkthrough.

This module defines the InstricutionsWindow class.

class ccu.fancyplots.gui.instructions.InstructionsWindow(parent: FancyPlotsGUI, *args, **kwargs)[source]¶

Bases: Toplevel

View the instructions of how to use FancyPlots.

Variables:

parent – The running root.FancyPlotsGUI instance.
image – The A Tkinter-compatible version of the usage instructions.
image_label – The ttk.Label containing the image.

Create a windown for viewing the instructions.

Parameters:

parent – The running root.FancyPlotsGUI instance.
*args – Positional arguments for tkinter.Toplevel.
**kwargs – Keyword arguments for tkinter.Toplevel.

ccu.fancyplots.gui.mechanism module¶

GUI elements for defining reaction mechanisms.

Specifically, this module defines the StepPanel, PathPanel, and MechanismSection classes.

class ccu.fancyplots.gui.mechanism.MechanismSection(parent: FancyPlotsGUI, *args, **kwargs)[source]¶

Bases: Labelframe, UpdatableFrame

GUI element for specifying mechanism free energies.

Variables:

parent – The running root.FancyPlotsGUI instance.
step_panel – A ttk.LabelFrame for defining the names of mechanism steps.
path_panel – A ttk.LabelFrame for defining the number of pathways.
gibbs_button – A ttk.Button for launching the EnergyWindow.
reorder_button – A ttk.Button for launching the ReorderWindow.

Create a subpanel for defining a reaction mechanism.

Parameters:

parent – The containing mechanism.MechanismSection.
*args – Positional arguments for ttk.LabelFrame.
**kwargs – Keyword arguments for ttk.LabelFrame.

launch_energy_window() → None[source]¶: Launch a window for defining mechanism free energies.

property mechanism: list[str]¶: The names used to define mechanism steps.

property npaths: int¶: The number of pathways.

update_data() → Literal[True][source]¶

Update the free energy diagram (meta)data.

Note that this method returns True in order for validation via tkinter to permit the value within StepPanel.entry to change.

update_frames() → None[source]¶: Update the path and step panels.

class ccu.fancyplots.gui.mechanism.PathPanel(parent: MechanismSection, *args, **kwargs)[source]¶

Bases: Labelframe

Define the number of pathways.

Variables:

parent – The parent ccu.fancyplots.gui.mechanism.MechanismSection.
spinbox – The tk.Spinbox used to define the number of pathways.
var – The tkinter.IntVar for the tk.Spinbox.

Create a subpanel for defining the number of mechanism pathways.

Parameters:

parent – The containing mechanism.MechanismSection.
*args – Positional arguments for ttk.LabelFrame.
**kwargs – Keyword arguments for ttk.LabelFrame.

property npaths: int¶: The number of pathways.

update_data() → None[source]¶

Update the mechanism data.

Returns True so as to ensure that tkinter accepts the new input.

Note

No validation is performed on the mechanism steps.

class ccu.fancyplots.gui.mechanism.StepPanel(parent: MechanismSection, *args, **kwargs)[source]¶

Bases: Labelframe

Define the name and number of mechanism steps.

Note that step names are stripped of all surrounding whitespace.

Variables:

entry – The ttk.Entry used to define mechanism steps.
parent – The parent ccu.fancyplots.gui.mechanism.MechanismSection.
var – The tk.StringVar for the ttk.Entry.

Create a subpanel for defining the mechanism steps.

Parameters:

parent – The containing mechanism.MechanismSection.
*args – Positional arguments for ttk.LabelFrame.
**kwargs – Keyword arguments for ttk.LabelFrame.

property mechanism: list[str]¶: The names used to define mechanism steps.

update_data() → Literal[True][source]¶

Update the mechanism data.

Returns True so as to ensure that tkinter accepts the new input.

Note

No validation is performed on the mechanism steps.

ccu.fancyplots.gui.menu module¶

Functions for menu creation and manipulation.

ccu.fancyplots.gui.menu.create_edit_menu(root: Widget | Widget) → Menu[source]¶

Create an edit menu.

Parameters:: root – The master object for the menu.
Returns:: The created edit menu.

ccu.fancyplots.gui.menu.show_edit_menu(root: Widget | Widget) → Callable[[Event], None][source]¶

Create an event handler that shows a cut-copy-paste-select all menu.

Parameters:: root – A widget to which the menu will belong.
Returns:: A handler that can create an edit menu.

ccu.fancyplots.gui.palette module¶

GUI elements for viewing the matplotlib colour palette.

This module defines the PaletteWindow class.

class ccu.fancyplots.gui.palette.PaletteWindow(parent: FancyPlotsGUI, *args, **kwargs)[source]¶

Bases: Toplevel

View available matplotlib colours.

Variables:

image – The A Tkinter-compatible version of the usage instructions.
image_label – The ttk.Label containing the image.
parent – The running root.FancyPlotsGUI instance.
source_label – The ttk.Label containing the image source.

Create a subpanel for defining a reaction mechanism.

Parameters:

parent – The runnnig root.FancyPlotsGUI instance.
*args – Positional arguments for tk.Toplevel.
**kwargs – Keyword arguments for tk.Toplevel.

ccu.fancyplots.gui.plotting module¶

Functions for plotting free energy diagrams.

The main function is ccu.fancyplots.gui.plotting.generate_figure().

Examples

>>> from ccu.fancyplots.data import DEFAULT_PARAMETERS
>>> from ccu.fancyplots.data import FEDData
>>> from ccu.fancyplots.gui.plotting import generate_figure
>>> energy_data = [[0.0, 1.5, 0.5]]
>>> data = FEDData(
...     energy_data=energy_data,
...     mechanism=["*", "*H", "H2"],
...     legend_labels=["Cu(111)"],
... )
>>> generate_figure(data, DEFAULT_PARAMETERS, visual=True)

class ccu.fancyplots.gui.plotting.SymHandler(marker_pad=0.3, numpoints=None, **kwargs)[source]¶

Bases: HandlerLine2D

Parameters:

marker_pad (float) – Padding between points in legend entry.
numpoints (int) – Number of points to show in legend entry.
**kwargs – Keyword arguments forwarded to .HandlerBase.

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)[source]¶

Return the legend artists generated.

Parameters:

legend (~matplotlib.legend.Legend) – The legend for which these legend artists are being created.
orig_handle (~matplotlib.artist.Artist or similar) – The object for which these legend artists are being created.
xdescent, ydescent, width, height (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.
fontsize (int) – The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.
trans (~matplotlib.transforms.Transform) – The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.

ccu.fancyplots.gui.plotting.add_annotations(engine: Axes | ModuleType, annotations: list[Annotation], fontsize: float, font: str) → None[source]¶

Add the annotations to the free energy diagram.

Parameters:

engine – The engine with which to create the legend. Can either be an axes.Axes object or matplotlib.pyplot.
annotations – The annotations to add.
fontsize – The font size to use for the annotations.
font – The matplotlib font family to use to write the annotations.

ccu.fancyplots.gui.plotting.bracket_ts_step(ts_step_index: int, energies: dict[str, float | None]) → tuple[int, int][source]¶

Determine the indices of the nearest mechanism steps to a TS.

Parameters:

ts_step_index – The index of the transition state step.
energies – A list of free energies. The ith entry in energies corresponds to the ith step in pathway.

Raises:

RuntimeError – Unable to bracket the transition step. Either there is no elementary reaction step defined prior to the reaction step or there is no elementary reaction step defined after the reaction step.

Returns:

A 2-tuple (index_before, index_after) indicating the indices of the nearest, defined reaction steps before and after the transition state, respectively.

ccu.fancyplots.gui.plotting.create_axes(parameters: FormattingParameters, *, visual: bool = True) → tuple[Axes, Figure][source]¶

Create the primary axes for plotting free energy diagrams.

Parameters:

parameters – The formatting parameters to use to plot the diagram
visual – Whether or not the image is being displayed. Determines the interface to matplotlib that is used. Defaults to True.

Returns:

A 2-tuple (ax, fig) whose first and second elements are the primary axes and figure used to plot the diagram, respectively.

ccu.fancyplots.gui.plotting.create_legend(engine: Axes | ModuleType, lines: list[Artist | None], legend_entries: list[str | None], fontsize: float, loc: str) → None[source]¶

Create the legend for the free energy diagram.

Parameters:

engine – The engine with which to create the legend. Can either be an axes.Axes object or matplotlib.pyplot.
lines – The artist.Artist objects for which legend entries will be made.
legend_entries – A list of legend entries.
fontsize – The fontsize for the legend.
loc – The legend location. See the documentation for matplotlib.legend.Legend for valid values.

ccu.fancyplots.gui.plotting.create_ts_curve(ts_step_index: int, energies: list[float | None], step_count: int) → tuple[list[float], list[float]][source]¶

Create the plotting data for a transition state curve.

Parameters:

ts_step_index – The index of the transition state step.
energies – A list of free energies. The ith entry in energies corresponds to the ith step in pathway.
step_count – A weighted index for mechanism steps. Elementary steps increment the index by 2 while steps corresponding to transition states increment the index by 1.

Returns:

A 2-tuple (xx, yy) whose first and second elements are the x and y values to be plotted on the free energy diagram.

ccu.fancyplots.gui.plotting.format_primary_axes(ax: Axes, engine: Axes | ModuleType, parameters: FormattingParameters, count: int) → None[source]¶

Format the primary axis.

Parameters:

ax – The primary matplotlib.axes.Axes.
engine – The engine with which to create the legend. Can either be an axes.Axes object or matplotlib.pyplot.
parameters – The formatting.FormattingParameters to use for the axes.
count – A weighted index for mechanism steps. Elementary steps increment the index by 2 while steps corresponding to transition states increment the index by 1.

ccu.fancyplots.gui.plotting.format_secondary_axes(ax: Axes, parameters: FormattingParameters) → None[source]¶

Format the secondary axis.

Parameters:

ax – The secondary matplotlib.axes.Axes.
parameters – The formatting.FormattingParameters to use for the axes.

ccu.fancyplots.gui.plotting.generate_figure(diagram_data: FEDData, parameters: FormattingParameters = {'boxsize': (6, 4.5), 'colors': ('black', 'blue', 'red', 'lime', 'fuchsia'), 'dpi': 1200, 'font': 'Sans Serif', 'fontsize': 14, 'legend_loc': 'best', 'linewidth': 2.25, 'markeredgewidth': 0.3, 'markersize': 7, 'savename': 'fed.svg', 'tick_dec': 2, 'tick_double': False, 'tick_loc': 'out', 'tick_min': 1, 'title': '', 'xlabel': 'Reaction Coordinate', 'xlim': None, 'xscale': 'linear', 'ylabel': '$\\Delta$G / eV', 'ylim': None, 'yscale': 'linear'}, annotations: list[Annotation] | None = None, *, visual: bool = True) → tuple[Axes, Axes | None, Figure][source]¶

Generate the free energy diagram figure.

Parameters:

diagram_data – The data for the free energy diagram.
parameters – The formatting parameters to use to create the free energy diagram.
annotations – Annotations for the free energy data. Defaults to an empty list.
visual – Whether or not to display the image. If False, the figure will be saved to file instead of displayed. Defaults to True.

Returns:

A 3-tuple (ax1,``ax2``, figure). ax1 is the primary axes containing the free energy diagram. ax2 is the secondary axes; it is None unless the “tick_double” parameter is True in parameters. figure is the matplotlib.figure.Figure containing all plot elements.

ccu.fancyplots.gui.plotting.interpolate(x0: tuple[float, float, float], y0: tuple[float, float, float]) → tuple[list[float], list[float]][source]¶

Interpolate between three points with a sinusoidal function.

Parameters:

x0 – The x-coordinates of the start, mid-, and end points.
y0 – The y-coordinates of the start, mid-, and end points.

Returns:

The x- and y-coordinates of the interpolation.

ccu.fancyplots.gui.plotting.plot_energy_data(ax: Axes, data: FEDData, parameters: FormattingParameters) → tuple[int, list[Artist | None]][source]¶

Plot the free energy diagrams of all pathways.

Parameters:

ax – The axes.Axes on which to plot the Gibbs plot.
data – The free energy data to plot.
parameters – The formatting parameters to use to plot the free energy diagram.

Returns:

A 2-tuple (step_count, lines) where step_count is a weighted index for mechanism steps. Elementary steps increment the index by 2 while steps corresponding to transition states increment the index by 1. lines is a list of artist.Artist objects, each corresponding to a data point in the data series.

ccu.fancyplots.gui.plotting.plot_fed(ax: Axes, energies: list[float | None], mechanism: list[str], color: str, zorder: int, linewidth: float) → tuple[int, Artist | None][source]¶

Plot the free energy diagram of a pathway.

Parameters:

ax – The axes.Axes on which to plot the free energy diagram.
energies – A list of free energies. The ith entry in energies corresponds to the ith step in pathway.
mechanism – A list of strings corresponding to the steps of a reaction mechanism.
color – A string corresponding to a matplotlib colour.
zorder – The zorder for the lines for the pathway. A lower zorder indicates that the line will be drawn first.
linewidth – The width of the line to use to plot the free energy diagram.

Returns:

A 2-tuple (step_count, line) where step_count is a weighted index for mechanism steps. Elementary steps increment the index by 2 while steps corresponding to transition states increment the index by 1. line is a representative artist.Artist object for the data series.

ccu.fancyplots.gui.plotting.save_fed_plot(savename: str, dpi: int) → None[source]¶

Save the free energy diagram.

Parameters:

savename – The filename to use when saving the file
dpi – The resolution in dots-per-inch.

ccu.fancyplots.gui.root module¶

The main logic for the FancyPlots root window.

The FancyPlotsGUI class encompasses the main application logic for a FancyPlots application.

In addition to the main application class, FancyPlotsGUI, this module also defines the following TypedDict subclasses:

Windows: A mapping whose values are the top-level subwindows of a FancyPlots GUI application.
Sections: A mapping whose values are subframes of the FancyPlots root window.

Example

Launch the FancyPlots GUI

import tkinter as tk
from ccu.fancyplots.gui.root import FancyPlotsGUI

root = tk.Tk()
app = FancyPlotsGUI(master=root)
app.master.mainloop()

class ccu.fancyplots.gui.root.FancyPlotsGUI(cache_file: str | ~pathlib.Path | None = None, master=<class 'tkinter.Tk'>)[source]¶

Bases: object

A Fancy Plots GUI application.

Variables:

master – The application root window - the topmost tkinter.Tk instance.
windows – A dictionary containing the child windows (:class`tkinter.TopLevel`) of the GUI.
sections – A Sections instance.

Note

FancyPlotsGUI is not a window and, as such, one cannot use it directly to manipulate properties of the GUI. For that, use FancyPlots.master.

Launch the main GUI for FancyPlots.

Parameters:

cache_file – A string or Path pointing to a cache file. Defaults to None. If provided, it is used to pre-populate the formatting parameters, mechanism info, and annotations. Otherwise, a fresh FancyPlots application is launched.
master – The top level tkinter.Tk instance.

property cache: FancyCache¶: Retrieve an updated account of FancyPlots’ data.

save_cache() → None[source]¶: Save the FancyPlots cache.

class ccu.fancyplots.gui.root.Sections[source]¶

Bases: TypedDict

The subframes of a FancyPlotsGUI app.

Variables:

formatting (ccu.fancyplots.gui.formatting.FormattingSection) – The subsection for defining plot formatting parameters.
mechanism (ccu.fancyplots.gui.mechanism.MechanismSection) – The subsection for defining reaction free energies and legend labels.
footer (ccu.fancyplots.gui.footer.FooterSection) – The subsection for miscelleneous support (e.g., instructions, graph viewing/saving.)
annotation (ccu.fancyplots.gui.annotation.AnnotationSection) – The subsection for defining graph annotations.

Example

>>> import tkinter as tk
>>> from ccu.fancyplots.gui.root import FancyPlotsGUI
>>> root = tk.Tk()
>>> app = FancyPlotsGUI(master=root)
>>> app.master.mainloop()
>>> app.sections[...]

annotation: AnnotationSection¶

footer: FooterSection¶

formatting: FormattingSection¶

mechanism: MechanismSection¶

class ccu.fancyplots.gui.root.Windows[source]¶

Bases: TypedDict

The top-level windows of a FancyPlots GUI.

Variables:

energy_window (ccu.fancyplots.gui.energy.EnergyWindow | None) – The tkinter.Toplevel instance for defining Gibbs free energies.
graph_window (ccu.fancyplots.gui.fed.FreeEnergyDiagram | None) – The tkinter.Toplevel instance for viewing the free energy diagram.
tight_layout (ccu.fancyplots.gui.fed.TightFreeEnergyDiagram | None) – The tkinter.Toplevel instance for viewing the free energy diagram in a tight layout.
instructions_window (ccu.fancyplots.gui.instructions.InstructionsWindow | None) – The tkinter.Toplevel instance for viewing the instructions for using FancyPlots.
matplotlib_palette (ccu.fancyplots.gui.palette.PaletteWindow | None) – The tkinter.Toplevel instance for viewing the instructions for viewing the matplotlib colour palette.

Example

>>> import tkinter as tk
>>> from ccu.fancyplots.gui.root import FancyPlotsGUI
>>> root = tk.Tk()
>>> app = FancyPlotsGUI(master=root)
>>> app.master.mainloop()
>>> app.windows[...]

energy_window: EnergyWindow | None¶

graph_window: FreeEnergyDiagram | None¶

instructions_window: InstructionsWindow | None¶

matplotlib_palette: PaletteWindow | None¶

tight_layout: TightFreeEnergyDiagram | None¶

ccu.fancyplots.gui.tooltip module¶

A robust tooltip class.

This module provides the Tooltip class.

class ccu.fancyplots.gui.tooltip.Tooltip(parent: Widget | Widget, *, bg: str = '#000000', pad: tuple[float, float, float, float] = (5, 3, 5, 3), text: str = '', waittime: int = 400, wraplength: float = 250)[source]¶

Bases: object

Create a tooltip for a given widget as the mouse goes on it.

see:

http://stackoverflow.com/questions/3221956/: what-is-the-simplest-way-to-make-tooltips- in-tkinter/36221216#36221216
http://www.daniweb.com/programming/software-development/: code/484591/a-tooltip-class-for-tkinter

Originally written by vegaseat on 2014.09.09.
Modified to include a delay time by Victor Zaccardo on 2016.03.25.

Variables:

parent – The widget over which the user must hover to activate the tooltip.
bg – The tooltip background as a hex string. Defaults to “#FFFFEA”.
pad – A 4-tuple (left, top, bottom, right), indicating the padding around the text within the tooltip (in pixels).
text – The text displayed in the tooltip. Defaults to an empty string.
waittime – Time before displaying (in milliseconds). Defaults to 400.
wraplength – Length before wrapping text (in pixels). Defaults to 250.

Create a tooltip.

Parameters:

parent – The parent widget over which one must hover to generate the tooltip.
bg – The tooltip background. Defaults to “#FFFFEA”.
pad – The padding to use for the tooltip. Defaults to (5, 3, 5, 3).
text – The text to display on the tooltip. Defaults to “”.
waittime – The time (in milliseconds) to wait for a user to hover before generating the tooltip. Defaults to 400.
wraplength – The character length at which the tooltip message will wrap. Defaults to 250.

hide() → None[source]¶: Hide the tooltip.

on_enter(_: Event | None = None) → None[source]¶: Begin counting to display the tooltip.

on_leave(_: Event | None = None) → None[source]¶: Stop counting to display the tooltip.

schedule() → None[source]¶: Plan to display the tooltip.

show() → None[source]¶: Show the tooltip.

unschedule() → None[source]¶: Cancel scheduling to show the tooltip.

ccu.fancyplots.gui.utils module¶

GUI utility functions.

Specifically, this module provides ccu.fancyplots.gui.utils.open_image(), which opens a Tkinter-compatible version of an image shipped with ccu., and ccu.fancyplots.gui.utils.print_decal(), which prints an Easter egg.

ccu.fancyplots.gui.utils.open_image(name: str, width: int, height: int) → PhotoImage[source]¶

Open Tkinter-compatible version of a ccu image.

Parameters:

name – The name of the image to open.
width – The width of the image when opened.
height – The height of the image when opened.

Returns:

A Tkinter-compatible version of the opened image.

ccu.fancyplots.gui.utils.print_easter_egg() → None[source]¶: Print an Easter egg.