matador.plotting package

The plotting module provides functions to make publication quality plots for bandstructures, phase diagrams, densities of states, voltages and volume curves.

Plot style settings can be configured by specifying a matplotlib style (either built-in or a custom file). The default “matador” style can be found in the matador.config submodule. User default styles can be set with the plotting.default_style option in user’s matadorrc. Minor tweaks can be made by passing style dictionaries on a per plot level.

matador.plotting.plot_spectral(seeds, **options)

This function wraps all of the spectral plotting capability of matador. When provided with a seed, or seeds, several files will be checked:

• <seed>.bands: CASTEP bandstructure expected, not DOS,

• <seed>.adaptive.dat: OptaDOS total DOS,

• <seed>.pdos.dat: OptaDOS pDOS,

• <seed>.pdis.dat: OptaDOS projected dispersion,

or, if the “phonons” flag is passed, or if a <seed>.phonon file is detected,

• <seed>.phonon: CASTEP phonon dispersion curves expected,

• <seed>.phonon_dos: CASTEP phonon DOS.

This function will then automatically choose what to plot, favouring a bandstructure with “the-most-projected” DOS it can find.

Parameters:

seeds (list) – list of filenames of bands/phonon files

Keyword Arguments:

• plot_bandstructure (bool) – whether to plot bandstructure, if available

• plot_dos (bool) – whether to plot density of states, if available

• plot_pdos (bool) – whether or not to plot projected DOS, if available

• plot_pdis (bool) – whether to plot projected dispersion, if available

• dos (str) – separate seed name for pDOS/DOS data

• phonons (bool) – whether to plot phonon or electronic data

• labels (list) – list of strings for legend labels for multiple bandstructures

• gap (bool) – whether to draw on the band gap

• external_efermi (float or list) – replace scraped Fermi energy with this value (eV) (can be specified per spin channel).

• highlight_bands (list) – list of integer indices, colour the bands with these indices in red

• band_colour (str) – if passed “occ”, bands will be coloured using cmap depending on whether they lie above or below the Fermi level. Otherwise, override all colour options with matplotlib-interpretable colour (e.g. hexcode or html colour name) to use for all bands (DEFAULT: ‘occ’).

• band_alpha (float) – transparency of plotted bands.

• filename (str) – filename for figure saving.

• cmap (str) – matplotlib colourmap name to use for the bands

• cmap_limits (tuple) – fraction of cmap to use (DEFAULT: (0.2, 0.8)).

• unstacked_pdos (bool) – whether to plot projected DOS as stack or overlapping.

• spin_only (str) – either ‘up’ or ‘down’ to only plot one spin channel.

• preserve_kspace_distance (bool) – whether to preserve distances in reciprocal space when linearising the kpoint path. If False, bandstructures of different lattice parameters with the same Bravais lattice can be more easily compared. If True, bandstructures may appear rarefied or compressed in particular regions.

• pdis_interpolation_factor (float) – multiple by which to interpolate pDIS bands

• pdis_point_scale (float) – size of points in pDIS (DEFAULT: 50).

• colours (list of str) – list of matplotlib colours to override default colour cycle for projectors and otherwise.

• spin_up_colour (str) – matplotlib colour to override the spin-up DOS colour.

• spin_down_colour (str) – matplotlib colour to override the spin-up DOS colour.

• projectors_to_plot (str) – comma-separted list of projectors to plot in the PDIS or PDOS, provided as element:orbital, e.g. “K:s,K:p,P” will plot s and p orbitals for K, and all orbitals for P.

• band_reorder (bool) – try to reorder bands based on local gradients (DEFAULT: True for phonons, otherwise False).

• title (str) – optional plot title

• pdos_hide_sum (bool) – whether or not to plot the total DOS on a PDOS plot; this is to hide regions where the PDOS is negative (leading to total DOS lower than stacked PDOS) (DEFAULT: False).

matador.plotting.plot_voltage_curve(profiles: Union[List[VoltageProfile], VoltageProfile], ax=None, show: bool = False, labels: bool = False, savefig: Optional[str] = None, curve_labels: Optional[Union[str, List[str]]] = None, line_kwargs: Optional[Union[Dict, List[Dict]]] = None, shade_average_voltage: bool = False, colour_by_stoichiometry: bool = False, plot_average_voltage: bool = False, plot_max_capacity: bool = False, legend: bool = True, label_suffix: str = None, expt: Optional[str] = None, expt_label: Optional[str] = None)

Plot voltage curve calculated for phase diagram.

Parameters:

profiles (list/VoltageProfile) – list of/single voltage profile(s).

Keyword Arguments:

• ax (matplotlib.axes.Axes) – an existing axis on which to plot.

• show (bool) – whether to show plot in an X window.

• savefig (str) – filename to use to save the plot.

• curve_labels (list) – optional list of labels for the curves in the profiles list.

• line_kwargs (list or dict) – parameters to pass to the curve plotter, if a list then the line kwargs will be passed to each line individually.

• shade_average_voltage (bool) – whether to shade the region spanned from average voltage to max capacity.

• plot_average_voltage (bool) – whether to draw a guideline at the average voltage.

• plot_max_capacity (bool) – whether to draw a guideline at the maximum capacity.

• legend (bool) – whether to draw the legend.

• label_suffix (str) – A suffix to add to every label on the plot (useful when combining axes)

• colour_by_stoichiometry (bool) – whether to use mixed VESTA colours for each curve based on the starting formula of the electrode.

