Spectra¶
These are generic objects for storing 1D/2D spectra e.g. density of states or S(Q,w) maps.
Metadata
All spectra objects have a metadata
attribute. By default it is an empty
dictionary, but it can contain keys/values to help describe the contained
spectra. The keys should be strings and values should be only strings or
integers. Note there are some special ‘functional’ keys, see the metadata
docstring below for each specific spectrum class for details.
Spectrum1D¶
Adding Spectrum1D¶
Two Spectrum1D
objects can be added together (provided they have the
same x_data
axes) with the +
operator. This will add their y_data
and return a single Spectrum1D
. Note that any metadata key/value pairs
that aren’t common to both spectra will be omitted from the new object. For
example:
from euphonic import Spectrum1D
pdos_si = Spectrum1D.from_json_file('si_pdos.json')
pdos_o = Spectrum1D.from_json_file('o_pdos.json')
total_dos = pdos_si + pdos_o
Broadening¶
A 1D spectrum can be broadened using
Spectrum1D.broaden
,
which broadens along the x-axis and returns a new Spectrum1D
object. It can broaden with either a Gaussian or Lorentzian and requires
a broadening FWHM in the same type of units as x_data
. For example:
from euphonic import ureg, Spectrum1D
dos = Spectrum1D.from_json_file('dos.json')
fwhm = 1.5*ureg('meV')
dos_broaden = dos.broaden(fwhm, shape='lorentz')
Docstring¶
-
class
Spectrum1D
(x_data, y_data, x_tick_labels=None, metadata=None)¶ For storing generic 1D spectra e.g. density of states
- Variables
x_data – Shape (n_x_data,) or (n_x_data + 1,) float Quantity. The x_data points (if size == (n_x_data,)) or x_data bin edges (if size == (n_x_data + 1,))
y_data – Shape (n_x_data,) float Quantity. The plot data in y
x_tick_labels – Sequence[Tuple[int, str]] or None. Special tick labels e.g. for high-symmetry points. The int refers to the index in x_data the label should be applied to
metadata –
Dict[str, Union[int, str]]. Contains metadata about the spectrum. Keys should be strings and values should be strings or integers There are some functional keys:
’label’ : str. This is used label lines on a 1D plot
-
__init__
(x_data, y_data, x_tick_labels=None, metadata=None)¶ - Parameters
x_data (
Quantity
) – Shape (n_x_data,) or (n_x_data + 1,) float Quantity. The x_data points (if size == (n_x_data,)) or x_data bin edges (if size == (n_x_data + 1,))y_data (
Quantity
) – Shape (n_x_data,) float Quantity. The plot data in yx_tick_labels (
Optional
[Sequence
[Tuple
[int
,str
]]]) – Special tick labels e.g. for high-symmetry points. The int refers to the index in x_data the label should be applied tometadata (
Optional
[Dict
[str
,Union
[int
,str
]]]) –Contains metadata about the spectrum. Keys should be strings and values should be strings or integers There are some functional keys:
’label’ : str. This is used label lines on a 1D plot
-
to_dict
()¶ Convert to a dictionary. See Spectrum1D.from_dict for details on keys/values
- Return type
Dict
[str
,Any
]- Returns
dict
-
classmethod
from_dict
(d)¶ Convert a dictionary to a Spectrum1D object
- Parameters
d (
Dict
[str
,Any
]) –A dictionary with the following keys/values:
’x_data’: (n_x_data,) or (n_x_data + 1,) float ndarray
’x_data_unit’: str
’y_data’: (n_x_data,) float ndarray
’y_data_unit’: str
There are also the following optional keys:
’x_tick_labels’: list of (int, string) tuples
’metadata’: dict
- Return type
~T
- Returns
spectrum
-
classmethod
from_castep_phonon_dos
(filename, element=None)¶ Reads DOS from a CASTEP .phonon_dos file
- Parameters
filename (
str
) – The path and name of the .phonon_dos file to readelement (
Optional
[str
]) – Which element’s PDOS to read. If not supplied reads the total DOS.
- Return type
~T
-
broaden
(x_width, shape='gauss')¶ Broaden y_data and return a new broadened spectrum object
- Parameters
x_width (
Quantity
) – Scalar float Quantity. The broadening FWHMshape (
str
) – One of {‘gauss’, ‘lorentz’}. The broadening shape
- Return type
~T
- Returns
broadened_spectrum – A new Spectrum1D object with broadened y_data
- Raises
ValueError – If shape is not one of the allowed strings
-
classmethod
from_json_file
(filename)¶ Read from a JSON file. See from_dict for required fields
- Parameters
filename (str) – The file to read from
- Return type
~T
-
get_bin_centres
()¶ Get x-axis bin centres. If the size of x_data is the same size as y_data, x_data is assumed to contain bin centres, but if x_data is one element larger, x_data is assumed to contain bin edges and a conversion is made. In this conversion, the bin centres are assumed to be in the middle of each bin, which may not be an accurate assumption in the case of differently sized bins.
- Return type
Quantity
-
get_bin_edges
()¶ Get x-axis bin edges. If the size of x_data is one element larger than y_data, x_data is assumed to contain bin edges, but if x_data is the same size, x_data is assumed to contain bin centres and a conversion is made. In the conversion, the bin edges will not go outside the existing data bounds so the first and last bins may be half-size. In addition, each bin edge is assumed to be halfway between each bin centre, which may not be an accurate assumption in the case of differently sized bins.
- Return type
Quantity
-
split
(indices=None, btol=None)¶ Split to multiple spectra
Data may be split by index. Alternatively, x-axis data may be split automatically by searching for unusually large gaps in energy values. These would usually correspond to disconnected special-points in a band-structure diagram.
- Parameters
indices (
Union
[Sequence
[int
],ndarray
,None
]) – positions in data of breakpointsbtol (
Optional
[float
]) – parameter used to identify breakpoints. This is a ratio between the gap in values and the median gap between neighbouring x-values. If neither indices nor btol is specified, this is set to 10.0.
- Return type
List
[~T]- Returns
split_spectra – Separated spectrum regions. If passed to the appropriate functions in euphonic.plot this would be interpreted as a series of subplots.
-
to_json_file
(filename)¶ Write to a JSON file. JSON fields are equivalent to from_dict keys
- Parameters
filename (str) – Name of the JSON file to write to
- Return type
None
Spectrum1DCollection¶
This is an object for storing multiple 1D spectra which share the same x-axis, e.g. bands in a dispersion plot.
From Spectrum1D¶
If you have multiple Spectrum1D
objects with the same x_data
,
they can be grouped together into a Spectrum1DCollection
object.
For example:
from euphonic import Spectrum1D, Spectrum1DCollection
pdos_si = Spectrum1D.from_json_file('si_pdos.json')
pdos_o = Spectrum1D.from_json_file('o_pdos.json')
pdos_collection = Spectrum1DCollection.from_spectra([pdos_si, pdos_o])
Adding Spectrum1DCollection¶
Two Spectrum1DCollection
objects can be added together (provided they
have the same x_data
axes) with the +
operator. This will concatenate
their y_data
, returning a single Spectrum1DCollection
that contains
all the y_data
of both objects. For example:
from euphonic import Spectrum1DCollection
coh_pdos = Spectrum1DCollection.from_json_file('coherent_pdos.json')
incoh_pdos = Spectrum1DCollection.from_json_file('incoherent_pdos.json')
all_pdos = coh_pdos + incoh_pdos
Indexing¶
A Spectrum1DCollection
can be indexed just like a list to obtain
a specific spectrum as a Spectrum1D
, or a subset of spectra as
another Spectrum1DCollection
, for example, to plot only specific
spectra:
from euphonic import Spectrum1DCollection
from euphonic.plot import plot_1d
spec1d_col = Spectrum1DCollection.from_json_file('dos.json')
# Plot the 1st spectrum
spec1d_0 = spec1d_col[0]
fig1 = plot_1d(spec1d_0)
# Plot the 2nd - 5th spectra
spec1d_col_1_5 = spec1d_col[1:5]
fig2 = plot_1d(spec1d_col_1_5)
Broadening¶
A collection of 1D spectra can also be broadened using
Spectrum1DCollection.broaden
,
which broadens each spectrum individually, giving the same result
as using Spectrum1D.broaden
on each contained spectrum.
Grouping By Metadata¶
You can group and sum specific spectra from a Spectrum1DCollection
based on their metadata using
Spectrum1DCollection.group_by
.
For example, if you have a collection spec1d_col
containing
8 spectra with the following metadata:
{'line_data': [
{'index': 1, 'species': 'Si', 'weighting': 'coherent'},
{'index': 2, 'species': 'Si', 'weighting': 'coherent'},
{'index': 3, 'species': 'O', 'weighting': 'coherent'},
{'index': 4, 'species': 'O', 'weighting': 'coherent'},
{'index': 1, 'species': 'Si', 'weighting': 'incoherent'},
{'index': 2, 'species': 'Si', 'weighting': 'incoherent'},
{'index': 3, 'species': 'O', 'weighting': 'incoherent'},
{'index': 4, 'species': 'O', 'weighting': 'incoherent'}]
}
If you want to group and sum spectra that have the same weighting
:
weighting_pdos = spec1d_col.group_by('weighting')
This would produce a collection containing 2 spectra with the following metadata
(the index
and species
metadata are not common across all the grouped
spectra, so have been discarded):
{'line_data': [
{'weighting': 'coherent'},
{'weighting': 'incoherent'}]
}
You can also group by multiple keys, for example to group and sum spectra that
have both the same weighting
and species
:
weighting_species_pdos = spec1d_col.group_by('weighting', 'species')
This would produce a collection containing 4 spectra with the following metadata:
{'line_data': [
{'species': 'Si', 'weighting': 'coherent'},
{'species': 'O', 'weighting': 'coherent'},
{'species': 'Si', 'weighting': 'incoherent'},
{'species': 'O', 'weighting': 'incoherent'}]
}
Selecting By Metadata¶
You can select specific spectra from a Spectrum1DCollection
based
on their metadata using
Spectrum1DCollection.select
.
For example, if you have a collection spec1d_col
containing
6 spectra with the following metadata:
{'line_data': [
{'species': 'Si', 'weighting': 'coherent'},
{'species': 'O', 'weighting': 'coherent'},
{'species': 'Si', 'weighting': 'incoherent'},
{'species': 'O', 'weighting': 'incoherent'},
{'species': 'Si', 'weighting': 'coherent-plus-incoherent'},
{'species': 'O', 'weighting': 'coherent-plus-incoherent'}]
}
If you want to select only the spectra where weighting='coherent'
:
coh_pdos = spec1d_col.select(weighting='coherent')
This would create a collection containing 2 spectra, with the following metadata:
{'line_data': [
{'species': 'Si', 'weighting': 'coherent'},
{'species': 'O', 'weighting': 'coherent'}]
}
You can also select multiple values for a specific key. To select spectra
where weighting='coherent'
or weighting='incoherent'
:
coh_or_incoh_pdos = spec1d_col.select(weighting=['coherent', 'incoherent'])
This would create a collection containing 4 spectra, with the following metadata:
{'line_data': [
{'species': 'Si', 'weighting': 'coherent'},
{'species': 'O', 'weighting': 'coherent'},
{'species': 'Si', 'weighting': 'incoherent'},
{'species': 'O', 'weighting': 'incoherent'}]
}
You can also select by multiple key/values. To select only the spectrum with
weighting='coherent'
and species='Si'
:
coh_si_pdos = spec1d_col.select(weighting='coherent', species='Si')
This would create a collection containing only one spectrum, with the following metadata:
{'species': 'Si', 'weighting': 'coherent'}
Summing Spectra¶
All spectra in a Spectrum1DCollection
can be summed with
Spectrum1DCollection.sum
.
This produces a single Spectrum1D
object.
Docstring¶
-
class
Spectrum1DCollection
(x_data, y_data, x_tick_labels=None, metadata=None)¶ A collection of Spectrum1D with common x_data and x_tick_labels
Intended for convenient storage of band structures, projected DOS etc. This object can be indexed or iterated to obtain individual Spectrum1D.
- Variables
x_data – Shape (n_x_data,) or (n_x_data + 1,) float Quantity. The x_data points (if size == (n_x_data,)) or x_data bin edges (if size == (n_x_data + 1,))
y_data – Shape (n_entries, n_x_data) float Quantity. The plot data in y, in rows corresponding to separate 1D spectra
x_tick_labels – Sequence[Tuple[int, str]] or None. Special tick labels e.g. for high-symmetry points. The int refers to the index in x_data the label should be applied to
metadata –
Dict[str, Union[int, str, LineData]] or None. Contains metadata about the spectra. Keys should be strings and values should be strings or integers. There are some functional keys:
- ’line_data’LineData
This is a Sequence[Dict[str, Union[int, str]], it contains metadata for each spectrum in the collection, and must be of length n_entries
-
__init__
(x_data, y_data, x_tick_labels=None, metadata=None)¶ - Parameters
x_data (
Quantity
) – Shape (n_x_data,) or (n_x_data + 1,) float Quantity. The x_data points (if size == (n_x_data,)) or x_data bin edges (if size == (n_x_data + 1,))y_data (
Quantity
) – Shape (n_entries, n_x_data) float Quantity. The plot data in y, in rows corresponding to separate 1D spectrax_tick_labels (
Optional
[Sequence
[Tuple
[int
,str
]]]) – Special tick labels e.g. for high-symmetry points. The int refers to the index in x_data the label should be applied tometadata (
Optional
[Dict
[str
,Union
[str
,int
,Sequence
[Dict
[str
,Union
[int
,str
]]]]]]) –Contains metadata about the spectra. Keys should be strings and values should be strings or integers. There are some functional keys:
- ’line_data’LineData
This is a Sequence[Dict[str, Union[int, str]], it contains metadata for each spectrum in the collection, and must be of length n_entries
-
to_dict
()¶ Convert to a dictionary consistent with from_dict()
- Return type
Dict
[str
,Any
]- Returns
dict
-
classmethod
from_dict
(d)¶ Convert a dictionary to a Spectrum1DCollection object
- Parameters
d (dict) –
A dictionary with the following keys/values:
’x_data’: (n_x_data,) or (n_x_data + 1,) float ndarray
’x_data_unit’: str
’y_data’: (n_x_data,) float ndarray
’y_data_unit’: str
There are also the following optional keys:
’x_tick_labels’: list of (int, string) tuples
’metadata’: dict
- Return type
~T
- Returns
spectrum_collection
-
classmethod
from_castep_phonon_dos
(filename)¶ Reads total DOS and per-element PDOS from a CASTEP .phonon_dos file
- Parameters
filename (
str
) – The path and name of the .phonon_dos file to read- Return type
~T
-
broaden
(x_width, shape='gauss')¶ Individually broaden each line in y_data, returning a new Spectrum1DCollection
- Parameters
x_width (
Quantity
) – Scalar float Quantity. The broadening FWHMshape (
str
) – One of {‘gauss’, ‘lorentz’}. The broadening shape
- Return type
~T
- Returns
broadened_spectrum – A new Spectrum1DCollection object with broadened y_data
- Raises
ValueError – If shape is not one of the allowed strings
-
group_by
(*line_data_keys)¶ Group and sum y_data for each spectrum according to the values mapped to the specified keys in metadata[‘line_data’]
- Parameters
line_data_keys (
str
) – The key(s) to group by. If only one line_data_key is supplied, if the value mapped to a key is the same for multiple spectra, they are placed in the same group and summed. If multiple line_data_keys are supplied, the values must be the same for all specified keys for them to be placed in the same group- Return type
~T
- Returns
grouped_spectrum – A new Spectrum1DCollection with one line for each group. Any metadata in ‘line_data’ not common across all spectra in a group will be discarded
-
sum
()¶ Sum y_data over all spectra
- Return type
- Returns
summed_spectrum – A Spectrum1D created from the summed y_data. Any metadata in ‘line_data’ not common across all spectra will be discarded
-
select
(**select_key_values)¶ Select spectra by their keys and values in metadata[‘line_data’]
- Parameters
**select_key_values – Key-value/values pairs in metadata[‘line_data’] describing which spectra to extract. For example, to select all spectra where metadata[‘line_data’][‘species’] = ‘Na’ or ‘Cl’ use spectrum.select(species=[‘Na’, ‘Cl’]). To select ‘Na’ and ‘Cl’ spectra where weighting is also coherent, use spectrum.select(species=[‘Na’, ‘Cl’], weighting=’coherent’)
- Return type
~T
- Returns
selected_spectra – A Spectrum1DCollection containing the selected spectra
- Raises
ValueError – If no matching spectra are found
-
count
(value) → integer – return number of occurrences of value¶
-
classmethod
from_json_file
(filename)¶ Read from a JSON file. See from_dict for required fields
- Parameters
filename (str) – The file to read from
- Return type
~T
-
get_bin_centres
()¶ Get x-axis bin centres. If the size of x_data is the same size as y_data, x_data is assumed to contain bin centres, but if x_data is one element larger, x_data is assumed to contain bin edges and a conversion is made. In this conversion, the bin centres are assumed to be in the middle of each bin, which may not be an accurate assumption in the case of differently sized bins.
- Return type
Quantity
-
get_bin_edges
()¶ Get x-axis bin edges. If the size of x_data is one element larger than y_data, x_data is assumed to contain bin edges, but if x_data is the same size, x_data is assumed to contain bin centres and a conversion is made. In the conversion, the bin edges will not go outside the existing data bounds so the first and last bins may be half-size. In addition, each bin edge is assumed to be halfway between each bin centre, which may not be an accurate assumption in the case of differently sized bins.
- Return type
Quantity
-
index
(value[, start[, stop]]) → integer – return first index of value.¶ Raises ValueError if the value is not present.
Supporting start and stop arguments is optional, but recommended.
-
split
(indices=None, btol=None)¶ Split to multiple spectra
Data may be split by index. Alternatively, x-axis data may be split automatically by searching for unusually large gaps in energy values. These would usually correspond to disconnected special-points in a band-structure diagram.
- Parameters
indices (
Union
[Sequence
[int
],ndarray
,None
]) – positions in data of breakpointsbtol (
Optional
[float
]) – parameter used to identify breakpoints. This is a ratio between the gap in values and the median gap between neighbouring x-values. If neither indices nor btol is specified, this is set to 10.0.
- Return type
List
[~T]- Returns
split_spectra – Separated spectrum regions. If passed to the appropriate functions in euphonic.plot this would be interpreted as a series of subplots.
-
to_json_file
(filename)¶ Write to a JSON file. JSON fields are equivalent to from_dict keys
- Parameters
filename (str) – Name of the JSON file to write to
- Return type
None
Spectrum2D¶
Broadening¶
A 2D spectrum can be broadened using
Spectrum2D.broaden
, which
broadens along either or both of the x/y-axes and returns a new
Spectrum2D object. It can broaden with either a Gaussian or Lorentzian
and requires a broadening FWHM in the same type of units as
x_data
/y_data
for broadening along the x/y-axis respectively.
For example:
from euphonic import ureg, Spectrum2D
sqw = Spectrum2D.from_json_file('sqw.json')
x_fwhm = 0.05*ureg('1/angstrom')
y_fwhm = 1.5*ureg('meV')
sqw_broaden = sqw.broaden(x_width=x_fwhm, y_width=y_fwhm, shape='lorentz')
Docstring¶
-
class
Spectrum2D
(x_data, y_data, z_data, x_tick_labels=None, metadata=None)¶ For storing generic 2D spectra e.g. S(Q,w)
- Variables
x_data – Shape (n_x_data,) or (n_x_data + 1,) float Quantity. The x_data points (if size == (n_x_data,)) or x_data bin edges (if size == (n_x_data + 1,))
y_data – Shape (n_y_data,) or (n_y_data + 1,) float Quantity. The y_data bin points (if size == (n_y_data,)) or y_data bin edges (if size == (n_y_data + 1,))
z_data – Shape (n_x_data, n_y_data) float Quantity. The plot data in z
x_tick_labels – Sequence[Tuple[int, str]] or None. Special tick labels e.g. for high-symmetry points. The int refers to the index in x_data the label should be applied to
metadata – Dict[str, Union[int, str]]. Contains metadata about the spectrum. Keys should be strings and values should be strings or integers
-
__init__
(x_data, y_data, z_data, x_tick_labels=None, metadata=None)¶ - Parameters
x_data (
Quantity
) – Shape (n_x_data,) or (n_x_data + 1,) float Quantity. The x_data points (if size == (n_x_data,)) or x_data bin edges (if size == (n_x_data + 1,))y_data (
Quantity
) – Shape (n_y_data,) or (n_y_data + 1,) float Quantity. The y_data bin points (if size == (n_y_data,)) or y_data bin edges (if size == (n_y_data + 1,))z_data (
Quantity
) – Shape (n_x_data, n_y_data) float Quantity. The plot data in zx_tick_labels (
Optional
[Sequence
[Tuple
[int
,str
]]]) – Special tick labels e.g. for high-symmetry points. The int refers to the index in x_data the label should be applied tometadata (
Optional
[Dict
[str
,Union
[int
,str
]]]) – Contains metadata about the spectrum. Keys should be strings and values should be strings or integers.
-
broaden
(x_width=None, y_width=None, shape='gauss')¶ Broaden z_data and return a new broadened Spectrum2D object
- Parameters
x_width (
Optional
[Quantity
]) – Scalar float Quantity. The broadening FWHM in xy_width (
Optional
[Quantity
]) – Scalar float Quantity. The broadening FWHM in yshape (
str
) – One of {‘gauss’, ‘lorentz’}. The broadening shape
- Return type
~T
- Returns
broadened_spectrum – A new Spectrum2D object with broadened z_data
- Raises
ValueError – If shape is not one of the allowed strings
-
get_bin_edges
(bin_ax='x')¶ Get bin edges for the axis specified by bin_ax. If the size of bin_ax is one element larger than z_data along that axis, bin_ax is assumed to contain bin edges, but if bin_ax is the same size, bin_ax is assumed to contain bin centres and a conversion is made. In the conversion, the bin edges will not go outside the existing data bounds so the first and last bins may be half-size. In addition, each bin edge is assumed to be halfway between each bin centre, which may not be an accurate assumption in the case of differently sized bins.
- Parameters
bin_ax (
str
) – The axis to get the bin edges for, ‘x’ or ‘y’- Return type
Quantity
-
classmethod
from_json_file
(filename)¶ Read from a JSON file. See from_dict for required fields
- Parameters
filename (str) – The file to read from
- Return type
~T
-
get_bin_centres
(bin_ax='x')¶ Get bin centres for the axis specified by bin_ax. If the size of bin_ax is the same size as z_data along that axis, bin_ax is assumed to contain bin centres, but if bin_ax is one element larger, bin_ax is assumed to contain bin centres and a conversion is made. In this conversion, the bin centres are assumed to be in the middle of each bin, which may not be an accurate assumption in the case of differently sized bins.
- Parameters
bin_ax (
str
) – The axis to get the bin centres for, ‘x’ or ‘y’- Return type
Quantity
-
split
(indices=None, btol=None)¶ Split to multiple spectra
Data may be split by index. Alternatively, x-axis data may be split automatically by searching for unusually large gaps in energy values. These would usually correspond to disconnected special-points in a band-structure diagram.
- Parameters
indices (
Union
[Sequence
[int
],ndarray
,None
]) – positions in data of breakpointsbtol (
Optional
[float
]) – parameter used to identify breakpoints. This is a ratio between the gap in values and the median gap between neighbouring x-values. If neither indices nor btol is specified, this is set to 10.0.
- Return type
List
[~T]- Returns
split_spectra – Separated spectrum regions. If passed to the appropriate functions in euphonic.plot this would be interpreted as a series of subplots.
-
to_json_file
(filename)¶ Write to a JSON file. JSON fields are equivalent to from_dict keys
- Parameters
filename (str) – Name of the JSON file to write to
- Return type
None
-
to_dict
()¶ Convert to a dictionary. See Spectrum2D.from_dict for details on keys/values
- Return type
Dict
[str
,Any
]- Returns
dict
-
classmethod
from_dict
(d)¶ Convert a dictionary to a Spectrum2D object
- Parameters
d (dict) –
A dictionary with the following keys/values:
’x_data’: (n_x_data,) or (n_x_data + 1,) float ndarray
’x_data_unit’: str
’y_data’: (n_y_data,) or (n_y_data + 1,) float ndarray
’y_data_unit’: str
’z_data’: (n_x_data, n_y_data) float Quantity
’z_data_unit’: str
There are also the following optional keys:
’x_tick_labels’: list of (int, string) tuples
’metadata’: dict
- Return type
~T
- Returns
spectrum