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='', 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 (
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 titlexlabel (
str
) – X-axis labelylabel (
str
) – Y-axis labelymin (
Optional
[float
]) – Minimum value on the y-axis. Can be useful to set y-axis minimum to 0 for energy, for example.ymax (
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 plotax (
Axes
) – Matplotlib axes to which spectra will be drawnlabels (
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 = 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='', xlabel='', ylabel='')
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 docsvmax (
Optional
[float
]) – Maximum of data range for colormap. See Matplotlib imshow docscmap (
Union
[str
,Colormap
,None
]) – Which colormap to use, see Matplotlib docstitle (
str
) – Set a title for the Figure.xlabel (
str
) – X-axis labelylabel (
str
) – Y-axis label
- Return type
Figure
- Returns
fig (matplotlib.figure.Figure) – The Figure instance
- 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 drawncmap (
Union
[str
,Colormap
,None
]) – Matplotlib colormap or registered colormap nameinterpolation (
str
) – Interpolation method: ‘nearest’ or ‘bilinear’ for a pixellated or smooth resultnorm (
Optional
[Normalize
]) – 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
.