• expt (str) – string to a filename of a csv Q, V to add to the plot.

• expt_label (str) – label for any experimental profile passed to the plot.

matador.plotting.plot_volume_curve(hull, ax=None, show=True, legend=False, as_percentages=False, label=None, label_suffix=None, exclude_elemental=False, line_kwargs: Optional[Union[Dict, List[Dict]]] = None, colour_by_stoichiometry: bool = False, end_marker_only: bool = True, **kwargs)

Plot volume curve calculated for phase diagram.

Parameters:

hull (matador.hull.QueryConvexHull) – matador hull object.

Keyword Arguments:

• ax (matplotlib.axes.Axes) – an existing axis on which to plot.

• show (bool) – whether or not to display plot in X-window.

• legend (bool) – whether to add the legend.

• label (str/list) – Either a list of labels or a single label for the volume curves.

• label_suffix (str) – A suffix to add to every label on the plot (useful when combining axes)

• as_percentages (bool) – whether to show the expansion as a percentage.

• exclude_elemental (bool) – whether to include any elemental electrodes when considering ternary phase diagrams.

• line_kwargs (list or dict) – parameters to pass to the curve plotter, if a list then the line kwargs will be passed to each line individually.

• colour_by_stoichiometry (bool) – whether to use mixed VESTA colours for each curve based on the starting formula of the electrode.

• end_marker_only (bool) – Only place a marker on the worst volume expansion for each curve.

matador.plotting.plot_2d_hull(hull, ax=None, show=True, plot_points=True, plot_tie_line=True, plot_hull_points=True, labels=None, label_cutoff=None, colour_by_source=False, sources=None, hull_label=None, source_labels=None, title=True, plot_fname=None, show_cbar=True, colour_by_composition=False, label_offset=(1, 0.1), specific_label_offset=None, eform_limits=None, legend_kwargs=None, hull_dist_unit='meV', **kwargs)

Plot calculated hull, returning ax and fig objects for further editing.

Parameters:

hull (matador.hull.QueryConvexHull) – matador hull object.

Keyword Arguments:

• ax (matplotlib.axes.Axes) – an existing axis on which to plot,

• show (bool) – whether or not to display the plot in an X window,

• plot_points (bool) – whether or not to display off-hull structures,

• plot_hull_points (bool) – whether or not to display on-hull structures,

• labels (bool) – whether to label formulae of hull structures, also read from hull.args.

• label_cutoff (float/tuple of float) – draw labels less than or between these distances form the hull, also read from hull.args.

• specific_label_offset (dict) – A dictionary keyed by chemical formula strings containing 2-length float tuples of label offsets. A value of None for a particular formula will exclude that label from the plot.

• colour_by_source (bool) – plot and label points by their sources

• show_cbar – Whether or not to plot the hull distance colourbar.

• alpha (float) – alpha value of points when colour_by_source is True

• sources (list) – list of possible provenances to colour when colour_by_source is True (others will be grey)

• title (str/bool) – whether to include a plot title.

• png/pdf/svg (bool) – whether or not to write the plot to a file.

• plot_fname (str) – filename to write plot to, without file extension.

Returns:

matplotlib axis with plot.

Return type:

matplotlib.axes.Axes

matador.plotting.plot_ternary_hull(hull, axis=None, show=True, plot_points=True, hull_cutoff=None, fig_height=None, fig_width=None, label_cutoff=None, label_corners=True, expecting_cbar=True, labels=None, plot_fname=None, colour_points_by='hull_distance', hull_dist_unit='meV', efmap=None, sampmap=None, concmap=None, capmap=None, pathways=False, scale_override=None, label_spacing=0.05, label_offset=0.8, **kwargs)

Plot calculated ternary hull as a 2D projection.

Parameters:

hull (matador.hull.QueryConvexHull) – matador hull object.

Keyword Arguments:

• axis (matplotlib.axes.Axes) – matplotlib axis object on which to plot.

• show (bool) – whether or not to show plot in X window.

• plot_points (bool) – whether or not to plot each structure as a point.

• colour_points_by (str) – either hull_distance or concentration.

• label_cutoff (float/tuple of float) – draw labels less than or between these distances form the hull, also read from hull.args.

• expecting_cbar (bool) – whether or not to space out the plot to preserve aspect ratio if a colourbar is present.

• labels (bool) – whether or not to label on-hull structures

• label_corners (bool) – whether or not to put axis labels on corners or edges.

• label_offset (float) – Location of the top left rcorner of the labels.

• label_spacing (float) – Spacing between label list.

• hull_dist_unit (str) – either “eV” or “meV”,

• png/pdf/svg (bool) – whether or not to write the plot to a file.

• plot_fname (str) – filename to write plot to.

• efmap (bool/str) – plot heatmap of formation energy,

• sampmap (bool/str) – plot heatmap showing sampling density,

• concmap (bool/str) – colour background by concentration and VESTA colours

• capmap (bool/str) – plot heatmap showing gravimetric capacity.

• pathways (bool) – plot the pathway from the starting electrode to active ion.

Returns:

matplotlib axis with plot.

Return type:

matplotlib.axes.Axes

matador.plotting.plot_ir_spectrum(seed, bin_width=1.0, ax=None, show=True, **kwargs)

This function plots the IR/Raman spectrum found in the given .phonon file.

Parameters:

seed (str) – the filename to scrape and plot.

Keyword Arguments:

