Plotting

Plotting in Euphonic is contained in a separate euphonic.plot module, and most plotting functions return a matplotlib.figure.Figure, which can be tweaked, then viewed with matplotlib.figure.Figure.show()

Plotting Dispersion

Phonon dispersion can be plotted from any Euphonic object that contains q-points and frequencies. For example, from QpointPhononModes using QpointPhononModes.get_dispersion to convert the frequencies into a Spectrum1DCollection object, which is plotted with euphonic.plot.plot_1d(). Converting to Spectrum1DCollection creates a defined x-axis for the plot. Extra arguments get passed to plot_1d, for adding axis labels etc.:

from euphonic import QpointPhononModes
from euphonic.plot import plot_1d

phonons = QpointPhononModes.from_castep('quartz.phonon')
bands = phonons.get_dispersion()  # type: Spectrum1DCollection

fig = plot_1d(bands, y_label='Energy (meV)')
fig.show()

Phonon dispersion plots often include large steps between discontinuous regions in reciprocal space. In order to accommodate this, a single Spectrum1D or Spectrum1DCollection can be split into a list of spectra with the euphonic.spectra.Spectrum1D.split() method. plot_1d will happily accept this list as input, plotting each region to a series of proportionally-spaced subplots.

A compact recipe to write a band-structure plot with discontinuities could be

from euphonic import QpointFrequencies
from euphonic.plot import plot_1d

phonon_frequencies = QpointFrequencies.from_castep('quartz.phonon')

fig = plot_1d(phonon_frequencies.get_dispersion().split())
fig.savefig('quartz-dispersion.pdf')

1D Plots

1D spectra are arranged in a matplotlib Figure with euphonic.plot.plot_1d(). For multiple lines on the same axes, use Spectrum1DCollection objects. A sequence of Spectrum1D or Spectrum1DCollection objects will be interpreted as a series of axis regions:

from euphonic import Spectrum1D, Spectrum1DCollection
from euphonic.plot import plot_1d

dos = Spectrum1D.from_json_file('dos.json')
dos_broaden = Spectrum1D.from_json_file('dos_broaden.json')

dos_collection = Spectrum1DCollection.from_spectra([dos, dos_broaden])

fig = plot_1d(dos_collection, x_label='Energy (meV)', y_min=0,
              labels=['Density of states', 'Broadened'])
fig.show()

Plotting to a specific axis

This can be used to have multiple subplots in the same figure, or to plot multiple Spectrum1D objects on the same axis (for example if they have different x_data values, so using a Spectrum1DCollection is not possible). An example of plotting 2 DOS with different energy bins on the same axis:

import matplotlib.pyplot as plt
from euphonic import Spectrum1D
from euphonic.plot import plot_1d, plot_1d_to_axis

dos1 = Spectrum1D.from_json_file('dos_ebins1.json')
dos2 = Spectrum1D.from_json_file('dos_ebins2.json')

fig = plot_1d(dos1)
ax = fig.get_axes()[0]
plot_1d_to_axis(dos2, ax)
fig.show()

An example of plotting 2 DOS on different axes on the same figure:

import matplotlib.pyplot as plt
from euphonic import Spectrum1D
from euphonic.plot import plot_1d_to_axis

dos1 = Spectrum1D.from_json_file('dos_ebins1.json')
dos2 = Spectrum1D.from_json_file('dos_ebins2.json')
fig, axes = plt.subplots(1, 2)
plot_1d_to_axis(dos1, axes[0])
plot_1d_to_axis(dos2, axes[1])
fig.show()

Docstrings

plot_1d(spectra, title='', x_label='', y_label='', y_min=None, y_max=None, labels=None, **line_kwargs)

Creates a Matplotlib figure for a Spectrum1D object, or multiple Spectrum1D objects to be plotted on the same axes

