Plotting - matplotlib

Wrappers

These functions provide a high-level API for visualizing various objects/results (e.g., DataSet). Most of them are the same functions included in pyimpspec with the notable exception of plot().

deareis.mpl.plot(settings, project, x_limits=None, y_limits=None, title=True, legend=None, legend_loc=0, grid=False, tight_layout=False, figure=None, axes=None, num_per_decade=100)

Plot a complex plot containing one or more items from a project based on the provided settings.

Parameters:

settings (PlotSettings) – The settings for the plot.
project (Project) – The project that the plot is a part of.
x_limits (Optional[Tuple[Optional[float], Optional[float]]], optional) – The lower and upper limits of the x-axis.
y_limits (Optional[Tuple[Optional[float], Optional[float]]], optional) – The lower and upper limits of the y-axis.
title (bool, optional) – Whether or not to include the title in the figure.
legend (Optional[bool], optional) – Whether or not to include a legend in the figure.
legend_loc (Union[int, str], optional) – The position of the legend in the figure. See matplotlib’s documentation for valid values.
grid (bool, optional) – Whether or not to include a grid in the figure.
tight_layout (bool, optional) – Whether or not to apply a tight layout that the sizes of the reduces margins.
figure (Optional[matplotlib.Figure], optional) – The matplotlib.figure.Figure instance to use when plotting the data.
axes (List[Axes], optional) – The matplotlib.axes.Axes instance to use when plotting the data.
num_per_decade (int, optional) – If any circuit fits, circuit simulations, or Kramers-Kronig test results are included in the plot, then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_circuit(circuit, frequencies, label=None, colors=None, markers=None, figure=None, title=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot the simulated impedance response of a circuit as both a Nyquist and a Bode plot.

Parameters:

circuit (Circuit) – The circuit to use when simulating the impedance response.
frequencies (Frequencies) – The frequencies (in hertz) to use when simulating the impedance response.
label (Optional[str], optional) – The optional label to use in the legend.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘impedance’, ‘magnitude’, ‘phase’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘impedance’, ‘magnitude’, ‘phase’.
figure – The matplotlib.figure.Figure instance to use when plotting the data.
title (Optional[str], optional) – The title of the figure. If not title is provided, then the circuit description code of the circuit is used instead.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_data(data, label=None, admittance=False, colors=None, markers=None, figure=None, title=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot a DataSet instance as both a Nyquist and a Bode plot.

Parameters:

data (DataSet) – The DataSet instance to plot.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘impedance’, ‘magnitude’, ‘phase’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘impedance’, ‘magnitude’, ‘phase’.
figure – The matplotlib.figure.Figure instance to use when plotting the data.
title (Optional[str], optional) – The title of the figure. If not title is provided, then the label of the DataSet is used instead.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_drt(drt, data, peak_threshold=-1.0, label=None, admittance=False, colors=None, markers=None, figure=None, title=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, frequency=False, **kwargs)

Plot the result of calculating the distribution of relaxation times (DRT) as a Bode plot, a DRT plot, and a plot of the residuals.

Parameters:

drt (DRTResult) – The result to plot.
data (DataSet) – The DataSet instance that was used in the DRT calculations.
peak_threshold (float, optional) – The threshold to use for identifying and marking peaks (0.0 to 1.0, relative to the highest peak). Negative values disable marking peaks.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘gamma’, ‘real’, ‘imaginary’, ‘data_real’, ‘data_imaginary’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘real’, ‘imaginary’, ‘data_real’, ‘data_imaginary’.
figure – The matplotlib.figure.Figure instance to use when plotting the data.
title (Optional[str], optional) – The title of the figure. If no title is provided, then the circuit description code (and label of the DataSet) is used instead.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
frequency (bool, optional) – Plot gamma as a function of frequency.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_fit(fit, data, label=None, admittance=False, colors=None, markers=None, num_per_decade=100, figure=None, title=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot the result of a fit as a Nyquist plot, a Bode plot, and a plot of the residuals.

Parameters:

fit (Union[KramersKronigResult, FitResult, DRTResult]) – The circuit fit or test result.
data (DataSet) – The DataSet instance that a circuit was fitted to.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘real’, ‘imaginary’, ‘data_impedance’, ‘impedance’, ‘data_magnitude’, ‘data_phase’, ‘magnitude’, ‘phase’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘real’, ‘imaginary’, ‘data_impedance’, ‘data_magnitude’, ‘data_phase’.
num_per_decade (int, optional) – If the data being plotted is not a DataSet instance (e.g. a KramersKronigResult instance), then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).
figure – The matplotlib.figure.Figure instance to use when plotting the data.
title (Optional[str], optional) – The title of the figure. If no title is provided, then the circuit description code (and label of the DataSet) is used instead.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_kramers_kronig_tests(tests, suggestion, data, admittance=False, estimate_noise=False, colors=None, markers=None, figure=None, title=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, limit=0.55, moving_average_width=0, **kwargs)

Plot the results of exploratory Kramers-Kronig tests as a Nyquist plot, a Bode plot, a plot of the residuals, and a plot of the \(\chi^2_{ps.}\) values and the scores used to suggest the number of RC elements.

Parameters:

tests (List[KramersKronigResult]) – The test results to plot.
suggestion (Tuple[KramersKronigResult, List[int], int, int]) – The return value of suggest_num_RC().
data (DataSet) – The DataSet instance that was tested.
admittance (bool, optional) – Whether or not to plot the admittance representation of the data instead of the impedance representation.
estimate_noise (bool, optional) – Whether or not to plot the estimated standard deviation of the noise based on the pseudo chi-squared value and the number of measured frequencies. The 3-sigma standard deviations are indicated in the plots. The noise is assumed to be Gaussian and the noise in each part (real and imaginary) is assumed to be independent of the other. See equation 16 in Yrjänä and Bobacka (2024) for details.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘chisqr’, ‘num_RC’, ‘real’, ‘imaginary’, ‘data_impedance’, ‘impedance’, ‘data_magnitude’, ‘data_phase’, ‘magnitude’, ‘phase’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘chisqr’, ‘num_RC’, ‘real’, ‘imaginary’, ‘data_impedance’, ‘data_magnitude’, ‘data_phase’.
figure – The matplotlib.figure.Figure instance to use when plotting the data.
title (Optional[str], optional) – The title of the figure. If no title is provided, then the label of the DataSet is used instead.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
moving_average_width (int, optional) – The width of the moving average to use when plotting the residuals. Must be an odd integer number greater than or equal to three. Otherwise, the moving averages are not plotted.
**kwargs
limit (float)

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

Primitives

These functions are used by the wrapper functions to make a more complex figure with multiple subplots. These are all the same as those included in pyimpspec.

deareis.mpl.plot_bht_scores(drt, colors=None, label_bars=False, figure=None, title=None, legend=True, axes=None, adjust_axes=True, **kwargs)

Plot the scores of a BHTResult as a bar chart.

Parameters:

drt (BHTResult) – The result to plot.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘real’, ‘imaginary’.
label_bars (bool, optional) – Whether or not to add labels above the bars.
figure – The matplotlib.figure.Figure instance to use when plotting the data.
title (Optional[str], optional) – The title of the figure.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_bode(data, label=None, admittance=False, colors=None, markers=None, line=False, num_per_decade=100, figure=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot some data as a Bode plot (Mod(Z) vs f and Phase(Z) vs f).

Parameters:

data (Optional[Union[DataSet, KramersKronigResult, FitResult, DRTResult]]) – The data to plot.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘magnitude’, ‘phase’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘magnitude’, ‘phase’.
line (bool, optional) – Whether or not lines should be used instead of markers.
num_per_decade (int, optional) – If the data being plotted is not a DataSet instance (e.g. a KramersKronigResult instance), then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_gamma(drt, peak_threshold=-1.0, label=None, bounds_alpha=0.3, colors=None, figure=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, frequency=False, **kwargs)

Plot the distribution of relaxation times (gamma vs tau).

Parameters:

drt (Optional[DRTResult]) – The result to plot.
peak_threshold (float, optional) – The threshold to use for identifying and marking peaks (0.0 to 1.0, relative to the highest peak). Negative values disable marking peaks.
label (Optional[str], optional) – The optional label to use in the legend.
bounds_alpha (float, optional) – The alpha to use when plotting the bounds of the Bayesian credible intervals (if they are included in the data).
colors (Optional[Dict[str, str]], optional) – The colors of the lines. Valid keys: ‘gamma’.
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – The matplotlib.axes.Axes instance to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
frequency (bool, optional) – Plot gamma as a function of frequency.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_imaginary(data, label=None, admittance=False, colors=None, markers=None, line=False, num_per_decade=100, figure=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot the negative imaginary impedance of some data (-Im(Z) vs f).

Parameters:

data (Optional[Union[DataSet, KramersKronigResult, FitResult, DRTResult]]) – The data to plot.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘imaginary’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘imaginary’.
line (bool, optional) – Whether or not a line should be used instead of markers.
num_per_decade (int, optional) – If the data being plotted is not a DataSet instance (e.g. a KramersKronigResult instance), then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_magnitude(data, label=None, admittance=False, colors=None, markers=None, line=False, num_per_decade=100, figure=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot the absolute magnitude of the impedance of some data (Mod(Z) vs f).

Parameters:

data (Optional[Union[DataSet, KramersKronigResult, FitResult, DRTResult]]) – The data to plot.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘magnitude’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘magnitude’.
line (bool, optional) – Whether or not a line should be used instead of markers.
num_per_decade (int, optional) – If the data being plotted is not a DataSet instance (e.g. a KramersKronigResult instance), then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_nyquist(data, label=None, admittance=False, colors=None, markers=None, line=False, num_per_decade=100, figure=None, legend=True, axes=None, adjust_axes=True, **kwargs)

Plot some data as a Nyquist plot (-Im(Z) vs Re(Z)).

Parameters:

data (Optional[Union[DataSet, KramersKronigResult, FitResult, DRTResult]]) – The data to plot.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘impedance’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘impedance’.
line (bool, optional) – Whether or not a line should be used instead of markers.
num_per_decade (int, optional) – If the data being plotted is not a DataSet instance (e.g. a KramersKronigResult instance), then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_phase(data, label=None, admittance=False, colors=None, markers=None, line=False, num_per_decade=100, figure=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot the negative phase shift of the impedance of some data (-Phase(Z) vs f).

Parameters:

data (Optional[Union[DataSet, KramersKronigResult, FitResult, DRTResult]]) – The data to plot.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘phase’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘phase’.
line (bool, optional) – Whether or not a line should be used instead of markers.
num_per_decade (int, optional) – If the data being plotted is not a DataSet instance (e.g. a KramersKronigResult instance), then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_real(data, label=None, admittance=False, colors=None, markers=None, line=False, num_per_decade=100, figure=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot the real impedance of some data (Re(Z) vs f).

Parameters:

data (Optional[Union[DataSet, KramersKronigResult, FitResult, DRTResult]]) – The data to plot.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘real’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘real’.
line (bool, optional) – Whether or not a line should be used instead of markers.
num_per_decade (int, optional) – If the data being plotted is not a DataSet instance (e.g. a KramersKronigResult instance), then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_real_imaginary(data, label=None, admittance=False, colors=None, markers=None, line=False, num_per_decade=100, figure=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, **kwargs)

Plot the real and imaginary parts of the impedance of some data (Re(Z) vs f and -Im(Z) vs f).

Parameters:

data (Optional[Union[DataSet, KramersKronigResult, FitResult, DRTResult]]) – The data to plot.
label (Optional[str], optional) – The optional label to use in the legend.
admittance (bool, optional) – Plot the admittance representation of the immittance data.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘real’, ‘imaginary’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘real’, ‘imaginary’.
line (bool, optional) – Whether or not lines should be used instead of markers.
num_per_decade (int, optional) – If the data being plotted is not a DataSet instance (e.g. a KramersKronigResult instance), then this parameter can be used to change how many points are used to draw the line (i.e. how smooth or angular the line looks).
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

deareis.mpl.plot_residuals(result, colors=None, markers=None, figure=None, legend=True, axes=None, adjust_axes=True, colored_axes=False, limit=-1.0, moving_average_width=0, **kwargs)

Plot the residuals of a result.

Parameters:

result (Union[KramersKronigResult, FitResult, DRTResult]) – The result to plot.
colors (Optional[Dict[str, str]], optional) – The colors of the markers or lines. Valid keys: ‘real’, ‘imaginary’.
markers (Optional[Dict[str, str]], optional) – The markers to use when not plotting lines. Valid keys: ‘real’, ‘imaginary’.
figure – The matplotlib.figure.Figure instance to use when plotting the data.
legend (bool, optional) – Whether or not to add a legend.
axes – A list of matplotlib.axes.Axes instances to use when plotting the data.
adjust_axes (bool, optional) – Whether or not to adjust the axes (label, scale, limits, etc.).
colored_axes (bool, optional) – Color the y-axes.
limit (float, optional) – The absolute value of the positive and negative limits to apply to each y-axis. If equal to or less than zero, then the limits are adjusted automatically.
moving_average_width (int, optional) – The width of the moving average. Must be an odd integer number greater than or equal to three. Otherwise, the moving averages are not plotted.
**kwargs

Return type:

Tuple[matplotlib.Figure, List[matplotlib.Axes]]

Examples

Below are some examples of plots created using the plotting functions listed above. The circuit and the data set are based on test circuit 1 (TC-1) from this 1995 article by Bernard Boukamp.

Legends are disabled and colored axes are used instead in the figures generated by the wrapper functions (i.e., the first figure in each series). This has been done due to the small size of the figures in this documentation. However, the figures generated by the individual primitive functions are also included with the legends enabled and without colored axes.

The default color scheme is based on the Vibrant qualitative color scheme presented in Paul Tol’s blog. Colors and markers can be defined when calling any of the functions.