• bin_width (float) – the bin width for the IR plot.

• ax (matplotlib.axes.Axes) – an existing axis on which to plot.

• show (bool) – whether or not to display the plot in an X window

Raises:

RuntimeError – if unable to scrape IR data.

Returns:

matplotlib axis with plotted data.

Return type:

matplotlib.axes.Axes

matador.plotting.get_linear_cmap(colours, num_colours=100, list_only=False)

Create a linear colormap from a list of colours.

Parameters:

colours (list of str) – list of fractional RGB/hex values of colours

Keyword Arguments:

• num_colours (int) – number of colours in resulting cmap

• list_only (bool) – return only a list of colours

Returns:

returns list of colours if list_only is True, otherwise matplotlib.colors.LinearSegmentedColormap.

Return type:

matplotlib.colors.LinearSegmentedColormap or list

matador.plotting.plot_free_energy(model, temperatures=None, ax=None, line_kwargs=None, **kwargs)

Plot G(T) on the array of given temperatures. Default T is [0, 800].

Keyword Arguments:

• temperatures (list/np.ndarray) – list or array of temperatures to plot. If the array/list has length 2, use these as the start and endpoints with 21 plotting points.

• ax (matplotlib.pyplot.Axis) – axis object to plot onto.

matador.plotting.plot_cutoff_kpt_grid(data, figsize=None, forces=False, max_energy=None, max_force=None, legend=True, colour_by='formula', log=False, **kwargs)

Create a composite plot of cutoff energy and kpoint convergence.

Parameters:

data (dict) – dictionary of convergence data.

Keyword Arguments:

• forces (bool) – whether or not to plot forces.

• legend (bool) – whether or not to show a legend.

• max_energy (float) – max ylimit for convergence data in meV.

matador.plotting.plot_ensemble_hull(hull, data_key, ax=None, formation_energy_key='formation_enthalpy_per_atom', plot_points=False, plot_hull_points=True, alpha_scale=0.25, plot_hulls=True, **kwargs)

Plot and generate an ensemble of hulls. If axis not requested, a histogram of frequency of a particular concentration appearing on the convex hull is also generated as a second axis.

Parameters:

• hull (QueryConvexHull) – hull object created with a cursor that contains the data key for all entries in hull.cursor.

• data_key (str) – the key under which ensemble data is stored.

Keyword Arguments:

• ax (matplotlib.axes.Axes) – matplotlib axis object on which to plot.

• formation_energy_key (str) – the key under which formation energies have been stored.

• alpha_scale (float) – value by which to scale transparency of hulls.

• plot_points (bool) – whether to plot the hull points for each hull in the ensemble.

• plot_hulls (bool) – whether to plot the hull tie-lines for each hull in the ensemble.

• voltages (bool) – compute average voltage and heatmaps.

matador.plotting.plot_temperature_hull(hull, cmap='plasma', cmap_limits=(0.2, 0.8), ax=None, formation_energy_key='formation_free_energy_per_atom', plot_points=False, show_cbar=True, plot_hull_points=True, alpha_scale=1, lw_scale=1, plot_hulls=True, plot_fname=None, **kwargs)

Plot and generate an ensemble of hulls. If axis not requested, a histogram of frequency of a particular concentration appearing on the convex hull is also generated as a second axis.

Parameters:

hull (QueryConvexHull) – hull object created with a cursor that contains the data key for all entries in hull.cursor.

Keyword Arguments:

• ax (matplotlib.axes.Axes) – matplotlib axis object on which to plot.

• formation_energy_key (str) – the key under which formation energies have been stored.

• alpha_scale (float) – value by which to scale transparency of hulls.

• plot_points (bool) – whether to plot the hull points for each hull in the ensemble.

• plot_hulls (bool) – whether to plot the hull tie-lines for each hull in the ensemble.

• voltages (bool) – compute average voltage and heatmaps.

matador.plotting.plot_pdf(pdfs, labels=None, r_min=None, r_max=None, offset=1.2, text_offset=(0.0, 0.0), legend=False, annotate=True, figsize=None, ax=None, projected=False, colour_labels=True, **kwargs)

Plot PDFs.

Parameters:

pdfs (list of matador.fingerprints.pdf.PDF or matador.crystal.Crystal or dict) – the PDFs to plot, as a list of PDF or Crystal objects, or a matador document.

Keyword Arguments:

• labels (list of str) – labels to add to the PDF plot.

• offset (float) – amount by which to separate the PDFs in the plot. A value of 1 will separate by the maximum intensity across the PDFs. Default is 1.5.

• text_offset (tuple of float) – two float values to move annotations around relative to the base of their corresponding PDF, in units of (Angstrom, max_gr).

• r_max (float) – the radius to plot out to. Default is the minmax(radius across all PDFs).

• annotate (bool) – whether or not to apply the PDF labels as an annotation.

• legend (bool) – whether or not to apply the PDF labels as a legend.

• figsize (tuple of float) – matplotlib figure size. Default scales with number of PDFs.

• ax (matplotlib.Axis) – optional axis object to plot on.

• projected (list(str)) – if provided or True, will plot the PDFs projected onto the given keys.

• colour_labels (bool) – whether to colour the labels based on the PDF’s colour.

Returns:

axis object which can be modified further.

Return type:

matplotlib.pyplot.Axes

matador.plotting.plot_projected_pdf(*args, **kwargs)

DEPRECATED