Parameters

  • spectra (Union[Spectrum1D, Spectrum1DCollection, Sequence[Spectrum1D], Sequence[Spectrum1DCollection]]) –

    1D data to plot. Spectrum1D objects contain a single line, while Spectrum1DCollection is suitable for plotting multiple lines simultaneously (e.g. band structures).

    Data split across several regions should be provided as a sequence of spectrum objects:

    [Spectrum1D, Spectrum1D, ...]

    or:

    [Spectrum1DCollection, Spectrum1DCollection, ...]

    Where each segment will be plotted on a separate subplot. (This approach is mainly used to handle discontinuities in Brillouin-zone band structures, so the subplot widths will be based on the x-axis ranges.)

  • title (str) – Plot title

  • x_label (str) – X-axis label

  • y_label (str) – Y-axis label

  • y_min (Optional[float]) – Minimum value on the y-axis. Can be useful to set y-axis minimum to 0 for energy, for example.

  • y_max (Optional[float]) – Maximum value on the y-axis.

  • labels (Optional[Sequence[str]]) – A sequence of labels corresponding to the sequence of lines in spectra, used to label each line. If this is None, the label(s) contained in spectra.metadata[‘label’] (Spectrum1D) or spectra.metadata[‘line_data’][i][‘label’] (Spectrum1DCollection) will be used. To disable labelling for a specific line, pass an empty string.

  • **line_kwargs – matplotlib.line.Line2D properties, optional Used in the axes.plot command to specify properties like linewidth, linestyle

Return type

Figure

Returns

fig (matplotlib.figure.Figure)

plot_1d_to_axis(spectra, ax, labels=None, **mplargs)

Plot a (collection of) 1D spectrum lines to matplotlib axis

Where there are two identical x-values in a row, plotting will restart to avoid creating a vertical line

Parameters

  • spectra (Union[Spectrum1D, Spectrum1DCollection]) – Spectrum1D or Spectrum1DCollection to plot

  • ax (Axes) – Matplotlib axes to which spectra will be drawn

  • labels (Optional[Sequence[str]]) – A sequence of labels corresponding to the sequence of lines in spectra, used to label each line. If this is None, the label(s) contained in spectra.metadata[‘label’] (Spectrum1D) or spectra.metadata[‘line_data’][i][‘label’] (Spectrum1DCollection) will be used. To disable labelling for a specific line, pass an empty string.

  • **mplargs – Keyword arguments passed to Axes.plot

Return type

None

2D Plots

2D spectra are arranged in a matplotlib Figure with euphonic.plot.plot_2d():

from euphonic import Spectrum2D
from euphonic.plot import plot_2d

sqw = Spectrum2D.from_json_file('sqw.json')
fig, ims = plot_2d(sqw, ratio=1.0)
fig.show()

Plotting to a specific axis

This can be used to multiple subplots showing Spectrum2D in the same figure. A matplotlib.colors.Normalize object can also be used to ensure both spectra are on the same colour scale. An example of this for 2 S(Q,w) is below:

import matplotlib.pyplot as plt
from matplotlib.colors import Normalize
from euphonic import Spectrum2D
from euphonic.plot import plot_2d_to_axis

sqw1 = Spectrum2D.from_json_file('sqw1.json')
sqw2 = Spectrum2D.from_json_file('sqw2.json')
norm = Normalize(vmin=0, vmax=1e-10)
fig, axes = plt.subplots(1, 2)
plot_2d_to_axis(sqw1, axes[0], norm=norm)
plot_2d_to_axis(sqw2, axes[1], norm=norm)
fig.show()

Docstrings

plot_2d(spectra, vmin=None, vmax=None, cmap='viridis', title='', x_label='', y_label='')

Creates a Matplotlib figure for a Spectrum2D object

Parameters

  • spectra (Union[Spectrum2D, Sequence[Spectrum2D]]) – Containing the 2D data to plot. If a sequence of Spectrum2D is given, they will be plotted from right-to-left as separate subplots. This is recommended for band structure/dispersion plots with discontinuous regions.

  • vmin (Optional[float]) – Minimum of data range for colormap. See Matplotlib imshow docs

  • vmax (Optional[float]) – Maximum of data range for colormap. See Matplotlib imshow docs

  • cmap (Union[str, Colormap]) – Which colormap to use, see Matplotlib docs

  • title (str) – Set a title for the Figure.

  • x_label (str) – X-axis label

  • y_label (str) – Y-axis label

Return type

Figure

Returns

fig (matplotlib.figure.Figure) – The Figure instance

plot_2d_to_axis(spectrum, ax, cmap='viridis', interpolation='nearest', norm=None)

Plot Spectrum2D object to Axes

Parameters

  • spectrum (Spectrum2D) – 2D data object for plotting as NonUniformImage. The x_tick_labels attribute will be used to mark labelled points.

  • ax (Axes) – Matplotlib axes to which image will be drawn

  • cmap (Union[str, Colormap]) – Matplotlib colormap or registered colormap name

  • interpolation (str) – Interpolation method: ‘nearest’ or ‘bilinear’ for a pixellated or smooth result

  • norm (Optional[Normalize]) – Matplotlib normalization object; set this in order to ensure separate plots are on the same colour scale.

Return type

NonUniformImage