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, ylabel='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, xlabel='Energy (meV)', ymin=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=None, xlabel='', ylabel='', ymin=None, ymax=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 (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 | None) – Plot title
xlabel (str) – X-axis label
ylabel (str) – Y-axis label
ymin (float | None) – Minimum value on the y-axis. Can be useful to set y-axis minimum to 0 for energy, for example.
ymax (float | None) – Maximum value on the y-axis.
labels (Sequence[str] | None) – 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

Returns:

fig (matplotlib.figure.Figure)

Return type:

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 (Spectrum1D | Spectrum1DCollection) – Spectrum1D or Spectrum1DCollection to plot
ax (Axes) – Matplotlib axes to which spectra will be drawn
labels (Sequence[str] | None) – 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 = plot_2d(sqw, cmap='bone')
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=None, title=None, xlabel='', ylabel='')

Creates a Matplotlib figure for a Spectrum2D object

Parameters:

spectra (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 (float | None) – Minimum of data range for colormap. See Matplotlib imshow docs
vmax (float | None) – Maximum of data range for colormap. See Matplotlib imshow docs
cmap (str | Colormap | None) – Which colormap to use, see Matplotlib docs
title (str | None) – Set a title for the Figure.
xlabel (str) – X-axis label
ylabel (str) – Y-axis label

Returns:

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

Return type:

Figure

plot_2d_to_axis(spectrum, ax, *, cmap=None, 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 (str | Colormap | None) – Matplotlib colormap or registered colormap name
interpolation (str) – Interpolation method: ‘nearest’ or ‘bilinear’ for a pixellated or smooth result
norm (Normalize | None) – Matplotlib normalization object; set this in order to ensure separate plots are on the same colour scale.

Return type:

NonUniformImage

Styling 

To produce consistent and beautiful plots, it is recommended to use Matplotlib style sheets. The cleanest way to apply this is using a context manager. Within the indented block, a user-provided combination of style sheets is applied to any new plots. These can be built-in themes, file paths or parameter dictionaries, e.g.:

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

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

with plt.style.context(['dark_background', {'lines.linewidth': 2.0}]):
    fig = plot_1d(dos)
fig.show()

This approach is used in the Euphonic command-line tools; for more information see Customising plots. The CLI defaults can be imitated by using the same style sheet euphonic.style.base_style.