matador.plotting.plot_diff_overlap(pdf_overlap)

Simple plot for comparing two PDFs.

Parameters:

• pdf_overlap (matador.fingerprints.pdf.PDFOverlap) – the

• plot. (overlap object to) –

matador.plotting.plot_magres(magres: Union[List[Crystal], Crystal], species: str, magres_key: str = 'chemical_shielding_iso', xlabel: str = None, broadening_width: float = 1, text_offset: float = 0.2, ax=None, figsize: Tuple[float, float] = None, show: bool = False, savefig: Optional[str] = None, signal_labels: Optional[Union[str, List[str]]] = None, signal_limits: Tuple[float, float] = None, line_kwargs: Optional[Union[Dict, List[Dict]]] = None, invert_xaxis: bool = True, species_label: Optional[str] = None, label_fontsize: int = None)

Plot magnetic resonance data for a set of crystals.

Parameters:

• magres (Union[Crystal, List[Crystal]]) – list of Crystal containing magres data.

• species (str | Tuple[str, int]) – the species to plot the shifts of, either as a simple element symbol, or an element and isotope tuple used for labelling, e.g., “P” or (“P”, 31).

Keyword Arguments:

• ax (matplotlib.axes.Axes) – an existing axis on which to plot.

• magres_key (str) – the data key for which the magres site data is stored under.

• show (bool) – whether to show plot in an X window.

• figsize (Tuple[float]) – overrides the default size for the matplotlib figure.

• broadening_width (float) – the Lorentzian width to apply to the shifts.

• xlabel (str) – a custom label for the x-axis.

• savefig (str) – filename to use to save the plot.

• signal_labels (list) – optional list of labels for the curves in the magres list.

• signal_limits (Tuple[float]) – values at which to clip the magres signals. Defaults to the maximum and minimum shifts across all passed structures.

• line_kwargs (list or dict) – parameters to pass to the curve plotter, if a list then the line kwargs will be passed to each line individually.

• label_fontsize (int) – font size override for the labels.

matador.plotting.plot_projected_diff_overlap(pdf_overlap)

Simple plot for comparing two PDFs.

Parameters:

pdf_overlap (matador.fingerprints.pdf.PDFOverlap) – the overlap object to plot.

matador.plotting.plot_pxrd(pxrds, two_theta_range=None, text_loc='right', rug=False, rug_height=0.05, rug_offset=0.04, offset=None, ax=None, labels=None, figsize=None, text_offset=0.1, colour_labels=True, filename=None, **kwargs)

Plot PXRD or PXRDs.

Parameters:

pxrds (list or matador.fingerprints.pxrd.PXRD) – the PXRD or list of PXRDs to plot.

Keyword Arguments:

• two_theta_range (tuple) – plotting limits for 2theta

• rug (bool) – whether to provide a rug plot of all peaks.

• rug_height (float) – size of rug ticks.

• rug_offset (float) – offset of rug ticks.

• offset (float) – extra space added between patterns (as fraction of max intensity). Default 0.1.

• labels (list of str) – list of labels to plot alongside pattern.

• figsize (tuple) – specify a figure size, the default scales with the number of PXRDs to be plotted.

• ax (matplotlib.Axis) – optional axis object to plot on.

• text_offset (float) – amount by which to offset the labels.

• text_loc (str) – location of text, either ‘left’ or ‘right’.

• filename (str) – optional filename for saving.

matador.plotting.set_style(style=None)

Set the matplotlib style for all future plots, manually. This will conflict with the context manager used by the plotting_function wrapper.

Submodules

matador.plotting.battery_plotting module

This submodule contains functions to plot battery-relevant curves, such as voltages and volume expansions.

matador.plotting.battery_plotting.plot_voltage_curve(profiles: Union[List[VoltageProfile], VoltageProfile], ax=None, show: bool = False, labels: bool = False, savefig: Optional[str] = None, curve_labels: Optional[Union[str, List[str]]] = None, line_kwargs: Optional[Union[Dict, List[Dict]]] = None, shade_average_voltage: bool = False, colour_by_stoichiometry: bool = False, plot_average_voltage: bool = False, plot_max_capacity: bool = False, legend: bool = True, label_suffix: str = None, expt: Optional[str] = None, expt_label: Optional[str] = None)

Plot voltage curve calculated for phase diagram.

Parameters:

profiles (list/VoltageProfile) – list of/single voltage profile(s).

Keyword Arguments:

• ax (matplotlib.axes.Axes) – an existing axis on which to plot.

• show (bool) – whether to show plot in an X window.

• savefig (str) – filename to use to save the plot.

• curve_labels (list) – optional list of labels for the curves in the profiles list.

• line_kwargs (list or dict) – parameters to pass to the curve plotter, if a list then the line kwargs will be passed to each line individually.

• shade_average_voltage (bool) – whether to shade the region spanned from average voltage to max capacity.

• plot_average_voltage (bool) – whether to draw a guideline at the average voltage.

• plot_max_capacity (bool) – whether to draw a guideline at the maximum capacity.

• legend (bool) – whether to draw the legend.

• label_suffix (str) – A suffix to add to every label on the plot (useful when combining axes)

• colour_by_stoichiometry (bool) – whether to use mixed VESTA colours for each curve based on the starting formula of the electrode.

• expt (str) – string to a filename of a csv Q, V to add to the plot.

• expt_label (str) – label for any experimental profile passed to the plot.

