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)[source]¶
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[matador.battery.electrode.VoltageProfile], matador.battery.electrode.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, expt: Optional[str] = None, expt_label: Optional[str] = None)[source]¶
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.
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, **kwargs)[source]¶
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.
as_percentages (bool) – whether to show the expansion as a percentage.
- 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, label_offset=(1.15, 0.05), eform_limits=None, legend_kwargs=None, **kwargs)[source]¶
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
offloat
) – draw labels less than or between these distances form the hull, also read from hull.args.colour_by_source (bool) – plot and label points by their sources
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
- matador.plotting.plot_ternary_hull(hull, axis=None, show=True, plot_points=True, hull_cutoff=None, fig_height=None, label_cutoff=None, label_corners=True, expecting_cbar=True, labels=None, plot_fname=None, hull_dist_unit='meV', efmap=None, sampmap=None, capmap=None, pathways=False, **kwargs)[source]¶
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.
label_cutoff (float/
tuple
offloat
) – 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.
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) – plot heatmap of formation energy,
sampmap (bool) – plot heatmap showing sampling density,
capmap (bool) – plot heatmap showing gravimetric capacity.
pathways (bool) – plot the pathway from the starting electrode to active ion.
- Returns
matplotlib axis with plot.
- Return type
- matador.plotting.plot_ir_spectrum(seed, bin_width=1.0, ax=None, show=True, **kwargs)[source]¶
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
- matador.plotting.get_linear_cmap(colours, num_colours=100, list_only=False)[source]¶
Create a linear colormap from a list of colours.
- Parameters
colours (
list
ofstr
) – list of fractional RGB/hex values of colours- Keyword Arguments
- Returns
returns list of colours if list_only is True, otherwise
matplotlib.colors.LinearSegmentedColormap
.- Return type
- matador.plotting.plot_free_energy(model, temperatures=None, ax=None, line_kwargs=None, **kwargs)[source]¶
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=50, max_force=None, legend=True, colour_by='formula', **kwargs)[source]¶
Create a composite plot of cutoff energy and kpoint convergence.
- 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, voltages=False, show=True, plot_fname=None, **kwargs)[source]¶
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, voltages=False, show=True, plot_fname=None, **kwargs)[source]¶
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, filename=None, **kwargs)[source]¶
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.
- Returns
axis object which can be modified further.
- Return type
matplotlib.pyplot.Axes
- matador.plotting.plot_projected_pdf(pdf, keys=None, other_pdfs=None, vlines=None)[source]¶
Plot projected PDFs.
- Parameters
pdf (matador.fingerprints.pdf.PDF) – the main PDF to plot.
- Keyword Arguments
keys (list) – plot only a subset of projections, e.g. [(‘K’, )].
other_pdfs (list of PDF) – other PDFs to plot.
vlines (list of float) – plot vertical lines at these points.
- matador.plotting.plot_diff_overlap(pdf_overlap)[source]¶
Simple plot for comparing two PDFs.
- Parameters
pdf_overlap (matador.fingerprints.pdf.PDFOverlap) – the
object to plot. (overlap) –
- matador.plotting.plot_magres(magres: Union[List[matador.crystal.crystal.Crystal], matador.crystal.crystal.Crystal], species: str, magres_key: str = 'chemical_shielding_iso', xlabel: str = None, broadening_width: float = 1, text_offset: float = 0.1, ax=None, figsize: Tuple[float] = None, show: bool = False, savefig: Optional[str] = None, signal_labels: Optional[Union[str, List[str]]] = None, signal_limits: Tuple[float] = None, line_kwargs: Optional[Union[Dict, List[Dict]]] = None)[source]¶
Plot voltage curve calculated for phase diagram.
- Parameters
- 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.
- matador.plotting.plot_projected_diff_overlap(pdf_overlap)[source]¶
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, rug=False, rug_height=0.05, rug_offset=0.04, offset=None, ax=None, labels=None, figsize=None, text_offset=0.1, filename=None, **kwargs)[source]¶
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.
filename (str) – optional filename for saving.
- matador.plotting.set_style(style=None)[source]¶
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[matador.battery.electrode.VoltageProfile], matador.battery.electrode.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, expt: Optional[str] = None, expt_label: Optional[str] = None)[source]¶
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.
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, **kwargs)[source]¶
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.
as_percentages (bool) – whether to show the expansion as a percentage.
matador.plotting.convergence_plotting module¶
This submodule contains functions to plot convergence test data for a series of calculations.
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, label_offset=(1.15, 0.05), eform_limits=None, legend_kwargs=None, **kwargs)[source]¶
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
offloat
) – draw labels less than or between these distances form the hull, also read from hull.args.colour_by_source (bool) – plot and label points by their sources
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
- matador.plotting.hull_plotting.plot_ternary_hull(hull, axis=None, show=True, plot_points=True, hull_cutoff=None, fig_height=None, label_cutoff=None, label_corners=True, expecting_cbar=True, labels=None, plot_fname=None, hull_dist_unit='meV', efmap=None, sampmap=None, capmap=None, pathways=False, **kwargs)[source]¶
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.
label_cutoff (float/
tuple
offloat
) – 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.
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) – plot heatmap of formation energy,
sampmap (bool) – plot heatmap showing sampling density,
capmap (bool) – plot heatmap showing gravimetric capacity.
pathways (bool) – plot the pathway from the starting electrode to active ion.
- Returns
matplotlib axis with plot.
- Return type
- 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, voltages=False, show=True, plot_fname=None, **kwargs)[source]¶
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, voltages=False, show=True, plot_fname=None, **kwargs)[source]¶
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)[source]¶
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
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[matador.crystal.crystal.Crystal], matador.crystal.crystal.Crystal], species: str, magres_key: str = 'chemical_shielding_iso', xlabel: str = None, broadening_width: float = 1, text_offset: float = 0.1, ax=None, figsize: Tuple[float] = None, show: bool = False, savefig: Optional[str] = None, signal_labels: Optional[Union[str, List[str]]] = None, signal_limits: Tuple[float] = None, line_kwargs: Optional[Union[Dict, List[Dict]]] = None)[source]¶
Plot voltage curve calculated for phase diagram.
- Parameters
- 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.
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, filename=None, **kwargs)[source]¶
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.
- Returns
axis object which can be modified further.
- Return type
matplotlib.pyplot.Axes
- matador.plotting.pdf_plotting.plot_projected_pdf(pdf, keys=None, other_pdfs=None, vlines=None)[source]¶
Plot projected PDFs.
- Parameters
pdf (matador.fingerprints.pdf.PDF) – the main PDF to plot.
- Keyword Arguments
keys (list) – plot only a subset of projections, e.g. [(‘K’, )].
other_pdfs (list of PDF) – other PDFs to plot.
vlines (list of float) – plot vertical lines at these points.
- matador.plotting.pdf_plotting.plot_diff_overlap(pdf_overlap)[source]¶
Simple plot for comparing two PDFs.
- Parameters
pdf_overlap (matador.fingerprints.pdf.PDFOverlap) – the
object to plot. (overlap) –
- matador.plotting.pdf_plotting.plot_projected_diff_overlap(pdf_overlap)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Create a linear colormap from a list of colours.
- Parameters
colours (
list
ofstr
) – list of fractional RGB/hex values of colours- Keyword Arguments
- Returns
returns list of colours if list_only is True, otherwise
matplotlib.colors.LinearSegmentedColormap
.- Return type
- class matador.plotting.plotting.XYvsZPlot(xys, zs, y_scale=1.0, **kwargs)[source]¶
Bases:
object
This class wraps plotting (x, y) lines against a third variable.
Construct plot from data.
- Parameters
xys (
list
oflist
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¶
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, rug=False, rug_height=0.05, rug_offset=0.04, offset=None, ax=None, labels=None, figsize=None, text_offset=0.1, filename=None, **kwargs)[source]¶
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.
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)[source]¶
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)[source]¶
Plot a density of states on the given axis. Will detect pDOS and spin-dependent DOS data automatically.
- Parameters
- 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)[source]¶
Plot a dispersion/bandstructure on the given axis. Will detect and projected dispersion data automatically.
- Parameters
- 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)[source]¶
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.