matador.plotting.battery_plotting.plot_volume_curve(hull, ax=None, show=True, legend=False, as_percentages=False, label=None, label_suffix=None, exclude_elemental=False, line_kwargs: Optional[Union[Dict, List[Dict]]] = None, colour_by_stoichiometry: bool = False, end_marker_only: bool = True, **kwargs)

Plot volume curve calculated for phase diagram.

Parameters:

hull (matador.hull.QueryConvexHull) – matador hull object.

Keyword Arguments:

• ax (matplotlib.axes.Axes) – an existing axis on which to plot.

• show (bool) – whether or not to display plot in X-window.

• legend (bool) – whether to add the legend.

• label (str/list) – Either a list of labels or a single label for the volume curves.

• label_suffix (str) – A suffix to add to every label on the plot (useful when combining axes)

• as_percentages (bool) – whether to show the expansion as a percentage.

• exclude_elemental (bool) – whether to include any elemental electrodes when considering ternary phase diagrams.

• line_kwargs (list or dict) – parameters to pass to the curve plotter, if a list then the line kwargs will be passed to each line individually.

• colour_by_stoichiometry (bool) – whether to use mixed VESTA colours for each curve based on the starting formula of the electrode.

• end_marker_only (bool) – Only place a marker on the worst volume expansion for each curve.

matador.plotting.convergence_plotting module

This submodule contains functions to plot convergence test data for a series of calculations.

matador.plotting.convergence_plotting.plot_cutoff_kpt_grid(data, figsize=None, forces=False, max_energy=None, max_force=None, legend=True, colour_by='formula', log=False, **kwargs)

Create a composite plot of cutoff energy and kpoint convergence.

Parameters:

data (dict) – dictionary of convergence data.

Keyword Arguments:

• forces (bool) – whether or not to plot forces.

• legend (bool) – whether or not to show a legend.

• max_energy (float) – max ylimit for convergence data in meV.

matador.plotting.hull_plotting module

This submodule contains functions to plot convex hulls and phase diagrams generally.

matador.plotting.hull_plotting.plot_2d_hull(hull, ax=None, show=True, plot_points=True, plot_tie_line=True, plot_hull_points=True, labels=None, label_cutoff=None, colour_by_source=False, sources=None, hull_label=None, source_labels=None, title=True, plot_fname=None, show_cbar=True, colour_by_composition=False, label_offset=(1, 0.1), specific_label_offset=None, eform_limits=None, legend_kwargs=None, hull_dist_unit='meV', **kwargs)

Plot calculated hull, returning ax and fig objects for further editing.

Parameters:

hull (matador.hull.QueryConvexHull) – matador hull object.

Keyword Arguments:

• ax (matplotlib.axes.Axes) – an existing axis on which to plot,

• show (bool) – whether or not to display the plot in an X window,

• plot_points (bool) – whether or not to display off-hull structures,

• plot_hull_points (bool) – whether or not to display on-hull structures,

• labels (bool) – whether to label formulae of hull structures, also read from hull.args.

• label_cutoff (float/tuple of float) – draw labels less than or between these distances form the hull, also read from hull.args.

• specific_label_offset (dict) – A dictionary keyed by chemical formula strings containing 2-length float tuples of label offsets. A value of None for a particular formula will exclude that label from the plot.

• colour_by_source (bool) – plot and label points by their sources

• show_cbar – Whether or not to plot the hull distance colourbar.

• alpha (float) – alpha value of points when colour_by_source is True

• sources (list) – list of possible provenances to colour when colour_by_source is True (others will be grey)

• title (str/bool) – whether to include a plot title.

• png/pdf/svg (bool) – whether or not to write the plot to a file.

• plot_fname (str) – filename to write plot to, without file extension.

Returns:

matplotlib axis with plot.

Return type:

matplotlib.axes.Axes

matador.plotting.hull_plotting.plot_ternary_hull(hull, axis=None, show=True, plot_points=True, hull_cutoff=None, fig_height=None, fig_width=None, label_cutoff=None, label_corners=True, expecting_cbar=True, labels=None, plot_fname=None, colour_points_by='hull_distance', hull_dist_unit='meV', efmap=None, sampmap=None, concmap=None, capmap=None, pathways=False, scale_override=None, label_spacing=0.05, label_offset=0.8, **kwargs)

Plot calculated ternary hull as a 2D projection.

Parameters:

hull (matador.hull.QueryConvexHull) – matador hull object.

Keyword Arguments:

• axis (matplotlib.axes.Axes) – matplotlib axis object on which to plot.

• show (bool) – whether or not to show plot in X window.

• plot_points (bool) – whether or not to plot each structure as a point.

• colour_points_by (str) – either hull_distance or concentration.

• label_cutoff (float/tuple of float) – draw labels less than or between these distances form the hull, also read from hull.args.

• expecting_cbar (bool) – whether or not to space out the plot to preserve aspect ratio if a colourbar is present.

• labels (bool) – whether or not to label on-hull structures

• label_corners (bool) – whether or not to put axis labels on corners or edges.

• label_offset (float) – Location of the top left rcorner of the labels.

• label_spacing (float) – Spacing between label list.

• hull_dist_unit (str) – either “eV” or “meV”,

• png/pdf/svg (bool) – whether or not to write the plot to a file.

• plot_fname (str) – filename to write plot to.

• efmap (bool/str) – plot heatmap of formation energy,

• sampmap (bool/str) – plot heatmap showing sampling density,

• concmap (bool/str) – colour background by concentration and VESTA colours

• capmap (bool/str) – plot heatmap showing gravimetric capacity.

• pathways (bool) – plot the pathway from the starting electrode to active ion.

Returns:

matplotlib axis with plot.

Return type:

matplotlib.axes.Axes

matador.plotting.hull_plotting.plot_ensemble_hull(hull, data_key, ax=None, formation_energy_key='formation_enthalpy_per_atom', plot_points=False, plot_hull_points=True, alpha_scale=0.25, plot_hulls=True, **kwargs)

Plot and generate an ensemble of hulls. If axis not requested, a histogram of frequency of a particular concentration appearing on the convex hull is also generated as a second axis.

Parameters:

• hull (QueryConvexHull) – hull object created with a cursor that contains the data key for all entries in hull.cursor.

• data_key (str) – the key under which ensemble data is stored.

Keyword Arguments:

• ax (matplotlib.axes.Axes) – matplotlib axis object on which to plot.

• formation_energy_key (str) – the key under which formation energies have been stored.

• alpha_scale (float) – value by which to scale transparency of hulls.

• plot_points (bool) – whether to plot the hull points for each hull in the ensemble.

• plot_hulls (bool) – whether to plot the hull tie-lines for each hull in the ensemble.

• voltages (bool) – compute average voltage and heatmaps.

matador.plotting.hull_plotting.plot_temperature_hull(hull, cmap='plasma', cmap_limits=(0.2, 0.8), ax=None, formation_energy_key='formation_free_energy_per_atom', plot_points=False, show_cbar=True, plot_hull_points=True, alpha_scale=1, lw_scale=1, plot_hulls=True, plot_fname=None, **kwargs)

Plot and generate an ensemble of hulls. If axis not requested, a histogram of frequency of a particular concentration appearing on the convex hull is also generated as a second axis.

Parameters:

hull (QueryConvexHull) – hull object created with a cursor that contains the data key for all entries in hull.cursor.

Keyword Arguments:

• ax (matplotlib.axes.Axes) – matplotlib axis object on which to plot.

• formation_energy_key (str) – the key under which formation energies have been stored.

• alpha_scale (float) – value by which to scale transparency of hulls.

• plot_points (bool) – whether to plot the hull points for each hull in the ensemble.

• plot_hulls (bool) – whether to plot the hull tie-lines for each hull in the ensemble.

• voltages (bool) – compute average voltage and heatmaps.

matador.plotting.ir_plotting module

This submodule implements functions useful for plotting the results of infrared and Raman spectroscopy calculations.

matador.plotting.ir_plotting.plot_ir_spectrum(seed, bin_width=1.0, ax=None, show=True, **kwargs)

This function plots the IR/Raman spectrum found in the given .phonon file.

Parameters:

seed (str) – the filename to scrape and plot.

Keyword Arguments:

• bin_width (float) – the bin width for the IR plot.

• ax (matplotlib.axes.Axes) – an existing axis on which to plot.

• show (bool) – whether or not to display the plot in an X window

Raises:

RuntimeError – if unable to scrape IR data.

Returns:

matplotlib axis with plotted data.

Return type:

matplotlib.axes.Axes

matador.plotting.magres_plotting module

This submodule contains functions to plot chemical shifts and chemical shieldings from NMR calculations.

matador.plotting.magres_plotting.plot_magres(magres: Union[List[Crystal], Crystal], species: str, magres_key: str = 'chemical_shielding_iso', xlabel: str = None, broadening_width: float = 1, text_offset: float = 0.2, ax=None, figsize: Tuple[float, float] = None, show: bool = False, savefig: Optional[str] = None, signal_labels: Optional[Union[str, List[str]]] = None, signal_limits: Tuple[float, float] = None, line_kwargs: Optional[Union[Dict, List[Dict]]] = None, invert_xaxis: bool = True, species_label: Optional[str] = None, label_fontsize: int = None)

Plot magnetic resonance data for a set of crystals.

Parameters:

• magres (Union[Crystal, List[Crystal]]) – list of Crystal containing magres data.

• species (str | Tuple[str, int]) – the species to plot the shifts of, either as a simple element symbol, or an element and isotope tuple used for labelling, e.g., “P” or (“P”, 31).

Keyword Arguments:

• ax (matplotlib.axes.Axes) – an existing axis on which to plot.

• magres_key (str) – the data key for which the magres site data is stored under.

• show (bool) – whether to show plot in an X window.

• figsize (Tuple[float]) – overrides the default size for the matplotlib figure.

• broadening_width (float) – the Lorentzian width to apply to the shifts.

• xlabel (str) – a custom label for the x-axis.

• savefig (str) – filename to use to save the plot.

• signal_labels (list) – optional list of labels for the curves in the magres list.

• signal_limits (Tuple[float]) – values at which to clip the magres signals. Defaults to the maximum and minimum shifts across all passed structures.

• line_kwargs (list or dict) – parameters to pass to the curve plotter, if a list then the line kwargs will be passed to each line individually.

• label_fontsize (int) – font size override for the labels.

matador.plotting.misc_plotting module

matador.plotting.misc_plotting.plot_relative_diffs(structure_map, structure_comparator, categories, field, ax=None, x_field='concentration', category_labels=None, field_label=None, x_field_label=None, colour_by_index=1, cbar_label=None, diff_type='rel', invert=False, colour_by=None, figsize=None, colourbar=True)

Plot relative and absolute differences between fields for a set of structures computed at different levels of theory/accuracy.

matador.plotting.pdf_plotting module

This file implements plotting routines specifically for the PDF and PDFOverlap objects defined in the matador.fingerprints.pdf module.

matador.plotting.pdf_plotting.plot_pdf(pdfs, labels=None, r_min=None, r_max=None, offset=1.2, text_offset=(0.0, 0.0), legend=False, annotate=True, figsize=None, ax=None, projected=False, colour_labels=True, **kwargs)

Plot PDFs.

Parameters:

pdfs (list of matador.fingerprints.pdf.PDF or matador.crystal.Crystal or dict) – the PDFs to plot, as a list of PDF or Crystal objects, or a matador document.

Keyword Arguments:

• labels (list of str) – labels to add to the PDF plot.

• offset (float) – amount by which to separate the PDFs in the plot. A value of 1 will separate by the maximum intensity across the PDFs. Default is 1.5.

• text_offset (tuple of float) – two float values to move annotations around relative to the base of their corresponding PDF, in units of (Angstrom, max_gr).

• r_max (float) – the radius to plot out to. Default is the minmax(radius across all PDFs).

• annotate (bool) – whether or not to apply the PDF labels as an annotation.

• legend (bool) – whether or not to apply the PDF labels as a legend.

• figsize (tuple of float) – matplotlib figure size. Default scales with number of PDFs.

• ax (matplotlib.Axis) – optional axis object to plot on.

• projected (list(str)) – if provided or True, will plot the PDFs projected onto the given keys.

• colour_labels (bool) – whether to colour the labels based on the PDF’s colour.

Returns:

axis object which can be modified further.

Return type:

matplotlib.pyplot.Axes

matador.plotting.pdf_plotting.plot_projected_pdf(*args, **kwargs)

DEPRECATED

matador.plotting.pdf_plotting.plot_diff_overlap(pdf_overlap)

Simple plot for comparing two PDFs.

Parameters:

• pdf_overlap (matador.fingerprints.pdf.PDFOverlap) – the

• plot. (overlap object to) –

matador.plotting.pdf_plotting.plot_projected_diff_overlap(pdf_overlap)

Simple plot for comparing two PDFs.

Parameters:

pdf_overlap (matador.fingerprints.pdf.PDFOverlap) – the overlap object to plot.

matador.plotting.plotting module

This submodule implements some useful auxiliary routines for use in the other plotting functions, and some generic routines for plotting simple (x, y) line data (e.g. pair distribution functions), or lists of (x, y) data against some third parameter (e.g. powder x-ray spectrum vs voltage).

matador.plotting.plotting.set_style(style=None)

Set the matplotlib style for all future plots, manually. This will conflict with the context manager used by the plotting_function wrapper.

matador.plotting.plotting.plotting_function(function)

Wrapper for plotting functions to safely fail on X-forwarding errors and handle the plot style context manager.

matador.plotting.plotting.get_linear_cmap(colours, num_colours=100, list_only=False)

Create a linear colormap from a list of colours.

Parameters:

colours (list of str) – list of fractional RGB/hex values of colours

Keyword Arguments:

• num_colours (int) – number of colours in resulting cmap

• list_only (bool) – return only a list of colours

Returns:

returns list of colours if list_only is True, otherwise matplotlib.colors.LinearSegmentedColormap.

Return type:

matplotlib.colors.LinearSegmentedColormap or list

class matador.plotting.plotting.XYvsZPlot(xys, zs, y_scale=1.0, **kwargs)

Bases: object

This class wraps plotting (x, y) lines against a third variable.

Construct plot from data.

Parameters:

• xys (list of list or numpy.ndarray) – list or array of data to be plotted. For N lines of M samples, this can be provided as an (N, M, 2) or (2, M, N) array, or corresponding list/sublist format.

• zs (list) – third parameter to plot lines against. The y-values are rescaled relative to the maximum across all lines so that no lines overlap (this can be overridden using offset_factor keyword).

Keyword Arguments:

y_scale (float) – controls the scale factor between the arbitrary y-scale and the z-scale.

property y_scale

get_plot()

plot(*args, **kwargs)

Actually plot the data and optionally save it.

matador.plotting.pxrd_plotting module

This file implements plotting routines specifically for the PXRD objects defined in the matador.fingerprints.pxrd module.

matador.plotting.pxrd_plotting.plot_pxrd(pxrds, two_theta_range=None, text_loc='right', rug=False, rug_height=0.05, rug_offset=0.04, offset=None, ax=None, labels=None, figsize=None, text_offset=0.1, colour_labels=True, filename=None, **kwargs)

Plot PXRD or PXRDs.

Parameters:

pxrds (list or matador.fingerprints.pxrd.PXRD) – the PXRD or list of PXRDs to plot.

Keyword Arguments:

• two_theta_range (tuple) – plotting limits for 2theta

• rug (bool) – whether to provide a rug plot of all peaks.

• rug_height (float) – size of rug ticks.

• rug_offset (float) – offset of rug ticks.

• offset (float) – extra space added between patterns (as fraction of max intensity). Default 0.1.

• labels (list of str) – list of labels to plot alongside pattern.

• figsize (tuple) – specify a figure size, the default scales with the number of PXRDs to be plotted.

• ax (matplotlib.Axis) – optional axis object to plot on.

• text_offset (float) – amount by which to offset the labels.

• text_loc (str) – location of text, either ‘left’ or ‘right’.

• filename (str) – optional filename for saving.

matador.plotting.spectral_plotting module

This submodule contains functions to plot densities of states and bandstructures for electronic and vibrational calculations.

matador.plotting.spectral_plotting.plot_spectral(seeds, **options)

This function wraps all of the spectral plotting capability of matador. When provided with a seed, or seeds, several files will be checked:

• <seed>.bands: CASTEP bandstructure expected, not DOS,

• <seed>.adaptive.dat: OptaDOS total DOS,

• <seed>.pdos.dat: OptaDOS pDOS,

• <seed>.pdis.dat: OptaDOS projected dispersion,

or, if the “phonons” flag is passed, or if a <seed>.phonon file is detected,

• <seed>.phonon: CASTEP phonon dispersion curves expected,

• <seed>.phonon_dos: CASTEP phonon DOS.

This function will then automatically choose what to plot, favouring a bandstructure with “the-most-projected” DOS it can find.

Parameters:

seeds (list) – list of filenames of bands/phonon files

Keyword Arguments:

• plot_bandstructure (bool) – whether to plot bandstructure, if available

• plot_dos (bool) – whether to plot density of states, if available

• plot_pdos (bool) – whether or not to plot projected DOS, if available

• plot_pdis (bool) – whether to plot projected dispersion, if available

• dos (str) – separate seed name for pDOS/DOS data

• phonons (bool) – whether to plot phonon or electronic data

• labels (list) – list of strings for legend labels for multiple bandstructures

• gap (bool) – whether to draw on the band gap

• external_efermi (float or list) – replace scraped Fermi energy with this value (eV) (can be specified per spin channel).

• highlight_bands (list) – list of integer indices, colour the bands with these indices in red

• band_colour (str) – if passed “occ”, bands will be coloured using cmap depending on whether they lie above or below the Fermi level. Otherwise, override all colour options with matplotlib-interpretable colour (e.g. hexcode or html colour name) to use for all bands (DEFAULT: ‘occ’).

• band_alpha (float) – transparency of plotted bands.

• filename (str) – filename for figure saving.

• cmap (str) – matplotlib colourmap name to use for the bands

• cmap_limits (tuple) – fraction of cmap to use (DEFAULT: (0.2, 0.8)).

• unstacked_pdos (bool) – whether to plot projected DOS as stack or overlapping.

• spin_only (str) – either ‘up’ or ‘down’ to only plot one spin channel.

• preserve_kspace_distance (bool) – whether to preserve distances in reciprocal space when linearising the kpoint path. If False, bandstructures of different lattice parameters with the same Bravais lattice can be more easily compared. If True, bandstructures may appear rarefied or compressed in particular regions.

• pdis_interpolation_factor (float) – multiple by which to interpolate pDIS bands

• pdis_point_scale (float) – size of points in pDIS (DEFAULT: 50).

• colours (list of str) – list of matplotlib colours to override default colour cycle for projectors and otherwise.

• spin_up_colour (str) – matplotlib colour to override the spin-up DOS colour.

• spin_down_colour (str) – matplotlib colour to override the spin-up DOS colour.

• projectors_to_plot (str) – comma-separted list of projectors to plot in the PDIS or PDOS, provided as element:orbital, e.g. “K:s,K:p,P” will plot s and p orbitals for K, and all orbitals for P.

• band_reorder (bool) – try to reorder bands based on local gradients (DEFAULT: True for phonons, otherwise False).

• title (str) – optional plot title

• pdos_hide_sum (bool) – whether or not to plot the total DOS on a PDOS plot; this is to hide regions where the PDOS is negative (leading to total DOS lower than stacked PDOS) (DEFAULT: False).

matador.plotting.spectral_plotting.dos_plot(seeds, ax_dos, options, bbox_extra_artists=None)

Plot a density of states on the given axis. Will detect pDOS and spin-dependent DOS data automatically.

Parameters:

• seeds (list) – the seednames of the data to plot.

• ax_dos (matplotlib.Axes) – the axis to plot on.

• options (dict) – any plotting keywords (from e.g. dispersion script).

• bbox_extra_artists (list) – a list to which to append legends.

Returns:

the axis that was plotted on.

Return type:

matplotlib.Axes

matador.plotting.spectral_plotting.dispersion_plot(seeds, ax_dispersion, options, bbox_extra_artists=None)

Plot a dispersion/bandstructure on the given axis. Will detect and projected dispersion data automatically.

Parameters:

• seeds (str or list) – the seedname(s) of the data to plot.

• ax_dispersion (matplotlib.Axes) – the axis to plot on.

• options (dict) – any plotting keywords (from e.g. dispersion script).

• bbox_extra_artists (list) – a list to which to append legends.

Returns:

the axis that was plotted on.

Return type:

matplotlib.Axes

matador.plotting.temperature_plotting module

This submodule contains functions to plot temperature-dependent quantities for particular structures, e.g. free energies and heat capacities.

matador.plotting.temperature_plotting.plot_free_energy(model, temperatures=None, ax=None, line_kwargs=None, **kwargs)

Plot G(T) on the array of given temperatures. Default T is [0, 800].

Keyword Arguments:

• temperatures (list/np.ndarray) – list or array of temperatures to plot. If the array/list has length 2, use these as the start and endpoints with 21 plotting points.

• ax (matplotlib.pyplot.Axis) – axis object to plot onto.